CvsGraphCtx3D Reference Manual

CvsGraphCtx3D coordinate system

The coordinate system is left handed, +ve X to the right of the canvas, +ve Y up the canvas and +ve Z into the canvas. The canvas lies in the XY plane i.e at Z=0. The viewpoint is at a user defined distance from the canvas on the Z axis i.e. at (0, 0, -viewpointDistance).

All axes have the same scale factor. The default scaling sets the width (X span) of the canvas to be 100 units, therefore default Y span is set by the aspect ratio of the canvas element Yspan = 100 / canvas aspect-ratio. The origin (0, 0, 0) is at the bottom left of the canvas. A user defined scale can be set by the command setWorldCoords3D(LowerLeftX, LowerLeftY, Xspan). The Z axis is 0 in the plane of the canvas.

Creating a CvsGraphCtx3D graphics context

To start creating a 3D object and then drawing it onto the canvas, an instance of the CvsGraphCtx3D graphics context must be created. This requires the canvas element to exist in the web page and for it to have a unique ID. Then call the CvsGraphCtx3D constructor passing the canvas ID as the parameter as follows:

 var g = new CvsGraphCtx3D('canvasID');

The variable g now holds a reference to a CvsGraphCtx3D object. g has the properties and drawing methods listed below.

CvsGraphCtx3D properties

Syntax:

var value = cvsCtx.property;

Properties:

ctx:CanvasRenderingContext2D - the canvas 2D drawing context.

aRatio:Number - Aspect ratio of the canvas element, the canvas width divided by canvas height. If the canvas is square, aRatio=1, if canvas is 300 pixels wide and 200 pixels high, aRatio=1.5.

penWid:Number - Current width of the drawing pen measured in screen pixels. All stroked lines will be rendered in this width until a call to setPenWidth changes the pen width.

penCol:String - Current color for drawing. The returned string will be in the "rgba(r, g, b, a)" format where r is the value (0 to 255) of the red component of the pen color, g is the green component, b is the blue component and a is the alpha or transparency component (0 to 1.0). The default color is black "rgba(0, 0, 0, 1.0)".

viewpointDistance:Number - The location of the viewpoint for perspective projection is always along the -ve Z axis a distance viewpointDistance from the origin, i.e. {x:0, y:0, z:-viewpointDistance}. The default value is 500

lightSource:Object - {x:, y:, z:} Defines a direction in user coordinates by the vector starting at the origin and pointing in the direction {x:, y:, z:}.

CvsGraphCtx3D methods

clearCanvas,
setPenColor, setPenWidth
setWorldCoords3D,
setViewpointDistance, setLightSource
polyLine3D, polygon3D, svgPath3D, rect3D, arc3D, text3D,
renderPath3D,
groupPaths, groupClosedPaths, groupByRotation,
rotateGroup3D, translateGroup3D, resetTransformGroup3D
renderGroup3D, wireframeGroup3D.

clearCanvas

Syntax:

cvsCtx.clearCanvas(fillColor:String);

Description:

Fills the canvas with the color fillColor.

Parameters:

fillColor:String - The fill color to be used. The fill color may be expressed in any of the four canvas color formats:
- Hex notation "#rrggbb", where rr sets the red level (00 to ff), gg sets the green and bb sets the blue level.
- RGBA notation "rgba(r, g, b, a)" where r, g and b are decimal numbers in the range 0 to 255 representing the red, green and blue levels respectively and a is the alpha or transparency value 0 (transparent) to 1.0 (opaque).
- RGB notation "rgb(r, g, b)" where r, g and b are decimal numbers in the range 0 to 255 representing the red, green and blue levels respectively.
- Predefined colors names eg. "red", "blue", "maroon", "palegoldenrod", "wheat" etc. There are 140 standard color names in the extended color list.

If clearCanvas is called with no parameter passed, the canvas is filled with the canvas element's current style background-color value. If no style has been set the default is 'transparent'.

setWorldCoords3D

Syntax:

cvsCtx.setWorldCoords3D(lowerLeftX:Number, lowerLeftY:Number, spanX:Number)

Description:

Defines a world coordinate system for subsequent drawing operations with this graphics context. The world coordinate system sets translation and scaling factors to map world coordinate values to canvas drawing pixel values. This is done by setting the world coordinate values of the lower left corner of the canvas and the width of the canvas. The 3D space represented on the canvas has equal scaling factors in the x, y and z directions so setting the span of the canvas X dimension is sufficient to set all scaling factors. The coordinates of the lower left corner are sufficient to set the origin of the coordinate system (which may not be visible on the canvas) no Z coordinate value is needed as the canvas is considered to be in the X,Y plane i.e.z=0 for all points on the canvas. X axis is always +ve to the right, Y axis is +ve up the screen and Z axis is +ve into the screen.

Parameters:

lowerLeftX:Number - World X coordinate value of the lower left corner of the canvas.

lowerLeftY:Number - World Y coordinate value of the lower left corner of the canvas.

spanX:Number - The world coordinate value of the width of the canvas.

If setWorldCoords3D is called with no parameter passed, or not called at all, the world coordinate system is set to have the canvas lowerLeft=0,0 and spanX = 100.

setPenColor

Syntax:

cvsCtx.setPenColor(color:String)

Description:

Sets the color for drawing operations where the object being drawn does not have its color property defined to a valid RGBA string. The color is stored as the property cvsCtx.penCol.

Parameters:

color:String - The color to be used. The color may be expressed in any of the four canvas color formats:
- Hex notation "#rrggbb", where rr sets the red level (00 to ff), gg sets the green and bb sets the blue level.
- RGBA notation "rgba(r, g, b, a)" where r, g and b are decimal numbers in the range 0 to 255 representing the red, green and blue levels respectively and a is the alpha or transparency value 0 (transparent) to 1.0 (opaque).
- RGB notation "rgb(r, g, b)" where r, g and b are decimal numbers in the range 0 to 255 representing the red, green and blue levels respectively. This is a suitable format for entering dynamic color values. The calculated r, g and b values may be passed to drawing methods by the string "rgb("+r+","+g+","+b+")".
- Predefined colors names eg. "red", "blue", "maroon", "palegoldenrod", "wheat" etc. There are 140 standard color names in the extended color list.

If no call is made to setPenCol the default pen color is black ("#000000").

setPenWidth

Syntax:

cvsCtx.setPenWidth(width:Number)

Description:

Sets the line width for subsequent stroked drawing. The width is stored as the property cvsCtx.penWid.

Parameters:

width:Number - Pen width, measured in canvas drawing pixels. Drawing pixels are mapped 1 to 1 with screen pixels unless the display has been zoomed by the user.

If no call is made to setPenWid the default pen width is 1.

setViewpointDistance

Syntax:

cvsCtx.setViewpointDistance(d:Number)

Description:

Sets the location of the viewpoint for all subsequent rendering on the canvas. The 3D objects are projected onto the 2D canvas with perspective determined by the viewpoint. The viewpointDistance, measured in user units (see setWorldCoords3D) from the origin along the -ve Z axis. If no call is made to setViewpointDistance the default value is 500.

Parameters:

d:Number - viewpoint distance.

setLightSource

Syntax:

cvsCtx.setLightSource(x:Number, y:Number, z:Number)

Description:

Defines a direction in 3D space by the vector starting at the origin and pointing in the direction {x:, y:, z:}. Shading of rendered Path3D objects is determined by the dot product of the light source vector and each Path3D.normal. If no call is made to setLightSource the default value is {x:0, y:100, z:0}.

Parameters:

x:Number - X coordinate of the light source direction vector measured in world coordinates.

y:Number - Y coordinate.

z:Number - Z coordinate.

polyLine3D

Syntax:

cvsCtx.polyLine3D(data:Array, fillColor:String)

Description:

Draws a multi-segment path in the X,Y plane, represented by the coordinate pairs stored in the array data. The first segment of the path is defined by a 'moveTo' the first point, which has 2D coordinates: data[0], data[1] and then a 'lineTo' is drawn to each successive point defined by successive pairs of points in the data array. The Path3D returned has all the line segments coordinates stored as 3D values initially all z coordinate values are set to 0.

Parameters:

data:Array - An array of x,y values measured in world coordinates. The x,y data pairs should be stored as a one dimensional array where every second value represents an x coordinate and every other value represents a y coordinate: data = [x0, y0, x1, y1, x2, .... ]. In this format, n data points are held in an array with 2*n elements (n = data.length/2).

fillColor:String (optional) - Fill color, if present the Path3D created will be filled with this color. fillColor may be expressed in any of the three HTML/CSS color formats (see setPenColor). If fillColor parameter is omitted the Path3D 'closed' property is set 'false' so that the path is rendered as a wireframe in the current pen color.

Returns:

Path3D - with properties defining the polyline which can be moved in 3D space and rendered to the canvas.

polygon3D

Syntax:

cvsCtx.polygon3D(data:Array, fillColor:String)

Description:

Draws a multi-segment line represented by the coordinate pairs stored in the array data. The first segment of the path is defined by a 'moveTo' the first point, which has coordinates data[0], data[1] and then a 'lineTo' is drawn to each successive point defined by successive pairs of points in the data array. The last point is then joined to the first by a 'lineTo' command ensuring the path formed is closed. The path returned has the 'closed' property set true regardless of whether the optional fillColor parameter was defined.

Parameters:

fillColor:String (optional) - Fill color, if present the polygon3D is filled with this color. The fill color may be expressed in any of the three HTML/CSS color formats (see setPenColor). If fillColor parameter is omitted the polygon3D is filled with the current pen color.

Returns:

Path3D - with properties defining the polygon which can be moved in 3D space and rendered to the canvas.

svgPath3D

Syntax:

cvsCtx.svgPath3D(svgData:String, x:Number, y:Number, scale:Number, fillColor:String)

Description:

Draws a shape whose outline comprises a set of segments each specified in the SVG Path element syntax. The path is initially defined in as a 2D figure in the X,Y plane (z=0). The shape is created with x, and y added to each x and y coordinate embedded in the svgData string. If the svgData string has been copied from an SVG drawing application such as 'Inkscape', the svgData coordinates will be referenced to the top left of the drawing screen, not ideal for this 3D environment. The x, y parameters allow a new reference point for the path to be set. Typically setting x and y to the -ve values of svgData's initial 'M' (moveTo) command will place the reference point at the 'M' coordinates. If the svgData has been manually encoded it will probably have a useful reference point in which case x and y can be set to 0. The shape's width and height may be scaled by a factor scale. If the optional fillColor is specified then the shape closed and is filled with that color when rendered. If fillColor is omitted then the Path3D closed property is set false so the path is drawn as a wireframe.

Parameters:

svgData:String - A string holding the drawing instructions for the path. The string data is in the format of the SVG path d="(path data)" attribute, where the d attribute contains the 'M' (moveto), 'L' (lineto), 'C' (cubic Bezier) etc instructions followed by their respective coordinate pairs.

x:Number - X coordinate of the point at which the SVG path drawing origin is to be positioned, measured in the SVG coordinates in which it was originally drawn.

y:Number - Y coordinate of the point at which the SVG path drawing origin is to be positioned, measured in the SVG coordinates in which it was originally drawn.

scale:Number - The scale factor, greater than 0, by which all SVG path coordinates will be multiplied. This parameter allows the shape defined by the SVG path to be stretched or shrunk as required. The same scale factor is applied to both x and y coordinates.

fillColor:String - Optional fill color. If present the shape defined by the path is filled with this color. The fill color may be expressed in any of the four canvas color formats:
- Hex notation "#rrggbb", where rr sets the red level (00 to ff), gg sets the green and bb sets the blue level.
- RGBA notation "rgba(r, g, b, a)" where r, g and b are decimal numbers in the range 0 to 255 representing the red, green and blue levels respectively and a is the alpha or transparency value 0 (transparent) to 1.0 (opaque).
- RGB notation "rgb(r, g, b)" where r, g and b are decimal numbers in the range 0 to 255 representing the red, green and blue levels respectively. This is a suitable format for entering dynamic color values. The calculated r, g and b values may be passed to drawing methods by the string "rgb("+r+","+g+","+b+")".
- Predefined colors names eg. "red", "blue", "maroon", "palegoldenrod", "wheat" etc. There are 140 standard color names in the extended color list.

Returns:

Path3D - with properties required to manipulate and render the 3D path.

rect3D

Syntax:

cvsCtx.rect3D(x:Number, y:Number, w:Number, h:Number, fillColor:String)

Description:

Creates a Path3D object representing a rectangle. The rectangle is defined as a 2D rectangle in the X,Y plane with lower left corner at x, y with width w, and height h.

Parameters:

x:Number - X coordinate of the lower left corner of the rectangle measured in world coordinates.

y:Number - Y coordinate of the lower left corner of the rectangle measured in world coordinates.

w:Number - Width of the rectangle measured in world coordinates.

h:Number - Height of the rectangle measured in world coordinates.

fillColor:String (optional) - Fill color, if present the rectangle is filled with this color. The fill color may be expressed in any of the three HTML/CSS color formats (see setPenColor).

If fillColor parameter is omitted the Path3D.closed property is set false so that the rectangle is rendered as a wireframe in the current pen color.

Returns:

Path3D - with properties required to manipulate and render the rectangle.

arc3D

Syntax:

cvsCtx.arc3D(cx:Number, cy:Number, r:Number, startAngle:Number, endAngle:Number, antiClockwise:Boolean, fillColor:String)

Description:

Creates a Path3D object that draws an arc in 3D. The arc is specified as a segment of the circumference of a circle in the X,Y plane (z=0) with center at cx, cy and radius r. The segment of the circle is defined by the startAngle and endAngle parameters measured in degrees anti-clockwise from the X axis. The direction of the arc is traversed to get to the endAngle is anti-clockwise if parameter antiClockwise is true otherwise the arc is traversed clockwise. If fillColor is specified the arc is closed by a straight line from the start point to the end point, the arc will be filled with fillColor. If fillColor is omitted the arc is drawn as a wireframe in the current pen color.

Parameters:

cx:Number - X coordinate of the center of the circular arc measured in world coordinates.

cy:Number - Y coordinate of the center of the circular arc measured in world coordinates.

r:Number - Radius of the circle of which the arc is a section, measured in world coordinates.

startAngle:Number - Start angle measured in degrees from the X axis.

endAngle:Number - End angle measured in degrees from the X axis.

antiClockwise:Boolean - If true then the arc is drawn starting at the 'startAngle' and traversing the circumference of the circle anti-clockwise to the 'endAngle', otherwise the arc is traversed clockwise.

fillColor:String (optional) - Fill color, if present the rectangle is filled with this color. The fill color may be expressed in any of the three HTML/CSS color formats (see setPenColor).

If fillColor parameter is omitted the Path3D.closed property is set false so that the rectangle is rendered as a wireframe in the current pen color.

Returns:

Path3D - with properties required to manipulate and render the arc.

text3D

Syntax:

cvsCtx.text3D(str:String, x:Number, y:Number, lorg:Number, fontSize:Number, color:String)

Description:

Creates a Path3D object representing the text string str in stroked font. The text object is initially in the X,Y plane with its reference point at x, y. The reference point may be set to any of 9 positions within the rectangle enclosing the text, the parameter lorg takes the values 1 .. 9 and sets which of the origin positions to use as the reference point. The text size is set by the fontSize in world coordinate unit. The optional color string parameter sets the color in which the text will be rendered, if color is omitted the text will be rendered in the current pen color.

Parameters:

str:String - The text to be converted to a Path3D object.

x:Number - X coordinate of the lower left corner of the rectangle measured in world coordinates.

y:Number - Y coordinate of the lower left corner of the rectangle measured in world coordinates.

lorg:Number - Location of the origin within the bounding rectangle of the text that is used as the reference point for positioning the text Path3D in 3D space. lorg can take integer values 1..9. lorg=1 locates the top, left of the text at the x, y position, lorg=2 locates the top, center of the text at the x, y position, and so on. Fig 1 shows the effect of each lorg value. In fig 1, each label's x, y coordinates are those of the adjacent grid intersection, the lorg value of each label determines where the text is positioned with respect to its x, y values.

Figure 1. Placement of label relative to the x,y parameter for the 9 possible values of lorg.

fontSize:Number - Height of an upper case character, measured in world coordinates.

color:String (optional) - Stroke color, if present the text is rendered with this color. The color may be expressed in any of the three HTML/CSS color formats (see setPenColor).

If color parameter is omitted the text object is rendered in the current pen color.

Returns:

Path3D - with properties required to manipulate and render the text string as a single 3D entity.

renderPath3D

Syntax:

cvsCtx.renderPath3D(path:Path3D)

Description:

Projects the vertices and the Bezier control points of path onto the X,Y plane with perspective calculated from the current viewpoint. The 2D draw commands are then passed to the canvas graphics context to be drawn.

Parameters:

path:Path3D - The path to be rendered.

groupPaths

Syntax:

cvsCtx.groupPaths(paths:Array)

Description:

This method forms a new object of type Group3D that concatenates all the DrawCmd3D objects of the Path3D objects referenced by paths. The Path3Ds are always drawn when the group is rendered i.e. they are not subject to backculling.

Parameters:

paths:Array (optional)- An array of Path3D objects representing various panels that will be grouped so that they can be move as one and then rendered to the canvas as a unit.

Returns:

Group3D - with properties required to manipulate and render the 3D assembly formed by the paths.

groupClosedPaths

Syntax:

cvsCtx.groupClosedPaths(paths:Array)

Description:

This method forms a new object of type Group3D that concatenates all the DrawCmd3D objects of the Path3D objects referenced by paths. The Path3Ds are subject to backculling. If the normal of any of the Path3Ds is facing away from the line of sight from the viewpoint to the Path3D's origin, then the path is culled i.e. not drawn.

Parameters:

paths:Array (optional)- An array of Path3D objects representing various panels that will be grouped so that they can be move as one and then rendered to the canvas as a unit.

Returns:

Group3D - with properties required to manipulate and render the 3D assembly formed by the paths.

groupByRotation

Syntax:

cvsCtx.groupByRotation(path:String, radius:Number, totalAngle:Number, segments:Number, fillColor:String)

Description:

Generates a Group3D formed by rotating the path described by the SVG format data about an axis. The rotation is about the Y axis with the SVG path starting with its first point (always the end point of a 'move' command) at a distance radius from the Y axis.

Parameters:

data:String - A string holding the SVG format data defining a 2D path.

Returns:

Group3D - with properties required to manipulate and render the 3D shape formed by rotating the path about the Y axis.

translateGroup3D

Syntax:

cvsCtx.translateGroup3D(grp:Group3D, x:Number, y:Number, z:Number)

Description:

A matrix is created that will translate a 3D point to the position {x, y, z}. The current grp.xfrm matrix is multiplied by this translation matrix. The grp.xfrm matrix accumulates the effects of all translateGroup3D and rotateGroup3D calls until a call is made, to resetTransformGroup3D is made, resetting the grp.xfrm matrix to the identity matrix.

Parameters:

grp:Group3D - The group to be translated.

x:Number - The X coordinate in worlds coordinates of the point in 3D space to which the group reference point is to be moved prior to rendering the group onto the canvas.

y:Number - The Y coordinate.

z:Number - The Z coordinate.

rotateGroup3D

Syntax:

cvsCtx.rotateGroup3D(grp:Group3D, xRot:Number, yRot:Number, zRot:Number, cx:Number, cy:Number, cz:Number)

Description:

A matrix is created that will rotate a 3D point about the point {cx, cy, cz}. The rotation angle about the axis parallel to the Z axis is zRot, the Y axis is yRot and X axis is xRot. The current grp.xfrm matrix is multiplied by this rotation matrix. The grp.xfrm matrix accumulates the effects of all translateGroup3D and rotateGroup3D calls until a call is made to resetTransformGroup3D is made, resetting the grp.xfrm matrix to the identity matrix.

Parameters:

grp:Group3D - The group to be rotated.

xRot:Number - The angle through which all points are rotated about the center of rotation parallel to the X axis, prior to rendering the group. xRot is measured in degrees.

yRot:Number - The rotation angle parallel to Y axis.

zRot:Number - The rotation angle parallel to Z axis.

cx:Number - The X coordinate of the center of rotation about which the xRot, yRot and zRot are made, all are measured in worlds coordinates.

cy:Number - The Y coordinate of the center of rotation.

cz:Number - The Z coordinate of the center of rotation.

resetTransformGroup3D

Syntax:

cvsCtx.resetTransformGroup3D(grp:Group3D)

Description:

The grp.xfrm matrix is reset to the identity matrix.

Parameters:

grp:Group3D - The Group3D whose transform matrix is to be set to the identity matrix.

renderGroup3D

Syntax:

cvsCtx.renderGroup3D(grp:Group3D)

Description:

All the vertices and control points of the Path3Ds forming the group grp are multiplied by the current grp.xfrm matrix. The vertices and Bezier control points are then projected onto the X,Y plane, with perspective calculated from the current viewpoint. The resulting 2D draw commands are then passed to the canvas graphics context and drawn. All the component Path3Ds that are closed are filled with the color specified by their color property.

Parameters:

grp:Group3D - The Group3D to be rendered to the canvas.

wireframeGroup3D

Syntax:

cvsCtx.wireframeGroup3D(grp:Group3D)

Description:

Parameters:

grp:Group3D - The Group3D to be rendered to the canvas.

Cvs3DLib Reference Manual

Path3D

A Path3D may be as simple as a single straight line segment or a complicated set of curved and straight segments. These path segments are defined in an array of DrawCmd3D objects, each of which has a 'drawFn' which is the name of a canvas draw command ("lineTo", "quadBezier", "arc" etc) that will be used to render the path segment onto the canvas. Along with 'drawFn' string, the DrawCmd3D 'cPts' property holds the coordinates of the Bezier control points for curved segments (empty array for straight line segments) and the 'ep' property holding the coordinates of the endpoint of the segment.

A Path3D also has methods such as translate and rotate which move the object in 3D space, these methods are assembly movements, used to align components of larger 3D objects.

Each Path3D has a an origin and a normal that allows calculation of shading the path when it is rendered or back-culling the path if its facing away from the viewpoint when it is part of a solid shape.

Path3D properties:

Syntax:

var value = cvsCtx.property;

Properties:

ppPts:Array - an array holding a references to all coordinates of drawCmds[] to facilitate 3D transformations (rotate, translate, projection to 2D).

drawCmds:Array - Array of DrawCmd3D objects describing how to draw the path, a DrawCmd3D object has properties {drawFn:String, cPts:[Points], ep:Point} where the 'drawFn' String is a HTML5 canvas format draw function eg. 'lineTo', 'bezierCurveTo' etc. 'cPts' is an array of Bezier control points. 'ep' is the end coordinates of the path segment.

color:String - string in the "rgba(r, g, b, a)" format where r is the value (0 to 255) of the red component of the pen color, g is the green component, b is the blue component and a is the alpha or transparency component (0 to 1.0). If the Path3D is closed it will be filled with this color. If it is not closed or is to be drawn as part of a wireframe rendering of a group, the wireframe will be drawn in this color.

closed:Boolean - true: path is filled, false: draw as wireframe.

drawData:Array - Array of DrawCmd objects, these are 2D commands, generated when each DrawCmd3D is projected into the canvas plane prior to rendering. Each DrawCmd element has the property {drawFn: String, parms:Array}. The 'drawFn is the 'drawFn' from the corresponding DrawCmd3D, the 'parms' array of 2D coordinates that are the 2D projections of the DrawCmd3D in the correct format for passing to the canvas ctx for drawing.

origin:Point object - the average of x, y and z coordinates of all vertices used as the reference point for sorting the Path3Ds of a group prior to rendering.

normal:Point object - calculated so that the vector from the origin to the normal point is perpendicular to the plane of the Path3D, the plane is defined by the first three vertices of the Path3D. The normal vector is used for shading calculations and backculling.

Path3D methods

dup,
appendPath3D, addDrawCmd
setColor,
translate, rotate

dup

Syntax:

path.dup(void)

Description:

Creates a copy of the Path3D object path. The copy is not just a reference to the original, changing the properties of the new Path3D will not affect the original.

Parameters:

none.

Returns:

Path3D - a new object with all properties a copy of path properties.

appendPath3D

Syntax:

path.appendPath3D(newPath:Path3D)

Description:

Concatenates two Path3D objects. The DrawCmds of newPath will be appended to the drawCmds array of path. All Path3D drawCmds start with a 'moveTo' command, if the pen would already be in the correct location to start drawing the appended path, then the initial 'moveTo' would be redundant and so can be deleted. If the optional delMove is true then the 'moveTo' draw command of the newPath is deleted. The origin and normal of path will be recalculated after the newPath is added.

Parameters:

newPath:Path3D - A reference to a Path3D object to be appended to the current path.

delMove:Boolean - If true the initial 'moveTo' drawCmd of 'newPath' is deleted prior to concatenation.

addDrawCmd

Syntax:

path.addDrawCmd(drawcmd:DrawCmd3D)

Description:

Adds a single drawCmd to the current path.drawCmds. The path.origin and path.normal will be recalculated incorporating the effect of the new command.

Parameters:

drawcmd:DrawCmd3D - The draw command to be added to the current Path3D.

setColor

Syntax:

path.setColor(color:String)

Description:

Sets the color with which path will be filled or stroked when rendered.

Parameters:

translate

Syntax:

path.translate(x:Number, y:Number, z:Number)

Description:

Generate a transform matrix to translate a point's coordinates by {x, y, z}. Then multiply every point in path.ppPts array and the path.origin and path.normal by this matrix. The transformed x,y,z values overwrite each point's current values. These relative movements should be used in shape construction not animation.

Parameters:

x:Number - The distance in the X direction, measured in world coordinates, by which every point in the group will be moved.

y:Number - The Y coordinate.

z:Number - The Z coordinate.

rotate

Syntax:

path.rotate(xRot:Number, yRot:Number, zRot:Number)

Description:

Generate a transform matrix to produce the rotations xRot, yRot, zRot in a point's coordinates. The order of rotation is: rotation about Z axis first, then about the Y axis then about the X axis. Then multiply every point in path.ppPts array and the path.origin and path.normal by this matrix. The transformed x,y,z values overwrite each point's current values. These relative movements should be used in shape construction not animation.

NOTE: The 3D space is left handed. Rotation of +ve angles are in the direction the fingers of the left hand wrap when the thumb is pointed along the axis of rotation.

NOTE: To rotate path about a particular point, rather than the x, y or z axis, path should be translated so that the desired center of rotation is at the origin, then rotate should be called. After rotation the path should be translated back to its desired location with the 'translate' method.

Parameters:

xRot:Number - The angle measured in degrees by which path should be rotated about the X axis.

yRot:Number - The angle measured in degrees by which path should be rotated about the Y axis.

zRot:Number - The angle measured in degrees by which path should be rotated about the Z axis.

Group3D

Group3D objects have translate and rotate which setup the Group3D just like the Path3D can translate and rotate all the objects as a single entity, these movements are again relative to the current position and orientation of the objects in the group they are not suitable for animation but should be used to construct more complex 3D shapes.

Group3D properties:

Syntax:

var value = Group3D.property;

Properties:

paths:Array - an array of Path3D Objects that are not checked for backculling when rendered. Path3Ds that don't form a closed solid should be grouped in this array.

backcullPaths:Array - an array of Path3D objects forming a solid 3D object. Those Path3Ds facing the away from the observer line of sight can not be seen and so are culled. Those visible to the observer are added to the list of paths to be rendered. The normal property determines whether the Path3D is facing away from the viewer.

xfrm:Array (4x4 Matrix) - holds the product of all translations and rotations calls that will be applied to each vertex and control point of the group, prior to projection into 2D for drawing.

pathDrawList:Array - array holding all the DrawCmds to be drawn to render the Group3D onto the canvas. These are sorted in the order in which they are to be drawn according to the 'painters' algorithm, those whose origin is furthest from the observer drawn first and the closest drawn last.

Group3D methods

addPath3D, addBackcullPath3D
translate, rotate

addPath3D

Syntax:

group.addPath3D(newPath:Path3D)

Description:

Add a Path3D object to an existing Group3D object. The Path3D will be added to the group.paths array so it will always be drawn i.e. it will not be backculled.

Parameters:

newPath:Path3D - A reference to a Path3D object returned by a call to a Path3D creation method eg. g.rect() or g.polyLine3D().

addBackcullPath3D

Syntax:

group.addBackcullPath3D(bcPath:Path3D)

Description:

Add a Path3D object to an existing Group3D object. The Path3D will be added to the group.backcullPaths array so it will not be drawn if its normal is pointing away from the line of sight from the viewpoint to the path's origin.

Parameters:

bcPath:Path3D - A reference to a Path3D object returned by a call to a Path3D creation method eg. g.rect() or g.polyLine3D().

translate

Syntax:

group.translate(x:Number, y:Number, z:Number)

Description:

Generate a transform matrix to tranlate a point's coodinates by {x, y, z}. Then multiply every vertex, control point, origin and normal of all Path3Ds of the goup by this matrix. The transformed x,y,z values overwrite the current values. These relative movements should be used in shape construction not animation.

Parameters:

x:Number - The distance in the X direction, measured in world coordinates, by which every point in the group will be moved.

y:Number - The distance in the Y direction.

z:Number - The distance in the Z direction.

rotate

Syntax:

group.rotate(xRot:Number, yRot:Number, zRot:Number)

Description:

Generate a transform matrix to produce the rotations xRot, yRot, zRot in a point's coordinates. The order rotation is about Z axis first, then about the Y axis then about the X axis. Then multiply every vertex, control point, origin and normal of all Path3Ds of the goup by this matrix. The transformed x,y,z values overwrite the current values. These relative movements should be used in shape construction not animation.

NOTE: The 3D space is left handed. Rotation of +ve angles are in the direction the fingers of the left hand wrap when the thumb is pointed along the axis of rotation.

NOTE: To rotate a 3D shape about a particular point, rather than the x, y or z axis, the shape should be translated so that the desired center of rotation is at the origin, then rotated then the shape should be translated back to its desired location.

Parameters:

xRot:Number - The angle, measured in degrees, by which the shape should be rotated about the X axis.

yRot:Number - The angle, measured in degrees, by which the shape should be rotated about the Y axis.

zRot:Number - The angle, measured in degrees, by which the shape should be rotated about the Z axis.