postscript.lsp

Module index

source download

Module: postscript.lsp

Routines for creating postscript files

Version: 2.0 - bugfixes and documentation overhaul.
Version: 2.1 - doc changes
Version: 2.2 - formatting
Version: 2.3 - documentation
Version: 2.4 - replaced if-not with unless
Version: 2.43 - doc corrections
Author: Lutz Mueller, July 2006, 2009, 2010, 2012, 2013


Routines for creating postscript files

To use this module include the following load statement at the beginning of the program file:
 (load "/usr/share/newlisp/modules/postscript.lsp")
 ; or shorter
 (module "postscript.lsp")
 


See http://newlisp.org/index.cgi?Postscript for many examples with source code.

Postscript files can be viewed using: open filename.ps on Mac OS X or using the Ghostscript program on Unix's or Win32 to convert to PDF or any graphics file format. Best quality is achieved on Mac OS X when using the Preview.app viewer for loading the postscript files and converting to PDF or bitmapped formats like JPEG, PNG, GIF by re-saving.

If not using Mac OS X look for Ghostscript here: www.ghostscript.com and here: www.cs.wisc.edu/~ghost/

NOTE! on some Mac OS X installations it is necessary to quit out of the Preview.app completely before viewing a .ps file for the first time. Subsequent views of .ps documents are fine.

On Linux/UNIX systems the following command can be used to convert a .ps file to a .pdf file:
   gs -sDEVICE=pdfwrite -dBATCH -sOutputFile=aFile.pdf -r300 aFile.ps
 
Most functions work like in turtle graphics relative to the current position of an imaginary drawing pen with an orientation of 0 to 360 degree starting streight up: 0 and moving clockwise right 90, down 180, left 270, up and 360 degrees. Other functions work on absolute X,Y coordinates.

The coordinate system starts on the bottom left with 0,0 and extends on a 8 1/2 x 11 inch letter page to x': 612, 'y: 792, 72 points for each inch. The functions ps:transpose and ps:scale can be used to move the origin point x=0, y=0 or scale from points to other measurements.

Return value from ps:xxx functions are not used and not mentioned in the documentation.

A package with all demo files can be downloaded at www.newlisp.org/postscript/postscript-24.tgz The demo files in the package assume execution on Mac OS X with automatic preview of PS pages. For other platforms chamges the last ps:render statement to include a filename for a postscript file.

Summary of functions

Turtle coordinate positioning and turning

 ps:goto  - move turtle to position x, y
 ps:move  - move turtle a distance s forward from the current position
 ps:turn  - turn the turtle degress dg left (negative) or right (positive)
 ps:angle - set the turtle orientation to dg degrees
 

Line drawing

 ps:draw   - draw distance s forward from current position
 ps:drawto - draw to the absolute position x,y from the current position
 ps:line   - draw a multipart line consisting of line and bezier curve segments
 ps:bezier - draw a Bezier curve 
 

Closed shapes, filling and clipping

 ps:rectangle - draw a rectangle
 ps:polygon   - draw a polygon with radius rad and n number of sides
 ps:circle    - draw a circle
 ps:ellipse   - draw an open or closed ellipse with x-rad and y-rad radius
 ps:pie       - draw a pie piece with radius rad and width
 ps:petal     - draw a petal shape from Bezier curves
 ps:shape     - draw a shape defined by a list of line and Bezier segments
 ps:clip      - define a clipping path using line and Bezier segments
 

Text output and clipping

 ps:text           - draw a solid text string
 ps:textoutline    - draw text in outline shape
 ps:textarc        - draw text around an arc
 ps:textarcoutline - draw text in outline shape around an arc
 ps:textclip       - use a textoutline as clipping path
 

Global settings

 ps:translate  - move coordinate origin
 ps:scale      - scale postscript output
 ps:rotate     - rotate postscript output
 ps:gsave      - save current graphics state (X, Y, orientation, translation, scale, rotation)
 ps:grestore   - restore current graphics state
 ps:font       - set font family and size
 ps:line-witdh - set line width in points
 ps:line-cap   - set line termination shape
 ps:line-join  - set line join mode
 ps:line-color - set line color
 ps:fill-color - set fill color
 

Rendering and output

 ps:render     - render output to a monitor
 ps:save       - deprecated, use ps:render with file-name instead
 


§

ps:angle

syntax: (ps:angle num-dg)
parameter: num-dg - Angle degrees from 0 to 360.

Set the turtle angle to num-dg degrees. Upwards is 0, right 90, downwards 180 and left 270 degrees. The turtle position is aved on the graphics state stack when using (ps:gsave).

§

ps:bezier

syntax: (ps:bezier num-x1 num-y1 num-x2 num-y2 num-x3 num-y3)
parameter: - num-x1,num-y1 Bezier coordinates of p1 relative to p0 = 0,0
parameter: - num-x2,num-y2 Bezier coordinates of p2 relative to p0 = 0,0
parameter: - num-x3,num-y3 Bezier coordinates of p3 relative to p0 = 0,0

Draw a Bezier curve. The Bezier curve starts at point p0 which is the current turtle position and stops at point p3 which is at offset num-x3 and num-y3 relative to starting point. The turtle orientation after the drwaing the Bezier curve is perpendicular to the Bezier curve baseline p0 to p3 and the position is p3.

§

ps:circle

syntax: (ps:circle num-rad [bool-fill])
parameter: num-rad - Radius of the circle.
parameter: num-fill - Optional fill flag.

Draw a circle with radius num-rad. The optional num-fill flag with either true or nil (default) indicates if the circle is filled with the fill color specified by ps:fill-color. The circle is drawn around the current turtle position. The turtle position or orientation is not changed.

§

ps:clip

syntax: (ps:clip list-of-num-lists)
parameter: list-of-num-lists - A list of turtle movements and/or Bezier curves.
Define a clipping path using turtle movements (degree distance) and
Bezier curves (x1 y1 x2 y2 x3 y3) starting from the last turtle coordinates x0, y0 and finishing at x3, y3. All Bezier coordinates are relative to the previous turtle position and orientation.

Before redefining the clipping area (ps:gsave) should be used to save the old graphics state parameters, after clipping and drawing in the clipped area the graphics state should be restored using (ps:grestore). The turtle position or orientation is not changed.

§

ps:draw

syntax: (ps:draw num-s)
parameter: num-s - Distance to draw.

Draw going forward distance num-s. Moves the turtle forward by the amount of points specified in num-s and draws with the current line color set by ps:line-color.



§

ps:drawto

syntax: (ps:drawto x y)
parameter: x - The x coordinate to draw to.
parameter: y - The y coordinate to draw to.

Draw a line to point x, y. Moves the turtle to point x, y like (ps:goto x y), but also draws a line from the old to the new position. The turtle position is changed to the new point x, y and the orientation is changed to the orientaion of the line drawn.

§

ps:ellipse

syntax: (ps:ellipse num-x-rad num-y-rad num-start num-end [bool-fill])
parameter: num-x-rad - The x axis radius.
parameter: num-y-rad - The y axis radius.
parameter: num-start - The start angle in 0 to 360 degrees.
parameter: end-num - The end angle in 0 to 360 degrees.

Draw an ellipse with optional bool-fill either true or nil (default). The ellipse is drawn around the current turtle position with the Y axis oriented like the turtle. For num-start, num-end set to 0, 360 an ellipse is drawn. For a partial radius the opening is closed by a line resulting in segment shape, i.e. -90, 90 would result in a half circle from the left to the right of the turtle. When num-x-rad and num-y-rad are of equal size a full circle can be drawn. The turtle position or orientation is not changed.

§

ps:fill-color

syntax: (ps:fill-color float-R float-G float-B)
parameter: float-R - The red color value.
parameter: float-G - The green color value.
parameter: float-B - The blue color value.

Set color for shape filling. Color values assume the following value:
    R - value for red 0.0 to 1.0
    B - value for green 0.0 to 1.0
    G - value for blue 0.0 to 1.0
 


syntax: (ps:fill-color str-hex)
parameter: str-hex - A hex string specifying the line color.

In an alternative syntax color values can be specified in a hex string:

str-hex is a hex string constant "000000" to "FFFFFF" Colors are specified as usual in HTML coding. Each two hex digits define a color: rrggbb.

§

ps:font

syntax: (ps:font str-name num-size)
parameter: str-name - The font name.
parameter: num-size - The size of the font in points.

The current font is set for all subsequent text operations. Depending on the version of the Postsrcipt viewer or device installed different fonts are available.

§

ps:goto

syntax: (ps:goto num-x num-y)
parameter: num-x - The new x coordinate.
parameter: num-y - The new y coordinate.

Moves to position num-x, num-y. On a US letter page of 612 by 792 point positions are defined with 72 points per inch. The turtle position is saved on the graphics state stack when using (ps:gsave).

§

ps:grestore

syntax: (ps:grestore)

Restores the graphics state from the stack.

§

ps:gsave

syntax: (ps:gsave)

Saves the current graphics state. The function pushes the current graphics state on a special stack, from where it can be resored using (ps:grestore). States saved are: The turtle position X, Y and orientation and transformation scaling and rotation factors.

§

ps:line

syntax: (ps:line list-of-lists)
parameter: list-of-lists - A list of turtle movements or Bezier curves.

Draw a multipart line. lists are turtle movements (num-dg num-s), or Bezier curves (x1 y1 x2 y2 x3 y3) starting from the last turtle coordinates x0, y0 and finishing at x3, y3. All Bezier coordinates are relative to the previous turtle position and orientation.

The turtle position and orientation are changed after drawing the line.

§

ps:line-cap

syntax: (ps:line-cap num-mode | str-mode)
parameter: mode - The line termination shape mode as a string or number

Sets the line termination shape as either a number or string:
    0 or "butt"
    1 or "round"
    2 or "square"
 


§

ps:line-color

syntax: (ps:line-color float-R float-G float-B)
parameter: float-R - The red color value.
parameter: float-G - The green color value.
parameter: float-B - The blue color value.

Set color for line drawing. Color values assume the following value:
    R - value for red 0.0 to 1.0
    G - value for green 0.0 to 1.0
    B - value for blue 0.0 to 1.0
 


syntax: (ps:line-color str-hex)
parameter: str-hex - A hex string specifying the line color.

In an alternative syntax color values can be specified in a hex string:

str-hex is a hex string constant "000000" to "FFFFFF" Colors are specified as usual in HTML coding. Each to two hex digits define a color: rrggbb.

§

ps:line-join

syntax: (ps:line-join num-mode | str-mod)
parameter: mode - The line join mode.

Sets the line join mode as either a number or string:
    0 or "miter"
    1 or "round"
    2 or "bevel"
 


§

ps:line-width

syntax: (ps:line-width points)
parameter: points - The line width in points.

Sets the line width in points for line drawing and the outlines drawn by shapes and text outlines.

§

ps:move

syntax: (ps:move num-s)
parameter: num-s - The distance to move the pen.

Move the turtle forward distance s without drawing.

§

ps:petal

syntax: (ps:petal num-width num-height [bool-fill])
parameter: num-width - The x1 coordinate of the underlying Bezier curve p0 to p1 p2 p3.
parameter: num-height - The y1 coordinate of the underlying Bezier curve p0 to p1 p2 p3.
parameter: bool-fill - An optional fill flag for color fill.

Draws a petal using a Bezier curve with optional num-fill either true or nil (default). The num-height and num-width parameters are relative to to the current position. The petal is drawn with the tip at the current turtle position and oriented in the direction of the turtle. The turtle position or orientation is not changed.

§

ps:pie

syntax: (ps:pie num-rad num-width [bool-fill])
parameter: num-rad - The radius of the pie.
parameter: num-width - The width of the pie slice as an angle.
parameter: bool-fill - An optional fill flag for color fill, true or nil (default).

Draw a pie slice with optional bool-fill either true or nil (default). The left edge of the pie is in turtle orientation. The width angle spreads clockwise. The pie is drawn around the current turtle position. The turtle position or orientation is not changed.

§

ps:polygon

syntax: (ps:polygon num-rad num-n [bool-fill])
parameter: num-rad - Radius.
parameter: num-n - Number of sides.
parameter: fill - Optional fill flag.

Draw a polygon with radius num-rad and num-n sides. num-fill is true or nil (default) for optional color fill The polygon is drawn around the current turtle position. The turtle position or orientation is not changed.

§

ps:rectangle

syntax: (ps:rectangle num-width num-height [bool-fill])
parameter: num-width - The width of the rectangle.
parameter: num-height - The height of the rectangle.
parameter: bool-fill - An optional flag to draw a filled rectangle.

A rectangle is drawn at the current turtle position. The width of the rectangle will be perpendicular to the turtle orientation. If the turtle never turned or the turtle angle never was set then the width of the rectangle will lie horizontally.

The position or orientation of the turtle will not change.

§

ps:render

syntax: (ps:render [filename])

Without the filename parameter, render creates a file noname.ps and on Mac OS X the file is shown on the monitor using the Mac OS X Preview application.

Specify the filename parameter to save the postscript file and convert and view it using ghostscript from www.ghostscript.com/ and www.cs.wisc.edu/~ghost .



§

ps:rotate

syntax: (ps:rotate num-deg)
parameter: num-deg - The degrees of rotation: -360 to 0 to 360.

Rotate the coordinate space. The coordinate space is rotated to the right for positive angles and to the left for negative angles. The current rotation angle is 0 by default. The rotation angle is part of the graphics state saved by the ps:gsave function and restored by ps:grestore.

§

ps:save

syntax: (ps:save str-filename)
parameter: str-filename - The filename.

Save to str-filename. This function is deprecated use ps:render instead.

§

ps:scale

syntax: (ps:scale num-x num-y)
parameter: num-x - The new x scale factor.
parameter: num-y - The new y scale factor.

Scale the coordinate space. Scaling factors are 1.0 by default and compress for factors less 1.0 or expand for factors bigger than 1.0. With a scaling factor for x = 2.0 each point position specified would cover the double of horizontal distance on the page. Previou scaling factors can be saved on the graphics state stack using the function ps:gsave and restored using ps:grestore.

§

ps:shape

syntax: (ps:shape list-of-num-lists [bool-fill])
parameter: list-of-num-lists - A list of turtle movements and/or Bezier curves.
parameter: bool-fill - An optional fill flag for color fill.

Draws a shape with optional bool-fill or eiher true or nil (default). num-lists is either a turtle movement (degree distance) or a Bezier curve (x1 y1 x2 y2 x3 y3) starting from the last turtle coordinates x0, y0 and finishing at x3, y3. All Bezier coordinates are relative to the previous turtle position and orientation The turtle position or orientation is not changed.

§

ps:text

syntax: (ps:text str-text)
parameter: str-text - The text to draw.

Draws text. (...) parenthesis in text should be escaped with double \\ characters as in in \\( or \\), when limiting the string with double quotes ". When limiting the string with {,} braces a single \ character is enough as in \( and \). Before drawing, a font can be specified, the default font after loading the postscript.lsp modules is Helvetica 12 points and using the current ps:line-color for drawing.

The turtle position is changed to the baseline after the last character. The turtle orientation stays the same.

§

ps:textarc

syntax: (ps:textarc str-text num-rad)
parameter: str-text - The text to draw.
parameter: num-rad - The radius of imaginary circle path for text.

Draw text around a circle. The text is drawn out side of an imaginary circle starting at turtle position and orientation and drawing at the current tangent. For a positive radius text goes outside the circle and clockwise. For a negative radius text goes inside the circle and counter lock wise. The turtle position and orientation move along the radius.

§

ps:textarcoutline

syntax: (ps:textarcoutline str-text num-rad [bool-fill])
parameter: str-text - The text to draw.
parameter: num-rad - The radius of imaginary circle path for text.
parameter: bool-fill - An optional fill flag for color fill.

Draw text around a circle. Same as ps:textarc but the text is drawn as ane outline and can be filled with ps:fill-color when specifying the optional fill flag. The turtle position and orientation move along the radius.

§

ps:textoutline

syntax: (ps:textoutline str-text [bool-fill])
parameter: str-text - The text to draw.
parameter: bool-fill - An optional fill flag for color fill.

Draw a text outline with optional color bool-fill specified by either true or nil (default). Before drawing a font can be specified the default font after loading postscript.lsp is Helvetica 12 points, the text is drawn using the current line color.

The turtle position is changed to the baseline after the last character. The turtle orientation stays the same.

§

ps:textclip

syntax: (ps:textclip str-text)
parameter: str-text - The text used as a clipping shape.

A text outline is used as a clipping path. Before redefining the clipping area (ps:gsave) should be used to save the old graphics state parameters, after clipping and drawing in the clipped area the graphics state should be restored using (ps:grestore). The turtle moves with the text shape clipped.

§

ps:translate

syntax: (ps:translate num-dx num-dy)
syntax: (ps:translate)
parameter: num-dx - Moves the x' origin by 'dx.
parameter: num-y - Move the y' origin by 'dy.

Move the coordinate origin. By default the origin 0,0 is in the bottom left corner of the page. The num-dx and num-dy values extend to the right and top. When no num-x, num-y values are specified the coordinate origin is moved to the current position of the turtle. Previous translation offsets can be saved on the graphics state stack using the function ps:gsave and restored using ps:grestore.

§

ps:turn

syntax: (ps:turn num-dg)
parameter: num-dg - The degrees to turn: -360 to 0 to 360.

Turn the turtle pen by num-dg degrees. The degrees are specified in angles from 0 to 360. For turning clockwise specifiy positive values. Negative degrees turn the turtle pen counter clockwise. The turtle position is aved on the graphics state stack when using (ps:gsave).

- ∂ -

generated with newLISP  and newLISPdoc