NAME

PS.pm - Produce PostScript files from Perl

SYNOPSIS

use PS;

# create a new PostScript object
$p = new PS(papersize => "A4",
            colour => 1,
            units => "in");

# create a new page
$p->newpage;

# draw some lines and other shapes
$p->line(1,1, 1,4);
$p->linextend(2,4);
$p->box(1.5,1, 2,3.5);
$p->circle(2,2, 1);

# draw a rotated polygon in a different colour
$p->setcolour(0,100,200);
$p->polygon("rotate=45", 1,1, 1,2, 2,2, 2,1, 1,1);

# add some text in red
$p->setcolour("red");
$p->setfont("Times-Roman", 20);
$p->text(1,1, "Hello");

# write the output to a file
$p->output("file.ps");

DESCRIPTION

PS.pm allows you to have a simple method of writing PostScript files from Perl. It has several graphics primitives that allow lines, circles, polygons and boxes to be drawn. Text can be added to the page using standard PostScript fonts.

The images can be single page EPS files, or multipage PostScript files. The image size can be set by using a recognised paper size ("A4", for example) or by giving dimensions. The units used can be specified ("mm" or "in", etc) and are the same as those used in TeX. The default unit is a bp, or a PostScript point, unlike TeX.

It is hoped that one day there may be a GD to PS wrapper, but this does not currently exist.

PREREQUISITES

This module requires the strict module.

PS Methods

new(options)

Create a new PostScript object. The different options that can be set are:

units

Units that are to be used in the file. Common units would be mm, in, pt, bp, and cm. Others are as used in TeX. (Default: bp)

xsize

Specifies the width of the drawing area in units.

ysize

Specifies the height of the drawing area in units.

papersize

The size of paper to use, if xsize or ysize are not defined. This allows a document to easily be created using a standard paper size without having to remember the size of paper using PostScript points. Valid choices are currently "A3", "A4", "A5", and "Letter".

landscape

Use the landscape option to rotate the page by 90 degrees. The paper dimensions are also rotated, so that clipping will still work. (Default: 0)

clip

If set to 1, the image will be clipped to the xsize and ysize. This is most useful for an EPS image. (Default: 0)

colour

Specifies whether the image should be rendered in colour or not. If set to 0 (default) all requests for a colour are mapped to a greyscale. Otherwise the colour requested with setcolour or line is used. This option is present because most modern laser printers are only black and white. (Default: 0)

eps

Generate an EPS file, rather than a standard PostScript file. If set to 1, no newpage methods will actually create a new page. This option is probably the most useful for generating images to be imported into other applications, such as TeX. (Default: 1)

page

Specifies the initial page number of the (multi page) document. The page number is set with the Adobe DSC comments, and is used nowhere else. It only makes finding your pages easier. See also the newpage method. (Default: 1)

Example:

$ref = new PS(landscape => 1,
              eps => 0,
              xsize => 4,
              ysize => 3,
              units => "in");

Create a document that is 4 by 3 inches and prints landscape on a page. It is not an EPS file, and must therefore use the newpage method.

$ref = new PS(eps => 1,
              colour => 1,
              xsize => 12,
              ysize => 12,
              units => "cm");

Create a 12 by 12 cm EPS image that is in colour. Note that "eps => 1" does not have to be specified because this is the default.

newpage([number])

Generates a new page on a PostScript file. If specified, number gives the number (or name) of the page.

The page number is automatically incremented each time this is called without a new page number, or decremented if the current page number is negative.

Example:

$p->newpage(1);
$p->newpage;
$p->newpage("hello");
$p->newpage(-6);
$p->newpage;

will generate five pages, numbered: 1, 2, "hello", -6, -7.

output(filename)

Writes the current PostScript out to the file named filename. Will destroy any existing file of the same name.

Use this option whenever output is required to disk. The current PostScript document in memory is not cleared, and can still be extended.

setcolour((red, green, blue)|(name))

Sets the new drawing colour to the values specified in red, green and blue. The values range from 0 to 255.

Alternatively, a colour name may be specified. Those currently defined are listed at the top of PS.pm in the %pscolours hash.

Example:

# set new colour to brown
$p->setcolour(200,100,0);
# set new colour to black
$p->setcolour("black");

setlinewidth(width)

Sets the new line width to width units.

Example:

# draw a line 10mm long and 4mm wide
$p = new PS(units => "mm");
$p->setlinewidth(4);
$p->line(10,10, 20,10);

line(x1,y1, x2,y2 [,red, green, blue])

Draws a line from the co-ordinates (x1,x2) to (x2,y2). If values are specified for red, green and blue, then the colour is set before the line is drawn.

Example:

# set the colour to black
$p->setcolour("black");

# draw a line in the current colour (black)
$p->line(10,10, 10,20);

# draw a line in red
$p->line(20,10, 20,20, 255,0,0);

# draw another line in red
$p->line(30,10, 30,20);

linextend(x,y)

Assuming the previous command was line or linextend, extend that line to include another segment to the co-ordinates (x,y). Behaviour after any other method is unspecified.

Example:

$p->line(10,10, 10,20);
$p->linextend(20,20);
$p->linextend(20,10);
$p->linextend(10,10);

Notes

The polygon method may be more appropriate.

polygon(["options",] x1,y1, x2,y2, ..., xn,yn [,filled])

The polygon method is multi-function, allowing many shapes to be created and manipulated. Polygon draws lines from (x1,y1) to (x2,y2) and then from (x2,y2) to (x3,y3) up to (xn-1,yn-1) to (xn,yn).

If the value of filled is 1 then the PostScript output is set to fill the object rather than just draw the lines.

The options may be set as follows. Note that no whitespace may appear in each option, which must be specified as name=value1,value2. Each option must be separated by whitespace.

rotate=angle[,x,y]

Rotate the polygon by angle degrees anti-clockwise. If x and y are specified then use the co-ordinate (x,y) as the centre of rotation, otherwise use the co-ordinate (x1,y1) from the main polygon.

filled=1

Synonymous with the option filled above.

offset=x,y

Displace the object by the vector (x,y).

Example:

# draw a square with lower left point at (10,10)
$p->polygon(10,10, 10,20, 20,20, 20,10, 10,10);

# draw a filled square with lower left point at (20,20)
$p->polygon("offset=10,10", 10,10, 10,20, 20,20, 20,10, 10,10, 1);

# draw a filled square with lower left point at (10,10)
# rotated 45 degrees
$p->polygon("rotate=45 filled=1", 10,10, 10,20,
            20,20, 20,10, 10,10);

circle(x,y, r [,filled])

Plot a circle with centre at (x,y) and radius of r.

If filled is 1 then fill the circle.

Example:

$p->circle(40,40, 20);

box(x1,y1, x2,y2 [,filled])

Draw a rectangle from lower left co-ordinates (x1,y1) to upper right co-ordinates (y1,y2). If filled is 1 then fill the rectangle.

Example:

$p->box(10,10, 20,30);

Notes

The polygon method is far more flexible, but this method is quicker!

setfont(font, size)

Set the current font to the PostScript font font. Set the size in PostScript points to size.

Notes

This method must be called on every page before the text method is used.

text(x,y, string)

Plot text on the current page with the lower left co-ordinates at (x,y). The text is specified in string.

Example:

$p->setfont("Times-Roman", 12);
$p->text(40,40, "The frog sat on the leaf in the pond.");

Bugs

The text method does not currently support using some non-alphanumeric characters, notably parentheses.

BUGS

Some current functionality may not be as expected, and/or may not work correctly.

More functions need to be added. See the bottom of the PS.pm file.

AUTHOR

The PS.pm perl module was written by Matthew Newton, with a small amount of help and suggestions from Mark Withall.

The idea for the module came from the two aforementioned whilst (apparently) thinking.