NAME EPS - Routines for creating Encapsulated-Postscript Images SYNOPSIS use EPS; $p = EPS -> new(x_size=>150, y_size=>100); # new image with 150x100 mm size $p -> set_default(unit_length=>"cm", verbose=>1); $p -> set (background=>"Blue"); # blue background $p -> set (gradient=>[2,"Blue","Black",[0,0],[10,50],1]); # color gradient $p -> set (background=>"gradient"); # gradient background $p -> setcolor("Green"); $p -> line([10,10],[20,10],[30,20]); $p -> circle(50,20,15); $p -> filled_circle(50,20,15); $p -> polygon([20,20],[30,20],[40,40],[20,50]); $p -> filled_polygon([20,20],[30,20],[40,40],[20,50]); $p -> rawcode("0 0 moveto 20 10 lineto stroke"); $p -> font('Helvetica',10); # setting font (10 pt size) $p -> text('This is a left justified text','l'); $p -> text('This is a centered text','c'); $p -> text('This is a right justified text','r'); $p -> draw($p1, $x_position=>10,y_position=>20); $p -> any_postscript_command($a,$b,$c,$d); $p -> write("image.eps"); INTRODUCTION This Perl package supports the creation of Encapsulated Postscript images (level 3) with a single color or a color gradient as background, containing simple shapes (as lines, polygons, circles etc.) and text. Additionally, any Postscript code can be included verbatim. The unit length for all dimensions can be set with the property "unit_length", initially it is set to millimeters. Nevertheless, the fontsize is always given in Postscript points. Colors: Any color can be given in the following ways: List of RGB-values: List or reference to a list of the red-, green- and blue-values ranging either from 0 to 1 or from 0 to 255 Examples: "(0, 0.5, 0.7)", "[$rvalue, $gvalue, $bvalue]", "[255,0,0]" RGB-values hexadecimal: a string representing the hex values blue, green, and red ranging from 00 to ff Examples: ""#0000ff"" (red), ""#009900"" (dark green) Named Colors: a string representing an named color. Initially all the colors names from Mathematica are defined; additionally to those, new color names can be defined with $p -> definecolor(color_name -> [$r, $g, $b]); Examples: ""Red"", ""BlueViolet"", ""color_name"" PROPERTIES An image object has the following properties which can be set with the methods "new" (for a new image), "set" (for an existing image) or "set_default" (for all subsequently created images): Basic Properties: background Background color (default: no background) clip If set to 1, all drawings are confined to the bounding box of the image, determined by "x_size" and "y_size", objects outside are clipped; if set to 0, no clipping is performed; default: 1. frame Specifies whether a frame is drawn around the image (0...no frame, 1...frame), default: 0 framecolor, framewidth Color and width of the frame, default: 'Black' and 0, respectively. gradient Contains an array of several values which control the generation of a shaded background or a shaded fill, consisting of the following values: * Shading Type: an integer representing the type of shading according to the Adobe Postscript recerence manual. Currently only two shading types are supported: axial shading (shading type 2) and radial shading(shading type 3). * starting color * final color * reference to an array containing the coordinates for the statring point of the color axis (shading type 2) or the coordinates for the center and the radius for the starting circle (shading type 3). * same as above, for the final point and the final circle, respectively * Exponent of the interpolation function for the color-gradient Examples: gradient => [2, 'Blue', 'Black', [0,0], [20,90], 1] gradient => [3, '#0000ff', '#001234', [60,45,0], [80,50,100], 1] reencode If set to "iso" when a font is used for the first time, that font will be reencoded to ISO-Latin 1 encoding; this allows the use of umlauts and other language specific characters. If set to 0 (or empty string), subsequently introduced fonts are used with their original encoding. space_width When set to a positive value, spaces in text are replaced by direct positioning of the particular words. That value (in relation to the font size) specifies the widths of the gaps between words (proper values are 0.3 to 0.5). That property is useful for fonts which are designed for TeX (such as the CM- and the EC-fonts), as those do not have a real space character which is blank. unit_length Unit length for all dimensions; can be set with a string (""pt""...Postscipt points, ""mm""...millimeters, ""cm""...centimeters, ""in""...inch) or a number representing a multiple of Postscript points (default ""mm""). verbose Controls the output of messages: A value of 0 supresses all messages; at 1 the creation and vanishing of images is reported, as well as writing to file, 2 causes (additional to 1) reporting all calls of "AUTOLOAD", which translate any methods, which are not declared explicitely, into Postsript commands. psverbose Controls writing comments into the EPS file: when set to one, some actions as the begin and end of drawing an image into another image are commented. x_size Horizontal size of the image (default 120). y_size Vertical size of the image (default 90). Properties for merging images: The following properties are only significant, if images (i.e. EPS objects) are drawn into other images using the methods "draw" or "include". align Specifies the alignment for the included image (with respect to "x_position" and "y_position"); its value is a string containing one or an appropriate combination of the following letters (default: "'lb'"): * "l"...left * "r"...right * "c"...center * "t"...top * "b"...bottom angle Specifies the angle of the included image in degrees, default:0 width, height, scale These parameters specify the actual size of an image when drawn into another image; the image to be drawn is resized accordingly in order not to exceed any of the specified parameters. Default for "scale": 1 (which means no resizing), "width" and "height" are initially undefined x_position, y_position Specifies the position of the image to be included; unless specified, the image is included at the actual drawing position (of the receiving image). All properties stated above, usually are set be set by the user, it is therefore hardly necessary to read them out; nevertheless a "get"-method exists to read them out. Besides, an image consists of the following additional properties, which are not set by the user directly. Additional properties: _p_code A string receiving all the Postscript code generated by the methods; that string is written to the image-file with the method "write". number An integer number (begining with 1) for every created image. METHODS circle Draws an outlined circle, requires three parameters: the x- and y-coordinate of the center point and the radius. Example: $img -> circle($x0, $y0, $radius); clone Clones an image; example: $newimg = $img -> clone; definecolor Defines additional color names for the "EPS" class, example: $EPS -> definecolor("Gelb"=>"Yellow", "Lila"=>[0.4,0.7,0]); destroy Destructor of an image; releases memory when an object is not needed any more: $img -> destroy: draw Draws an image into another image. All properties of the drawn image can be set temporarily in the parameter list as key-value pairs, which is primarily useful for the properties regarding the drawing (e.g. "x_position", "y_position", "scale", "width", "height", "align", "angle"). The properties are not set permanently (as done by "set"). Example: $img -> draw($another_img, x_position=>10, y_position=>20, scale=>0.5); If only "x_position", "y_position" (and "scale") need to be specified, a short form without specifying key-value pairs but only specifying the values, exists for sake of conveniency: $img -> draw($another_img,10,20,0.5); filled_circle Draws a filled circle, example: $img -> filled_circle($x0, $y0, $radius); filled_polygon Draws a filled polygon, exaple; $img -> filled_polygon([0,0],[0,100],[50,50]); font Setting the font and fontsize (in Postscript points), example: $img -> font("Helvetica", 12); get Reads out properties of an image object, arguments are strings containing the property names, an array containing the property values is returned. Example: ($width, $height) = $img -> get("x_size", "y_size"); gfill Fills a path with a color gradient, which is either defined in the property gradient or given as a parameter. Example: $img -> set(gradient => [2,"Blue","Black",[0,0],[0,50],1]); $img -> path([0,0],[0,100],[50,50]); $img -> gfill; include On principle the same as "draw" but from the point of view of the image which is receiving the other image. The following example do exactly the same as the previous examples: $another_img -> include($img, x_position=>10, y_position=>20, scale=>0.5); $another_img -> include($img,10,20,0.5); line Draws concatenated lines, the points are given as list references containing the x- and y-coordinates. Example: $img -> line([10,10], [55,10], [10,60], [55,60]); new Creation a new image object; arbitrary properties can be passed to the object like in the "set"-method. Example: $img = EPS -> new(x_size=>150, y_size=>100, background=>"Black"); If only "x_size", "y_size" (and "background") need to be specified, a short form without specifying key-value pairs but only specifying the values, exists for sake of conveniency: $img = EPS -> new(150,100,"Black"); path Makes a drawing path defined by points, but does not actually put any color on that path (like "polygon") or into the surrounded region (like "filled_polygon"), that method is just a prerequisite for "gfill" (but can also be used in a very general way to make drawing paths for subsequent stroking or filling). polygon Draws an outlined polygon with arbitrary verticees, the vertices are given as list references its containing x- and y-coordinates. Example: $img -> polygon([0,0],[0,100],[50,50]); rawcode Includes Postscript Code, which is given as a string, verbatim in the image. Example: $img -> rawcode("gsave 50 50 moveto 45 rotate"); set Sets and changes the properties of an image; arguments are key-values pairs of the properties. Example: $img -> set(background=>[0,0,1], verbose=>1); setcolor Sets the drawing color, which can be given in any of the above stated ways. Examples: $img -> setcolor(1,1,0); $img -> setcolor([1,1,0]); $img -> setcolor("Yellow"); $img -> setcolor("#00ffff"); setdash Sets dash patterns for lines; the parameter values are the lengths of the line segments and the gaps between. The value 0 turns off dashing. Example: $img -> setdash(6,1,2,1); set_default Sets default values of the properties for all subsequently created image objects. Example: $EPS -> set_default(x_size=>50, x_size=>50); text Writes a textstring (which is given as th first parameter) at the current plot position, an alignment can be given as second parameter: 'l'...left aligned (default), 'c'...centered, 'r'...right aligned. Example: $img -> text('This is a centered text!','c'); textp Similar to "text", but specifies the insertion point as the first two parameters, example: $img -> textp(25,50,'This is a centered text!','c'); textpath Similar to "Text", but only prepares a character path for subsequent filling (preferably with a color gradient) or stroking, example: $img -> textpath('This is a centered text!','c'); $img -> gfill; write Writes the Postscript code which is contained in "_p_code" (additional to an EPS header and trailer) to a file, which is given as an argument. If no filename is given, the EPS-file gets the same name as the calling Perl-file (with the extension changed to ".eps"). The filename extension ".eps" is assumed (unless given explicitely); an existing file with the same name will be overwritten without mention. Example: $img -> write("picture1.eps"); writepdf Like "write", additional to that, the program *epstopdf* (which is part of Ghostscript) is invoked to produce a "PDF"-file; the file-extension ".pdf" is appended automatically. Example: $img -> writepdf("picture1"); Translation of methods into Postscript commands Additional to the methods listed above, any Postscript command can be declared as a method, which will be translated via AUTOLOAD into the respective Postscript command in the following way: $p -> any_postscript_command($a,$b,$c,$d,...) is translated to $a $b $c $d ... any_postscript_command Thus, basic knowledge of the Postscript language is helpful; see Postscript Language Reference Manual ("Red Book") for further details. Beware: Perl will not complain about a method like $img -> totally_nonsense("blah-blah") but very likely the Postscript interpreter will produce an error message. Examples: $p -> newpath; # begins a new drawing path $p -> closepath; # finishes a the current drawing path $p -> gsave; # saves the graphic state $p -> grestore; # restores the graphic state $p -> moveto(10,10); # moves the drawing cursor to the point (10,20) $p -> lineto(10,20); # draws a line to the point (10,20) $p -> stroke; # fills the path with color $p -> fill; # fills the region wihthin the path with color $p -> setlinewidth(0.3);# sets the linewidth $p -> setlinecap(0); # sets the type of line endings $p -> setlinejoin(0); # sets the type of line joins $p -> translate(100,20);# moves the origin of the coordinate system $p -> scale(2,2); # scales the x- and y-axis of the coordinate system $p -> rotate(45); # rotates the coordinate system by 45 degrees $p -> rectfill(10,10,70,50); # draws a filled rectangle $p -> rectstroke(10,10,70,50); # draws an outlined rectangle VERSION EPS 3.0 (2003-11-03) AUTHOR Wilhelm Haager, HTL St.Poelten, Austria "(wilhelm.haager@htlstp.ac.at)" COPYRIGHT Copyright 2003, Wilhelm Haager This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.