source download ## postscript.lsp

## 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 followingloadstatement 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.pson 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.psfile for the first time. Subsequent views of.psdocuments are fine.

On Linux/UNIX systems the following command can be used to convert a.psfile to ags -sDEVICE=pdfwrite -dBATCH -sOutputFile=aFile.pdf -r300 aFile.psMost functions work like inturtle graphicsrelative 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 tox': 612, 'y: 792, 72 points for each inch. The functionsps:transposeandps:scalecan be used to move the origin pointor scale from points to other measurements.x=0, y=0

Return value fromps:xxxfunctions 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 lastps:renderstatement 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:anglenum-dg)

parameter:num-dg- Angle degrees from 0 to 360.

Set the turtle angle tonum-dgdegrees. 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:beziernum-x1num-y1num-x2num-y2num-x3num-y3)

parameter:-num-x1,num-y1Bezier coordinates ofp1relative top0= 0,0

parameter:-num-x2,num-y2Bezier coordinates ofp2relative top0= 0,0

parameter:-num-x3,num-y3Bezier coordinates ofp3relative top0= 0,0

Draw a Bezier curve. The Bezier curve starts at pointp0which is the current turtle position and stops at pointp3which is at offsetnum-x3andnum-y3relative to starting point. The turtle orientation after the drwaing the Bezier curve is perpendicular to the Bezier curve baselinep0top3and the position isp3.§

## ps:circle

syntax: (ps:circlenum-rad[bool-fill])

parameter:num-rad- Radius of the circle.

parameter:num-fill- Optional fill flag.

Draw a circle with radiusnum-rad. The optionalnum-fillflag with eithertrueornil(default) indicates if the circle is filled with the fill color specified byps:fill-color. The circle is drawn around the current turtle position. The turtle position or orientation is not changed.§

## ps:clip

syntax: (ps:cliplist-of-num-lists)

parameter:list-of-num-lists- A list of turtle movements and/or Bezier curves.

Define a clipping path using turtle movements (degreedistance) and

Bezier curves (x1y1x2y2x3y3) starting from the last turtle coordinatesx0,y0and finishing atx3,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:drawnum-s)

parameter:num-s- Distance to draw.

Draw going forward distancenum-s. Moves the turtle forward by the amount of points specified innum-sand draws with the current line color set byps:line-color.

§

## ps:drawto

syntax: (ps:drawtoxy)

parameter:x- The x coordinate to draw to.

parameter:y- The y coordinate to draw to.

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

## ps:ellipse

syntax: (ps:ellipsenum-x-radnum-y-radnum-startnum-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 optionalbool-filleithertrueornil(default). The ellipse is drawn around the current turtle position with the Y axis oriented like the turtle. Fornum-start,num-endset 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. Whennum-x-radandnum-y-radare of equal size a full circle can be drawn. The turtle position or orientation is not changed.§

## ps:fill-color

syntax: (ps:fill-colorfloat-Rfloat-Gfloat-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-colorstr-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-hexis 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:fontstr-namenum-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:gotonum-xnum-y)

parameter:num-x- The new x coordinate.

parameter:num-y- The new y coordinate.

Moves to positionnum-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:linelist-of-lists)

parameter:list-of-lists- A list of turtle movements or Bezier curves.

Draw a multipart line.listsare turtle movements (num-dgnum-s), or Bezier curves (x1y1x2y2x3y3) starting from the last turtle coordinatesx0,y0and finishing atx3,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-capnum-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-colorfloat-Rfloat-Gfloat-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-colorstr-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-hexis 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-joinnum-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-widthpoints)

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:movenum-s)

parameter:num-s- The distance to move the pen.

Move the turtle forward distanceswithout drawing.§

## ps:petal

syntax: (ps:petalnum-widthnum-height[bool-fill])

parameter:num-width- Thex1coordinate of the underlying Bezier curvep0top1p2p3.

parameter:num-height- They1coordinate of the underlying Bezier curvep0top1p2p3.

parameter:bool-fill- An optional fill flag for color fill.

Draws a petal using a Bezier curve with optionalnum-filleithertrueornil(default). Thenum-heightandnum-widthparameters 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:pienum-radnum-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,trueornil(default).

Draw a pie slice with optionalbool-filleithertrueornil(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:polygonnum-radnum-n[bool-fill])

parameter:num-rad- Radius.

parameter:num-n- Number of sides.

parameter:fill- Optional fill flag.

Draw a polygon with radiusnum-radandnum-nsides.num-fillistrueornil(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:rectanglenum-widthnum-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,rendercreates a filenoname.psand on Mac OS X the file is shown on the monitor using the Mac OS X Preview application.

Specify thefilenameparameter 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:rotatenum-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 theps:gsavefunction and restored byps:grestore.§

## ps:save

syntax: (ps:savestr-filename)

parameter:str-filename- The filename.

Save tostr-filename. This function is deprecated useps:renderinstead.§

## ps:scale

syntax: (ps:scalenum-xnum-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 functionps:gsaveand restored usingps:grestore.§

## ps:shape

syntax: (ps:shapelist-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 optionalbool-fillor eihertrueornil(default).num-listsis either a turtle movement (degreedistance) or a Bezier curve (x1y1x2y2x3y3) starting from the last turtle coordinatesx0,y0and finishing atx3,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:textstr-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 thepostscript.lspmodules is Helvetica 12 points and using the currentps:line-colorfor drawing.

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

## ps:textarc

syntax: (ps:textarcstr-textnum-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:textarcoutlinestr-textnum-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 asps:textarcbut 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:textoutlinestr-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 colorbool-fillspecified by eithertrueornil(default). Before drawing a font can be specified the default font after loadingpostscript.lspis 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:textclipstr-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:translatenum-dxnum-dy)

syntax: (ps:translate)

parameter:num-dx- Moves thex' origin by 'dx.

parameter:num-y- Move they' origin by 'dy.

Move the coordinate origin. By default the origin 0,0 is in the bottom left corner of the page. Thenum-dxandnum-dyvalues extend to the right and top. When nonum-x,num-yvalues 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 functionps:gsaveand restored usingps:grestore.§

## ps:turn

syntax: (ps:turnnum-dg)

parameter:num-dg- The degrees to turn: -360 to 0 to 360.

Turn the turtle pen bynum-dgdegrees. 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