canvas.lsp

Module index

source download

Module: canvas.lsp

Routines for creating HTML canvas tag graphics

Version: 1.0 initial release
Version: 1.1 doc changes only
Version: 1.21 doc changes only
Version: 1.3 compatibility pre and post 10.2.0 for new extend
Version: 1.32 doc formatting, spelling
Version: 1.33 took out license
Version: 1.4 cv:petal was broken (JavaScript change?)
Version: 1.44 doc corrections
Version: 1.45 cv:render works on Emscripten newLISP
Version: 1.52 changed Win32 to Windows and spelling
Version: 1.6 sign error in shape caused incompatibility with postscript.lsp
Version: 1.61 eliminated canvas-15.tgz link
Version: 1.7 fixed ellipse, petal, pie, polygon, shape fill first the stroke
Version: 1.71 fixed documentation for cv:clip
Author: Lutz Mueller, March 2009, June 2012, January 2014, 2015

Turtle graphics for the HTML-5 canvas tag

This module generates HTML pages suited for browsers which recognize the HTML-5 canvas tag.

Example program

The following is a simple example how to create an HTML page with one or more embedded graphics.

Example:
 (module "canvas.lsp") ; does a load from standard location

 (cv:html "<h2>First canvas</h2>") ; optional mixed in HTML
 (cv:canvas "FirstCanvas" 300 100) ; required canvas creation
 (cv:fill-color 1.0 0.0 0.0)
 (cv:rectangle 100 80 true) ; one or more drawing statements
 (cv:html "<h2>Second canvas</h2>")

 (cv:canvas "SecondCanvas" 300 100)
 (cv:fill-color 0.0 1.0 0.0)
 (cv:rectangle 200 80 true)
 (cv:render "page.html") ; required rendering of the page
 (exit)
All canvas functions are prefixed with cv and emit the JavaScript code necessary to the <script></script> section in the header section of the HTML page. Only the function html is not prefixed and outputs strings directoy to the <body></body> tagged section of the HTML page.

Example:
 (html "<p>This is a parapgraph of text.</p>")
Sometimes it is necessary to output JavaScript explicity to the script section of the page, e.g. to use canvas features not implemented in this module. This can be done via the cv default functor:

Example:
 (cv "document.write('this is a test');")
Most functions in the canvas cv module work the same as in the older postscript ps modul, and some functions in the postscript module have been changed to achieve more compatibility between both modules. The following example shows how name-space prefix switching can be used to to run a postscript.lsp based program with canvas:

Example:
 (module "canvas.lsp")
 
 (html "<center>")
 (cv:canvas "TheCanvas" 200 200)
 ; reuse postrcipt.lsp code
 (set 'ps cv) ; switch prefix

 (ps:goto 120 132)
 (ps:line-color  1 0 0.6)
 (ps:line-width 3.0)
 (ps:angle 15)
 (dotimes (i 12)
     (cv:turn 30)
     (cv:bezier -20 75 40 75 20 0))
 ; end postscript snippet

 (html "</center>")
 (cv:render "rose.html")
 (exit)
A package with more demo files can be downloaded from www.newlisp.org/canvas/canvas-15.tgz . The demo files assume the Safari (4.0 beta) browser on Mac OS X and Windows or The Firefox browser (3.1. beta 3) on Linux and start the browser automatically. Change the last cv:render line in each of the demo file to manually load the generated page-file spciefied in the cv:render statement.

Using JavaScript directly

Complex graphics with many looping statements can generate huge HTML files which may be slow to load over an internet connection. The newLISP program itself may be small, but the JavaScript it generates may fill hundreds of kilobytes because of repeated output of JavaScript statements. The cv function can be used to to emit JavaScript directly. For most cv:xxx (but not all) -functions a similar named JavaScript function exists in canvas.lsp. The following example generates the same graphic twice, first as a looping newLISP script, then as an explicitly written JavaScript script:

Example:
 (module "canvas.lsp")
 
 (html "<h3>Indirect draw</h3>")
 
 (cv:canvas "CanvasOne" 400 200)
 (cv:line-color 0 0.5 0.5)
 
 (cv:angle -90)
 (dotimes (i 180)
     (cv:goto 200 0)
     (cv:draw 300)
     (cv:turn 1))
 
 (html "<h3>Direct draw</h3>")
 
 (cv:canvas "CanvasTwo" 400 200)
 (cv:line-color 0 0.5 0.5)
 
 (cv [text]
 Angle(-90);
 for(var i = 0; i < 180; i++) {
     Goto(200, 0);
     Draw(300);
     Turn(1);
     }
 [/text])

 (cv:render) ; render page automatically in browser on OS X (Safari 4.0)
 ; as an alternative specify the HTML filename
 (cv:render "direct.html") ; renders to file specified
 (exit)

Differences to the postscript module

Differences between the canvas.lsp and postscript.lsp modules are mainly in the treatment of text colors and fonts.

Summary of functions

Return values from functions are not used when programming with canvas functions and are not mentioned in the documentation.

Turtle coordinate positioning and turning

 cv:goto  - move turtle to position x, y
 cv:move  - move turtle a distance s forward from the current position
 cv:turn  - turn the turtle degress dg left (negative) or right (positive)
 cv:angle - set the turtle orientation to dg degrees

Line drawing

 cv:draw   - draw distance s forward from current position
 cv:drawto - draw to the absolute position x,y from the current position
 cv:line   - draw a multipart line consisting of line and bezier curve segments
 cv:bezier - draw a Bezier curve

Closed shapes, filling and clipping

 cv:rectangle - draw a rectangle
 cv:polygon   - draw a polygon with radius rad and n number of sides
 cv:circle    - draw a circle
 cv:ellipse   - draw an open or closed ellipse with x-rad and y-rad radius
 cv:pie       - draw a pie piece with radius rad and width
 cv:petal     - draw a petal shape from Bezier curves
 cv:shape     - draw a shape defined by a list of line and bezier segments
 cv:clip      - define a clipping path using line and Bezier segments

Text output and clipping

 cv:text           - draw a solid text string
 cv:textoutline    - draw text in outline shape
 cv:textarc        - draw text around an arc
 cv:textarcoutline - draw text in outline shape around an arc

Global settings

 cv:translate  - move coordinate origin
 cv:scale      - scale output
 cv:rotate     - rotate output
 cv:gsave      - save current graphics state (translation, scale, rotation)
 cv:grestore   - restore current graphics state
 cv:font       - set font specifications
 cv:line-witdh - set line width in pixels
 cv:line-cap   - set line termination shape
 cv:line-join  - set line join mode
 cv:line-color - set line color
 cv:fill-color - set fill color

Rendering and output

 cv:render     - render HTML output to CGI or a file


§

cv:angle

syntax: (cv: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 (cv:gsave).

§

cv:bezier

syntax: (cv: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.

§

cv:circle

syntax: (cv: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 cv:fill-color. The circle is drawn around the current turtle position. The turtle position or orientation is not changed.

§

cv:clip

syntax: (cv:clip list-of-lists)
parameter: list-of-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 (cv: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 (cv:grestore). The turtle position or orientation is not changed.

§

cv:draw

syntax: (cv:draw num-s)
parameter: num-s - Distance to draw.

Draw going forward distance num-s. Moves the turtle forward by the amount of pixels specified in num-s and draws with the current line color set by cv:line-color.



§

cv:drawto

syntax: (cv: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 (cv: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.

§

cv:ellipse

syntax: (cv: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.

§

cv:fill-color

syntax: (cv: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: (cv: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.

§

cv:font

syntax: (cv:font str-name)
parameter: str-name - The font name.

The current font is set for all subsequent text operations. Depending on the browser and OS installed, different fonts are available.

Example:
 (cv:font "normal 14px sans-serif") ; Helvetica
 (cv:font "bold 20px serif") ; Times
 (cv:font "italic 32px sans-serif") ; Cursive


§

cv:goto

syntax: (cv: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. The turtle position can be saved on the graphics state stack when using (cv:gsave).

§

cv:grestore

syntax: (cv:grestore)
Restores the graphics state from the stack.

§

cv:gsave

syntax: (cv:gsave)
Saves the current graphics state. The function pushes the current graphics state on a special stack, from where it can be resored using (cv:grestore). States saved are: The turtle position X, Y and orientation, the transformation scaling and rotation factors, the line cap and join value and the colors set.

§

cv:line

syntax: (cv: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.

§

cv:line-cap

syntax: (cv: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"


§

cv:line-color

syntax: (cv: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: (cv: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.

§

cv:line-join

syntax: (cv:line-join num-mode | str-mode)
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"


§

cv:line-width

syntax: (cv:line-width int-pixels)
parameter: int-pixels - The line width in pixels.

Sets the line width in pixels for line drawing and the outlines drawn by shapes and text outlines.

§

cv:move

syntax: (cv:move num-s)
parameter: num-s - The distance to move the pen.

Move turtle the forward distance s without drawing.

§

cv:petal

syntax: (cv: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.

§

cv:pie

syntax: (cv: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.

§

cv:polygon

syntax: (cv: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.

§

cv:rectangle

syntax: (cv: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.

§

cv:render

syntax: (cv:render [HTML-file-name])
parameter: - HTML-file-name Optionam HTML file-name to save to.

On Mac OX X system when using the function without a file-name, the default HTML browser is opened automatically and a temporary file /tmp/noname.html is shown. This is the best mode for interactive development.

On Windows cv:render tries to open c:\Program Files\Safari\Safari.exe. The function cv:render at the end of the source in canvas.lsp can be modified for a different browser.

When a file-name is supplied, then cv:render generates a HTML file. When the file-name is specified as "cgi", then output is directed to standard out. This is useful for writing CGI programs. The CGI program must take care to emit a content-type header first using: 

(print "Content-Type: text/html\r\n\r\n")


§

cv:rotate

syntax: (cv: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 (upwards) by default. The rotation angle is part of the graphics state saved by the cv:gsave function and restored by cv:grestore.

§

cv:scale

syntax: (cv: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. Previou scaling factors can be saved on the graphics state stack using the function cv:gsave and restored using cv:grestore.

§

cv:shape

syntax: (cv: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.

§

cv:text

syntax: (cv:text str-text)
parameter: str-text - The text to draw.

Draws text. Before drawing, a font can be specified, the default font after loading the canvas.lsp modules is the default font of the canvas tag. The text color is the current cv:fill-color.

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

§

cv:textarc

syntax: (cv:textarc str-text num-rad)
parameter: str-text - The text to draw.
parameter: num-rad - The radius of an imaginary circle path for str-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.

§

cv:textarcoutline

syntax: (cv:textarcoutline 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. Same as cv:textarc but the text is drawn as ane outline. The color of the text outline is the current cv:line-color. The turtle position and orientation move along the radius.

§

cv:textoutline

syntax: (cv:textoutline str-text)
parameter: str-text - The text to draw.

Draw a text outline Before drawing a font can be specified the default font after loading canvas.lsp is the font of the HTML canvas tag.

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

§

cv:translate

syntax: (cv:translate num-dx num-dy)
syntax: (cv:translate)
parameter: num-dx - Move the current x-origin by dx.
parameter: num-y - Move the current 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 cv:gsave and restored using cv:grestore.

§

cv:turn

syntax: (cv: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 -380 to 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 (cv:gsave).

- ∂ -

generated with newLISP  and newLISPdoc