s9fes-char-graphics

The Scheme 9 from Empty Space character graphics routines, and many extras. Features and API of the original are preserved, just extended.

Extras:

canvas properties
canvas print w/ frame
canvas polyline
canvas i/o
canvas clear, flood, copy, paste, scroll
multiple virtual-canvases
compositing
canvas sub-region (rect)
canvas character random-access is O(1)
canvas record printers

Char Canvas

This is a set of routines for drawing characters and lines on a scaled, character-based (a.k.a. "ASCII Art") canvas.

Assumes one character per column. Do not use wide characters.

Usage

(import (s9fes char-canvas))

make-canvas

make-canvas COLUMNS ROWS #!optional WIDTH HEIGHTprocedure

Creates a character canvas with a physical size of COLUMNS X ROWS characters. The virtual size of the canvas is WIDTH X HEIGHT "pixels".

"Real coordinates" relate to the physical size of the canvas. "Virtual coordinates" are translated to real coordinates by scaling. Both types of coordinates are specified in X/Y notation.

The origin 0/0 is at the lower left corner of the canvas. The new canvas will be filled with (current-plotter-bkgd-char) initially.

new-canvas

new-canvas CANVAS WIDTH HEIGHTprocedure: Creates a canvas, sharing the char-canvas of CANVAS, but with a virtual size of WIDTH X HEIGHT "pixels".

canvas-duplicate

canvas-duplicate CANVASprocedure: Returns a deep-copy of the CANVAS.

canvas-height

canvas? OBJprocedure
canvas-columns CANVASprocedure
canvas-rows CANVASprocedure
canvas-width CANVASprocedure
canvas-height CANVASprocedure

canvas-real-center

canvas-real-center CHAR-CANVASprocedure

Returns the real coordinates center x & y of the CHAR-CANVAS.

Uses a rounding cutoff value of .6, not .5.

canvas-virtual-center

canvas-virtual-center CHAR-CANVASprocedure

Returns the virtual coordinates center x & y of the CHAR-CANVAS.

Uses round.

canvas-real

canvas-real CANVAS X Yprocedure: Returns the real (physical) coordinates for the supplied virtual X Y.

canvas-virtual

canvas-virtual CANVAS X Yprocedure

Returns virtual coordinates for the supplied real (physical) X Y.

Note that canvas-virtual <=> canvas-real is not guaranteed. So this routine is of little use.

canvas-dump

canvas-dump CANVASprocedure

Returns a (vector-of string) that contains the characters written to the canvas. The vector elements are the rows, the string code-points the columns.

Original API, an alias of canvas->vector now.

canvas-print

canvas-print CANVAS #!optional FRAMEprocedure

Prints the CANVAS, one row per line, with an optional frame.

FRAME: (vector char char char char char char char char) ; top/bottom horizontal, top/bottom vertical, corner top left/right & bottom left/right chars; default #(#\- #\- #\| #\| #\+ #\+ #\+ #\+).
FRAME: #t ; use ASCII-FRAME-CHARS.
ASCII-FRAME-CHARS: #(#\- #\- #\| #\| #\+ #\+ #\+ #\+)
THIN-FRAME-CHARS: #(#\─ #\─ #\│ #\│ #\┌ #\┐ #\└ #\┘)
THICK-FRAME-CHARS: #(#\━ #\━ #\┃ #\┃ #\┏ #\┓ #\┗ #\┛)

make-frame-chars

make-frame-chars TOP BTM LFT RGT TOP-LFT TOP-RGT BTM-LFT BTM-RGTprocedure

TOP BTM LFT RGT ; char char char char ; straights
TOP-LFT TOP-RGT BTM-LFT BTM-RGT: char char char char ; corners

string->canvas

string->canvas STRprocedure

Returns a canvas from the line-feed-encoded STR.

STR: string : string w/ embedded #\newline for each row.

with-output-to-canvas

with-output-to-canvas THUNKprocedure

Returns a canvas from the read output of THUNK. Useful for the result capture of other character graphics output as a canvas.

THUNK: (-> void) : writes to current-output-port.

Capture a plot:

(define *data* '(0 1 2 3 4 5 6 7 8 9))
(define data-plot (lambda () (char-plot *data* 'data 7 35 #f)))
(define data-plot-image (canvas->image (with-output-to-canvas data-plot)))

canvas->vector

canvas->vector CANVASprocedure: Converts the CANVAS to a vector, row h-1 to row 0.

canvas->list

canvas->list CANVASprocedure: Converts the CANVAS to a list, row h-1 to row 0.

canvas->string

canvas->string CANVASprocedure: Converts the CANVAS to a string, row h-1 to row 0, delimited by #\newline.

Makes a plotter-configuration.

PLT-CHR: (or false char) ; plot character

canvas-plot

canvas-plot CANVAS X Y #!optional CHARprocedure

Draws the character CHAR at the virtual position X/Y.

Draws a line from the virtual position X/Y to DX/DY using the character CHAR. All arguments must be integers. Lines originating or extending outside of the canvas will be clipped.

canvas-plot-string

canvas-plot-string CANVAS X Y STRINGprocedure: Draws a STRING at virtual position X/Y. When STRING extends beyond the limits of the canvas, it will be clipped.

canvas-plot-line

canvas-plot-line CANVAS X0 Y0 X1 Y1 #!optional CHARprocedure

Plots a line from X0 Y0 to X1 Y1, using CHAR.

X0 Y0 X1 Y1: fixnum ; .
CHAR: char ; drawing character, default (current-plotter-char).

canvas-plot-lines

canvas-plot-lines CANVAS LINES #!optional CONFIGprocedure

LINES: (list-of integer) ; list of line segment x y.
CONFIG: (or false char plotter-configuration) ; drawing pattern, n elements, #f for skip or a char to draw; default is (current-plotter-char).

canvas-draw

canvas-draw CANVAS X Y #!optional CHARprocedure: Draws character CHAR at position X/Y. It uses real coordinates. When the X or Y coordinate is outside of the canvas, CHAR will not be drawn.

canvas-draw-string

canvas-draw-string CANVAS X Y STRINGprocedure: Draws a STRING at position X/Y. It uses real coordinates. When STRING extends beyond the limits of the canvas, it will be clipped.

canvas-draw-line

canvas-draw-line CANVAS X0 Y0 X1 Y1 #!optional CHARprocedure

Draws a line from X0 Y0 to X1 Y1, using CHAR.

X0 Y0 X1 Y1: fixnum ; .
CHAR: char ; drawing character, default (current-plotter-char).

canvas-draw-lines

canvas-draw-lines CANVAS LINES #!optional CONFIGprocedure

LINES: (list-of fixnum) ; list of line segment x y.
CONFIG: (or false char plotter-configuration) ; drawing pattern, n elements, #f for skip or a char to draw; default is (current-plotter-char).

char-canvas-cmap

make-char-canvas COLS ROWS CHAR-OR-CMAPprocedure
char-canvas? OBJprocedure
char-canvas-columns CHAR-CANVASprocedure
char-canvas-rows CHAR-CANVASprocedure
char-canvas-cmap CHAR-CANVASprocedure

Char Canvas Block

Usage

(import (s9fes char-canvas block))

canvas-clear

canvas-clear CANVAS #!optional RGNprocedure

Uses the (current-plotter-bkgd-char) to clear the CANVAS RGN.

RGN: rect : canvas sub-area, default is whole canvas.

canvas-flood

canvas-flood CANVAS FILL #!optional RGNprocedure

Cover the CANVAS RGN with the FILL char.

FILL: char : fill char, default (current-plotter-char).
RGN: rect : canvas sub-area, default is whole canvas.

canvas-scroll

canvas-scroll CANVAS #!optional DX DY RGNprocedure

Scroll the CANVAS RGN.

DX: integer : negative (left) or positive (right)
DY: integer : negative (up) or positive (down)
RGN: rect : canvas sub-area, default is whole canvas.

canvas-copy

canvas-copy CANVAS #!optional RGN TRANSprocedure

Copy the CANVAS RGN, clipping the RGN to fit if necessary.

RGN: rect : canvas sub-area, default is whole canvas.
TRANS: (char char fixnum fixnum) ; transformation function (see canvas-paste)

canvas-paste

canvas-paste CANVAS SOURCE-CANVAS #!optional X Y TRANSprocedure

Paste the SOURCE-CANVAS into CANVAS at lower-left X Y, clipping the SOURCE-CANVAS to fit if necessary.

X: integer : x, default is 0
Y: integer : y, default is 0
TRANS: (char char fixnum fixnum -> char) ; result char is function of source char+index & target+index.

The operation is performed, in the absence of a transformation function, as if (lambda (t s i j) s) was specified, i.e. overwrite.

Example of transform as used by the image shape:

(define ((compositor-alpha #!optional
                           (c (current-plotter-bkgd-char)))
          tc sc i j)
  (if (char=? c sc) tc sc) )

canvas-clear-chars

canvas-clear-chars CANVAS #!optional RGNprocedure

Uses the (current-plotter-bkgd-char) to clear the CANVAS RGN.

RGN: char-rect : canvas sub-area, default is whole canvas.

canvas-flood-chars

canvas-flood-chars CANVAS FILL #!optional RGNprocedure

Fill the CANVAS RGN with the FILL.

FILL: char : fill char, default (current-plotter-char).
RGN: char-rect : canvas sub-area, default is whole canvas.

canvas-scroll-chars

canvas-scroll-chars CANVAS #!optional DX DY RGNprocedure

Scroll the CANVAS RGN.

DX: fixnum : columns negative (left) or positive (right)
DY: fixnum : rows negative (up) or positive (down)
RGN: char-rect : canvas sub-area, default is whole canvas.

canvas-copy-chars

canvas-copy-chars CANVAS #!optional RGN TRANSprocedure

Copy the CANVAS RGN.

RGN: char-rect : canvas sub-area, default is whole canvas.
TRANS: (char char fixnum fixnum) ; transformation function (see canvas-paste)

canvas-paste-chars

canvas-paste-chars CANVAS SOURCE-CANVAS #!optional X Y TRANSprocedure

Paste the SOURCE-CANVAS into CANVAS at lower-left X Y.

X: fixnum : x, default is 0
Y: fixnum : y, default is 0
TRANS: (char char fixnum fixnum) ; transformation function (see canvas-paste)

The returned canvas is the TARGET-CANVAS.

Char Canvas Rectangle

Usage

(import (s9fes char-canvas rect))

Shared Arguments & Types:

X Y: integer integer : position - x (column) & y (row) .
WD HT: integer integer : size - width (columns) & height (rows).

rect-ht

rect X Y WD HTprocedure
rect? OBJprocedure
rect-x RECTprocedure
rect-y RECTprocedure
rect-wd RECTprocedure
rect-ht RECTprocedure

rect-size

rect-spot RECTprocedure
rect-size RECTprocedure

rect-x-end

rect-x-end RECTprocedure: One beyond the canvas horizontal.

rect-y-end

rect-y-end RECTprocedure: One beyond the canvas vertical.

rect-x-min

rect-x-min RECTprocedure: Same as rect-x. For symmetry.

rect-y-min

rect-y-min RECTprocedure: Same as rect-y. For symmetry.

rect-x-max

rect-x-max RECTprocedure: Right-most horizontal coordinate.

rect-y-max

rect-y-max RECTprocedure: Top-most vertical coordinate.

rect-null

rect-nullprocedure: Returns an empty rectangle.

rect-null?

rect-null? OBJprocedure: Is the rectangle empty? (0 rect-wd or rect-ht)

rect-bias

rect-bias RECT DX DYprocedure

Shift the RECT by DX in the horizontal and DY in the vertical. Does not change the size.

DX: integer : negative (left) or positive (right)
DY: integer : negative (up) or positive (down)

rect-scale

rect-scale RECT SX SYprocedure

Grow the RECT by SX in the horizontal and SY in the vertical. Does not change the position.

SX: integer : negative (thin) or positive (widen)
SY: integer : negative (shorten) or positive (lengthen)

rect-inset

rect-inset RECT DX DYprocedure: Returns a rect inside the RECT by the supplied distance DX DY.

rect-outset

rect-outset RECT DX DYprocedure: Returns a rect outside the RECT by the supplied distance DX DY.

rect-reset

rect-reset RECT #!optional X0 Y0procedure: Returns a rect with the supplied origin but size from RECT.

list->rect

list->rect LSprocedure

LS: (list integer integer integer integer)

canvas-rect

canvas-rect CANVASprocedure: Returns a rect from the CANVAS dimensions.

real-rect

real-rect CANVAS RECTprocedure: Returns the rectangle in the real (physical) coordinate system.

virtual-rect

virtual-rect CANVAS RECTprocedure: Returns the rectangle in the virtual coordinate system.

rect-area

rect-area RECTprocedure: Returns the size of the rectangle.

rect-smaller?

rect-smaller? RECT1 RECT2procedure

rect-larger?

rect-larger? RECT1 RECT2procedure

rect-relates

rect-relates RECT1 RECT2procedure

Returns a, possibly empty, list of symbols describing the spatial relationship of RECT1 & RECT2.

left right: x
above below: y
thinner wider: width
shorter taller: height

rect-union

rect-union RECT1 RECT2procedure: Returns the encompassing rectangle of RECT1 & RECT2.

rect-intersection

rect-intersection RECT1 RECT2procedure: Returns the overlapping rectangle of RECT1 & RECT2, which may be empty.

rect-overlaps?

rect-overlaps? RECT1 RECT2procedure: Does RECT1 intersect RECT2?

Char Plot

Usage

(import (s9fes char-plot))

char-plot

char-plot LIST SYMBOL HEIGHT WDITH #!optional COMPR?procedure

Creates a character canvas (see make-canvas), marks the data points in LIST with #\X and draws a line through the points with #\-. SYMBOL will be used to label the X axis (on which the data points will be distributed).

HEIGHT and WDITH specify the physical dimensions of the char canvas. Its virtual dimensions will be computed in such a way that all data points can be displayed.

When the COMPR? (compression) argument is set to #t, then the X axis will start at the magnitude of the least data point instead of zero, so that the entire width of the canvas is available for distributing the supplied data points. The default is #t.

(char-plot '(0 1 2 3 4 5 6 7 8 9) 'foo 7 35 #f)</procedure>
;=>
----------- foo --> -----------------
|                              -X   |
|                          --X-     |
|                   --X--X-         |
|                -X-                |
|         -X---X-                   |
|     --X-                          |
|X--X-                              |
----------- foo --> -----------------

Draw Tree

Usage

(import (s9fes draw-tree))

draw-tree

draw-tree ROOT #!optional MAX-WIDTHprocedure

Draws a character graphic representation of the tree LIST on (current-output-port).

ROOT: pair ; tree root node.
MAX-WIDTH: fixnum ; maximum printed node width, in characters. default is 7.

(draw-tree '((a) (b . c) (d e)))
;=>
[o|o]---[o|o]---[o|/]
  |       |       |
[o|/]     |     [o|o]---[o|/]
  |       |       |       |
  a       |       d       e
          |
        [o|o]---  c
          |
          b

Polygon

Usage

(import (s9fes polygon))

circle-polygon-lines

(circle-polygon-lines X0 Y0 RADIUS [N [ANGLE]) -> (list-of integer)procedure

Returns a list of coordinates suitable for use w/ *-plot-lines. A closed, convex, polygon is described.

X0 Y0: integer integer ; circle center in virtual coordinates
RADIUS: integer ; circle radius in virtual coordinates
N: fixnum ; number of points ; default 360
ANGLE: fixnum ; starting degree ; default 0

(import (s9fes char-canvas) (s9fes polygon))

(let ((cv (make-canvas 10 10 100 100)))
  (canvas-plot-lines cv (circle-polygon-lines 50 50 50))
  (canvas-print cv) )
;=>
  ******
 *      *
*        *
*        *
*        *
*        *
*        *
*        *
 *      *
  ******

Note how restricting the number of segments coarsens the image, even clipping. ((circle-polygon-lines 50 50 49 4) produces an ok diamond.)

(let ((cv (make-canvas 10 10 100 100)))
  (canvas-plot-lines cv (circle-polygon-lines 50 50 50 4))
  (canvas-print cv #t) )
;=>
+----------+
|    * *   |
|   *   *  |
|  *     * |
| *       *|
|*         |
| *       *|
|  *    ** |
|  *   *   |
|   * *    |
|    *     |
+----------+

Bugs & Limitations

None. A thing of beauty.

Notes

The plot/virtual API with the draw/real distinction follows the original pattern. However, except as implementation details, using the draw/real is unlikely to be worth the effort. For performance have pixels always be chars: don't specify a virtual canvas size.

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Version history

1.21.0: Add canvas-real-center & canvas-virtual-center.
1.20.1: .
1.20.0: Add circle-polygon-lines.
1.19.2: .
1.19.1: Fix for CHICKEN 6.
1.19.0: Add rect-spot & rect-size.
1.18.0: Add plot-config.
1.17.1: Actually remove format dependency.
1.17.0: Remove format dependency.
1.16.3: Add frame-chars?.
1.16.2: Add rect-inset, rect-outset, rect-reset.
1.16.1: Add make-frame-chars.
1.16.0: Move shapes to the s9fes-char-canvas-shapes) egg.
1.15.5: Rename canvas->rect => canvas-rect. Move block operations to (s9fes char-canvas block).
1.15.4: Shape info is a vector, Add info helper syntax: ^info, ^info-real, ^info-virtual, @info-class, @info-coords, @info.
1.15.3: Fix shape-cardinality & shape-elements.
1.15.2: Add registered-shape-methods, shape-cardinality, shape-elements, shape-layout, shape-show, shape-fold
1.15.1: Shape configuration information includes kind & coordinate-system. Add (s9fes char-canvas shape shape) & shape-size.
1.15.0: Remove (draw|plot)-(box|image|circle. {Rename icon' to image''.(s9fes char-canvas shape icon) => (s9fes char-canvas shape image), shape-icon => shape-image.
1.14.6: Rename oval to circle: (s9fes char-canvas shape oval) => (s9fes char-canvas shape circle), shape-oval => shape-circle.
1.14.5: Rename shape- => real-shape- & virtual-shape- to shape-.
1.14.4: Rename physical to real. Add virtual-rect.
1.14.3: Add copy & paste clipping.
1.14.2: Add canvas && char-canvas record printers. Better "too big" paste error.
1.14.1: Add canvas->image & canvas-duplicate.
1.14.0: Add "compositing" to canvas-copy, canvas-paste]canvas-copy-chars, canvas-paste-chars], shape-image, & shape-image.
1.13.0: Add (s9fes char-canvas shape image) module.
1.12.1: Fix box shape plotter position.
1.12.0: Rename to (s9fes char-canvas rect). Add rect-null, rect-null?, rect-area, rect-overlaps?, rect-union, rect-intersection, rect-smaller?, rect-larger?, rect-relates.
1.11.0: Add string->canvas & with-output-to-canvas. canvas-print takes optional frame (remove canvas-print/frame). Add (s9fes char-canvas shape box).
1.10.0: Add canvas-print/frame, new-canvas, canvas-flood, canvas-scroll, canvas-copy, canvas-paste, canvas-flood-chars, canvas-scroll-chars, canvas-copy-chars, canvas-paste-chars, canvas->list, canvas->vector. Add (s9fes rect) module. Add shape introspection.
1.9.1: shape-oval & shape-oval proper shapes (optional center).
1.9.0: Add shape-oval & shape-oval.
1.8.1: Fix (s9fes char-canvas shape cross) naming, again.
1.8.0: Fix (s9fes char-canvas shape cross) naming.
1.7.1: Smaller.
1.7.0: Fix shape-point-plotter, takes center, not top-left. Add cross-x-drawer & cross-+-drawer.
1.6.0: Add canvas-draw-line & canvas-draw-lines.
1.5.0: .
1.4.4: Prevent division-by-zero in canvas-plot-line.
1.4.3: .
1.4.2: .
1.4.1: .
1.4.0: Add current-plotter-char, shape oval & shape cross.
1.3.2: Fix octant stream.
1.3.1: Fix canvas? type.
1.3.0: Add generate-circle-octant & friends.
1.2.0: Add canvas-plot-string.
1.1.0: Add canvas-print, canvas-physical, canvas-virtual.
1.0.1: .
1.0.0: Initial release.

License

Public Domain

chickadee » s9fes-char-graphics

Identifier search

TOC »

Contents »