|
PostScript::Simple - Produce PostScript files from Perl |
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 (``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.
This module requires strict and Exporter.
None.
new(options)mm, in,
pt, bp, and cm. Others are as used in TeX. (Default: bp)
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''.
setcolour or line is used. This option is present
because most modern laser printers are only black and white. (Default: 0)
newpage method. (Default: 1)
LeftBottom, LeftTop, RightBottom and RightTop. The default is
LeftBottom.
RightUp,
RightDown, LeftUp and LeftDown. The default value is RightUp.
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 newpage 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 ``eps => 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 newpage 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.
newpage([number])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)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.
getUse this method whenever output is required as a scalar. The current PostScript document in memory is not cleared, and can still be extended.
getepsThis 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))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.
Example:
# set new colour to brown
$p->setcolour(200,100,0);
# set new colour to black
$p->setcolour("black");
setlinewidth(width)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])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)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)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:
filled 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);
polygon([options,] x1,y1, x2,y2, ..., xn,yn)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:
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 is 1 then the PostScript output is set to fill the object rather
than just draw the lines.
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);
circle([options,] x,y, r)There is only one option.
filled 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);
circletext([options,] x, y, r, a, text)a with circle midpoint (x,y)
and radius r.
There is only one option.
alignment 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!");
box(x1,y1, x2,y2 [, options])Options are:
filled is 1 then fill the rectangle.
Example:
$p->box(10,10, 20,30);
$p->box( {filled => 1}, 10,10, 20,30);
Notes
The polygon method is far more flexible, but this method is quicker!
setfont(font, size)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)string.
Options are:
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.");
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.
importepsfile([options,] filename, x1,y1, x2,y2)Options are:
overlap is 1 then the scaling is calculated on the lesser dimension
and the EPS can overlap the area.
stretch is 1 then fill the entire area, ignoring the aspect ratio.
This option overrides overlap 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);
importeps(filename, x,y)(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);
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 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-2003 Matthew C. Newton / Newton Computing
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.
the PostScript::Simple::EPS manpage
|
PostScript::Simple - Produce PostScript files from Perl |