PostScript::Simple - Produce PostScript files from Perl

    use PostScript::Simple;

    # create a new PostScript object
    $p = new PostScript::Simple(papersize => "A4",
                                colour => 1,
                                eps => 0,
                                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);
    $p->setlinewidth( 0.01 );
    $p->curve(1,5, 1,7, 3,7, 3,5);
    $p->curvextend(3,3, 5,3, 5,5);

    # 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");

PostScript::Simple allows you to have a simple method of writing PostScript files from Perl. It has graphics primitives that allow lines, curves, 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 ("CWA4, for example) or by giving dimensions. The units used can be specified (CWmm or CWin", etc) and are the same as those used in TeX. The default unit is a bp, or a PostScript point, unlike TeX.

This module requires CWstrict and CWExporter.

None.

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

units

Units that are to be used in the file. Common units would be CWmm, CWin, CWpt, CWbp, and CWcm. Others are as used in TeX. (Default: CWbp)

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 CWxsize or CWysize 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 "CWA3, CWA4, CWA5, and CWLetter".

landscape

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

copies

Set the number of copies that should be printed. (Default: 1)

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 CWsetcolour or CWline 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 CWnewpage method. (Default: 1)

coordorigin

Defines the co-ordinate origin for each page produced. Valid arguments are CWLeftBottom, CWLeftTop, CWRightBottom and CWRightTop. The default is CWLeftBottom.

direction

The direction the co-ordinates go from the origin. Values can be CWRightUp, CWRightDown, CWLeftUp and CWLeftDown. The default value is CWRightUp.

reencode

Requests that a font re-encode function be added and that the 13 standard PostScript fonts get re-encoded in the specified encoding. The most popular choice (other than undef) is 'ISOLatin1Encoding' which selects the iso8859-1 encoding and fits most of western Europe, including the Scandinavia. Refer to Adobes Postscript documentation for other encodings. The output file is, by default, re-encoded to ISOLatin1Encoding. To stop this happening, use 'reencode => undef'. To use the re-encoded font, '-iso' must be appended to the names of the fonts used, e.g. 'Helvetica-iso'. Example:

    $ref = new PostScript::Simple(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 CWnewpage method.

    $ref = new PostScript::Simple(eps => 1,
                                  colour => 1,
                                  xsize => 12,
                                  ysize => 12,
                                  units => "cm",
                                  reencode => "ISOLatin1Encoding");

Create a 12 by 12 cm EPS image that is in colour. Note that "CWeps => 1" did not have to be specified because this is the default. Re-encode the standard fonts into the iso8859-1 encoding, providing all the special characters used in Western Europe. The CWnewpage method should not be used.

All object methods return 1 for success or 0 in some error condition (e.g. insufficient arguments). Error message text is also drawn on the page. Generates a new page on a PostScript file. If specified, CWnumber gives the number (or name) of the page. This method should not be used for EPS files. 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;

  $eps = new PostScript::Simple::EPS(source => $ps->get);

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

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

    # 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);

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

filled => 1

If CWfilled is 1 then the arc will be filled in. Example:

    # semi-circle
    $p->arc(10, 10, 5, 0, 180);

    # complete filled circle
    $p->arc({filled=>1}, 30, 30, 10, 0, 360);

The CWpolygon 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). Any options are passed in a hash reference as the first parameter. The available options are as follows:

rotate => angle =item rotate => [angle,x,y]

Rotate the polygon by CWangle 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

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

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], filled => 1},
                10,10, 10,20, 20,20, 20,10, 10,10);

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

Plot a circle with centre at (x,y) and radius of r. There is only one option.

filled => 1

If CWfilled is 1 then the PostScript output is set to fill the object rather than just draw the lines. Example:

    $p->circle(40,40, 20);
    $p->circle( {filled => 1}, 62,31, 15);

Draw text in an arc centered about angle CWa with circle midpoint (CWx,CWy) and radius CWr. There is only one option. CWalignment can be 'inside' or 'outside'. The default is 'inside'. Example:

    # outside the radius, centered at 90 degrees from the origin
    $p->circletext(40, 40, 20, 90, "Hello, Outside World!");
    # inside the radius centered at 270 degrees from the origin
    $p->circletext( {align => "inside"}, 40, 40, 20, 270, "Hello, Inside World!");

Draw a rectangle from lower left co-ordinates (x1,y1) to upper right co-ordinates (y1,y2). Options are:

filled => 1

If CWfilled is 1 then fill the rectangle. Example:

    $p->box(10,10, 20,30);
    $p->box( {filled => 1}, 10,10, 20,30);

Notes The CWpolygon method is far more flexible, but this method is quicker! Set the current font to the PostScript font CWfont. Set the size in PostScript points to CWsize. Notes This method must be called on every page before the CWtext method is used. Plot text on the current page with the lower left co-ordinates at (x,y) and using the current font. The text is specified in CWstring. Options are: alignment can be 'left', 'centre' or 'right'. The default is 'left'.

rotate => angle

rotate degrees of rotation, defaults to 0 (i.e. no rotation). The angle to rotate the text, in degrees. Centres about (x,y) and rotates clockwise. (?). Default 0 degrees. Example:

    $p->setfont("Times-Roman", 12);
    $p->text(40,40, "The frog sat on the leaf in the pond.");
    $p->text( {align => 'centre'}, 140,40, "This is centered.");
    $p->text( {rotate => 90}, 140,40, "This is rotated.");
    $p->text( {rotate => 90, align => 'centre'}, 140,40, "This is both.");

curve( x1, y1, x2, y2, x3, y3, x4, y4 )

Create a curve from (x1, y1) to (x4, y4). (x2, y2) and (x3, y3) are the control points for the start- and end-points respectively.

curvextend( x1, y1, x2, y2, x3, y3 )

Assuming the previous command was CWline, CWlinextend, CWcurve or CWcurvextend, extend that path with another curve segment to the co-ordinates (x3, y3). (x1, y1) and (x2, y2) are the control points. Behaviour after any other method is unspecified.

newpath

This method is used internally to begin a new drawing path - you should generally NEVER use it.

moveto( x, y )

This method is used internally to move the cursor to a new point at (x, y) - you will generally NEVER use this method. Imports an EPS file and scales/translates its bounding box to fill the area defined by lower left co-ordinates (x1,y1) and upper right co-ordinates (x2,y2). By default, if the co-ordinates have a different aspect ratio from the bounding box, the scaling is constrained on the greater dimension to keep the EPS fully inside the area. Options are:

overlap => 1

If CWoverlap is 1 then the scaling is calculated on the lesser dimension and the EPS can overlap the area.

stretch => 1

If CWstretch is 1 then fill the entire area, ignoring the aspect ratio. This option overrides CWoverlap if both are given. Example:

    # Assume smiley.eps is a round smiley face in a square bounding box

    # Scale it to a (10,10)(20,20) box
    $p->importepsfile("smiley.eps", 10,10, 20,20);

    # Keeps aspect ratio, constrained to smallest fit
    $p->importepsfile("smiley.eps", 10,10, 30,20);

    # Keeps aspect ratio, allowed to overlap for largest fit
    $p->importepsfile( {overlap => 1}, "smiley.eps", 10,10, 30,20);

    # Aspect ratio is changed to give exact fit
    $p->importepsfile( {stretch => 1}, "smiley.eps", 10,10, 30,20);

Imports a PostScript::Simple::EPS object into the current document at position CW(x,y). Example:

    use PostScript::Simple;

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

    # create a new page
    $p->newpage;

    # create an eps object
    $e = new PostScript::Simple::EPS(file => "test.eps");
    $e->rotate(9);
    $e->scale(0.5);

    # add eps to the current page
    $p->importeps($e, 10,50);

Some current functionality may not be as expected, and/or may not work correctly. That's the fun with using code in development!

The PostScript::Simple module was created by Matthew Newton, with ideas and suggestions from Mark Withall.

Contributions to the work (either code or suggestions / improvements) have been gratefully received from: Andreas Marcel, P Kent, Flemming Frandsen, Michael Tomuschat, Vladi Belperchinov-Shabanski, Eric Wilhelm, Peter Kuhn, Glen Harris.

Apologies if you have contributed and I have missed you... please let me know so I can add your name to the next release.

PostScript::Simple::EPS GD