postscript.lsp

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.45 - doc corrections
Version: 2.5 - eliminated link to postscript-24.tgz
Version: 2.51 - description of ps:drawto
Author: Lutz Mueller, July 2006, 2009, 2010, 2012, 2013, 2015

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.

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 saved 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 drawing 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: bool-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. On some systems ps:drawto can crash when the current coordinates and the coordinates to draw to are identical.

§

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