plot

An interface to the GNU libplot library.

Usage

(import plot)

Documentation

libplot is a part of the GNU plotutils package. It is a 2-D vector graphics library capable of exporting to many file formats, both vector and raster.

The Chicken plot library provides a Scheme interface to a large subset of the libplot procedures. This interface follows closely the libplot API, so the main reference is the plotutils manual.

In libplot, function names are of the form pl_function_r. The Scheme corresponding function name is function.

Below is a list of procedures that are included in this egg, along with brief descriptions. This egg has been tested with plotutils version 2.6.

Version Information

libplot-versionprocedure: Returns the version string of the underlying libplot library.

Data Types and Constructors

Plotter Types

plotter-typerecord

An algebraic datatype representing the type of plotter to create. Each plotter type corresponds to a different output format. Constructors include:

(X): X Window System display
(PNG): Portable Network Graphics (raster)
(PNM): Portable Anymap format (raster)
(GIF): Graphics Interchange Format (raster)
(SVG): Scalable Vector Graphics (vector)
(AI): Adobe Illustrator format (vector)
(PS): PostScript (vector)
(CGM): Computer Graphics Metafile (vector)
(FIG): XFIG format (vector)
(PCL): HP PCL format
(HPGL): HP-GL/2 format (vector)
(REGIS): ReGIS graphics format
(TEK): Tektronix format
(META): GNU metafile format (vector)

plotter-type? objprocedure: Returns #t if obj is a plotter-type value, #f otherwise.

Plotter Parameters

plotter-parameterrecord

An algebraic datatype representing configuration parameters for plotters. Each constructor takes one or more arguments to specify the parameter value.

Common Parameters (apply to most or all plotter types):

(DISPLAY string): X Window System display name (X plotter only)
(BITMAPSIZE string): Size specification for bitmap plotters (e.g., "800x600")
(PAGESIZE string): Page size for vector plotters (e.g., "letter", "A4", "11x17in")
(ROTATION string): Rotation angle in degrees (e.g., "0", "90", "180", "270")
(BG_COLOR string): Background color name (e.g., "white", "black")
(EMULATE_COLOR boolean): Whether to emulate color on monochrome devices
(MAX_LINE_LENGTH integer): Maximum line segment length for path approximation
(INTERLACE boolean): Whether to use interlaced format (GIF, PNG)
(TRANSPARENT_COLOR string): Color to treat as transparent (GIF, PNG)

Plotter-Specific Parameters:

(CGM_ENCODING string): CGM encoding type ("clear_text" or "binary")
(CGM_MAX_VERSION string): Maximum CGM version (e.g., "1", "2", "3", "4")
(GIF_ANIMATION boolean): Whether to produce animated GIF
(GIF_DELAY integer): Frame delay in hundredths of a second for animated GIFs
(GIF_ITERATIONS integer): Number of times to loop animation (0 = infinite)
(HPGL_ASSIGN_COLORS boolean): Whether to assign pen colors automatically
(HPGL_OPAQUE_MODE boolean): Whether to use opaque drawing mode
(HPGL_PENS string): Number of pens to use
(HPGL_ROTATE string): Rotation angle for HPGL output
(HPGL_VERSION string): HPGL version ("1", "1.5", or "2")
(META_PORTABLE boolean): Whether to use portable metafile format
(PCL_ASSIGN_COLORS boolean): Whether to assign colors automatically
(PCL_BEZIERS boolean): Whether to use native Bezier curve support
(PNM_PORTABLE boolean): Whether to use ASCII (portable) PNM format
(TERM string): Terminal type for display
(USE_DOUBLE_BUFFERING boolean): Whether to use double buffering (X plotter)
(VANISH_ON_DELETE boolean): Whether window vanishes when plotter deleted (X)
(X_AUTO_FLUSH boolean): Whether to flush X display automatically

plotter-parameter? objprocedure: Returns #t if obj is a plotter-parameter value, #f otherwise.

Text Justification

h-justifyrecord

Horizontal text justification. Constructors:

(Left): Left-aligned text
(HCenter): Horizontally centered text
(Right): Right-aligned text

h-justify? objprocedure: Returns #t if obj is a horizontal justification value.

v-justifyrecord

Vertical text justification. Constructors:

(Bottom): Align to bottom of bounding box
(Baseline): Align to text baseline
(VCenter): Vertically centered
(Cap-line): Align to capital letter height
(Top): Align to top of bounding box

v-justify? objprocedure: Returns #t if obj is a vertical justification value.

Line Styles

linetyperecord

Line drawing styles. The following constructors are exported directly as values:

Solid: Solid line
Dotted: Dotted line
Dotdashed: Alternating dots and dashes
Shortdashed: Short dashes
Longdashed: Long dashes

Additional line types (not exported but available via the linetype datatype):

Dotdotdashed: Two dots followed by a dash
Dotdotdotdashed: Three dots followed by a dash
Disconnected: Disconnected line segments

Marker Styles

markerrecord

Point marker styles for plotting discrete points. Constructors:

No-marker: No marker drawn
Dot: Small dot
Plus: Plus sign (+)
Asterisk: Asterisk (*)
Circle: Circle outline
Cross: X-shaped cross
Square: Square outline
Triangle: Upward-pointing triangle
Diamond: Diamond shape
Star: Five-pointed star
Inv-triangle: Downward-pointing triangle
Starburst: Multi-pointed starburst

marker? objprocedure: Returns #t if obj is a marker value.

Line Cap Styles

capmodrecord

Line endpoint cap styles. Constructors:

Butt: Square butt caps (default)
CRound: Rounded caps
Projecting: Projecting square caps
Triangular: Triangular caps

capmod? objprocedure: Returns #t if obj is a cap mode value.

Fill Modes

fillmodrecord

Polygon fill rule modes. Constructors:

Alternate: Alternate winding rule
Winding: Non-zero winding rule

fillmod? objprocedure: Returns #t if obj is a fill mode value.

Join Styles

joinmodrecord

Line segment join styles. Constructors:

Miter: Mitered joins (default)
JRound: Rounded joins
Bevel: Beveled joins

joinmod? objprocedure: Returns #t if obj is a join mode value.

Drawing Direction

directionrecord

Arc and ellipse drawing direction. Constructors:

Clockwise: Draw in clockwise direction
Counterclockwise: Draw in counterclockwise direction

direction? objprocedure: Returns #t if obj is a direction value.

Parameter Management

params-newprocedure: Creates a new plotter parameter structure. This structure must be passed to make-plotter and should be deleted with params-delete after the plotter is created.

params-delete paramsprocedure: Deletes a plotter parameter structure and frees associated resources.

params-copy paramsprocedure: Creates a copy of an existing plotter parameter structure.

param-set params parameterprocedure

Sets a parameter in a plotter parameter structure. The parameter argument must be a plotter-parameter value created with one of the constructors described above.

Example:

(param-set params (PAGESIZE "A4"))
(param-set params (INTERLACE #t))

param-unset params parameterprocedure: Unsets (removes) a parameter from a plotter parameter structure.

Creating and Deleting Plotters

make-plotter type out params #!key errprocedure

Creates and initializes a new plotter.

type: A plotter-type value specifying the output format
out: Output port for plotter graphics data
params: List of plotter-parameter values for configuration
err: Optional error output port (keyword argument)

Returns a plotter object. The parameter list is processed internally, so you don't need to manage the parameter structure manually.

Example:

(define plotter 
  (make-plotter (PNG) 
                (open-output-file "output.png")
                (list (PAGESIZE "A4") 
                      (INTERLACE #t)
                      (BG_COLOR "white"))))

delete-plotter plotterprocedure: Deletes a plotter and frees all associated resources. The plotter should not be used after deletion.

Control Functions

openpl plotterprocedure: Opens a plotter for drawing. This must be called before any drawing operations.

closepl plotterprocedure: Closes a plotter and finalizes output. After closing, openpl can be called again to start a new page or frame.

erase plotterprocedure: Erases the current drawing surface, filling it with the background color.

space plotter x0 y0 x1 y1procedure: Sets the coordinate system using integer coordinates. The rectangle from (x0, y0) to (x1, y1) in user coordinates is mapped to the plotter's drawable region.

fspace plotter x0 y0 x1 y1procedure: Sets the coordinate system using floating-point coordinates. This is the floating-point version of space.

space2 plotter x0 y0 x1 y1 x2 y2procedure: Sets up a coordinate system with an arbitrary affine transformation using integer coordinates. Maps (x0, y0) to the lower-left and (x1, y1) to the lower-right of the drawable region, with (x2, y2) specifying the vertical extent.

fspace2 plotter x0 y0 x1 y1 x2 y2procedure: Floating-point version of space2.

bgcolorname plotter color-nameprocedure: Sets the background color by name (e.g., "white", "black", "red"). Takes effect on the next erase operation.

havecap plotter capabilityprocedure: Tests whether the plotter has a specific capability. Returns #t if the capability is supported, #f otherwise.

flushpl plotterprocedure: Flushes drawing output to the output stream. This is primarily useful for X Window and interactive plotters.

Object Drawing Functions

Lines and Paths

move plotter x yprocedure: Moves the graphics cursor to position (x, y) using integer coordinates without drawing.

fmove plotter x yprocedure: Moves the graphics cursor using floating-point coordinates.

moverel plotter dx dyprocedure: Moves the graphics cursor relative to current position using integer offsets.

fmoverel plotter dx dyprocedure: Moves the graphics cursor relative to current position using floating-point offsets.

cont plotter x yprocedure: Continues the current path by drawing a line segment to (x, y) using integer coordinates.

fcont plotter x yprocedure: Continues the current path using floating-point coordinates.

contrel plotter dx dyprocedure: Continues the current path with a relative line segment using integer offsets.

fcontrel plotter dx dyprocedure: Continues the current path with a relative line segment using floating-point offsets.

line plotter x0 y0 x1 y1procedure: Draws a line segment from (x0, y0) to (x1, y1) using integer coordinates.

fline plotter x0 y0 x1 y1procedure: Draws a line segment using floating-point coordinates.

linerel plotter dx0 dy0 dx1 dy1procedure: Draws a line segment using relative integer coordinates from current position.

flinerel plotter dx0 dy0 dx1 dy1procedure: Draws a line segment using relative floating-point coordinates.

endpath plotterprocedure: Ends the current path, drawing and/or filling it according to current attributes.

endsubpath plotterprocedure: Ends the current subpath within a compound path.

closepath plotterprocedure: Closes the current path by drawing a line segment back to the starting point.

Points

point plotter x yprocedure: Draws a point or marker at (x, y) using integer coordinates.

fpoint plotter x yprocedure: Draws a point or marker using floating-point coordinates.

pointrel plotter dx dyprocedure: Draws a point or marker at a relative position using integer offsets.

fpointrel plotter dx dyprocedure: Draws a point or marker at a relative position using floating-point offsets.

marker plotter x y type sizeprocedure: Draws a marker of specified type and size at (x, y) using integer coordinates. The type should be a marker value.

fmarker plotter x y type sizeprocedure: Draws a marker using floating-point coordinates.

markerrel plotter dx dy type sizeprocedure: Draws a marker at a relative position using integer offsets.

fmarkerrel plotter dx dy type sizeprocedure: Draws a marker at a relative position using floating-point offsets.

Rectangles

box plotter x0 y0 x1 y1procedure: Draws a rectangle from (x0, y0) to (x1, y1) using integer coordinates. The rectangle is drawn and/or filled according to current pen and fill attributes.

fbox plotter x0 y0 x1 y1procedure: Draws a rectangle using floating-point coordinates.

boxrel plotter dx0 dy0 dx1 dy1procedure: Draws a rectangle using relative integer coordinates from the current position.

fboxrel plotter dx0 dy0 dx1 dy1procedure: Draws a rectangle using relative floating-point coordinates.

Circles

circle plotter x y radiusprocedure: Draws a circle centered at (x, y) with the specified radius using integer coordinates.

fcircle plotter x y radiusprocedure: Draws a circle using floating-point coordinates.

circlerel plotter dx dy radiusprocedure: Draws a circle at a position relative to the current point using integer offsets.

fcirclerel plotter dx dy radiusprocedure: Draws a circle at a relative position using floating-point offsets.

Ellipses

ellipse plotter x y rx ry angleprocedure: Draws an ellipse centered at (x, y) with semi-axes rx and ry, rotated by angle degrees, using integer coordinates.

fellipse plotter x y rx ry angleprocedure: Draws an ellipse using floating-point coordinates.

ellipserel plotter dx dy rx ry angleprocedure: Draws an ellipse at a relative position using integer coordinates.

fellipserel plotter dx dy rx ry angleprocedure: Draws an ellipse at a relative position using floating-point coordinates.

Arcs

arc plotter xc yc x0 y0 x1 y1procedure: Draws a circular arc from point (x0, y0) to (x1, y1), with center at (xc, yc), using integer coordinates.

farc plotter xc yc x0 y0 x1 y1procedure: Draws a circular arc using floating-point coordinates.

arcrel plotter dxc dyc dx0 dy0 dx1 dy1procedure: Draws a circular arc using relative integer coordinates.

farcrel plotter dxc dyc dx0 dy0 dx1 dy1procedure: Draws a circular arc using relative floating-point coordinates.

ellarc plotter xc yc x0 y0 x1 y1procedure: Draws an elliptic arc using integer coordinates. The arc is part of the ellipse that would pass through all three specified points.

fellarc plotter xc yc x0 y0 x1 y1procedure: Draws an elliptic arc using floating-point coordinates.

ellarcrel plotter dxc dyc dx0 dy0 dx1 dy1procedure: Draws an elliptic arc using relative integer coordinates.

fellarcrel plotter dxc dyc dx0 dy0 dx1 dy1procedure: Draws an elliptic arc using relative floating-point coordinates.

Bezier Curves

bezier2 plotter x0 y0 x1 y1 x2 y2procedure: Draws a quadratic Bezier curve with control points (x0, y0), (x1, y1), and (x2, y2) using integer coordinates.

fbezier2 plotter x0 y0 x1 y1 x2 y2procedure: Draws a quadratic Bezier curve using floating-point coordinates.

bezier2rel plotter dx0 dy0 dx1 dy1 dx2 dy2procedure: Draws a quadratic Bezier curve using relative integer coordinates.

fbezier2rel plotter dx0 dy0 dx1 dy1 dx2 dy2procedure: Draws a quadratic Bezier curve using relative floating-point coordinates.

bezier3 plotter x0 y0 x1 y1 x2 y2 x3 y3procedure: Draws a cubic Bezier curve with control points (x0, y0), (x1, y1), (x2, y2), and (x3, y3) using integer coordinates.

fbezier3 plotter x0 y0 x1 y1 x2 y2 x3 y3procedure: Draws a cubic Bezier curve using floating-point coordinates.

bezier3rel plotter dx0 dy0 dx1 dy1 dx2 dy2 dx3 dy3procedure: Draws a cubic Bezier curve using relative integer coordinates.

fbezier3rel plotter dx0 dy0 dx1 dy1 dx2 dy2 dx3 dy3procedure: Draws a cubic Bezier curve using relative floating-point coordinates.

Text Labels

label plotter textprocedure: Draws a text label at the current position. The text is positioned according to the current text justification settings.

alabel plotter h-justify v-justify textprocedure

Draws a text label with explicit horizontal and vertical justification. h-justify should be an h-justify value and v-justify should be a v-justify value.

Example:

(alabel plotter (HCenter) (Baseline) "Centered Text")

Attribute-Setting Functions

Colors

color plotter red green blueprocedure: Sets both pen and fill color using RGB values (0-65535 range). This is equivalent to calling both pencolor and fillcolor.

pencolor plotter red green blueprocedure: Sets the pen (drawing) color using RGB values.

fillcolor plotter red green blueprocedure: Sets the fill color using RGB values.

bgcolor plotter red green blueprocedure: Sets the background color using RGB values. Takes effect on next erase operation.

colorname plotter color-nameprocedure: Sets both pen and fill color by name (e.g., "red", "blue", "#FF0000").

pencolorname plotter color-nameprocedure: Sets the pen color by name.

fillcolorname plotter color-nameprocedure: Sets the fill color by name.

Line Attributes

linewidth plotter widthprocedure: Sets the line width in user coordinates using an integer value.

flinewidth plotter widthprocedure: Sets the line width in user coordinates using a floating-point value.

linemod plotter line-typeprocedure

Sets the line style. line-type should be one of the exported line type values: Solid, Dotted, Dotdashed, Shortdashed, or Longdashed.

Example:

(linemod plotter Dotted)

linedash plotter dashes offsetprocedure

Sets a custom dash pattern. dashes is a list of integers specifying dash and gap lengths in user coordinates. offset is an integer offset into the pattern.

Example:

(linedash plotter '(10 5 5 5) 0)  ; long dash, gap, short dash, gap

flinedash plotter dashes offsetprocedure: Sets a custom dash pattern using floating-point values.

capmod plotter cap-styleprocedure: Sets the line cap style. cap-style should be a capmod value.

joinmod plotter join-styleprocedure: Sets the line join style. join-style should be a joinmod value.

fmiterlimit plotter limitprocedure: Sets the miter limit for mitered line joins. The limit is the maximum ratio of miter length to line width before the join is beveled instead.

Fill Attributes

filltype plotter fill-fractionprocedure: Sets the fill level. fill-fraction is an integer from 0 (no fill) to 65535 (solid fill), controlling the density of the fill pattern.

fillmod plotter fill-modeprocedure: Sets the fill rule. fill-mode should be a fillmod value.

Text Attributes

fontname plotter font-nameprocedure: Sets the current font by name (e.g., "Helvetica", "Times-Roman").

fontsize plotter sizeprocedure: Sets the font size in user coordinates using an integer value.

ffontsize plotter sizeprocedure: Sets the font size using a floating-point value.

textangle plotter angleprocedure: Sets the text rotation angle in degrees using an integer value.

ftextangle plotter angleprocedure: Sets the text rotation angle using a floating-point value.

labelwidth plotter textprocedure: Returns the width of a text label in user coordinates as an integer.

flabelwidth plotter textprocedure: Returns the width of a text label in user coordinates as a floating-point value.

Drawing Modes

pentype plotter pen-typeprocedure: Sets the pen type (0 = no drawing, 1 = normal drawing).

orientation plotter directionprocedure: Sets the path orientation. direction should be a direction value.

State Management

savestate plotterprocedure: Saves the current graphics state (colors, line styles, fonts, etc.) onto an internal stack.

restorestate plotterprocedure: Restores the most recently saved graphics state from the internal stack.

Coordinate Transformation Functions

fsetmatrix plotter m0 m1 m2 m3 m4 m5procedure

Sets the transformation matrix directly. The matrix maps user coordinates (x, y) to device coordinates using:

x' = m0*x + m2*y + m4
y' = m1*x + m3*y + m5

fconcat plotter m0 m1 m2 m3 m4 m5procedure: Concatenates (multiplies) the current transformation matrix with the specified matrix.

frotate plotter angleprocedure: Rotates the coordinate system by angle degrees around the origin.

fscale plotter sx syprocedure: Scales the coordinate system by factors sx horizontally and sy vertically.

ftranslate plotter dx dyprocedure: Translates the coordinate system by (dx, dy).

Examples

Basic Example: C Curve

(import plot)

(define (ccurve plotter maxorder dx dy order)
  (if (>= order maxorder)
      (fcontrel plotter dx dy)
      (begin
        (ccurve plotter maxorder
                (* 0.5 (- dx dy))
                (* 0.5 (+ dx dy))
                (+ order 1))
        (ccurve plotter maxorder
                (* 0.5 (+ dy dx))
                (* 0.5 (- dy dx))
                (+ order 1)))))

(define (simple-test plotter max-order)
  (openpl plotter)
  (fspace plotter 0. 0. 1000. 1000.)
  (flinewidth plotter 0.25)
  (pencolorname plotter "blue")
  (erase plotter)
  (fmove plotter 600. 300.)
  (ccurve plotter max-order 0. 400. 0)
  (closepl plotter))

(define (main)
  (print "libplot version: " (libplot-version))
  (let ((plotter (make-plotter (PNG) 
                               (open-output-file "testplot.png") 
                               (list (PAGESIZE "A4") 
                                     (INTERLACE #t)
                                     (X_AUTO_FLUSH #f) 
                                     (META_PORTABLE #t)))))
    (simple-test plotter 5)
    (delete-plotter plotter)))

(main)

Multiple Shapes Example

(import plot)

(define (draw-shapes plotter)
  (openpl plotter)
  (fspace plotter 0.0 0.0 400.0 400.0)
  (erase plotter)
  
  ; Red filled circle
  (pencolorname plotter "red")
  (fillcolorname plotter "pink")
  (filltype plotter 65535)
  (fcircle plotter 100.0 100.0 40.0)
  
  ; Blue dashed rectangle
  (pencolorname plotter "blue")
  (filltype plotter 0)
  (linemod plotter Dashed)
  (flinewidth plotter 2.0)
  (fbox plotter 200.0 50.0 300.0 150.0)
  
  ; Green triangle using path
  (pencolorname plotter "green")
  (fillcolorname plotter "lightgreen")
  (filltype plotter 32767)
  (linemod plotter Solid)
  (fmove plotter 150.0 250.0)
  (fcont plotter 250.0 250.0)
  (fcont plotter 200.0 350.0)
  (closepath plotter)
  (endpath plotter)
  
  ; Text label
  (pencolorname plotter "black")
  (fontname plotter "Helvetica-Bold")
  (ffontsize plotter 16.0)
  (alabel plotter (HCenter) (VCenter) "Shapes Demo")
  
  (closepl plotter))

(define plotter 
  (make-plotter (SVG) 
                (open-output-file "shapes.svg")
                (list (PAGESIZE "letter")
                      (BG_COLOR "white"))))

(draw-shapes plotter)
(delete-plotter plotter)

Animated GIF Example

(import plot)

(define (draw-frame plotter angle)
  (openpl plotter)
  (fspace plotter -150.0 -150.0 150.0 150.0)
  (erase plotter)
  
  (pencolorname plotter "blue")
  (flinewidth plotter 3.0)
  
  ; Rotating line
  (let ((x (* 100.0 (cos angle)))
        (y (* 100.0 (sin angle))))
    (fline plotter 0.0 0.0 x y))
  
  (closepl plotter))

(define (animate frames)
  (let ((plotter (make-plotter (GIF)
                               (open-output-file "animation.gif")
                               (list (BITMAPSIZE "300x300")
                                     (BG_COLOR "white")
                                     (GIF_ANIMATION #t)
                                     (GIF_DELAY 5)
                                     (GIF_ITERATIONS 0)))))
    (do ((i 0 (+ i 1)))
        ((>= i frames))
      (draw-frame plotter (* 2.0 3.14159 (/ i frames))))
    (delete-plotter plotter)))

(animate 36)  ; 36 frames for smooth rotation

Notes

Integer coordinate functions work with fixnums, while floating-point functions (prefixed with f) work with flonums.
Colors can be specified either by name (using X11 color names) or by RGB values in the range 0-65535.
The coordinate system must be set using space or fspace before drawing operations.
Plotters should be properly closed with closepl and deleted with delete-plotter to ensure output is finalized.
For animated GIFs, each call to openpl/closepl creates a new frame.
The fill fraction for filltype ranges from 0 (transparent) to 65535 (opaque/solid).

2.1-2.2: Ported to CHICKEN 5
1.1: Added matchable and datatype as dependencies (thanks to Mario Domenech Goulart)
1.0: Initial release

License

Copyright 2011-2026 Ivan Raikov.

Based on the Ocamlplot library by Olivier Andrieu.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>.

chickadee » plot

Identifier search

TOC »

Contents »