mXrap - Xshapes

Xshapes

require.mx('mxjs/base/xplot3D.js');

This library provides functions to assist in rendering 3D shapes in mXrap.

Create
Create.arrow
Create.circle
Create.cone
Create.cuboid
Create.cylinder
Create.disc
Create.ellipsoid
Create.frame
Create.icosphere
Create.pyramid
Create.quad
Create.sphere
Create.spheroid
Create.triangle
Generating lots of shapes efficiently
Graphics
Graphics.createLine
Graphics.createLinesAdapter
Graphics.createPresetLinesAdapter
Graphics
Graphics.createAdapter
Graphics.createPresetAdapter
Op
Op.addShape
Op.cloneShape
Op.copyShape
Op.createShape
Op.rekeyShape
Op.scaleAndWriteShape
Op.scaleShape
Op.scaleTranslateAndWriteShape
Op.transform3AndWriteShape
Op.transform3Shape
Op.transform4AndWriteShape
Op.transform4Shape
Op.transformViaFunctionAndWriteShape
Op.transformViaFunctionShape
Op.translateAndWriteShape
Op.translateShape
Op.writeShape
Path
Path.cubicBezier
Path.cubicBezierSmart
Path.linear
Path.linearSmart
Path.quadraticBezier
Path.quadraticBezierSmart
Simple
Simple.arrow
Simple.arrowScaled
Simple.circle
Simple.cone
Simple.cuboid
Simple.cuboidRegular
Simple.cylinder
Simple.disc
Simple.ellipsoid
Simple.frame
Simple.icosphere
Simple.octArrow
Simple.octArrowScaled
Simple.pyramid
Simple.quad
Simple.sphere
Simple.spheroid
Simple.tri
Utility
Utility.convertQuadsToTris
GraphicsAdapter
LineHandle
LineHandle.addPoint
LineHandle.createNewLine
LinesAdapter
Shape
Shape.addShape
Shape.cloneShape
Shape.copyShape
Shape.getFacesCount
Shape.getVerticesCount
Shape.loadFromText
Shape.printShape
Shape.rekeyShape
Shape.saveAsText
Shape.scaleAndWriteShape
Shape.scaleShape
Shape.scaleTranslateAndWriteShape
Shape.transform3AndWriteShape
Shape.transform3Shape
Shape.transform4AndWriteShape
Shape.transform4Shape
Shape.transformViaFunctionAndWriteShape
Shape.transformViaFunctionShape
Shape.translateAndWriteShape
Shape.translateShape
Shape.writeShape

Status	Name
	`Shape` Create.arrow ( `Object` config, `Shape` shape ) Creates an arrow. Vertices are shared between sides. startPoint : location point, default [0, 0, -1] endPoint : location point, default [0, 0, 1]. The arrow head is on the endPoint. arrowHeadWidthValue : The width of the arrow head as a fixed value. This configuration if specified takes precedence over arrowHeadWidthRatio. arrowHeadWidthRatio : The width of the arrow head as a fraction of the arrow length. arrowHeadLengthValue : The length of the arrow head as a fixed value. This configuration if specified takes precedence over arrowHeadLengthRatio. The length of the arrow body would be the length of the whole arrow (as configured from the start and end points) minus the length of the arrow head. arrowHeadLengthRatio : The length of the arrow head as a fraction of the arrow length. lineWidthValue : The width of the arrow body as a fixed value. This configuration if specified takes precedence over lineWidthRatio lineWidthRatio : The width of the arrow body as a fraction of the arrow length. foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered.
	`Shape` Create.circle ( `Object` config, `Shape` shape ) Creates a circle. The configuration available are: centrePoint : centre location point, default [0, 0, 0] radius : circle radius, default 1. radialRes : "radial resolution". Around the circle will be rendered by the number of points specified. This will be reduced if only part of the circle is rendered. Default 30, Minimum 4 angleStart : Only specify if rendering part of the circle. Around the circle, what angle to render from. Default 0 degrees angleEnd : Only specify if rendering part of the circle. Around the circle, what angle to render to. Default 360 degrees dirVector : Point representing vector. This is the normal vector of the plane that the circle sits on (e.g. the "facing" of the circle) foreignKey : either a number value, or a function f(location, i), where location is the location of the vertex being considered and i is the radial index (-1 for centre).
	`Shape` Create.cone ( `Object` config, `Shape` shape ) Creates an cone. startPoint : location point, default [0, 0, -1]. This is the center of the base of the cone endPoint : location point, default [0, 0, 1]. This is the top "pointy" point of the cone coneRadius : The radius of the base of the cone. Default 1. longRes : "longitudinal resolution". The cone, lengthwise, will be made up of smaller triangles/rectangles with the length no larger than this value. Default 5000 radialRes : "radial resolution". Around the cone will be rendered by the number of points specified. This will be reduced if only part of the cone is rendered. Default 30, Minimum 4 angleStart : Only specify if rendering part of the cone. Around the circular base, what angle to render from. Default 0 degrees angleEnd : Only specify if rendering part of the cone. Around the circular base, what angle to render to. Default 360 degrees closePartialArc : Boolean. If only part of the cone is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false closeCone : Boolean. Do you want the cone base to be rendered. Default true foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (longitudinal index) are the index along the current radial/longitudinal rendering respectively.
	`Shape` Create.cuboid ( `Object` config, `Shape` shape ) Creates a cuboid. Unlike a true cuboid, this function allows you to specify all 8 points, so you could essentially have a irregular 6 sided 3D polygon. Note that the faces/sides do not share vertices, as they may need to be coloured differently. The configuration available are: pointStart1 : location point, default [1, 1, 1] pointStart2 : location point, default [1, -1, 1] pointStart3 : location point, default [-1, -1, 1] pointStart4 : location point, default [-1, 1, 1] pointEnd1 : location point, default [1, 1, -1] pointEnd2 : location point, default [1, -1, -1] pointEnd3 : location point, default [-1, -1, -1] pointEnd4 : location point, default [-1, 1, -1] drawFaces : boolean array of size 6. Determines if each face is rendered. Default all true. Face 0 is all the start points, Face 1 is all the end points, and the subsequent 4 faces longRes : "longitudinal resolution". The quad will be made up of smaller triangles/rectangles with the length/width no larger than this value. Default 5000 foreignKey : either a number value, or a function f(location, ref), where location is the location of the vertex being considered, and ref is the face of the cuboid (0-5) being considered.
	`Shape` Create.cylinder ( `Object` config, `Shape` shape ) Creates an cylinder. startPoint : location point, default [0, 0, -1]. This is the center of the base of the cone startRadius : The radius of the cylinder on the startPoint end. Default 1. endPoint : location point, default [0, 0, 1]. This is the top "pointy" point of the cone endRadius : The radius of the cylinder on the endPoint end. Default 1. longRes : "longitudinal resolution". The cylinder, lengthwise, will be made up of smaller triangles/rectangles with the length no larger than this value. Default 5000 radialRes : "radial resolution". Around the cylinder will be rendered by the number of points specified. This will be reduced if only part of the cylinder is rendered. Default 30, Minimum 4 angleStart : Only specify if rendering part of the cylinder. Around the cylinder, what angle to render from. Default 0 degrees angleEnd : Only specify if rendering part of the cylinder. Around the cylinder, what angle to render to. Default 360 degrees closePartialArc : Boolean. If only part of the cylinder is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false closeStart : Boolean. Do you want the circle of the startPoint end to be rendered. Default true closeEnd : Boolean. Do you want the circle of the endPoint end to be rendered. Default true foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (longitudinal index) are the index along the current radial/longitudinal rendering respectively.
	`Shape` Create.disc ( `Object` config, `Shape` shape ) Creates a disc. A Disc is essentially a "hollow" cylinder, being rendered from two (one inner, one outer) cylinders. startPoint : location point, default [0, 0, -1]. This is the center of the base of the cone startInnerRadius : The radius of the inner cylinder on the startPoint end. Default 0.25. startOuterRadius : The radius of the outer cylinder on the startPoint end. Default 1. endPoint : location point, default [0, 0, 1]. This is the top "pointy" point of the cone endInnerRadius : The radius of the inner cylinder on the startPoint end. Default 025. endOuterRadius : The radius of the outer cylinder on the startPoint end. Default 1. longRes : "longitudinal resolution". The disc, lengthwise, will be made up of smaller triangles/rectangles with the length no larger than this value. Default 5000 radialRes : "radial resolution". Around the disc will be rendered by the number of points specified. This will be reduced if only part of the disc is rendered. Default 30, Minimum 4 angleStart : Only specify if rendering part of the disc. Around the disc, what angle to render from. Default 0 degrees angleEnd : Only specify if rendering part of the disc. Around the disc, what angle to render to. Default 360 degrees closePartialArc : Boolean. If only part of the disc is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false closeStart : Boolean. Do you want the hollow circle of the startPoint end to be rendered. Default true closeEnd : Boolean. Do you want the hollow circle of the endPoint end to be rendered. Default true foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (longitudinal index) are the index along the current radial/longitudinal rendering respectively.
	`Shape` Create.ellipsoid ( `Object` config, `Shape` shape ) Creates an ellipsoid using UV mapping. An ellipsoid is a sphere with different radii along three axes. You can configure it to generate only part of the ellipsoid. The configuration available are: centrePoint : location point, default [0, 0, 0] axis1 : Point representing vector for the direction of axis 1. Expected to be perpendiucular to all other axis. Default x-axis. axis2 : Point representing vector for the direction of axis 2. Expected to be perpendiucular to all other axis. Default y-axis. axis3 : Point representing vector for the direction of axis 3. Expected to be perpendiucular to all other axis. Default z-axis. This is the direction of the UV mapping. radius1 : The ellipsoid is initially generated so its "axis3" is the radius of the ellipsoid along the x-axis, default 0.5. radius2 : The ellipsoid is initially generated so its "axis3" is the radius of the ellipsoid along the y-axis, default 1. radius3 : The ellipsoid is initially generated so its "axis3" is the radius of the ellipsoid along the z-axis, default 2. radialRes : "radial resolution". Around the ellipsoid will be rendered by the number of points specified. This will be reduced if only part of the ellipsoid is rendered. Default 30, Minimum 4 thetaRes : "theta resolution". Around the xz/yz plane, will be rendered by the number of points specified. This will be reduced if only part of the ellipsoid is rendered. Default 30, Miniumum 4 angleStart : Only specify if rendering part of the ellipsoid. Around the xy plane, what angle to render from. Default 0 degrees angleEnd : Only specify if rendering part of the ellipsoid. Around the xy plane, what angle to render to. Default 360 degrees thetaStart : Only specify if rendering part of the ellipsoid. Around the xz/yz plane, what angle to render from. Default/Min 0 degrees thetaEnd : Only specify if rendering part of the ellipsoid. Around the xz/yz plane, what angle to render to. Default/Max 180 degrees closePartialArc : Boolean. If only part of the ellipsoid is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (theta index) are the index along the current radial/theta rendering respectively.
	`Shape` Create.frame ( `Object` config, `Shape` shape ) A frame creates an "outline" of a box and is used to specify an area. Unlike the cuboid function, you only specify the max and min points of the box - the box is forced to be regular. minPoint : location point, default [-10, -10, -10]. This determines the lowest corner of the box maxPoint : location point, default [10, 10, 10]. This determines the highest corner of the box frameThickness : point representing vector. The thinkness of the frame in the xyz axes. Default [0.5, 0.5, 0.5]. foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered.
	`Shape` Create.icosphere ( `Object` config, `Shape` shape ) An icosphere is a sphere. Compared to the UV sphere it looks more regular. There is currently no support for only rendering part of this sphere. centrePoint : location point, default [0, 0, 0]. This is the center of the sphere radius : The radius of the sphere. Default 1. refines : The sphere starts out as a icosahedron, and then each triangle is refined into 4 triangles. This specifies the number of refines performed. The higher number of refines, the more it looks like a sphere. Do note that it gets very computationally expensive at higher values. Default 2. foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered. Refer to http://blog.andreaskahler.com/2009/06/creating-icosphere-mesh-in-code.html for a good description of UV vs ico spheres, and how the icosphere looks between 1-3 refines
	`Shape` Create.pyramid ( `Object` config, `Shape` shape ) Creates a pyramid. Note that the faces/sides do not share vertices, as they may need to be coloured differently. The configuration available are: pointTop : location point, default [0, 0, 1] pointBase1 : location point, default [1, 1, -1] pointBase2 : location point, default [1, -1, -1] pointBase3 : location point, default [-1, -1, -1] pointBase4 : location point, default [-1, 1, -1] drawFaces : boolean array of size 5. Determines if each face is rendered. Default all true. Face 0 is all the base points and the subsequent 4 triangle faces longRes : "longitudinal resolution". The quad will be made up of smaller triangles/rectangles with the length/width no larger than this value. Default 5000 foreignKey : either a number value, or a function f(location, ref), where location is the location of the vertex being considered, and ref is the face of the pyramid (0-4) being considered.
	`Shape` Create.quad ( `Object` config, `Shape` shape ) Creates a rectangle. The configuration available are: point1 : location point, default [1, 0, 1] point2 : location point, default [1, 0, -1] point3 : location point, default [-1, 0, -1] point4 : location point, default [-1, 0, 1] longRes : "longitudinal resolution". The quad will be made up of smaller triangles/rectangles with the length/width no larger than this value. Default 5000 foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered.
	`Shape` Create.sphere ( `Object` config, `Shape` shape ) Creates a sphere using UV mapping. You can configure it to generate only part of the sphere. The configuration available are: centrePoint : location point, default [0, 0, 0] radius : Radius of the sphere radialRes : "radial resolution". Around the sphere will be rendered by the number of points specified. This will be reduced if only part of the sphere is rendered. Default 30, Minimum 4 thetaRes : "theta resolution". Around the xz/yz plane, will be rendered by the number of points specified. This will be reduced if only part of the sphere is rendered. Default 30, Miniumum 4 angleStart : Only specify if rendering part of the sphere. Around the xy plane, what angle to render from. Default 0 degrees angleEnd : Only specify if rendering part of the sphere. Around the xy plane, what angle to render to. Default 360 degrees thetaStart : Only specify if rendering part of the sphere. Around the xz/yz plane, what angle to render from. Default/Min 0 degrees thetaEnd : Only specify if rendering part of the sphere. Around the xz/yz plane, what angle to render to. Default/Max 180 degrees closePartialArc : Boolean. If only part of the sphere is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false dirVector : Point representing vector. As described above, the sphere is initially generated so that the "length" of the sphere is in the direction of the z-axis. Specify another vector here and the sphere will be generated in the direction specified. foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (theta index) are the index along the current radial/theta rendering respectively.
	`Shape` Create.spheroid ( `Object` config, `Shape` shape ) Creates a spheroid using UV mapping. A spheroid is a sphere with different radii along two axes, so you could generate a stretched "egg". You can configure it to generate only part of the spheroid. The configuration available are: centrePoint : location point, default [0, 0, 0] longRadius : The spheroid is initially generated so its "longRadius" is the max radius of the spheroid along the z-axis, default 2. widthRadius : The spheroid is initially generated so its "widthRadius" is the radius of the spheroid in the xy plane, default 1. radialRes : "radial resolution". Around the spheroid will be rendered by the number of points specified. This will be reduced if only part of the spheroid is rendered. Default 30, Minimum 4 thetaRes : "theta resolution". Around the xz/yz plane, will be rendered by the number of points specified. This will be reduced if only part of the spheroid is rendered. Default 30, Miniumum 4 angleStart : Only specify if rendering part of the spheroid. Around the xy plane, what angle to render from. Default 0 degrees angleEnd : Only specify if rendering part of the spheroid. Around the xy plane, what angle to render to. Default 360 degrees thetaStart : Only specify if rendering part of the spheroid. Around the xz/yz plane, what angle to render from. Default/Min 0 degrees thetaEnd : Only specify if rendering part of the spheroid. Around the xz/yz plane, what angle to render to. Default/Max 180 degrees closePartialArc : Boolean. If only part of the spheroid is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false dirVector : Point representing vector. As described above, the spheroid is initially generated so that the "length" of the spheroid is in the direction of the z-axis. Specify another vector here and the spheroid will be generated in the direction specified. foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (theta index) are the index along the current radial/theta rendering respectively.
	`Shape` Create.triangle ( `Object` config, `Shape` shape ) Creates a triangle. The configuration available are: point1 : location point, default [0, 0, 1] point2 : location point, default [1, 0, -1] point3 : location point, default [-1, 0, -1] longRes : "longitudinal resolution". The quad will be made up of smaller triangles/rectangles with the length/width no larger than this value. Default 5000 foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered.
	`LineHandle` Graphics.createLine ( `LineHandle` ↑LineHandle, `LinesAdapter` ↓LinesAdapter, `Point` ↓location, `Number` ↓fk ) Creates a new LineHandle (which represents a new line) for the LinesAdapter provided. Optionally takes in a location and fk - which then forms the first vertex of this line
	`LinesAdapter` Graphics.createLinesAdapter ( `Table` ↓Vertices, `Function` ↓write_VID, `Function` ↓write_Location, `Function` ↓write_FK, `Table` ↓Lines, `Function` ↓write_ID, `Function` ↓write_LineID, `Function` ↓write_LineOrder, `Function` ↓write_VertexID ) Creates a LinesAdapter based on the two input tables and their write functions.
	`LinesAdapter` Graphics.createPresetLinesAdapter ( `Table` ↓Vertices, `Table` ↓Lines ) Creates a LinesAdapter based on the two input tables Vertices and Lines. This function assumes the relevant fields in Vertices and Lines are named exactly as expected - ie. for Vertices, "ID" (ids), "Location" (points), "FK" (ids/numbers), and for Faces, "ID", "LineID", "LineOrder", "VertexID" (ids)
	`GraphicsAdapter` Graphics.createAdapter ( `Table` Vertices, `Function` write_VID, `Function` write_Location, `Function` write_FK, `Table` Faces, `Function` write_FID, `Function` write_V1, `Function` write_V2, `Function` write_V3, `Function` write_V4 ) Creates a GraphicsAdapter based on the two input tables and their write functions.
	`GraphicsAdapter` Graphics.createPresetAdapter ( `Table` Vertices, `Table` Faces ) Creates a GraphicsAdapter based on the two input tables Vertices and Faces. This function assumes the relevant fields in Vertices and Faces are named exactly as expected - ie. for Vertices, "ID" (ids), "Location" (points), "FK" (ids), and for Faces, "ID", "V1", "V2", "V3", "V4" (ids)
	`Shape` Op.addShape ( `Shape` shape, `Shape` shapeToAdd ) Adds the input shapeToAdd to the input shape.
	`Shape` Op.cloneShape ( `Shape` shape ) Clones input Shape object and returns the new Shape object
	`Shape` Op.copyShape ( `Shape` shape, `Shape` shapeToCopy ) Clears a shape and makes it a copy of another shape.
	`Shape` Op.createShape ( ) Creates an empty Shape object.
	`Shape` Op.rekeyShape ( `Shape` shape, `Function` keyFunction ) Modifies the foreign key for the vertices of the input shape
	`Shape` Op.scaleAndWriteShape ( `Shape` shape, `Array` vec3, `GraphicsAdapter` graphicsAdapter ) Writes a scaled version of the shape. Unlike scaleShape, the input shape remains unchanged.
	`Shape` Op.scaleShape ( `Shape` shape, `Array` vec3 ) Scales input shape by input vector
	`Shape` Op.scaleTranslateAndWriteShape ( `Shape` shape, `Array` scale3, `Array` translate3, `GraphicsAdapter` graphicsAdapter ) Writes a scaled and translated version of the shape. The current shape is not modified.
	`Shape` Op.transform3AndWriteShape ( `Shape` shape, `glMatrix` mat3, `GraphicsAdapter` graphicsAdapter ) Writes a transformed version of the shape. Unlike transform3Shape, the input shape remains unchanged.
	`Shape` Op.transform3Shape ( `Shape` shape, `glMatrix` mat3 ) Transforms input shape by input 3x3 matrix
	`Shape` Op.transform4AndWriteShape ( `Shape` shape, `glMatrix` mat4, `GraphicsAdapter` graphicsAdapter ) Writes a transformed version of the shape. Unlike transform4Shape, the input shape remains unchanged.
	`Shape` Op.transform4Shape ( `Shape` shape, `glMatrix` mat4 ) Transforms input shape by input 4x4 matrix
	`Shape` Op.transformViaFunctionAndWriteShape ( `Shape` shape, `Function` func_vec3, `GraphicsAdapter` graphicsAdapter ) Writes a transformed version of the shape. Unlike transformViaFunctionShape, the input shape remains unchanged. The transformation uses a function w = f(v), where v is an input Point and w is the returned Point. The function may modify and return the original Point rather than create a new Point.
	`Shape` Op.transformViaFunctionShape ( `Shape` shape, `Function` func_vec3 ) Transforms input shape by a function w = f(v), where v is an input Point and w is the returned Point. The function may modify and return the original Point rather than create a new Point.
	`Shape` Op.translateAndWriteShape ( `Shape` shape, `Array` vec3, `GraphicsAdapter` graphicsAdapter ) Writes a translated version of the shape. Unlike translateShape, the input shape remains unchanged.
	`Shape` Op.translateShape ( `Shape` shape, `Array` vec3 ) Translates input shape by input vector
	Op.writeShape ( `Shape` shape, `GraphicsAdapter` graphicsAdapter ) Writes a Shape to a GraphicsAdapter object.
Constant	`Library` Path.Matrix - an instance of the glMatrix library that Xshapes uses.
Constant	`Object` Path.shapeCommonDefaults - common defaults for shapes.
	`Number` Path.cubicBezier ( `LineHandle` ↓LineHandle, `Point` ↓point1, `Point` ↓point2, `Point` ↓point3, `Point` ↓point4, `Number` ↓fk, `Number` ↓numPoints, `Boolean` ↓excludeFirst ) Plots a cubic bezier path from point 1 to point 4 using points 2 and 3 as a reference point and writes it to the specified LineHandle.
	`Number` Path.cubicBezierSmart ( `LineHandle` ↓LineHandle, `Point` ↓point1, `Point` ↓point2, `Point` ↓point3, `Point` ↓point4, `Number` ↓fk, `Number` ↓threshold, `Boolean` ↓excludeFirst ) Plots a cubic bezier path from point 1 to point 4 using points 2 and 3 as a reference point and writes it to the specified LineHandle. The smart variant of this function auto-generates the number of points required so that the distance between two points on the path is close to the threshold distance
	`Number` Path.linear ( `LineHandle` ↓LineHandle, `Point` ↓point1, `Point` ↓point2, `Number` ↓fk, `Number` ↓numPoints, `Boolean` ↓excludeFirst ) Plots a linear path from point 1 to point 2 and writes it to the specified LineHandle.
	`Number` Path.linearSmart ( `LineHandle` ↓LineHandle, `Point` ↓point1, `Point` ↓point2, `Number` ↓fk, `Number` ↓threshold, `Boolean` ↓excludeFirst ) Plots a linear path from point 1 to point 2 and writes it to the specified LineHandle. The smart variant of this function auto-generates the number of points required so that the distance between two points on the path is at most the threshold distance
	`Number` Path.quadraticBezier ( `LineHandle` ↓LineHandle, `Point` ↓point1, `Point` ↓point2, `Point` ↓point3, `Number` ↓fk, `Number` ↓numPoints, `Boolean` ↓excludeFirst ) Plots a quadratic bezier path from point 1 to point 3 using point2 as a reference point and writes it to the specified LineHandle.
	`Number` Path.quadraticBezierSmart ( `LineHandle` ↓LineHandle, `Point` ↓point1, `Point` ↓point2, `Point` ↓point3, `Number` ↓fk, `Number` ↓threshold, `Boolean` ↓excludeFirst ) Plots a quadratic bezier path from point 1 to point 3 using point2 as a reference point and writes it to the specified LineHandle. The smart variant of this function auto-generates the number of points required so that the distance between two points on the path is close to the threshold distance
	`Shape` Simple.arrow ( `Shape` ⇅shapeToAddTo, `Point` ↓startPoint, `Point` ↓endPoint, `Number` ↓foreignKey ) Creates an arrow.
	`Shape` Simple.arrowScaled ( `Shape` ⇅shapeToAddTo, `Point` ↓startPoint, `Point` ↓endPoint, `Number` ↓foreignKey, `Number` ↓maxArrowHeadLength, `Number` ↓maxArrowHeadRatio, `Number` ↓maxArrowHeadWidth, `Number` ↓maxLineWidth, `Number` ↓minArrowHeadWidth, `Number` ↓minLineWidth ) Creates an arrow. Normally arrows are scaled according to their length. This function will scale the arrowhead to a maximum size (defined by max arrow head length), such that - when the length of the arrow is small, the arrowhead is scaled. When the length of the arrow is large, the arrowhead scales up to a max size, above this size only the body of the arrow is lengthened but the arrowhead does not scale further.
	`Shape` Simple.circle ( `Shape` ⇅shapeToAddTo, `Point` ↓centrePoint, `Number` ↓radius, `Array` ↓facing, `Number` ↓foreignKey ) Creates a circle
	`Shape` Simple.cone ( `Shape` ⇅shapeToAddTo, `Point` ↓startPoint, `Point` ↓endPoint, `Number` ↓coneRadius, `Number` ↓foreignKey, `Boolean` ↓closeCone ) Creates an cone.
	`Shape` Simple.cuboid ( `Shape` ⇅shapeToAddTo, `Point` ↓pointStart1, `Point` ↓pointStart2, `Point` ↓pointStart3, `Point` ↓pointStart4, `Point` ↓pointEnd1, `Point` ↓pointEnd2, `Point` ↓pointEnd3, `Point` ↓pointEnd4, `Number` ↓foreignKey, `Array` ↓drawFaces ) Creates a cuboid. You can create a non-regular cuboid using this function - all 8 points are specified.
	`Shape` Simple.cuboidRegular ( `Shape` ⇅shapeToAddTo, `Point` ↓minPoint, `Point` ↓maxPoint, `Number` ↓foreignKey, `Array` ↓drawFaces, `Boolean` ↓independentVertices ) Creates a regular cuboid, by specifying the minimum and maximum 3D points.
	`Shape` Simple.cylinder ( `Shape` ⇅shapeToAddTo, `Point` ↓startPoint, `Point` ↓endPoint, `Number` ↓startRadius, `Number` ↓endRadius, `Number` ↓foreignKey, `Boolean` ↓closeEnds ) Creates a cylinder.
	`Shape` Simple.disc ( `Shape` ⇅shapeToAddTo, `Point` ↓startPoint, `Point` ↓endPoint, `Number` ↓startInnerRadius, `Number` ↓startOuterRadius, `Number` ↓endInnerRadius, `Number` ↓endOuterRadius, `Number` ↓foreignKey, `Boolean` ↓closeEnds ) Creates a disc - a hollow cylinder with a thickness - made up of an outer and inner cylinder.
	`Shape` Simple.ellipsoid ( `Shape` ⇅shapeToAddTo, `Point` ↓centrePoint, `Array` ↓axis1, `Array` ↓axis2, `Array` ↓axis3, `Number` ↓axis1Radius, `Number` ↓axis2Radius, `Number` ↓axis3Radius, `Number` ↓foreignKey ) Creates an ellipsoid using UV mapping. An ellipsoid is a sphere with different radii along three axes.
	`Shape` Simple.frame ( `Shape` ⇅shapeToAddTo, `Point` ↓minPoint, `Point` ↓maxPoint, `Number` ↓foreignKey, `Array` ↓frameThickness ) Creates a frame - an "outline" of a box that could be used to specify an area.
	`Shape` Simple.icosphere ( `Shape` ⇅shapeToAddTo, `Point` ↓centrePoint, `Number` ↓radius, `Number` ↓foreignKey, `Number` ↓refines ) Creates a icosphere. Compared to the UV sphere it looks more regular. Refer to http://blog.andreaskahler.com/2009/06/creating-icosphere-mesh-in-code.html for a good description of UV vs ico spheres, and how the icosphere looks between 1-3 refines
	`Shape` Simple.octArrow ( `Shape` ⇅shapeToAddTo, `Point` ↓startPoint, `Point` ↓endPoint, `Number` ↓foreignKey ) Creates an octagonal arrow.
	`Shape` Simple.octArrowScaled ( `Shape` ⇅shapeToAddTo, `Point` ↓startPoint, `Point` ↓endPoint, `Number` ↓foreignKey, `Number` ↓maxArrowHeadLength, `Number` ↓maxArrowHeadRatio, `Number` ↓maxArrowHeadWidth, `Number` ↓maxLineWidth, `Number` ↓minArrowHeadWidth, `Number` ↓minLineWidth ) Creates an octagonal arrow. Normally arrows are scaled according to their length. This function will scale the arrowhead to a maximum size (defined by max arrow head length), such that - when the length of the arrow is small, the arrowhead is scaled. When the length of the arrow is large, the arrowhead scales up to a max size, above this size only the body of the arrow is lengthened but the arrowhead does not scale further.
	`Shape` Simple.pyramid ( `Shape` ⇅shapeToAddTo, `Point` ↓pointTop, `Point` ↓pointBase1, `Point` ↓pointBase2, `Point` ↓pointBase3, `Point` ↓pointBase4, `Number` ↓foreignKey, `Array` ↓drawFaces ) Creates a pyramid.
	`Shape` Simple.quad ( `Shape` ⇅shapeToAddTo, `Point` ↓point1, `Point` ↓point2, `Point` ↓point3, `Point` ↓point4, `Number` ↓foreignKey ) Creates a rectangle
	`Shape` Simple.sphere ( `Shape` ⇅shapeToAddTo, `Point` ↓centrePoint, `Number` ↓radius, `Array` ↓dirVector, `Number` ↓foreignKey ) Creates a sphere using UV mapping.
	`Shape` Simple.spheroid ( `Shape` ⇅shapeToAddTo, `Point` ↓centrePoint, `Number` ↓widthRadius, `Number` ↓longRadius, `Array` ↓dirVector, `Number` ↓foreignKey ) Creates a spheroid using UV mapping. A spheroid is a sphere with different radii along two axes, so you could generate a stretched "egg".
	`Shape` Simple.tri ( `Shape` ⇅shapeToAddTo, `Point` ↓point1, `Point` ↓point2, `Point` ↓point3, `Number` ↓foreignKey ) Creates a triangle
	`Number` Utility.convertQuadsToTris ( `Table` ↓Faces, `Function` ↓Faces_read_ID, `Function` ↓Faces_read_V1, `Function` ↓Faces_read_V2, `Function` ↓Faces_read_V3, `Function` ↓Faces_read_V4, `Function` ⇅OutputFaces_write_ID, `Function` ⇅OutputFaces_write_OriginID, `Function` ⇅OutputFaces_write_V1, `Function` ⇅OutputFaces_write_V2, `Function` ⇅OutputFaces_write_V3, `Number` ↓numExtraFields, `Array` ↓Faces_extraFieldsArray, `Array` ⇅OutputFaces_extraFieldsArray ) Converts a Faces table that contains triangles and quads into another Faces table that contains only triangles

Category: Create

These functions create Shape objects. The functions in this category are full constructors that offer the full range of options in constructing each shape, but can be complex or cumbersome to specify. If you are after creating a quick, regular shape, take a look at the Simple category.

shape = Lib.Create.arrow ( config, shape ) Alpha

Creates an arrow. Vertices are shared between sides.

startPoint : location point, default [0, 0, -1]
endPoint : location point, default [0, 0, 1]. The arrow head is on the endPoint.
arrowHeadWidthValue : The width of the arrow head as a fixed value. This configuration if specified takes precedence over arrowHeadWidthRatio.
arrowHeadWidthRatio : The width of the arrow head as a fraction of the arrow length.
arrowHeadLengthValue : The length of the arrow head as a fixed value. This configuration if specified takes precedence over arrowHeadLengthRatio. The length of the arrow body would be the length of the whole arrow (as configured from the start and end points) minus the length of the arrow head.
arrowHeadLengthRatio : The length of the arrow head as a fraction of the arrow length.
lineWidthValue : The width of the arrow body as a fixed value. This configuration if specified takes precedence over lineWidthRatio
lineWidthRatio : The width of the arrow body as a fraction of the arrow length.
foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created arrow to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.circle ( config, shape ) Alpha

Creates a circle. The configuration available are:

centrePoint : centre location point, default [0, 0, 0]
radius : circle radius, default 1.
radialRes : "radial resolution". Around the circle will be rendered by the number of points specified. This will be reduced if only part of the circle is rendered. Default 30, Minimum 4
angleStart : Only specify if rendering part of the circle. Around the circle, what angle to render from. Default 0 degrees
angleEnd : Only specify if rendering part of the circle. Around the circle, what angle to render to. Default 360 degrees
dirVector : Point representing vector. This is the normal vector of the plane that the circle sits on (e.g. the "facing" of the circle)
foreignKey : either a number value, or a function f(location, i), where location is the location of the vertex being considered and i is the radial index (-1 for centre).

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created circle to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.cone ( config, shape ) Alpha

Creates an cone.

startPoint : location point, default [0, 0, -1]. This is the center of the base of the cone
endPoint : location point, default [0, 0, 1]. This is the top "pointy" point of the cone
coneRadius : The radius of the base of the cone. Default 1.
longRes : "longitudinal resolution". The cone, lengthwise, will be made up of smaller triangles/rectangles with the length no larger than this value. Default 5000
radialRes : "radial resolution". Around the cone will be rendered by the number of points specified. This will be reduced if only part of the cone is rendered. Default 30, Minimum 4
angleStart : Only specify if rendering part of the cone. Around the circular base, what angle to render from. Default 0 degrees
angleEnd : Only specify if rendering part of the cone. Around the circular base, what angle to render to. Default 360 degrees
closePartialArc : Boolean. If only part of the cone is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false
closeCone : Boolean. Do you want the cone base to be rendered. Default true
foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (longitudinal index) are the index along the current radial/longitudinal rendering respectively.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created cone to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.cuboid ( config, shape ) Alpha

Creates a cuboid. Unlike a true cuboid, this function allows you to specify all 8 points, so you could essentially have a irregular 6 sided 3D polygon.

Note that the faces/sides do not share vertices, as they may need to be coloured differently. The configuration available are:

pointStart1 : location point, default [1, 1, 1]
pointStart2 : location point, default [1, -1, 1]
pointStart3 : location point, default [-1, -1, 1]
pointStart4 : location point, default [-1, 1, 1]
pointEnd1 : location point, default [1, 1, -1]
pointEnd2 : location point, default [1, -1, -1]
pointEnd3 : location point, default [-1, -1, -1]
pointEnd4 : location point, default [-1, 1, -1]
drawFaces : boolean array of size 6. Determines if each face is rendered. Default all true. Face 0 is all the start points, Face 1 is all the end points, and the subsequent 4 faces
longRes : "longitudinal resolution". The quad will be made up of smaller triangles/rectangles with the length/width no larger than this value. Default 5000
foreignKey : either a number value, or a function f(location, ref), where location is the location of the vertex being considered, and ref is the face of the cuboid (0-5) being considered.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created cuboid to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.cylinder ( config, shape ) Alpha

Creates an cylinder.

startPoint : location point, default [0, 0, -1]. This is the center of the base of the cone
startRadius : The radius of the cylinder on the startPoint end. Default 1.
endPoint : location point, default [0, 0, 1]. This is the top "pointy" point of the cone
endRadius : The radius of the cylinder on the endPoint end. Default 1.
longRes : "longitudinal resolution". The cylinder, lengthwise, will be made up of smaller triangles/rectangles with the length no larger than this value. Default 5000
radialRes : "radial resolution". Around the cylinder will be rendered by the number of points specified. This will be reduced if only part of the cylinder is rendered. Default 30, Minimum 4
angleStart : Only specify if rendering part of the cylinder. Around the cylinder, what angle to render from. Default 0 degrees
angleEnd : Only specify if rendering part of the cylinder. Around the cylinder, what angle to render to. Default 360 degrees
closePartialArc : Boolean. If only part of the cylinder is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false
closeStart : Boolean. Do you want the circle of the startPoint end to be rendered. Default true
closeEnd : Boolean. Do you want the circle of the endPoint end to be rendered. Default true
foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (longitudinal index) are the index along the current radial/longitudinal rendering respectively.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created cylinder to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.disc ( config, shape ) Alpha

Creates a disc. A Disc is essentially a "hollow" cylinder, being rendered from two (one inner, one outer) cylinders.

startPoint : location point, default [0, 0, -1]. This is the center of the base of the cone
startInnerRadius : The radius of the inner cylinder on the startPoint end. Default 0.25.
startOuterRadius : The radius of the outer cylinder on the startPoint end. Default 1.
endPoint : location point, default [0, 0, 1]. This is the top "pointy" point of the cone
endInnerRadius : The radius of the inner cylinder on the startPoint end. Default 025.
endOuterRadius : The radius of the outer cylinder on the startPoint end. Default 1.
longRes : "longitudinal resolution". The disc, lengthwise, will be made up of smaller triangles/rectangles with the length no larger than this value. Default 5000
radialRes : "radial resolution". Around the disc will be rendered by the number of points specified. This will be reduced if only part of the disc is rendered. Default 30, Minimum 4
angleStart : Only specify if rendering part of the disc. Around the disc, what angle to render from. Default 0 degrees
angleEnd : Only specify if rendering part of the disc. Around the disc, what angle to render to. Default 360 degrees
closePartialArc : Boolean. If only part of the disc is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false
closeStart : Boolean. Do you want the hollow circle of the startPoint end to be rendered. Default true
closeEnd : Boolean. Do you want the hollow circle of the endPoint end to be rendered. Default true
foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (longitudinal index) are the index along the current radial/longitudinal rendering respectively.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created disc to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.ellipsoid ( config, shape ) Alpha

Creates an ellipsoid using UV mapping. An ellipsoid is a sphere with different radii along three axes. You can configure it to generate only part of the ellipsoid. The configuration available are:

centrePoint : location point, default [0, 0, 0]
axis1 : Point representing vector for the direction of axis 1. Expected to be perpendiucular to all other axis. Default x-axis.
axis2 : Point representing vector for the direction of axis 2. Expected to be perpendiucular to all other axis. Default y-axis.
axis3 : Point representing vector for the direction of axis 3. Expected to be perpendiucular to all other axis. Default z-axis. This is the direction of the UV mapping.
radius1 : The ellipsoid is initially generated so its "axis3" is the radius of the ellipsoid along the x-axis, default 0.5.
radius2 : The ellipsoid is initially generated so its "axis3" is the radius of the ellipsoid along the y-axis, default 1.
radius3 : The ellipsoid is initially generated so its "axis3" is the radius of the ellipsoid along the z-axis, default 2.
radialRes : "radial resolution". Around the ellipsoid will be rendered by the number of points specified. This will be reduced if only part of the ellipsoid is rendered. Default 30, Minimum 4
thetaRes : "theta resolution". Around the xz/yz plane, will be rendered by the number of points specified. This will be reduced if only part of the ellipsoid is rendered. Default 30, Miniumum 4
angleStart : Only specify if rendering part of the ellipsoid. Around the xy plane, what angle to render from. Default 0 degrees
angleEnd : Only specify if rendering part of the ellipsoid. Around the xy plane, what angle to render to. Default 360 degrees
thetaStart : Only specify if rendering part of the ellipsoid. Around the xz/yz plane, what angle to render from. Default/Min 0 degrees
thetaEnd : Only specify if rendering part of the ellipsoid. Around the xz/yz plane, what angle to render to. Default/Max 180 degrees
closePartialArc : Boolean. If only part of the ellipsoid is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false
foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (theta index) are the index along the current radial/theta rendering respectively.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created ellipsoid to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.frame ( config, shape ) Alpha

A frame creates an "outline" of a box and is used to specify an area. Unlike the cuboid function, you only specify the max and min points of the box - the box is forced to be regular.

minPoint : location point, default [-10, -10, -10]. This determines the lowest corner of the box
maxPoint : location point, default [10, 10, 10]. This determines the highest corner of the box
frameThickness : point representing vector. The thinkness of the frame in the xyz axes. Default [0.5, 0.5, 0.5].
foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created frame to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.icosphere ( config, shape ) Alpha

An icosphere is a sphere. Compared to the UV sphere it looks more regular. There is currently no support for only rendering part of this sphere.

centrePoint : location point, default [0, 0, 0]. This is the center of the sphere
radius : The radius of the sphere. Default 1.
refines : The sphere starts out as a icosahedron, and then each triangle is refined into 4 triangles. This specifies the number of refines performed. The higher number of refines, the more it looks like a sphere. Do note that it gets very computationally expensive at higher values. Default 2.
foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered.

Refer to http://blog.andreaskahler.com/2009/06/creating-icosphere-mesh-in-code.html for a good description of UV vs ico spheres, and how the icosphere looks between 1-3 refines

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created icosphere to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.pyramid ( config, shape ) Alpha

Creates a pyramid. Note that the faces/sides do not share vertices, as they may need to be coloured differently. The configuration available are:

pointTop : location point, default [0, 0, 1]
pointBase1 : location point, default [1, 1, -1]
pointBase2 : location point, default [1, -1, -1]
pointBase3 : location point, default [-1, -1, -1]
pointBase4 : location point, default [-1, 1, -1]
drawFaces : boolean array of size 5. Determines if each face is rendered. Default all true. Face 0 is all the base points and the subsequent 4 triangle faces
longRes : "longitudinal resolution". The quad will be made up of smaller triangles/rectangles with the length/width no larger than this value. Default 5000
foreignKey : either a number value, or a function f(location, ref), where location is the location of the vertex being considered, and ref is the face of the pyramid (0-4) being considered.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created pyramid to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.quad ( config, shape ) Alpha

Creates a rectangle. The configuration available are:

point1 : location point, default [1, 0, 1]
point2 : location point, default [1, 0, -1]
point3 : location point, default [-1, 0, -1]
point4 : location point, default [-1, 0, 1]
longRes : "longitudinal resolution". The quad will be made up of smaller triangles/rectangles with the length/width no larger than this value. Default 5000
foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created quad to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.sphere ( config, shape ) Alpha

Creates a sphere using UV mapping. You can configure it to generate only part of the sphere. The configuration available are:

centrePoint : location point, default [0, 0, 0]
radius : Radius of the sphere
radialRes : "radial resolution". Around the sphere will be rendered by the number of points specified. This will be reduced if only part of the sphere is rendered. Default 30, Minimum 4
thetaRes : "theta resolution". Around the xz/yz plane, will be rendered by the number of points specified. This will be reduced if only part of the sphere is rendered. Default 30, Miniumum 4
angleStart : Only specify if rendering part of the sphere. Around the xy plane, what angle to render from. Default 0 degrees
angleEnd : Only specify if rendering part of the sphere. Around the xy plane, what angle to render to. Default 360 degrees
thetaStart : Only specify if rendering part of the sphere. Around the xz/yz plane, what angle to render from. Default/Min 0 degrees
thetaEnd : Only specify if rendering part of the sphere. Around the xz/yz plane, what angle to render to. Default/Max 180 degrees
closePartialArc : Boolean. If only part of the sphere is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false
dirVector : Point representing vector. As described above, the sphere is initially generated so that the "length" of the sphere is in the direction of the z-axis. Specify another vector here and the sphere will be generated in the direction specified.
foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (theta index) are the index along the current radial/theta rendering respectively.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created sphere to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.spheroid ( config, shape ) Alpha

Creates a spheroid using UV mapping. A spheroid is a sphere with different radii along two axes, so you could generate a stretched "egg". You can configure it to generate only part of the spheroid. The configuration available are:

centrePoint : location point, default [0, 0, 0]
longRadius : The spheroid is initially generated so its "longRadius" is the max radius of the spheroid along the z-axis, default 2.
widthRadius : The spheroid is initially generated so its "widthRadius" is the radius of the spheroid in the xy plane, default 1.
radialRes : "radial resolution". Around the spheroid will be rendered by the number of points specified. This will be reduced if only part of the spheroid is rendered. Default 30, Minimum 4
thetaRes : "theta resolution". Around the xz/yz plane, will be rendered by the number of points specified. This will be reduced if only part of the spheroid is rendered. Default 30, Miniumum 4
angleStart : Only specify if rendering part of the spheroid. Around the xy plane, what angle to render from. Default 0 degrees
angleEnd : Only specify if rendering part of the spheroid. Around the xy plane, what angle to render to. Default 360 degrees
thetaStart : Only specify if rendering part of the spheroid. Around the xz/yz plane, what angle to render from. Default/Min 0 degrees
thetaEnd : Only specify if rendering part of the spheroid. Around the xz/yz plane, what angle to render to. Default/Max 180 degrees
closePartialArc : Boolean. If only part of the spheroid is rendered, Do you want another face/quad to be rendered to "close" the arc. Default false
dirVector : Point representing vector. As described above, the spheroid is initially generated so that the "length" of the spheroid is in the direction of the z-axis. Specify another vector here and the spheroid will be generated in the direction specified.
foreignKey : either a number value, or a function f(location, i, j), where location is the location of the vertex being considered, and i (radial index), j (theta index) are the index along the current radial/theta rendering respectively.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created spheroid to. If null, a new Shape object is created and returned.

Returns: Shape shape

shape = Lib.Create.triangle ( config, shape ) Alpha

Creates a triangle. The configuration available are:

point1 : location point, default [0, 0, 1]
point2 : location point, default [1, 0, -1]
point3 : location point, default [-1, 0, -1]
longRes : "longitudinal resolution". The quad will be made up of smaller triangles/rectangles with the length/width no larger than this value. Default 5000
foreignKey : either a number value, or a function f(location), where location is the location of the vertex being considered.

Parameters:

Object config - - optional. an object containing configuration with keys/values as described.
Shape shape - - shape to add the created triangle to. If null, a new Shape object is created and returned.

Returns: Shape shape

Category: Generating lots of shapes efficiently

This is a bad pattern:

let shape = null;
for (let i = 0; i < Minodes.size(); ++i) {
  Data.read_Location(i, config.startPoint);
  config.endPoint[0] = config.startPoint[0];
  config.endPoint[1] = config.startPoint[1];
  config.endPoint[2] = config.startPoint[2]-1;
  config.startRadius = config.endRadius = Data.read_Span(i)/2;
  config.foreignKey = Data.read_ID(i);
  shape = Xshapes.Create.cylinder(config, shape);
}
shape.writeShape(OutVertices, OutFaces);

Because the shape object will store all faces and vertices internally in JS arrays, and will eventually hit the memory limit (crashing mXrap).

This is a better pattern:

let shape = null;
for (let i = 0; i < Minodes.size(); ++i) {
  Data.read_Location(i, config.startPoint);
  config.endPoint[0] = config.startPoint[0];
  config.endPoint[1] = config.startPoint[1];
  config.endPoint[2] = config.startPoint[2]-1;
  config.startRadius = config.endRadius = Data.read_Span(i)/2;
  config.foreignKey = Data.read_ID(i);
  shape = Xshapes.Create.cylinder(config, shape);
  shape.writeShape(OutVertices, OutFaces);
  shape.reset();
}

This is better because the internal verts and faces storage is cleared and reused (efficiently) via the reset() call, and writeShape() writes out the calculated faces and vertices as it goes.

If every object is exactly the same, except for the size and location, there is an even faster way. That is to create the shape once, and then apply a scale and translate transformation while writing out each instance of the shape, like so:

const cylinder = Xshapes.Create.cylinder(config, null);
const scale = [1,1,1];
const centre = [0,0,0];
for (let i = 0; i < Minodes.size(); ++i) {
  Minodes.read_Location(i, centre);
  scale[0] = scale[1] = Minodes.read_Span(i)/2;
  Xshapes.Op.rekeyShape(cylinder, Minodes.read_ID(i));
  cylinder.scaleTranslateAndWriteShape(scale, centre, OutVertices, OutFaces);
}

The scaleTranslateAndWriteShape function is responsible for transforming the shape's vertices and writing the transformed shape to the output. The rekeyShape function also adjusts the "foreign key", so that the verts have the right foreign IDs for each instance of the shape.

More generally, we can apply a transformation matrix to the vertices of a shape as it is written out, using the transform4AndWriteShape function:

const cylinder = Xshapes.Create.cylinder(config, null);

const rotationQuat = glMatrix.quat.create(); // identity quat
const transformMat4 = glMatrix.mat4.create();

for (let i = 0; i < Minodes.size(); ++i) {
  Minodes.read_Location(i, centre);
  scale[0] = scale[1] = Minodes.read_Span(i)/2;

  glMatrix.mat4.fromRotationTranslationScale(transformMat4,
    rotationQuat, // rotation quaternion
    centre,       // translation vector
    scale         // scaling vector
  );

  Xshapes.Op.rekeyShape(cylinder, Minodes.read_ID(i));
  cylinder.transform4AndWriteShape(transformMat4, OutVertices, OutFaces);
}

In this case the transformation matrix method is more verbose than the scaleTranslateAndWriteShape method, but it also allows us to apply rotations to the generated shape. Note that fromRotationTranslationScale is simply a convenience method for building such a transformation matrix; it is also possible to build such a matrix from multiple elementary operations, e.g.:

glMatrix.mat4.identity(transformMat4);
glMatrix.mat4.translate(transformMat4, transformMat4, planeCentre);
glMatrix.mat4.rotateZ(transformMat4, transformMat4, -strike);
glMatrix.mat4.rotateY(transformMat4, transformMat4, dip);
glMatrix.mat4.rotateZ(transformMat4, transformMat4, rake);

An even more general form of transforming output is available through the transformViaFunctionAndWriteShape method, which accepts a transformation function. The transformation function should receive a vec3 as input, and return a transformed vec3 as output (this is allowed to be the same vec3, for efficiency). As an example:

const myTransform = function(vec) {
  vec[0] = scaleX * vec[0];
  vec[1] = scaleY * vec[1];

  glMatrix.vec3.add(vec, vec, offset);

  return vec;
};

...
cylinder.transformViaFunctionAndWriteShape(myTransform, OutVertices, OutFaces);

Category: Graphics

These functions create LinesAdapter(s) and LineHandle(s).

In mXrap, surfaces are rendered using two tables, a Vertices table (describing points) and a Lines table (describing lines by linking line segments defined). A LinesAdapter object contains the configuration required to define what your Vertices and Lines tables are, and the functions to write to the relevant fields.

A LineHandle object is based off a LinesAdapter. It represents a line in progress, which you can extend by adding new vertices. You can create multiple LineHandle objects based off a LinesAdapter, and then concurrently add new vertices to them.

↑LineHandle = Lib.Graphics.createLine ( ↑LineHandle, ↓LinesAdapter, ↓location, ↓fk ) Alpha

Creates a new LineHandle (which represents a new line) for the LinesAdapter provided. Optionally takes in a location and fk - which then forms the first vertex of this line

Parameters:

LineHandle ↑LineHandle - - optional, LineHandle object to replace. A new LineHandle object is created and returned if this is null.
LinesAdapter ↓LinesAdapter - - adapter to create this line in.
Point ↓location - - location of first vertex, optional
Number ↓fk - - key of first vertex, optional. Both location and fk must be provided to add the first vertex.

Returns: LineHandle ↑LineHandle

↑LinesAdapter = Lib.Graphics.createLinesAdapter ( ↓Vertices, ↓write_VID, ↓write_Location, ↓write_FK, ↓Lines, ↓write_ID, ↓write_LineID, ↓write_LineOrder, ↓write_VertexID ) Alpha

Creates a LinesAdapter based on the two input tables and their write functions.

Parameters:

Table ↓Vertices - - vertices table
Function ↓write_VID - - write function for vertices table, for an ids column. ID for the vertices table
Function ↓write_Location - - write function for vertices table, for a points column. Location of the vertices
Function ↓write_FK - - write function for vertices table, for an ids column. Foreign key of the vertices.
Table ↓Lines - - lines table
Function ↓write_ID - - write function for lines table, for an ids column. Unique ID for the lines table
Function ↓write_LineID - - write function for lines table, for an ids column. ID that determines which line this segment refers to.
Function ↓write_LineOrder - - write function for lines table, for an ids column. ID that determines the order of the segments of this line
Function ↓write_VertexID - - write function for lines table, for an ids column. ID of the vertex for this segment of the line

Returns: LinesAdapter ↑LinesAdapter

↑LinesAdapter = Lib.Graphics.createPresetLinesAdapter ( ↓Vertices, ↓Lines ) Alpha

Creates a LinesAdapter based on the two input tables Vertices and Lines. This function assumes the relevant fields in Vertices and Lines are named exactly as expected - ie. for Vertices, "ID" (ids), "Location" (points), "FK" (ids/numbers), and for Faces, "ID", "LineID", "LineOrder", "VertexID" (ids)

Parameters:

Table ↓Vertices - - Vertices table
Table ↓Lines - - Lines table

Returns: LinesAdapter ↑LinesAdapter

Category: Graphics

These functions create GraphicsAdapter(s).

In mXrap, surfaces are rendered using two tables, a Vertices table (describing points) and a Faces table (describing surfaces by linking the points defined). A GraphicsAdapter object contains the configuration required to define what your Vertices and Faces tables are, and the functions to write to the relevant fields.

graphicsAdapter = Lib.Graphics.createAdapter ( Vertices, write_VID, write_Location, write_FK, Faces, write_FID, write_V1, write_V2, write_V3, write_V4 ) Alpha

Creates a GraphicsAdapter based on the two input tables and their write functions.

Parameters:

Table Vertices - - vertices table
Function write_VID - - write function for vertices table, for an ids column. ID for the vertices table
Function write_Location - - write function for vertices table, for a points column. Location of the vertices
Function write_FK - - write function for vertices table, for an ids column. Foreign key of the vertices.
Table Faces - - faces table
Function write_FID - - write function for faces table, for an ids column. ID for the faces table
Function write_V1 - - write function for faces table, for an ids column. ID of the first vertex for this face
Function write_V2 - - write function for faces table, for an ids column. ID of the second vertex for this face
Function write_V3 - - write function for faces table, for an ids column. ID of the third vertex for this face
Function write_V4 - - write function for faces table, for an ids column. ID of the fourth vertex for this face

Returns: GraphicsAdapter graphicsAdapter

graphicsAdapter = Lib.Graphics.createPresetAdapter ( Vertices, Faces ) Alpha

Creates a GraphicsAdapter based on the two input tables Vertices and Faces. This function assumes the relevant fields in Vertices and Faces are named exactly as expected - ie. for Vertices, "ID" (ids), "Location" (points), "FK" (ids), and for Faces, "ID", "V1", "V2", "V3", "V4" (ids)

Parameters:

Table Vertices - - Vertices table
Table Faces - - Faces table

Returns: GraphicsAdapter graphicsAdapter

Category: Op

These functions perform operations on Shape objects.

shape = Lib.Op.addShape ( shape, shapeToAdd ) Alpha

Adds the input shapeToAdd to the input shape.

Parameters:

Shape shape - - input shape
Shape shapeToAdd - - input shape to be added

Returns: Shape shape - - input shape that was added to

clonedShape = Lib.Op.cloneShape ( shape ) Alpha

Clones input Shape object and returns the new Shape object

Parameters:

Shape shape

Returns: Shape clonedShape

shape = Lib.Op.copyShape ( shape, shapeToCopy ) Alpha

Clears a shape and makes it a copy of another shape.

Parameters:

Shape shape - - shape to be cleared and made a copy of the other specified shape
Shape shapeToCopy - - shape to copy

Returns: Shape shape - - first input shape

shape = Lib.Op.createShape ( ) Alpha

Creates an empty Shape object.

Parameters:

Returns: Shape shape

shape = Lib.Op.rekeyShape ( shape, keyFunction ) Alpha

Modifies the foreign key for the vertices of the input shape

Parameters:

Shape shape - - input shape
Function keyFunction - - you can specify either a value here (then the Shape will have that value for its foreign key), or a function f(location, oldKey) where location is the location of each vertex, and oldKey is the current value of the foreign key for that vertex.

Returns: Shape shape - - input shape that was rekeyed

shape = Lib.Op.scaleAndWriteShape ( shape, vec3, graphicsAdapter ) Alpha

Writes a scaled version of the shape. Unlike scaleShape, the input shape remains unchanged.

Parameters:

Shape shape - - input shape
Array vec3 - - vector defining scaling in the xyz axes
GraphicsAdapter graphicsAdapter - - the graphics adapter to write to

Returns: Shape shape - - input shape

shape = Lib.Op.scaleShape ( shape, vec3 ) Alpha

Scales input shape by input vector

Parameters:

Shape shape - - input shape
Array vec3 - - vector defining scaling in the xyz axes

Returns: Shape shape - - input shape that was scaled

shape = Lib.Op.scaleTranslateAndWriteShape ( shape, scale3, translate3, graphicsAdapter ) Alpha

Writes a scaled and translated version of the shape. The current shape is not modified.

Parameters:

Shape shape - - input shape
Array scale3 - - input array of 3 elements. First element is scaling for x-axis, second element is scaling for y-axis, third element is scaling for z-axis
Array translate3 - - input array of 3 elements defining the vector by which to translate the shape.
GraphicsAdapter graphicsAdapter - - the graphics adapter to write to

Returns: Shape shape - - input shape

shape = Lib.Op.transform3AndWriteShape ( shape, mat3, graphicsAdapter ) Alpha

Writes a transformed version of the shape. Unlike transform3Shape, the input shape remains unchanged.

Parameters:

Shape shape - - input shape
glMatrix mat3 - - 3x3 matrix defining transformation. Matrix is an array with elements defined according to glMatrix library
GraphicsAdapter graphicsAdapter - - the graphics adapter to write to

Returns: Shape shape - - input shape

shape = Lib.Op.transform3Shape ( shape, mat3 ) Alpha

Transforms input shape by input 3x3 matrix

Parameters:

Shape shape - - input shape
glMatrix mat3 - - 3x3 matrix defining transformation. Matrix is an array with elements defined according to glMatrix library

Returns: Shape shape - - input shape that was transformed

shape = Lib.Op.transform4AndWriteShape ( shape, mat4, graphicsAdapter ) Alpha

Writes a transformed version of the shape. Unlike transform4Shape, the input shape remains unchanged.

Parameters:

Shape shape - - input shape
glMatrix mat4 - - 4x4 matrix defining transformation. Matrix is an array with elements defined according to glMatrix library
GraphicsAdapter graphicsAdapter - - the graphics adapter to write to

Returns: Shape shape - - input shape

shape = Lib.Op.transform4Shape ( shape, mat4 ) Alpha

Transforms input shape by input 4x4 matrix

Parameters:

Shape shape - - input shape
glMatrix mat4 - - 4x4 matrix defining transformation. Matrix is an array with elements defined according to glMatrix library

Returns: Shape shape - - input shape that was transformed

shape = Lib.Op.transformViaFunctionAndWriteShape ( shape, func_vec3, graphicsAdapter ) Alpha

Writes a transformed version of the shape. Unlike transformViaFunctionShape, the input shape remains unchanged. The transformation uses a function w = f(v), where v is an input Point and w is the returned Point. The function may modify and return the original Point rather than create a new Point.

Parameters:

Shape shape - - input shape
Function func_vec3 - - input function
GraphicsAdapter graphicsAdapter - - the graphics adapter to write to

Returns: Shape shape - - input shape

shape = Lib.Op.transformViaFunctionShape ( shape, func_vec3 ) Alpha

Transforms input shape by a function w = f(v), where v is an input Point and w is the returned Point. The function may modify and return the original Point rather than create a new Point.

Parameters:

Shape shape - - input shape
Function func_vec3 - - input function

Returns: Shape shape - - input shape that was transformed

shape = Lib.Op.translateAndWriteShape ( shape, vec3, graphicsAdapter ) Alpha

Writes a translated version of the shape. Unlike translateShape, the input shape remains unchanged.

Parameters:

Shape shape - - input shape
Array vec3 - - vector defining translation
GraphicsAdapter graphicsAdapter - - the graphics adapter to write to

Returns: Shape shape - - input shape

shape = Lib.Op.translateShape ( shape, vec3 ) Alpha

Translates input shape by input vector

Parameters:

Shape shape - - input shape
Array vec3 - - vector defining translation

Returns: Shape shape - - input shape that was translated

Lib.Op.writeShape ( shape, graphicsAdapter ) Alpha

Writes a Shape to a GraphicsAdapter object.

Parameters:

Shape shape
GraphicsAdapter graphicsAdapter

Category: Path

These functions plot various curve types along a LineHandle.

↑numPointsWritten = Lib.Path.cubicBezier ( ↓LineHandle, ↓point1, ↓point2, ↓point3, ↓point4, ↓fk, ↓numPoints, ↓excludeFirst ) Alpha

Plots a cubic bezier path from point 1 to point 4 using points 2 and 3 as a reference point and writes it to the specified LineHandle.

Parameters:

LineHandle ↓LineHandle - - the line handle to write to.
Point ↓point1 - - point to start the path
Point ↓point2 - - reference middle point
Point ↓point3 - - reference middle point
Point ↓point4 - - point to end the path
Number ↓fk - - key for the path (when writing to the LineHandle)
Number ↓numPoints - - number of points to generate on the path
Boolean ↓excludeFirst - - optional. If true, it excludes the first point on the path. This is useful when generating multiple paths on a single line.

Returns: Number ↑numPointsWritten - - number of points written to the LineHandle

↑numPointsWritten = Lib.Path.cubicBezierSmart ( ↓LineHandle, ↓point1, ↓point2, ↓point3, ↓point4, ↓fk, ↓threshold, ↓excludeFirst ) Alpha

Plots a cubic bezier path from point 1 to point 4 using points 2 and 3 as a reference point and writes it to the specified LineHandle. The smart variant of this function auto-generates the number of points required so that the distance between two points on the path is close to the threshold distance

Parameters:

LineHandle ↓LineHandle - - the line handle to write to.
Point ↓point1 - - point to start the path
Point ↓point2 - - reference middle point
Point ↓point3 - - reference middle point
Point ↓point4 - - point to end the path
Number ↓fk - - key for the path (when writing to the LineHandle)
Number ↓threshold - - threshold distance
Boolean ↓excludeFirst - - optional. If true, it excludes the first point on the path. This is useful when generating multiple paths on a single line.

Returns: Number ↑numPointsWritten - - number of points written to the LineHandle

↑numPointsWritten = Lib.Path.linear ( ↓LineHandle, ↓point1, ↓point2, ↓fk, ↓numPoints, ↓excludeFirst ) Alpha

Plots a linear path from point 1 to point 2 and writes it to the specified LineHandle.

Parameters:

LineHandle ↓LineHandle - - the line handle to write to.
Point ↓point1 - - point to start the path
Point ↓point2 - - point to end the path
Number ↓fk - - key for the path (when writing to the LineHandle)
Number ↓numPoints - - number of points to generate on the path
Boolean ↓excludeFirst - - optional. If true, it excludes the first point on the path. This is useful when generating multiple paths on a single line.

Returns: Number ↑numPointsWritten - - number of points written to the LineHandle

↑numPointsWritten = Lib.Path.linearSmart ( ↓LineHandle, ↓point1, ↓point2, ↓fk, ↓threshold, ↓excludeFirst ) Alpha

Plots a linear path from point 1 to point 2 and writes it to the specified LineHandle. The smart variant of this function auto-generates the number of points required so that the distance between two points on the path is at most the threshold distance

Parameters:

LineHandle ↓LineHandle - - the line handle to write to.
Point ↓point1 - - point to start the path
Point ↓point2 - - point to end the path
Number ↓fk - - key for the path (when writing to the LineHandle)
Number ↓threshold - - threshold distance
Boolean ↓excludeFirst - - optional. If true, it excludes the first point on the path. This is useful when generating multiple paths on a single line.

Returns: Number ↑numPointsWritten - - number of points written to the LineHandle

↑numPointsWritten = Lib.Path.quadraticBezier ( ↓LineHandle, ↓point1, ↓point2, ↓point3, ↓fk, ↓numPoints, ↓excludeFirst ) Alpha

Plots a quadratic bezier path from point 1 to point 3 using point2 as a reference point and writes it to the specified LineHandle.

Parameters:

LineHandle ↓LineHandle - - the line handle to write to.
Point ↓point1 - - point to start the path
Point ↓point2 - - reference middle point
Point ↓point3 - - point to end the path
Number ↓fk - - key for the path (when writing to the LineHandle)
Number ↓numPoints - - number of points to generate on the path
Boolean ↓excludeFirst - - optional. If true, it excludes the first point on the path. This is useful when generating multiple paths on a single line.

Returns: Number ↑numPointsWritten - - number of points written to the LineHandle

↑numPointsWritten = Lib.Path.quadraticBezierSmart ( ↓LineHandle, ↓point1, ↓point2, ↓point3, ↓fk, ↓threshold, ↓excludeFirst ) Alpha

Plots a quadratic bezier path from point 1 to point 3 using point2 as a reference point and writes it to the specified LineHandle. The smart variant of this function auto-generates the number of points required so that the distance between two points on the path is close to the threshold distance

Parameters:

LineHandle ↓LineHandle - - the line handle to write to.
Point ↓point1 - - point to start the path
Point ↓point2 - - reference middle point
Point ↓point3 - - point to end the path
Number ↓fk - - key for the path (when writing to the LineHandle)
Number ↓threshold - - threshold distance
Boolean ↓excludeFirst - - optional. If true, it excludes the first point on the path. This is useful when generating multiple paths on a single line.

Returns: Number ↑numPointsWritten - - number of points written to the LineHandle

Category: Simple

These functions create Shape objects. The functions in this category are simple constructors that allow you to create shapes quickly with minimal options. If you are after the full range of options for each shape, take a look at the Create category.

↑shape = Lib.Simple.arrow ( ⇅shapeToAddTo, ↓startPoint, ↓endPoint, ↓foreignKey ) Alpha

Creates an arrow.

Parameters:

Shape ⇅shapeToAddTo - - if null, then a new shape is created and returned
Point ↓startPoint - - location point
Point ↓endPoint - - location point. The arrow head is at the end point.
Number ↓foreignKey - - number/ID to associate with vertices