NAME

PostScript::Simple - Produce PostScript files from Perl

SYNOPSIS

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

DESCRIPTION

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 (""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.

PREREQUISITES

This module requires "strict" and "Exporter".

CONSTRUCTOR

"new(options)"

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

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

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

OBJECT METHODS

Unless otherwise specified, 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.

"newpage([number])"

Generates a new page on a PostScript file. If specified, "number" 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;
    

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 method whenever output is required to disk. The current PostScript document in memory is not cleared, and can still be extended.

"get"

Returns the current document.

Use this method whenever output is required as a scalar. The current PostScript document in memory is not cleared, and can still be extended.

"geteps"

Returns the current document as a PostScript::Simple::EPS object. Only works if the current document is EPS.

This method calls new PostScript::Simple::EPS with all the default options. To change these, call it yourself as below, rather than using this method.

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

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

Sets the new drawing colour to the RGB 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 the PostScript::Simple module in the %pscolours hash and include the standard X-Windows colour names.

Example:

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

"setcmykcolour(cyan, magenta, yellow, black)"

Sets the new drawing colour to the CMYK values specified in "cyan", "magenta", "yellow" and "black". The values range from 0 to 1. Note that PostScript::Simple does not do any colour management, so the output colour (as also with "setcolour") may vary according to output device.

Example:

    # set new colour to a shade of blue
    $p->setcmykcolour(0.1, 0.5, 0, 0.2);
    # set new colour to black
    $p->setcmykcolour(0, 0, 0, 1);
    # set new colour to a rich black
    $p->setcmykcolour(0.5, 0.5, 0.5, 1);
    

"setlinewidth(width)"

Sets the new line width to "width" units.

Example:

    # draw a line 10mm long and 4mm wide
    $p = new PostScript::Simple(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", "linextend", "curve" or "curvextend", 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.

"arc([options,] x,y, radius, start_angle, end_angle)"

Draws an arc on the circle of radius "radius" with centre ("x","y"). The arc starts at angle "start_angle" and finishes at "end_angle". Angles are specified in degrees, where 0 is at 3 o'clock, and the direction of travel is anti-clockwise.

Any options are passed in a hash reference as the first parameter. The available option is:

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

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

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).

Any options are passed in a hash reference as the first parameter. The available options are as follows:

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

"circle([options,] x,y, r)"

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

There is only one option.

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

"circletext([options,] x, y, r, a, text)"

Draw text in an arc centered about angle "a" with circle midpoint ("x","y") and radius "r".

There is only one option.

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

"box(x1,y1, x2,y2 [, options])"

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

Options are:

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

"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([options,] x,y, string)"

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 "string".

Options are:

    $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 "line", "linextend", "curve" or "curvextend", 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.

"importepsfile([options,] filename, x1,y1, x2,y2)"

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:

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

"importeps(filename, x,y)"

Imports a PostScript::Simple::EPS object into the current document at position "(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(90);
    $e->scale(0.5);
    # add eps to the current page
    $p->importeps($e, 10,50);
    

"err()"

Returns the last error generated.

Example:

  unless ($ps->setcolour("purplewithyellowspots")) {
    print $ps->err();
  }
  # prints "bad colour name 'purplewithyellowspots'";
    

BUGS

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

AUTHOR

The PostScript::Simple module was created by Matthew Newton, with ideas and suggestions from Mark Withall and many other people from around the world. Thanks!

Please see the README file in the distribution for more information about contributors.

Copyright (C) 2002-2014 Matthew C. Newton

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details, available at http://www.gnu.org/licenses/gpl.html.

SEE ALSO

PostScript::Simple::EPS