PostScript text Isis software documentation

PostScript text

This library contains functions for generating high-quality anti-aliased text images, and other simple graphics. It uses the the public domain program GhostScript (gs) to render PostScript instructions. If GhostScript is not available on your platform, you cannot use this library. When initialized, GhostScript will run in a separate process, communicating with Isis through pipes. It is important that this task not be killed while your Isis script is running.

GhostScript converts PostScript language commands into bitmaps that can be rendered on a screen or a printer. This library translates text and graphics requests to PostScript and sends them to the GhostScript process which returns a bitmap graphics buffer that contains the rendered image.

Initializing the system

(ps-init) # initialize and return and ps handle (ps-close ps-handle) # terminates the ps handle ps-init starts the GhostScript process and returns a "handle" to that process which must be used in all later PostScript operations. The default font is Times-Roman. Default page sizes and colors are also set at this stage but should be reset immediately if using the low-level operations described later.
(set ps-handle (ps-init))
ps-close terminates the GhostScript process associated with the specified handle and deallocates any associated memory.

High-level commands

(ps-best-text ps-handle text height font quality crop) # last 3 args are optional This high-level function generates a single line of anti-aliased text. It returns a one-channel Isis image containing transparency information for specified text in the specified size and font. This image should be used as the alpha channel when the text is actually used in a composition. After calling this function, you can create an identically-sized RGB image containing a solid color to use as the main color channels for the text.

The returned image is tightly cropped to the text, unless False is passed for the crop argument. The font argument is optional, and defaults to "Times" if it is Null or not given. If the specified font cannot be found, the "nearest" font will be used. Italic or bold faces can be specifed after a hyphen in the string, such as "Times-Italic" or "Times-Bold".

The quality argument is also optional and defaults to 3. It can range between 1 (fastest and worst) and 10 (slowest and best).

Below is an example that generates the alpha channel for a piece of text, creates an solid-colored RGB image for the text, and composites that text into a background image.

# initialize the postscript renderer (set ps-handle (ps-init)) # render the alpha (transparency) channel for a piece of text (set alphaimage (ps-best-text ps-handle "Satyricon" 60 "Times")) # display the alpha channel for fun (set xwin (xwin-create Null Null [100 100] (alphaimage buf-dims))) (xwin-display-image xwin alphaimage) # make a yellowish RGB image that will serve as the text color (set rgbimage (new-standard-image 3 (alphaimage buf-dims))) (image-fill-constant 255 (isolate-channel 0 rgbimage)) (image-fill-constant 200 (isolate-channel 1 rgbimage)) (image-fill-constant 0 (isolate-channel 2 rgbimage)) # make a reddish "background image" to composite the text onto (set outimage (new-standard-image 3 (alphaimage buf-dims))) (image-fill-constant 128 (isolate-channel 0 outimage)) (image-fill-constant 0 (isolate-channel 1 outimage)) (image-fill-constant 0 (isolate-channel 2 outimage)) # composite the text using the alpha (image-composite rgbimage alphaimage outimage) # composite the text # display the result (set xwin2 (xwin-create Null Null [100 200] (outimage buf-dims))) (xwin-display-image xwin2 outimage)

Low-level commands

(ps-setpagesize ps-handle [width height]) # set page size in pixels (ps-setrgbcolor ps-handle [r g b]) # colors are 0.0 < x < 1.0 (ps-setfont ps-handle font-name) # set font face (ps-scalefont ps-handle font-size) # set font size (ps-moveto ps-handle [x y]) # origin (0,0) is bottom left (ps-translate ps-handle [x y]) # translate origin of coord. sys. (ps-rotate ps-handle degrees) # rotate coord. sys. about origin (ps-setcliprect ps-handle [x1 y1 x2 y2]) # set clipping rectangle (ps-showtext ps-handle text) # draws a line of text (ps-showoutline ps-handle text) # draws the outline of text (ps-setlinewidth ps-handle width) # set line width (ps-lineto ps-handle [x y]) # draw line from current pos (ps-curveto ps-handle [x y] [x y] [x y]) # draw Bezier from current pos (ps-arc ps-handle [x y] radius deg1 deg2) # draw arc (ps-render ps-handle) # returns image buffer GhostScript renders everything onto a "page" whose size is specified with ps-setpagesize. Any text or graphics that fall outside of this region will be clipped. All references to sizes and positions are in terms of pixels. Important: The origin is at the lower-left corner. The positive y-axis points upwards (opposite of Isis images).

Calling ps-render returns an RGB Isis image buffer of the current page size which reflects all of the commands sent since the last render command. The returned image should not be freed--it is reused by the rendering engine. Make a separate copy of the image using image-copy if you intend to keep it for later use.

Here are few low-level examples:

# EXAMPLE 1: Flash "Hello World" in changing colors (set width 700) (set height 100) (set winaddr (xwin-create Null "PostScript Test1" Null [width height])) (set engine (ps-init)) (ps-setpagesize engine [width height]) (ps-setrgbcolor engine [1.0 0.0 0.0]) (ps-scalefont engine 135) (while True (begin (ps-setrgbcolor engine [(/ (real (random)) rand-max) (/ (real (random)) rand-max) (/ (real (random)) rand-max)]) (ps-moveto engine [0 0]) (ps-showtext engine "Hello World") (xwin-display-image winaddr (ps-render engine)))) # EXAMPLE 2: A bunch of random arcs and lines.... (set width 300) (set height 300) (set winaddr (xwin-create Null "PostScript Test2" Null [width height])) (set engine (ps-init)) (ps-setpagesize engine [width height]) (ps-moveto engine [0 0]) (ps-lineto engine [100 100]) (ps-setlinewidth engine 5) (ps-curveto engine [200 200] [100 150] [125 125]) (ps-moveto engine [50 200]) (ps-setlinewidth engine 2) (ps-arc engine [50 200] 25 0 300) (set image (ps-render engine)) (xwin-display-image winaddr image) # EXAMPLE 3: make "Hello" in a circle (set width 300) (set height 300) (set winaddr (xwin-create Null "PostScript Test2" Null [width height])) (set engine (ps-init)) (ps-setpagesize engine [width height]) (ps-scalefont engine 40) (ps-moveto engine [(+ (/ width 2) 40) 40]) (set angle 0) (while (< angle 360) (begin (ps-setrgbcolor engine [(/ (real (random)) rand-max) (/ (real (random)) rand-max) (/ (real (random)) rand-max)]) (ps-rotate engine 40) (set angle (+ angle 40)) (ps-showtext engine "Hello"))) (set image (ps-render engine)) (xwin-display-image winaddr image) ## EXAMPLE 4: mesages around the screen (set rand-color (proc (engine) (ps-setrgbcolor engine [(/ (real (random)) rand-max) (/ (real (random)) rand-max) (/ (real (random)) rand-max)]))) (set width 800) (set height 800) (set winaddr (xwin-create Null "PostScript Test3" Null [width height])) (set engine (ps-init)) (ps-setpagesize engine [width height]) (ps-scalefont engine 30) (ps-moveto engine [(+ 125 (/ width 2)) (+ 50 (/ height 2))]) (set angle 90) (while (> angle 0) (begin (ps-rotate engine angle) (rand-color engine) (ps-showtext engine "In Postscript ") (ps-rotate engine angle) (rand-color engine) (ps-showtext engine "it is easy ") (ps-rotate engine angle) (rand-color engine) (ps-showtext engine "to go around ") (ps-rotate engine angle) (rand-color engine) (ps-showoutline engine "the screen! ") (set angle (- angle 1)))) (set image (ps-render engine)) (xwin-display-image winaddr image)

Requirements:
Scripts: (load "postscript.isis")
Other: Uses the Ghostscript (gs) postscript interpreter

Thanks to Chris Dodge and Jeremy Lilley for the contributions to this library.