PD CLASS

Provides tools and utilities to support building modelling and analysis.

21 Dec, 2024
Dr. Andrew Marsh

PD : object

Provides tools and utilities to support building modelling and analysis.

The PD namespace forms the core infrastructure for any interactive application that displays, edits and/or interacts with the BIM classes. It provides global state, actions, events and undo/redo, as well as a wide range of utilities for working with WebGL and front-end frameworks such as Vue, React, Knockpout and Enyo. It also provides a range of fundamental geometry creation, mesh generation, scene visualisation and user interaction management tools.

Kind: global namespace
Author: drajmarsh

PD.CAD

Provides a high-level API for generating complex 2D and 3D forms using the OpenCascade geometry kernel.

This class is also exposed as just CAD within the built-in code editor panel of each framework application that uses it.

The methods of this class can be used to generate complex geometry by creating, transforming and combining primitive shapes. Shapes created using these methods are cached by default for performance reasons and are automatically added to and removed from the model as they are created, transformed and modified. The model property is an array that stores the final geometric output that is converted to a mesh and sent back to the host application for display or further processing.

The aim of this class is to provide a relatively simple and intuitive set of commands that handle the majority of use cases and abstract away many of the complexities of managing a CAD model and handling geometry. However, these commands do not expose the full range of capabilities of the OpenCascade engine.

Going Deeper

Sitting beneath the higher-level methods in CAD is OCC, which provides lower-level methods that interface directly with OpenCascade. In fact, most of the creation, transformation and modification methods in CAD have corresponding lower-level methods with similar names in OCC that are called to do the actual work, which you can see if you look at the process logs.

These lower-level methods are more flexible and expose more capabilities of the engine, but have more complex input parameters, are not cached, and require you to manually add and remove the resulting shapes shapes to/from the CAD model yourself using the add and remove methods. When you need to move beyond the simpler CAD API, you are strongly encouraged to work directly with OCC as well.

For those who really like a challenge, the raw OpenCascade engine is also exposed via the oc object, so you can use its methods to access the full range of capabilities. Again, you can use the add and remove methods to add and remove any generated oc.TopoDS_Shape to/from the CAD model.

Caching

CAD has the option of caching its primitives and operations so that previous geometry kernel results can be reused instead of regenerated. This is on by default and can have significant performance benefits as very often the individual parts of many models are repetitive. This is particularly effective when a user is iteratively or interactively editing or refining just one or two primitives within a more complex boolean solid or model, as it means that only those steps with modified input parameters need to be regenerated each time.

Kind: static class of PD
Author: drajmarsh

CAD.Path

A utility class for creating a 2D path which may contain line, arc, bezier, spline and fillet segments.

This class is also exposed as just CAD.Path within the built-in code editor panel of each framework application that uses it.

After adding one or more segments, the path can be retrieved as either a oc.TopoDS_Wire or a oc.TopoDS_Face for subsequent use with other geometry operations.

Kind: static class of CAD
Author: drajmarsh

new PD.CAD.Path([point])

Creates a new 2D path starting at the optional [x,y] point (or [0,0] by default) and containing one or more line, arc, bezier, bspline and.or fillet segments.

ParamTypeDescription
[point]Array.<number>An [x,y] vector array defining the start position, defaults to origin.

Example

const path = new PD.CAD.Path()
     .moveTo([ 0, -1000 ])
     .lineTo([ 0,     0 ])
     .fillet(500)
     .lineTo([ 1000, 0 ])
     .arcTo([ 1500, 500 ], [ 1000, 1000 ])
     .bezierTo([ [ 0, 1000 ], [ 0, 2000 ] ])
     .bsplineTo([ [ 0, 3000 ], [ -500, 3500 ], [ -1000, 3000 ], [ -1500, 3500 ], [ -2000, 3000 ] ])
     .end(true, false);

const face = path.asFace();
const wire = path.asWire();

caD.Path.asWire([reverse]) ⇒ oc.TopoDS_Wire

Converts the current path to a wire and adds it to the CAD model.

Kind: instance method of Path
Returns: oc.TopoDS_Wire - Returns the current sketch as a wire.

ParamTypeDescription
[reverse]booleanWhether or not to reverse the vertex order, defaults to false..

caD.Path.asFace([reverse]) ⇒ oc.TopoDS_Face

Converts the current path to a face and adds it to the CAD model.

Kind: instance method of Path
Returns: oc.TopoDS_Face - Returns the current sketch as a face.

ParamTypeDescription
[reverse]booleanWhether or not to reverse the vertex order, defaults to false..

caD.Path.moveTo(point) ⇒ Path

Begins a new path or a new part of an existing path at the given [x,y] point.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
pointArray.<number>An [x,y] vector array defining the start position.

caD.Path.lineTo(point) ⇒ Path

Adds a line segment from the previous point to the given [x,y] point.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
pointArray.<number>An [x,y,z] vector array defining the end of the segment.

caD.Path.arcTo(through, point) ⇒ Path

Adds an arc segment from the previous point, through the given [x,y] point on the arc, to the given [x,y] point.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
throughArray.<number>An [x,y,z] vector array defining a point lying somewhere on the arc.
pointArray.<number>An [x,y,z] vector array defining the end of the arc segment.

caD.Path.bezierTo(controlPoints) ⇒ Path

Adds an bezier curve from the previous point through the [x,y] control points.

This constructs an order-N Bezier Curve where the first N-1 points are control points and the last point is the end point of the curve.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
controlPointsArray.<Array.<number>>An array of [x,y,z] vector arrays defining curve control points.

caD.Path.bsplineTo(controlPoints) ⇒ Path

Adds a BSpline from the previous point through the set of [x,y] control points.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
controlPointsArray.<Array.<number>>An array of [x,y,z] vector arrays defining curve control points.

caD.Path.fillet(radius) ⇒ Path

Adds a fillet with the given radius between the current and next segment.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
radiusnumberThe fillet radius in model units.

caD.Path.addWire(wire) ⇒ Path

Adds a new wire to the current path.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
wireoc.TopoDS_WireThe wire to add.

caD.Path.addCircle(center, radius, [reversed]) ⇒ Path

Adds a closed circle to the current path.

This method can be used to punch a circular hole in the existing face if it lies entirely within a bounding path segment. You may need to set the reversed argument to ensure the correct orientation.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
centerArray.<number>An [x,y,z] vector array defining the center point of the circle.
radiusnumberThe circle radius in model units.
[reversed]booleanWhether or not to reverse the vertex order the face, defaults to false.

caD.Path.end([close], [reverse]) ⇒ Path

Completes the path and generates the internal representation.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
[close]booleanWhether or not to close the current shape, defaults to false.
[reverse]booleanWhether or not to reverse the vertex order, defaults to false..

caD.Path.close([reverse]) ⇒ Path

Completes the current part of the path as a closed loop.

Kind: instance method of Path
Returns: Path - Returns this path instance to support method chaining.

ParamTypeDescription
[reverse]booleanWhether or not to reverse the vertex order, defaults to false..

CAD.model : Array.<oc.TopoDS_Shape> | Array.<Shape>

An array storing all the shapes that make up the final model.

Shapes created using CAD methods are automatically added to and removed from the model as they are created, transformed and modified. However all these creations, transformations and modifications rely on lower-level methods from OCC to do the actual work. You can use these lower-level methods directly to create interim geometry, but they will not be cached and will not become part of the final model until you specifically use the add method to add them. You can also use the remove to remove shapes from the model.

The add method is pretty robust in that it will only add shapes if they are valid and do not already exist within the model. You should therefore always use that method rather than pushing shapes directly into the model array.

Kind: static property of CAD

CAD.useCache : boolean

Whether or not to cache primitives and operations.

Kind: static property of CAD

CAD.font : object | null

The font to use for 3D text.

Kind: static property of CAD

CAD.isCancelled : boolean

A flag indicating that user has cancelled process.

Kind: static property of CAD

CAD.logLevel : number

The level of logging to display.

Kind: static property of CAD

CAD.processLog : Array.<LogEntry>

Maintains a log of each operation.

Kind: static property of CAD

CAD.checkCache(caller, args, generatorFn) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Hashes input arguments and checks the cache for that hash.

This method first checks if a cached result exists and, if so, returns it. If not, it executes the callback and caches the result.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the results of the cached function.

ParamTypeDescription
callerstringThe name of the calling method.
argsArray.<any>An array of arguments defining the operation.
generatorFnfunctionA callback function to execute the operation.

CAD.clearCache()

Removes all items from the cache to clear memory.

Kind: static method of CAD

CAD.add(…shapes)

Add a shape or array of shapes to the generated model.

Kind: static method of CAD

ParamTypeDescription
…shapesoc.TopoDS_ShapeOne or more shapes to add.

CAD.remove(…shapes)

Removes a shape or array of shapes from the generated model.

Kind: static method of CAD

ParamTypeDescription
…shapesoc.TopoDS_ShapeOne or more shapes to remove.

CAD.addWire(points, [closed]) ⇒ oc.TopoDS_Wire

Adds an infinitely thin wire with one or more segments to the scene.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Wire - Returns a wire.

ParamTypeDescription
pointsArray.<Array.<number>>An array of [x,y,z] vector arrays defining the vertices of the wire.
[closed]booleanAn optional flag indicating that the wire is a closed loop, defaults to false.

CAD.addWires(contours) ⇒ Array.<oc.TopoDS_Wire>

Adds an array of infinitely thin wires with one or more point contours to the scene.

This method will cache the generated wires if caching is enabled.

Kind: static method of CAD
Returns: Array.<oc.TopoDS_Wire> - Returns an array of one or more wires.

ParamTypeDescription
contoursArray.<Array.<Array.<number>>>An array of lines, each containing at least two [x,y,z] vector arrays defining the vertices of the wire.

Example

const text_lines = PD.VectorFont.generateText('This is a test.', PD.ALIGN.CENTER);
CAD.addWires(text_lines);

CAD.addCircle(radius, [outline]) ⇒ oc.TopoDS_Face | oc.TopoDS_Wire

Adds a flat circular face/wire at the origin to the scene.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Face | oc.TopoDS_Wire - Returns a circular shape.

ParamTypeDescription
radiusnumberThe radius of the circle.
[outline]booleanAn optional flag for the method to return the outline of the shape as a wire rather than as a shape, defaults to false.

CAD.addPolygon(points, [outline]) ⇒ oc.TopoDS_Face | Array.<oc.TopoDS_Wire>

Adds a flat multi-sided primitive face/wire to the scene.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Face | Array.<oc.TopoDS_Wire> - Returns a polygonal shape or the wires that bound it.

ParamTypeDescription
pointsArray.<Array.<number>>An array of [x,y,z] vector arrays defining the vertices of the polygon.
[outline]booleanAn optional flag for the method to return the outline of the shape as one or more wires rather than as a face, defaults to false.

CAD.addBox(width, depth, height, [centered]) ⇒ oc.TopoDS_Shape

Adds a rectangular prism to the scene.

The box is created with its bottom-left at the origin and its width in the X-axis, depth in the Y-axis and height in Z-axis. For more complex box shapes with different origins, orientations and rounded edges, you can use the cuboid method directly.

      (0,d,h) +---------------+ (w,d,h)
           Z /               /|  Y
           |/               / | /
   (0,0,h) +---------------+  |
           |               |  + (w,d,0)
           |               | /
           |               |/
   (0,0,0) +---------------+ (w,0,0) - X

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a rectangular prism shape.

ParamTypeDescription
widthnumberThe size of the box in the X-axis, defaults to 1000mm (1m).
depthnumberThe size of the box in the Y-axis, defaults to 1000mm (1m).
heightnumberThe size of the box in the Z-axis, defaults to 1000mm (1m).
[centered]booleanAn optional flag indicating that the box should be centered at the origin rather than at its bottom-left, defaults to false.

CAD.addBoxByMinMax(min, min) ⇒ oc.TopoDS_Shape

Adds a new rectangular prism to the scene using points at its minimum and maximum extents.

The box is created at the origin with its width in the X-axis, depth in the Y-axis and height in Z-axis. For more complex box shapes with different origins, orientations and rounded edges, you can use the cuboid method directly.

                             (max)
           Z  +---------------+
           | /               /|  Y
           |/               / | /
           +---------------+  |/
           |               |  +
           |               | /
           |               |/
           +---------------+ -- -- X
        (min)

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a rectangular prism shape.

ParamTypeDescription
minArray.<number>An [x,y,z] vector array defining the minimum box extents.
minArray.<number>An [x,y,z] vector array defining the maximum box extents.

CAD.addWedge(width, depth, height, [taperHeight], [taperWidth]) ⇒ oc.TopoDS_Shape

Adds a wedge shape at the origin along the Y-axis to the scene.

The construction of the wedge can be controlled by the number of arguments you provide to this method. The first three size values are absolutely required, but you can provide either a an additional height value, a height and width, or the minimum and maximum X and Z coordinates.

         Z
         |
      (0,0,h)             (w,d,h)  Y
         4-------------------5__  /
         |'' 3---------------|---2
         |  /(0,d,0)     (w,d,0)/
         | /                 | /
         |/                  |/
         +-------------------+ -- X
      (0,0,0)             (w,0,0)

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a wedge shape.

ParamTypeDescription
widthnumberThe size of the wedge in the X-axis.
depthnumberThe size of the wedge in the Y-axis.
heightnumberThe size of the wedge in the Z-axis.
[taperHeight]number | Array.<number>The height of the tapered end as a number or [min,max] array, defaults to [0,0].
[taperWidth]number | Array.<number>The width of the tapered end as a number or [min,max] array, defaults to [0,width].

Example

/// Define just the size.
PD.CAD.addWedge(2000, 4000, 1500);

Example

/// Define the height and width at end.
const width = 2000;
const depth = 4000;
const height = 1500;
const end_width = 0.5 * width;
const end_height = 0.25 * height;
PD.CAD.addWedge(width, depth, height, end_height, end_width);

Example

/// Define X and Z positions at each end.
const width  =  2000;
const depth  =  4000;
const height =  1500;
const x_min  =  0.40 * width;
const x_max  =  0.75 * width;
const z_min  = -0.25 * height;
const z_max  =  0.25 * height;
PD.CAD.addWedge(width, depth, height, [ x_min, x_max ], [ z_min, z_max ]);

CAD.addPyramid(width, depth, height, [truncate]) ⇒ oc.TopoDS_Shape

Construct a pyramid shape at the origin in the Z-axis.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a wedge shape.

ParamTypeDescription
widthnumberThe size of the wedge in the X-axis.
depthnumberThe size of the wedge in the Y-axis.
heightnumberThe size of the wedge in the Z-axis.
[truncate]numberThe fractional truncation amount (0 to 1), defaults to 1.0.

Example

CAD.addPyramid(4000, 3000, 2000);

Example

CAD.addPyramid(4000, 3000, 4000, 0.5);

CAD.addDome(radius) ⇒ oc.TopoDS_Shape

Add a new hemispherical shape at the origin.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a hemispherical shape.

ParamTypeDescription
radiusnumberThe distance of the dome surface from the centre.

CAD.addSphere(radius) ⇒ oc.TopoDS_Shape

Add a new spherical shape at the origin.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a spherical shape.

ParamTypeDescription
radiusnumberThe distance of the spherical surface from the centre.

CAD.addCylinder(radius, height, [centered]) ⇒ oc.TopoDS_Shape

Adds a cylindrical shape with flat ends to the scene.

The cylinder is created with its axis running vertically up from the origin. You can use transformation methods to move, scale and rotate it once created. For more complex cylindrical shapes with different positions, orientations and rounded ends, you can use the cylinder method directly.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a cylindrical shape.

ParamTypeDescription
radiusnumberThe distance of the cylinder surface from the centre axis.
heightnumberThe distance between the top and bottom planes.
[centered]numberAn optional flag indicating that the cylinder should be created with its geometric center at the origin rather than the center of its base, otherwise the bottom-left, defaults to false.

CAD.addCapsule(radius, height, [endRadius]) ⇒ oc.TopoDS_Shape

Adds a cylindrical shape with rounded ends to the scene.

The capsule is created with its axis running vertically up from the origin. You can use transformation methods to move, scale and rotate it once created. For more complex cylindrical shapes with different positions, orientations and fillet radii, you can use the cylinder method directly.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a cylindrical shape.

ParamTypeDescription
radiusnumberThe distance of the cylinder surface from the centre axis.
heightnumberThe distance between the top and bottom planes.
[endRadius]numberThe radius of the rounded end of the capsule (0 to radius), defaults to the cylinder radius.

CAD.addCone(radiusBot, radiusTop, height, [centered]) ⇒ oc.TopoDS_Shape

Construct a conical primitive shape at the origin.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a conical shape.

ParamTypeDescription
radiusBotnumberThe radius at the bottom of the cone.
radiusTopnumberThe radius at the top of the cone, typically 0.
heightnumberThe distance between the top and bottom planes.
[centered]numberAn optional flag indicating that the given position represents the center of the cone rather than the bottom-left, defaults to false.

CAD.addTorus(radiusRing, radiusPipe) ⇒ oc.TopoDS_Shape

Construct a toroidal primitive shape at the origin.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a toroidal shape.

ParamTypeDescription
radiusRingnumberThe distance of the pipe center from main centre.
radiusPipenumberThe distance of the pipe surface from the pipe centre.

CAD.addPrism(radius, sides, height) ⇒ oc.TopoDS_Shape

Construct a regular prism at the origin.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a shape sewn together from multiple faces.

ParamTypeDescription
radiusnumberThe radius of the regular prism.
sidesnumberThe number of sides of the prism (3 to 256).
heightnumberThe distance between the top and bottom planes.

CAD.addHull(shapes, [tolerance], [makeCopy]) ⇒ oc.TopoDS_Shape

Construct a convex hull shape from points or shape(s).

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a solid hull shape sewn from multiple faces.

ParamTypeDescription
shapesArray.<Array.<number>> | oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>An array of shape(s) and/or [x,y,z] point clouds.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.
[makeCopy]booleanApply to a copy and keep original shape(s) in the model, defaults to false.

CAD.addHullChain(shapes, [tolerance], [makeCopy]) ⇒ oc.TopoDS_Shape

Construct a shape from a series of unioned convex hulls.

The order of shapes within the shapes array will affect the resulting hull shape as each pair is grouped consecutively.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a hull shape sewn from multiple faces.

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape> | Array.<Array.<Array.<number>>>A shape or array of shapes/points to create a hull from.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.
[makeCopy]booleanApply to a copy and keep original shape in the model, defaults to false.

CAD.addIndexedShell(points, faces, [tolerance]) ⇒ oc.TopoDS_Shape

Construct a shell by sewing together a series of facets.

This method takes a collection of indexed planar faces and attempts to construct a connected TopoDS_Shell out of them. The faces do not have to be in any particular order or have shared edges and/or vertices as this process will do its best work out the interconnection relationships between faces and create shared edges.

Note that this method only deals with indexed face data, which means that all the vertices in the shape are stored in one array (vertices) and all the faces in another (faces). The vertices must all be [x,y,z] vector arrays and each face is defined by or contains an array of ordinal indexes of each vertex that make up its boundaries.

Thus, each entry in the faces array may be either an array of vertex indices or an object containing a boundaries property that is an array. If the boundaries array contains one or more contours of vertex indices, then the first will be considered as the outer boundary and any subsequent boundaries treated as holes within the face. If the boundary is a flat array of vertex indices, it will be considered as an outer boundary with no holes.

To be valid, each boundary and hole array must contain at least three (3) or more planar vertex indices defining each of its corners.

If you have data in which vertices are not given separately, but where each face is a list of [x,y,z] vector arrays, use the CAD.addFacettedShell method instead of this one.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a shape sewn together from indexed faces.

ParamTypeDescription
pointsArray.<Array.<number>>An array of [x,y,z] vector arrays defining the corners and edges of the shape.
facesArray.<Array.<number>> | Array.<object>An array of boundaries and/or contours, each containing ordinal indexes of the vertices that make up each face.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.

CAD.addFacetedShell(facets, [tolerance]) ⇒ oc.TopoDS_Shape

Construct a shape from the JSON representation of a simple faceted mesh.

There are several variants of point/face meshes, and this is one of the less optimised as it does not separate points and faces. Rather, it uses arrays of vertices to define face boundaries, which means that coincident vertices are repeated. However, in a faceted mesh, coincident vertices are very likely to have different surface normals,

A faceted mesh contains a list of all the facets that make up a shape. Each facet may optionally have a plane equation, but must always have an array of closed boundaries that define its outline. The first array of boundary points always defines the outer boundary of the facet and any subsequent boundaries defining holes within it. Each boundary is an array containing at least three (3) [x,y,z] vertex arrays points defining each corner.

Construct a shell shape sewn together from a series of facets.

This method only deals with faceted data, which means that each face is defined by or contains an array of [x,y,z] vector arrays giving the positions of each corner of its boundaries.

Each entry in the facets array is an object that has an optional plane property with the [a,b,c,d] plane equation of the face and a non-optional boundaries property containing one or more contours of [x,y,z] vertex positions. If there are multiple contours, the first will be considered the outer boundary and any subsequent contours will be treated as holes within the face.

To be valid, each boundary and hole array must contain at least three (3) or more planar vertex indices defining each of its corners.

If you have data in which vertices are given in a separate array and where each face is an ordinal index, you can use the CAD.AddIndexedShell method instead of this one.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a shape sewn together from facets.

ParamTypeDescription
facetsArray.<object>An array of objects with a boundaries property containing one ot more contours of [x,y,z] vector arrays that make up its outline and any holes it may contain.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.

CAD.addShell(shape, [tolerance]) ⇒ oc.TopoDS_Solid

Construct a shape shape from a facetted shape or indexed face shell.

Kind: static method of CAD
Returns: oc.TopoDS_Solid - Returns a shell shape sewn together from multiple faces.

ParamTypeDescription
shapeShape | objectThe shape to add, or an object with vertices and faces.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.

CAD.addSolid(shape, [tolerance]) ⇒ oc.TopoDS_Solid

Construct a solid shape from a facetted shape or indexed face shell.

Kind: static method of CAD
Returns: oc.TopoDS_Solid - Returns a solid shape sewn together from multiple faces.

ParamTypeDescription
shapeShape | objectThe shape to add, or an object with vertices and faces.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.

CAD.addPolyhedron(poly, [tolerance]) ⇒ oc.TopoDS_Shape

Construct a shape from a Polyhedron or a polyhedron notation string.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns a solid shape sewn together from multiple faces.

ParamTypeDescription
polyPolyhedron | stringThe polyhedron to add or a Conway polyhedron notation string.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.

CAD.addText(text, [size], [height]) ⇒ oc.TopoDS_Shape | oc.TopoDS_Solid

Construct a set of primitive shapes representing 3D text.

This method will cache the generated shape if caching is enabled.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | oc.TopoDS_Solid - Returns a complex shape representing the text.

ParamTypeDescription
textstringThe characters to be generated.
[size]numberThe size of the text in model units, defaults to 36.
[height]numberThe extrusion height of the text faces, defaults to 0.15.

CAD.addFillet(shape, radius, [edges], [makeCopy]) ⇒ oc.TopoDS_Shape | oc.TopoDS_Solid

Applies a rounded fillet to one or more edges in a shape.

For simple fillets with the same radius, the edges array should contain a flat list of edge indices and the radius value should give the radius to use on those edges.

If you want to fillet different edges with different radii, calling this method more than once is a very inefficient way of doing it and makes keeping track of the edge indexes after each iteration almost impossible. Instead, you can include multiple arrays within the edges argument, ensuring that each array starts with the required radius and is followed by one or more edge indices to fillet at that radius, as shown in the third example below.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | oc.TopoDS_Solid - Returns the filleted solid, or the given shape if no matching edges were found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to fillet.
radiusnumber | Array.<number>The radius of the fillet in model units or one or more radius/edge arrays.
[edges]Array.<number>An array of edge indices to apply the fillet to, with an empty array meaning all edges.
[makeCopy]booleanApply to a copy and keep original shape in the model, defaults to false.

Example

const horz_radius = 100;
const vert_radius = 200;

CAD.addFillet(
    CAD.addBox(2000, 2000, 100, true),
    [
        [ horz_radius, 1, 5, 9, 11 ],
        [ vert_radius, 0, 2, 4,  6 ]
    ]
);

CAD.addChamfer(shape, distance, edges, [makeCopy]) ⇒ oc.TopoDS_Shape | oc.TopoDS_Solid

Applies a flat chamfer to one or more edges in a shape.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | oc.TopoDS_Solid - Returns the chamfered solid, or the given shape if no matching edges were found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to chamfer.
distancenumberThe size of the chamfer in model units.
edgesArray.<number>An array of edge indices to apply the chamfer to, with an empty array meaning all edges.
[makeCopy]booleanApply to a copy and keep original shape in the model, defaults to false.

CAD.translate(shapes, offset, [makeCopy]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Translates the given shape(s) by a relative vector.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the translated shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to translate.
offsetArray.<number>An [x,y,z] vector array defining the translation offset in each axis.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.

CAD.move(shapes, offset, [makeCopy]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Translates the given shape(s) by a relative vector.

This method is simply an alias for translate.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the translated shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to translate.
offsetArray.<number>An [x,y,z] vector array defining the translation offset in each axis.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.

CAD.rotate(shapes, axis, degrees, [makeCopy]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Rotates the given shape(s) around a given axis.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the rotated shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to rotate.
axisArray.<number>An [x,y,z] vector array defining the axis of rotation.
degreesnumberThe angle of rotation in decimal degrees.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.

CAD.rotateX(shapes, degrees, [makeCopy]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Rotates the given shape(s) around the X axis axis.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the rotated shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to rotate.
degreesnumberThe angle of rotation in decimal degrees.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.

CAD.rotateY(shapes, degrees, [makeCopy]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Rotates the given shape(s) around the Y axis.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the rotated shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to rotate.
degreesnumberThe angle of rotation in decimal degrees.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.

CAD.rotateZ(shapes, degrees, [makeCopy]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Rotates the given shape(s) around the Z axis.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the rotated shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to rotate.
degreesnumberThe angle of rotation in decimal degrees.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.

CAD.mirror(shapes, axis, [makeCopy]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Mirrors the given shape(s) around a given axis.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the mirrored shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to mirror.
axisArray.<number>An [x,y,z] vector array defining the normal to the mirror plane.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.

CAD.scale(shapes, scale, [makeCopy]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Scales the given shape(s) from the origin.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the scaled shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to scale.
scalenumberA relative scale factor to apply equally in each axis.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.

CAD.combine(shapes, [makeCopy]) ⇒ oc.TopoDS_Shape

Combines the given shape(s) into a single compound shape.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the compound shape.

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>An array of shapes to combine.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.

CAD.union(shapes, [makeCopy], [tolerance], [keepEdges]) ⇒ oc.TopoDS_Shape

Combines a set of shapes into a single unioned shape.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the unioned shape.

ParamTypeDescription
shapesArray.<oc.TopoDS_Shape>An array of shapes to combine.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.
[tolerance]numberThe tolerance to use when unioning, defaults to 0.1.
[keepEdges]booleanWhether or not to keep the original edge(s) in the shape, defaults to false.

CAD.subtract(mainBody, shapesToSubtract, [makeCopy], [tolerance], [keepEdges]) ⇒ oc.TopoDS_Shape

Subtracts a set of shapes from a main body shape.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the resulting shape.

ParamTypeDescription
mainBodyoc.TopoDS_ShapeThe shape to subtract from.
shapesToSubtractoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>An array of shapes to subtract.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.
[tolerance]numberThe tolerance to use when subtracting, defaults to 0.1.
[keepEdges]booleanWhether or not to keep the original edge(s) in the shape, defaults to false.

CAD.intersect(shapes, [makeCopy], [tolerance], [keepEdges]) ⇒ oc.TopoDS_Shape

Computes the intersection of a set of shapes.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the intersection shape.

ParamTypeDescription
shapesArray.<oc.TopoDS_Shape>An array of shapes to intersect.
[makeCopy]booleanApply to copies and keep original shapes in the model, defaults to false.
[tolerance]numberThe tolerance to use when intersecting, defaults to 0.1.
[keepEdges]booleanWhether or not to keep the original edge(s) in the shape, defaults to false.

CAD.extrude(face, vector, [makeCopy]) ⇒ oc.TopoDS_Shape

Extrudes a flat polygonal face into a shape.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the extruded shape.

ParamTypeDescription
faceoc.TopoDS_ShapeA flat face shape to extrude.
vectorArray.<number>An [x,y,z] vector array defining the distances to extrude in each axis.
[makeCopy]booleanApply to a copy and keep original face in the model, defaults to false.

CAD.offset(shape, distance, [tolerance], [makeCopy]) ⇒ oc.TopoDS_Shape

Offsets the edges and faces of a shape by the given distance.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the offset shape.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to offset.
distancenumberThe distance to offset surfaces in the shape.
[tolerance]numberThe tolerance to use when welding offset vertices together, defaults to 0.1.
[makeCopy]booleanApply to a copy and keep original shape in the model, defaults to false.

CAD.revolve(shape, degrees, [axis], [about], [makeCopy]) ⇒ oc.TopoDS_Shape

Revolves a shape by the given angle and axis.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the revolved shape.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to revolve.
degreesnumberThe angle of revolution in degrees.
[axis]Array.<number>An [x,y,z] vector array defining the axis of revolution, defaults to [ 0, 0, 1 ].
[about]Array.<number>An [x,y,z] vector array defining the revolution origin, defaults to the origin.
[makeCopy]booleanApply to a copy and keep original shape in the model, defaults to false.

CAD.extrudeAndRotate(wire, height, degrees, [makeCopy]) ⇒ oc.TopoDS_Shape

Extrude and rotate a wire into a 3D shape.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the extruded shape.

ParamTypeDescription
wireoc.TopoDS_ShapeThe wire to extrude.
heightnumberThe height of the extrusion in model units.
degreesnumberThe angle of rotation in degrees.
[makeCopy]booleanApply to a copy and keep original wire in the model, defaults to false.

CAD.loft(wires, [makeCopy]) ⇒ oc.TopoDS_Shape

Lofts between a set or wires.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the lofted shape.

ParamTypeDescription
wiresArray.<oc.TopoDS_Shape>The set of wires to loft between.
[makeCopy]booleanApply to copies and keep original wires in the model, defaults to false.

CAD.sweep(shape, path, [makeCopy]) ⇒ oc.TopoDS_Shape

Creates a pipe by sweeping a shape along a wire path.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the swept shape.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to sweep along the path.
pathoc.TopoDS_WireA wire defining the path to sweep the shape along.
[makeCopy]booleanApply to a copy and keep original shape in the model, defaults to false.

CAD.hollow(shape, faces, thickness, [tolerance], [makeCopy]) ⇒ oc.TopoDS_Shape

Creates a hollowed out solid from a closed shell.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the hollowed out shape.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to hollow out.
facesArray.<oc.TopoDS_Face>An array of one or more faces to remove.
thicknessnumberThe thickness of the walls.
[tolerance]numberThe tolerance to use when unioning, defaults to 0.1.
[makeCopy]booleanApply to a copy and keep original shape in the model, defaults to false.

CAD.duplicate(shapes, offset, [copies]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Adds one or more translated copies of the given shape(s).

If the copies argument is a number greater than zero, it specifies the number of duplicate copies to create with the given offset. If the copies argument is given as a [copiesX,copiesY,copiesZ] array, that number of shape(s) will be duplicated in each axis

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the duplicated shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to duplicate.
offsetArray.<number>An [x,y,z] vector array defining the translation offset in each axis.
[copies]number | Array.<number>The number of copies to create, or [copiesX,copiesY,copiesZ] to array copy, defaults to 1.

CAD.distribute(shapes, spacing, [columns]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Distribute shapes over an XY grid.

This method takes an array of shapes and distributes them over grid with the given spacing. If you want to group items and keep them together, simply include them in a sub-array.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns the distributed shape(s).

ParamTypeDescription
shapesoc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to duplicate.
spacingnumber | Array.<number>A number or [x,y,z] vector array defining the grid cell size in each axis.
[columns]numberThe number of columns in the X-axis, defaults to 8.

CAD.removeInternalEdges(shape, [makeCopy]) ⇒ oc.TopoDS_Shape

Unifies a shape by cleaning up internal edges.

Kind: static method of CAD
Returns: oc.TopoDS_Shape - Returns the unified shape.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to clean up.
[makeCopy]booleanApply to a copy and keep original shape in the model, defaults to false.

CAD.getSolid(shape, [index], [makeCopy]) ⇒ oc.TopoDS_Shape | oc.TopoDS_Solid

Extracts a particular solid from within a compound shape.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | oc.TopoDS_Solid - Returns the solid at the given index, or the given shape if no matching solid was found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to extract the solid from.
[index]numberThe ordinal index of the solid within the shape, defaults to 0.
[makeCopy]booleanKeep the original solid compound in the model, defaults to false.

CAD.getFace(shape, [index], [makeCopy]) ⇒ oc.TopoDS_Shape | oc.TopoDS_Face

Extracts a particular face from within a shape.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | oc.TopoDS_Face - Returns the solid at the given index, or the given shape if no matching solid was found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to extract the face from.
[index]numberThe ordinal index of the face within the shape, defaults to 0.
[makeCopy]booleanKeep the original shape in the model, defaults to false.

CAD.getWire(shape, [index], [makeCopy]) ⇒ oc.TopoDS_Shape | oc.TopoDS_Wire

Extracts a particular wire from within a shape.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | oc.TopoDS_Wire - Returns the wire at the given index, or the given shape if no matching wire was found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to extract the wire from.
[index]numberThe ordinal index of the wire within the shape, defaults to 0.
[makeCopy]booleanKeep the original shape in the model, defaults to false.

CAD.evaluateCode(payload, code, json) ⇒ Array | null

Executes/evaluates some JavaScript code sent from the host application.

Kind: static method of CAD
Returns: Array | null - Returns an array of faces and edges, of null if there was invalid input.

ParamTypeDescription
payloadobjectA container object typically sent from the host application.
codestringThe JavaScript code block to evaluate.
jsonstringThe JSON data block to evaluate.

CAD.getShapeGeometry(payload, maxDeviation) ⇒ Array | null

This function accumulates all the shapes in PD.CAD.model into a single TopoDS_Compound and converts it to a mesh (and a set of edges) with PD.OCC.shapeToMesh(), and sends it back to the host application.

Kind: static method of CAD
Returns: Array | null - Returns a [faces,edges] array if successful, otherwise null.

ParamTypeDescription
payloadobjectA container object typically sent from the host application.
maxDeviationnumberThe welding tolerance and mesh resolution of the resulting geometry.

CAD.importSTEPorIGES(filename, content) ⇒ oc.TopoDS_Shape | null

This function parses the ASCII contents of a .STEP or .IGES file. and adds the resulting shapes to scene.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | null - Returns a shape if successfully loaded, otherwise null.

ParamTypeDescription
filenamestringThe name of the file.
contentstringThe contents of the file.

CAD.importSTL(filename, content) ⇒ oc.TopoDS_Shape | null

This function parses the contents of an ASCII .STL File as a Shape into the externalShapes dictionary.

Kind: static method of CAD
Returns: oc.TopoDS_Shape | null - Returns a shape if successfully loaded, otherwise null.

ParamTypeDescription
filenamestringThe name of the file.
contentstringThe contents of the file.

CAD.saveShapeSTEP([filename]) ⇒ object | null

Generates a STEP file containing the current shape(s).

Kind: static method of CAD
Returns: object | null - Returns the STEP file content, or null if the conversion failed.

ParamTypeDescription
[filename]stringThe name of the temporary file, defaults to ‘ShapeEditorPart.step’.

CAD.setCancelToken([token])

Sets the URL token used for cancelling operations.

Kind: static method of CAD

ParamTypeDescription
[token]stringA revokable URL token.

CAD.checkCancelToken()

If the URL token is valid and has been revoked, the host application must have cancelled the operation. Thus, this method throws an error in order to abort the process.

Kind: static method of CAD Throws:

  • Error Throws an error if URL token has been revoked.

CAD.cancelOperation(state)

Sets or clears the cancel operations flags.

Kind: static method of CAD

ParamTypeDescription
statebooleanThe name of the operation.

CAD.setLogLevel(level)

Sets or clears the cancel operations flags.

Kind: static method of CAD

ParamTypeDescription
levelnumberThe level to log at (0 to 3).

CAD.addLogEntry(level, message) ⇒ LogEntry

Adds a new entry to the process log.

Kind: static method of CAD
Returns: LogEntry - Returns a new log entry instance.

ParamTypeDescription
levelnumberThe log level of this message.
messagestringThe human-readable message to log.

CAD.progressOperation(level, [operation])

Check first if the process has been cancelled and, if not, format the operation and add it to the progress log.

The movement of the progress bar should not be affected by the current log level so, if the log level is less than the level of this operation, we still need to send undefined to the host application to increment it.

Kind: static method of CAD Throws:

  • Error Throws and error if process cancelled.
ParamTypeDescription
levellevelThe log level of the operation.
[operation]stringThe name of the operation to log.

CAD.progressMessage(level, [message])

First checks if the process has been cancelled and, if not, adds the given message to the progress log.

The movement of the progress bar should not be affected by the current log level so, if the log level is less than the level of this message, we still need to send undefined to the host application to increment it.

Kind: static method of CAD Throws:

  • Error Throws and error if process cancelled.
ParamTypeDescription
levellevelThe log level of this message.
[message]stringThe message to add to the log.

CAD.progress([operation])

Sends a progress message to the host application.

This is an important message as it informs the host application that the worker is busy and allows it to display the operation name and keep the user informed on what is happening.

The message argument should be included only at the very beginning of each operation. For ongoing progress updates, don’t include the message argument. When the process is complete, you can call this method with ‘Done’ as the message, but this is not necessary as the results will automatically be sent to the host application in a message that does not include the busy indicator, so the host will know that it is complete.

Kind: static method of CAD

ParamTypeDescription
[operation]stringThe operation name or message.

CAD.log(message)

Logs a message to the host application and console.

Kind: static method of CAD

ParamTypeDescription
messagestringThe message to log.

CAD.error(message)

Outputs an error message to the host application and console.

Kind: static method of CAD

ParamTypeDescription
messagestringThe error message to log.

PD.OCC

Contains lower-level methods than CADfor generating and operating on primitive shapes within OpenCascade.

This class is also exposed as just OCC within the built-in code editor panel of each framework application that uses it.

The methods in this class do the actual low-level work of interfacing with the OpenCascade module and the raw geometry it creates. They provide the engine that sits behind the higher-level methods in CAD, many of which are simply wrappers that marshal arguments and cache calls to the corresponding methods in this class, and manage the final CAD model.

You can use the lower-level methods in this class directly to create interim geometry, but it will not be cached and will not become part of the final model until you specifically use the add method to add them. You can also use the remove method to remove shapes from the CAD model.

Unlike shape generation methods within CAD, the methods in this class take a single configuration object as their primary argument and return a shape, which may be a transformed copy of a source shape or a compound assembly of multiple shapes. The properties of the configuration object provide the inputs and data required for each method. This allows these methods to be used directly with parsed JSON data, where the "type" property of each encapsulated JSON object is basically the method name. This greatly simplifies both the creation and parsing of JSON representations of complex constructive geometry.

Kind: static class of PD
Author: drajmarsh

OCC.ITwoPoints

Kind: static interface of OCC Properties

NameTypeDescription
pointsArray.<Array.<number>>An array of two [x,y,z] vector arrays.

OCC.IArcPath

Kind: static interface of OCC Properties

NameTypeDescription
pointsArray.<Array.<number>>An array of three [x,y,z] vector arrays defining the start, ptOnArc and end points.

OCC.ICentreRadius

Kind: static interface of OCC Properties

NameTypeDescription
[center]Array.<number>An [x,y,z] vector array defining the center of the circle, defaults to the origin.
[radius]numberThe radius of the circle, defaults to 1000mm (1m).

OCC.ICurvePoints

Kind: static interface of OCC Properties

NameTypeDescription
pointsArray.<Array.<number>>An array of three or more [x,y,z] vector array control points.
[closed]booleanWhether or not the points should form a closed loop.

OCC.IWirePath

Kind: static interface of OCC Properties

NameTypeDescription
[edges]Array.<oc.TopoDS_Edge>An array of edges to connect together to form a path.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining a path.
[closed]booleanWhether or not the path should be a closed loop.

OCC.getOpenCascadeInstance() ⇒ object

Retrieve the current OpenCascade WebAssembly instance being used.

Kind: static method of OCC
Returns: object - Returns the current OpenCascade instance.

OCC.isValidType(shape, type) ⇒ boolean

Checks if a shape is a non-null instance of the given type.

This method first checks the shape is not null and then calls its oc.TopoDS_Shape#ShapeType method to see if it matches the given type.

Kind: static method of OCC
Returns: boolean - Returns true if the shape is of the given type, otherwise false.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to check.
typeoc.TopAbs_ShapeEnumThe shape type to check for.

OCC.isValidVertex(shape) ⇒ boolean

Checks if a shape is a non-null instance of TopAbs_VERTEX.

Kind: static method of OCC
Returns: boolean - Returns true if the shape is of the right type, otherwise false.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to check the type of.

OCC.isValidEdge(shape) ⇒ boolean

Checks if a shape is a non-null instance of TopAbs_EDGE.

Kind: static method of OCC
Returns: boolean - Returns true if the shape is of the right type, otherwise false.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to check the type of.

OCC.isValidWire(shape) ⇒ boolean

Checks if a shape is a non-null instance of TopAbs_WIRE.

Kind: static method of OCC
Returns: boolean - Returns true if the shape is of the right type, otherwise false.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to check the type of.

OCC.isValidFace(shape) ⇒ boolean

Checks if a shape is a non-null instance of TopAbs_FACE.

Kind: static method of OCC
Returns: boolean - Returns true if the shape is of the right type, otherwise false.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to check the type of.

OCC.isValidShell(shape) ⇒ boolean

Checks if a shape is a non-null instance of TopAbs_SHELL.

Kind: static method of OCC
Returns: boolean - Returns true if the shape is of the right type, otherwise false.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to check the type of.

OCC.isValidSolid(shape) ⇒ boolean

Checks if a shape is a non-null instance of TopAbs_SOLID.

Kind: static method of OCC
Returns: boolean - Returns true if the shape is of the right type, otherwise false.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to check the type of.

OCC.isValidCompositeSolid(shape) ⇒ boolean

Checks if a shape is a non-null instance of TopAbs_COMPSOLID.

Kind: static method of OCC
Returns: boolean - Returns true if the shape is of the right type, otherwise false.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to check the type of.

OCC.isValidCompound(shape) ⇒ boolean

Checks if a shape is a non-null instance of TopAbs_COMPOUND.

Kind: static method of OCC
Returns: boolean - Returns true if the shape is of the right type, otherwise false.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to check the type of.

OCC.shellToSolid(shape) ⇒ oc.TopoDS_Solid | null

Converts a shell shape to a solid shape.

When used with CSG, shells and solids produce different results. This method first checks if the given shape is a shell and, if so, returns a solid. If it is already a solid, it is just passed through.

If the shape is not a shell or solid, and cannot be converted to a solid, the method returns null.

Kind: static method of OCC
Returns: oc.TopoDS_Solid | null - Returns the created solid, or null if the shape could not be converted into a solid.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to create a solid from.

OCC.edge([config], [points]) ⇒ oc.TopoDS_Edge

Construct a straight linear edge between two points.

Edges are lines typically used to represent the connection or intersection between two faces. They may be straight lines or complex curves, and can be connected together to form wires.

If the config.points array contains more than two points, only the first two will actually be used in the edge.

Kind: static method of OCC
Returns: oc.TopoDS_Edge - Returns a linear edge.

ParamTypeDescription
[config]ITwoPointsA configuration object.
[points]Array.<Array.<number>>An array of two [x,y,z] vector arrays defining the vertices at each end.

OCC.edgeArc([config], [points]) ⇒ oc.TopoDS_Edge

Construct an edge as a circular arc defined by three points.

Edges are lines typically used to represent the connection or intersection between two faces. They may be straight lines or complex curves, and can be connected together to form wires.

Kind: static method of OCC
Returns: oc.TopoDS_Edge - Returns a edge arc.

ParamTypeDescription
[config]IArcPathA configuration object.
[points]Array.<Array.<number>>An array of three [x,y,z] vector arrays defining the start, ptOnArc and end points.

OCC.edgeCircle([config], [center], [radius]) ⇒ oc.TopoDS_Edge

Construct a closed circular edge.

Edges are lines typically used to represent the connection or intersection between two faces. They may be straight lines or complex curves, and can be connected together to form wires.

Kind: static method of OCC
Returns: oc.TopoDS_Edge - Returns a circular edge.

ParamTypeDescription
[config]ICentreRadiusA configuration object.
[center]Array.<number>An [x,y,z] vector array defining the center of the circle.
[radius]numberThe radius of the circle, defaults to 1000mm (1m).

OCC.edgeBezier([config], [points], [closed]) ⇒ oc.TopoDS_Edge

Construct a Bezier curved edge from control points.

Edges are lines typically used to represent the connection or intersection between two faces. They may be straight lines or complex curves, and can be connected together to form wires.

Kind: static method of OCC
Returns: oc.TopoDS_Edge - Returns a curved edge.

ParamTypeDescription
[config]ICurvePointsA configuration object.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the control points of the bezier curve.
[closed]booleanWhether or not the edge forms a closed loop.

OCC.edgeBSpline([config], [points], [closed]) ⇒ oc.TopoDS_Edge

Construct a BSpline curved edge from control points.

Edges are lines typically used to represent the connection or intersection between two faces. They may be straight lines or complex curves, and can be connected together to form wires.

Kind: static method of OCC
Returns: oc.TopoDS_Edge - Returns a curved edge.

ParamTypeDescription
[config]ICurvePointsA configuration object.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the control points of the bspline.
[closed]booleanWhether or not the edge forms a closed loop.

OCC.wire([config], [edges], [points], [closed]) ⇒ oc.TopoDS_Wire

Construct a wire from points or edges.

Wires are used to represent shape outlines or face boundaries. They are formed by connecting one or more edges together, which may be curved or linear segments.

To create a wire, you must pass either an array of edges in the config.edges property, or an array of [x,y,z] vector array coordinates in the config.points property. The list of edges will be used in preference to points, so you should only include one or the other rather than both.

Kind: static method of OCC
Returns: oc.TopoDS_Wire - Returns a new wire.

ParamTypeDescription
[config]IWirePathA configuration object.
[edges]Array.<oc.TopoDS_Edge>An array of edges to connect together to form the wire path.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the wire path.
[closed]booleanWhether or not to form a closed loop from the given points.

OCC.wireArc([config]) ⇒ oc.TopoDS_Wire

Construct a wire from a circular arc.

Wires are used to represent shape outlines or face boundaries. They are formed by connecting one or more edges together, which may be curved or linear segments.

Kind: static method of OCC
Returns: oc.TopoDS_Wire - Returns a wire arc.

ParamTypeDescription
[config]IArcPathA configuration object defining the arc.

OCC.wireCircle([config], [center], [radius]) ⇒ oc.TopoDS_Wire

Construct a closed circular wire.

Wires are used to represent shape outlines or face boundaries. They are formed by connecting one or more edges together, which may be curved or linear segments.

Kind: static method of OCC
Returns: oc.TopoDS_Wire - Returns a circular wire.

ParamTypeDescription
[config]ICentreRadiusA configuration object.
[center]Array.<number>An [x,y,z] vector array defining the center of the circle.
[radius]numberThe radius of the circle, defaults to 1000mm (1m).

OCC.wireBezier([config], [points], [closed]) ⇒ oc.TopoDS_Edge

Construct a Bezier curved wire from control points.

Wires are used to represent shape outlines or face boundaries. They are formed by connecting one or more edges together, which may be curved or linear segments.

Kind: static method of OCC
Returns: oc.TopoDS_Edge - Returns a curved wire.

ParamTypeDescription
[config]ICurvePointsA configuration object.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the control points of the bezier curve.
[closed]booleanWhether or not the wire forms a closed loop.

OCC.wireBSpline([config], [points], [closed]) ⇒ oc.TopoDS_Edge

Construct a BSpline wire from control points.

Wires are used to represent shape outlines or face boundaries. They are formed by connecting one or more edges together, which may be curved or linear segments.

Kind: static method of OCC
Returns: oc.TopoDS_Edge - Returns a curved wire.

ParamTypeDescription
[config]ICurvePointsA configuration object.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the control points of the bspline.
[closed]booleanWhether or not the wire forms a closed loop.

OCC.path2D([config], [segments], [closed], [reverse]) ⇒ oc.TopoDS_Wire

Construct a wire as a series of 2D path segments.

This method basically wraps a Path instance and takes an array of segments that encapsulate the various generation methods it offers. Each segment requires a type property that corresponds to a method name in the path instance, as well as other properties that correspond to the arguments that method takes, as shown in the code example below.

Kind: static method of OCC
Returns: oc.TopoDS_Wire - Returns a flat closed polygonal face shape.

ParamTypeDescription
[config]objectA configuration object.
[segments]Array.<Array.<number>>An array of segment definitions, as shown in the code example.
[closed]booleanWhether or not the path forms a closed loop, defaults to false.
[reverse]booleanWhether or not to reverse the path direction.

Example

const wire = PD.CAD.Shape.path2D({
     closed: false,
     reverse: false,
     segments: [
         {
             type: "moveTo",
             point: [ 0, -1000 ]
         },
         {
             type: "lineTo",
             point: [ 0, 0 ]
         },
         {
             type: "fillet",
             radius: 500
         },
         {
             type: "lineTo",
             point: [ 1000, 0 ]
         },
         {
             type: "arcTo",
             through: [ 1500, 500 ]
             point: [ 1000, 1000 ],
         },
         {
             type: "bezierTo",
             points: [
                 [ 0, 1000 ],
                 [ 0, 2000 ]
             ]
          },
         {
             type: "bsplineTo",
             points: [
                 [     0, 3000 ],
                 [  -500, 3500 ],
                 [ -1000, 3000 ],
                 [ -1500, 3500 ],
                 [ -2000, 3000 ]
             ]
          },
     ],
});

OCC.wires([config], [contours]) ⇒ Array.<oc.TopoDS_Wire>

Construct one or more wires from an array of point contours.

To create wires, you must pass an array of contours in the config.contours property, each containing two or more [x,y,z] vector array coordinates defining a connected sequence of line vertices.

Kind: static method of OCC
Returns: Array.<oc.TopoDS_Wire> - Returns an array of wires new wire.

ParamTypeDescription
[config]objectA configuration object.
[contours]Array.<Array.<Array.<number>>>An array of contours, each containing [x,y,z] vector arrays defining a wire path.

OCC.face([config], [points], [wires]) ⇒ oc.TopoDS_Face

Construct a face from points or wires.

Faces are used to represent the surfaces of a shape. They are formed by connecting one or more wires together to form a boundary on a surface that may be curved or flat.

To create a face, you must pass either an array of wires in the config.wires property, or an array of [x,y,z] vector array coordinates in the config.points property. The list of wires will be used in preference to points, so you should only include one or the other rather than both.

Using config.points creates a simple face with a single outer boundary. For more complex faces with holes and/or multiple boundaries, you can use the PD.CAD.Shape#polygon method with config.contours or build the boundaries using a Path instance.

Using config.wires, you can add internal holes to the face by including closed wires that are entirely within the outer boundary wire. You can also add additional boundaries (like multiple islands) by including closed wires entirely outside any other boundary wire(s).

Kind: static method of OCC
Returns: oc.TopoDS_Face - Returns a new face.

ParamTypeDescription
[config]objectA configuration object.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the face boundary.
[wires]Array.<oc.TopoDS_Wire>An array of wires to connect together to form the face boundary.

OCC.polygon([config], [contours], [points]) ⇒ oc.TopoDS_Face

Construct a flat closed polygonal face from one or more boundary contours.

To create a polygonal face, you must pass either an array of contours in the config.contours property, or an array of [x,y,z] vector array coordinates in the config.points property. The list of contours will be used in preference to points, so you should only include one or the other rather than both.

Using config.points creates a simple polygon with a single outer boundary. For more complex faces with holes and/or multiple boundaries, use the config.contours property or build the boundaries using a Path instance.

Using config.contours, you can add internal holes to the face by including closed boundaries that are entirely within the first contour, which ia always assumed to define the outer boundary of the polygon.

Kind: static method of OCC
Returns: oc.TopoDS_Face - Returns a flat closed polygonal face.

ParamTypeDescription
[config]objectA configuration object.
[contours]Array.<Array.<Array.<number>>>An array of boundary contours, each containing 3 or more [x,y,z] vector arrays defining the polygon outlines.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the polygon boundary.

OCC.cuboid([config], [pos], [axis], [size], [min], [max], [centered], [centerXY], [fillet]) ⇒ oc.TopoDS_Shape

Construct a rectangular prism primitive shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a rectangular prism shape.

ParamTypeDescription
[config]objectAn optional configuration object.
[pos]Array.<number>An [x,y,z] vector array defining the start position of the shape.
[axis]Array.<number> | numberAn [x,y,z] axis array or a number (X:1, Y:2, Z:3), defaults to Z axis.
[size]Array.<number>An [x,y,z] vector array defining the size of the shape in each axis, defaults to [1000,1000,1000].
[min]Array.<number>An [x,y,z] vector array defining the bottom-left corner.
[max]Array.<number>An [x,y,z] vector array defining the top-right corner.
[centered]booleanAn optional flag indicating that the shape should be centered on its pos/min position rather than at its bottom-left, defaults to false.
[centerXY]booleanAn optional flag indicating that the shape should be centered on its X and Y pos/min position rather than at its bottom-left, defaults to false.
[fillet]number | Array.<number>An optional radius or [bot,sides,top] array for filleting edges and corners, defaults to 0 (no fillet).

Example

/// Define just the size.
PD.CAD.add(PD.OCC.cuboid({
    size: [ 1500, 2000, 3000 ]
}));

/// Define by min/max.
PD.CAD.add(PD.OCC.cuboid({
    min: [ -750, -1000,    0 ],
    max: [  750,  1000, 3000 ]
}));

/// Define fillet radii, etc.
PD.CAD.add(PD.OCC.cuboid({
    size: [ 1500, 2000, 3000 ],
    axis: [ 0.5773503, 0.5773503, 0.5773503 ],
    fillet: [ 50, 500, 50 ],
    centerXY: true
 }));

OCC.wedge([config], [pos], [axis], [size], [min], [max], [taperX], [taperZ], [taperWidth], [taperHeight], [centered], [centerXY], [fillet]) ⇒ oc.TopoDS_Shape

Construct a rectangular wedge primitive shape.

Wedges are rectangular primitives that taper in the X and/or Z axis as the shape runs along the Y axis. In addition to setting the overall size in each axis, you can provide either the taper width/height value or the minimum and maximum X and Z coordinates at the +Y end of the wedge.

This method will cache the generated shape if caching is enabled.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a rectangular wedge shape.

ParamTypeDescription
[config]objectAn optional configuration object.
[pos]Array.<number>An [x,y,z] vector array defining the start position of the shape, defaults to [0,0,0].
[axis]Array.<number> | numberAn [x,y,z] axis array or a number (X:1, Y:2, Z:3), defaults to Z axis.
[size]Array.<number>An [x,y,z] vector array defining the size of the shape in each axis, defaults to [1000,1000,1000].
[min]Array.<number>An [x,y,z] vector array defining the bottom-left extents.
[max]Array.<number>An [x,y,z] vector array defining the top-right extents.
[taperX]Array.<number>An array with the minimum and maximum X-axis values at the tapered end, defaults to [0, size[0]].
[taperZ]Array.<number>An array with the minimum and maximum Z-axis values at the tapered end, defaults to [0, 0].
[taperWidth]numberThe width of the tapered end in the X-axis, defaults to size[0].
[taperHeight]numberThe height of the tapered end in the Z-axis, defaults to 0.
[centered]booleanAn optional flag indicating that the shape should be centered on its pos/min position rather than at its bottom-left, defaults to false.
[centerXY]booleanAn optional flag indicating that the shape should be centered on its X and Y pos/min position rather than at its bottom-left, defaults to false.
[fillet]number | Array.<number>An optional radius or [bot,sides,top] array for filleting edges and corners, defaults to 0 (no fillet).

Example

/// Define just the size.
PD.CAD.add(PD.OCC.wedge({ size: [ 1000, 2000, 3000 ] }));

/// Define the height and width at end.
PD.CAD.add(PD.OCC.wedge({
     size: [ 1000, 2000, 3000 ],
     taperHeight: 50,
     taperWidth: 750,
     centerXY: true
}));

/// Define X and Z positions at end.
PD.CAD.add(PD.OCC.wedge({
    min: [ -500, -1000,    0 ],
    max: [  500,  1000, 3000 ],
    taperX: [  250, 750 ],
    taperZ: [ -100,  50 ]
}));

/// Define both dimensions.
const x_min =  0.40 * width;
const x_max =  0.75 * width;
const z_min = -0.25 * height;
const z_max =  0.25 * height;
PD.CAD.add(PD.CAD.addWedge({
    size: [ width, depth, height ],
    taperX: [ x_min, x_max ],
    taperZ[ z_min, z_max ]
}));

OCC.pyramid([config], [pos], [axis], [size], [min], [max], [truncate], [centered], [centerXY], [fillet]) ⇒ oc.TopoDS_Shape

Construct a pyramid primitive shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a pyramidal shape.

ParamTypeDescription
[config]objectAn optional configuration object.
[pos]Array.<number>An [x,y,z] vector array defining the start position of the shape, defaults to [0,0,0].
[axis]Array.<number> | numberAn [x,y,z] axis array or a number (X:1, Y:2, Z:3), defaults to Z axis.
[size]Array.<number>An [x,y,z] vector array defining the size of the shape in each axis, defaults [1000,1000,1000].
[min]Array.<number>An [x,y,z] vector array defining the bottom-left extents.
[max]Array.<number>An [x,y,z] vector array defining the top-right extents.
[truncate]numberA fractional top point truncation amount (0 to 1), defaults to 1.0.
[centered]booleanAn optional flag indicating that the shape should be centered on its pos/min position rather than at its bottom-left, defaults to false.
[centerXY]booleanAn optional flag indicating that the shape should be centered on its X and Y pos/min position rather than at its bottom-left, defaults to false.
[fillet]number | Array.<number>An optional radius or [bot,sides,top] array for filleting edges and corners, defaults to 0 (no fillet).

Example

PD.CAD.add(PD.OCC.pyramid({
    size: [ 2000, 10000, 3000 ],
    fillet: [ 100, 200, 300 ],
    centerXY: true,
    truncateX: 0.5
}));

OCC.prism([config], [axis], [height], [face], [points], [sides], [radius], [pos]) ⇒ oc.TopoDS_Shape

Construct an extruded prism shape from a face or connected points.

You can define the base of the prism by either:

  • providing a single face to extrude in the config.face property,
  • providing an array of [x,y,z] coordinates in the config.points property,
  • or providing a radius and number of sides in the config.radius and config.sides properties.

The single face will be used in preference to points or sides. If no face is provided, the array of points will be used in preference to the radius and sides. Thus, you should only include the properties for one of these ways.

Using config.points creates a simple prism from a face with a single outer boundary. For more complex prisms with holes and/or multiple boundaries, you can use the PD.OCC#polygon method with config.contours or build the face boundaries using a Path instance. You can use this method or the PD.OCC#extrude method to make the prism from the face.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a rectangular prism shape.

ParamTypeDescription
[config]objectAn optional configuration object.
[axis]Array.<number> | numberAn [x,y,z] axis array or a number (X:1, Y:2, Z:3), defaults to Z axis.
[height]numberThe height of the shape, defaults to 1000mm (1m).
[face]oc.TopoDS_FaceAn optional closed face to extrude into a prism.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the base shape of the prism.
[sides]numberThe number of sides of the prism (3 to 256) when no face or points are provided, defaults to 8.
[radius]numberThe radius of the prism when no face or points are provided, defaults to 1000mm (1m).
[pos]Array.<number>An [x,y,z] vector array defining the center when no face or points are provided, defaults to [0,0,0].

Example

const polygon = OCC.polygon({
    contours: [
        [ // Outer boundary.
            [ -3000.0, -2000.0, 0.0 ],
            [  3000.0, -2000.0, 0.0 ],
            [  3000.0,  2000.0, 0.0 ],
            [ -3000.0,  2000.0, 0.0 ]
        ],
        [ // Internal hole.
            [ -1000.0, -1000.0, 0.0 ],
            [  1000.0, -1000.0, 0.0 ],
            [  1000.0,  1000.0, 0.0 ],
            [ -1000.0,  1000.0, 0.0 ]
        ]
     ]
});

/// Define the face to use.
CAD.add(OCC.prism({
        axis: [ 0.5773503, 0.5773503, 0.5773503 ],
        face: polygon,
        height: 5000
    })
);

/// Define some boundary points.
CAD.add(OCC.prism({
        height: 5000,
        points: [
            [ -3000.0, -2000.0, 0.0 ],
            [  3000.0, -2000.0, 0.0 ],
            [  3000.0,  2000.0, 0.0 ],
            [ -3000.0,  2000.0, 0.0 ]
        ]
    })
);

/// Define radius and sides.
CAD.add(OCC.prism({
        axis: [ 0.5773503, 0.5773503, 0.5773503 ],
        height: 5000,
        radius: 2000,
        sides: 12
    })
);

OCC.cylinder([config], [pos], [axis], [height], [radius], [fillet], [chamfer], [angle]) ⇒ oc.TopoDS_Shape

Construct a cylindrical primitive shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a cylindrical shape.

ParamTypeDescription
[config]objectA configuration object.
[pos]Array.<number>An [x,y,z] vector array defining the shape center, defaults to the origin.
[axis]Array.<number> | numberAn [x,y,z] axis array or a number (X:1, Y:2, Z:3), defaults to Z axis.
[height]numberThe height of the shape, defaults to 1000mm (1m).
[radius]numberThe base radius of the shape, defaults to 1000mm (1m).
[fillet]number | Array.<number>An optional radius or [bot,top] array for filleting edges and corners, defaults to 0 (no fillet).
[chamfer]number | Array.<number>An optional radius or [bot,top] array for chamfering edges and corners, defaults to 0 (no chamfer).
[angle]numberAn optional angle in radians (0 to 2PI), defaults to 2PI.

OCC.cone([config], [pos], [axis], [radiusBot], [radiusTop], [height], [fillet], [angle]) ⇒ oc.TopoDS_Shape

Construct a conical primitive shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a conical shape.

ParamTypeDescription
[config]objectA configuration object.
[pos]Array.<number>An [x,y,z] vector array defining the shape center, defaults to the origin.
[axis]Array.<number> | numberAn [x,y,z] axis array or a number (X:1, Y:2, Z:3), defaults to Z axis.
[radiusBot]numberThe base radius of the shape, defaults to 1000mm (1m).
[radiusTop]numberThe top radius of the shape, defaults to 0 (a point).
[height]numberThe height of the shape, defaults to 1000mm (1m).
[fillet]numberAn optional fillet radius for the base, defaults to 0 (no fillet).
[angle]numberAn optional angle in radians (0 to 2PI), defaults to 2PI.

OCC.torus([config], [pos], [axis], [radiusRing], [radiusPipe], [longitude], [latitude]) ⇒ oc.TopoDS_Shape

Construct a toroidal primitive shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a toroidal shape.

ParamTypeDescription
[config]objectA configuration object.
[pos]Array.<number>An [x,y,z] vector array defining the shape center, defaults to the origin.
[axis]Array.<number> | numberAn [x,y,z] axis array or a number (X:1, Y:2, Z:3), defaults to Z axis.
[radiusRing]numberThe radius of the torus pipe line from the center, defaults to 400mm (0.4m).
[radiusPipe]numberThe radius of the rotated pipe, defaults to 100 (0.1m).
[longitude]numberAn optional longitudinal angle in radians to restrict the torus to (0 to 2PI), defaults to 2PI.
[latitude]Array.<number>An optional array with the start and stop latitude angles in radians (0 to 2PI), defaults to [0, 2PI].

OCC.sphere([config], [pos], [axis], [radius], [longitude], [latitude]) ⇒ oc.TopoDS_Shape

Construct a spherical primitive shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a spherical shape.

ParamTypeDescription
[config]objectA configuration object.
[pos]Array.<number>An [x,y,z] vector array defining the shape center, defaults to the origin.
[axis]Array.<number> | numberAn [x,y,z] axis array or a number (X:1, Y:2, Z:3), defaults to Z axis.
[radius]numberThe distance of the spherical surface from the centre, defaults to 1000mm (1m).
[longitude]numberAn optional longitudinal angle in radians to restrict the sphere to (0 to 2PI), defaults to 2PI.
[latitude]Array.<number>An optional array with the start and stop latitude angles in radians (-PI/2 to PI/2), defaults to [-PI/2, PI/2].

OCC.hull([config], [points], [shapes], [tolerance]) ⇒ oc.TopoDS_Shape

Construct a convex hull solid shape from a set of points or shapes.

This method will preference points over shapes when creating the hull, so you should provide only one or the other rather than both. To support some JSON variants, this method allows the use of config.vertices as an alias for config.points.

When using shapes, the method has to extract vertices and sample points over each curved face in the shape, so you should provide a config.maxDeviation argument to control the granularity of this surface sampling.

The config.tolerance value applies to both and affects the sewing together of faces when generating the solid shell.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a solid shape sewn from multiple faces.

ParamTypeDescription
[config]objectA configuration object.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the vertices the shape.
[shapes]oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to create the hull from.
[tolerance]numberThe sewing tolerance when converting hull to a shape, defaults to 0.1.

OCC.hullChain([config], [shapes], [maxDeviation], [tolerance]) ⇒ oc.TopoDS_Shape

Construct a chain of convex hulls from a set of shapes.

The method has to extract vertices and sample points over each curved face in each shape, so you should provide a config.maxDeviation argument to control the granularity of this surface sampling.

The config.tolerance value affects the sewing together of faces when generating the solid shell(s).

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a solid shape sewn from multiple hulls.

ParamTypeDescription
[config]objectA configuration object.
[shapes]oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to create the hull chain from.
[maxDeviation]numberThe mesh resolution when point sampling shape surfaces, defaults to 5.
[tolerance]numberThe sewing tolerance when converting hull to a shape, defaults to 0.1.

OCC.shell([config], [points], [vertices], [faces], [facets], [tolerance]) ⇒ oc.TopoDS_Shape

Construct a shell shape sewn together from facets.

This method tries to determine what format the facet data is in and then passes it to either the OCC.indexedShell or OCC.facetedShell methods for actual processing.

Both methods sew together a collection of planar faces into a TopoDS_Shape. It does this by making planar TopoDS_Wire objects out of each facet, then making TopoDS_Face objects out of each wire, and then sewing the faces together into a TopoDS_Shell.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a shell shape sewn together from faces/facets.

ParamTypeDescription
[config]objectA configuration object.
[points]Array.<Array.<number>>An optional array of [x,y,z] vector arrays defining the corners and edges of the shape.
[vertices]Array.<Array.<number>>An optional array of [x,y,z] vector arrays defining the corners and edges of the shape.
[faces]Array.<Array.<number>> | Array.<object>An array of faces with boundaries containing ordinal indexes of the points that make up the face.
[facets]Array.<object>An array of facets with boundary contours defined by sequential [x,y,z] vector arrays.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.

OCC.solid([config], [points], [vertices], [faces], [facets], [tolerance]) ⇒ oc.TopoDS_Shape

Construct a solid shape from an indexed face mesh.

This method first calls shell to generate a manifold shell of faces, and then converts that into solid for use with CSG. Not all shell topology can be converted to solid, so you may end up with a compound of shells instead of a solid if that is the case.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a solid shape sewn together from faces.

ParamTypeDescription
[config]objectA configuration object.
[points]Array.<Array.<number>>An optional array of [x,y,z] vector arrays defining the corners and edges of the shape.
[vertices]Array.<Array.<number>>An optional array of [x,y,z] vector arrays defining the corners and edges of the shape.
[faces]Array.<Array.<number>> | Array.<object>An array of faces with boundaries containing ordinal indexes of the points that make up the face.
[facets]Array.<object>An array of facets with boundary contours defined by sequential [x,y,z] vector arrays.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.

OCC.compoundShell([config], [vertices], [faces]) ⇒ oc.TopoDS_Shape

Construct a compound shell shape from a series of vertices and faces.

A compound shell is basically just a collection of faces without any connection information such as shared vertices or edges. Use this if you just want to visualise a shape as it is quick to assemble and does not require any processing. Obviously you will not be able to convert it to a solid for use in CSG.

There are several variants of point/face meshes, and this is one of the simplest. It consists of a flat list of point in its vertices property, together with a list of arrays in its faces property, each storing the ordinal indices of each vertex in the points list that forms the outer boundary of a face. Each face only has a single boundary so cannot contain holes or separate contours. As a result, it is mainly used to efficiently store polyhedra and simple manifold shapes.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a shape sewn together from multiple faces.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the corners and edges of the shape.
[faces]Array.<Array.<number>> | Array.<object>An array of faces with boundaries containing ordinal indexes of the points that make up the face.

OCC.indexedShell([config], [points], [faces], [tolerance]) ⇒ oc.TopoDS_Shape

Construct a shell shape sewn together from a series of indexed facets.

This method sews together a collection of indexed planar faces into a TopoDS_Shape. It does this by making planar TopoDS_Wire objects out of each facet boundary, then making TopoDS_Face objects out of each wire, and then sewing the faces together into a TopoDS_Shell.

This method only deals with indexed face data, which means that all the vertices in the shape are stored in one array (points) and all the faces in another (faces). The vertices must all be [x,y,z] vector arrays and each face is defined by or contains an array of ordinal indexes of each vertex that make up its boundaries.

Thus, each entry in the faces array may be either an array of vertex indices or an object containing a boundaries property that is array. If the boundaries array contain one or more sub-arrays of vertex indices, then the first will be considered as the outer boundary and any subsequent boundaries treated as holes within the face. If the boundary is a flat array of vertex indices, it will be considered as an outer boundary with no holes.

To be valid, each boundary and hole array must contain at least three (3) or more planar vertex indices defining each of its corners.

If you have data in which vertices are not given separately, but where each face is a list of [x,y,z] vector arrays, use the OCC.facetedShell method instead of this one.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a shell shape sewn together from multiple faces.

ParamTypeDescription
[config]objectA configuration object.
[points]Array.<Array.<number>>An array of [x,y,z] vector arrays defining the corners and edges of the shape.
[faces]Array.<Array.<number>> | Array.<object>An array of faces with boundaries containing ordinal indexes of the points that make up the face.
[tolerance]numberAn optional face sewing tolerance, defaults to 1mm.

OCC.facetedShell([config], [facets]) ⇒ oc.TopoDS_Shape

Construct a shell shape sewn together from a series of facets.

This method only deals with faceted data, which means that each face is defined by or contains an array of [x,y,z] vector arrays giving the positions of each corner of its boundaries.

Each entry in the facets array is an object that has an optional plane property with the [a,b,c,d] plane equation of the face and a non-optional boundaries property containing one or more contours of [x,y,z] vertex positions. If there are multiple contours, the first will be considered the outer boundary and any subsequent contours will be treated as holes within the face.

To be valid, each boundary and hole array must contain at least three (3) or more planar vertex indices defining each of its corners.

If you have data in which vertices are given in a separate array and where each face is an ordinal index, you can use the OCC.indexedShell method instead of this one.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns a shape sewn together from multiple faces.

ParamTypeDescription
[config]objectA configuration object.
[facets]Array.<object>An array of facets with boundary contours defined by sequential [x,y,z] vector arrays.

OCC.text([config], [text], [size], [height]) ⇒ oc.TopoDS_Shape | oc.TopoDS_Solid

Construct a set of primitive shapes representing 3D text.

Kind: static method of OCC
Returns: oc.TopoDS_Shape | oc.TopoDS_Solid - Returns a complex shape representing the text.

ParamTypeDescription
[config]objectA configuration object.
[text]stringThe characters to be generated.
[size]numberThe size of the text, defaults to 36.
[height]numberThe extrusion height of the text faces, defaults to 0.15 font size.

OCC.fillet([config], [shape], [radius], [edges]) ⇒ oc.TopoDS_Shape

Applies a rounded fillet to one or more edges in a shape.

For simple fillets with the same radius, the config.edges array should contain a flat list of edge indices and the radius value should give the radius to use on those edges.

If you want to fillet different edges with different radii, calling this method more than once is a very inefficient way of doing it and makes keeping track of the edges indexes after each iteration almost impossible. Instead, you can include the config.radius property as an array of radius/edges arrays, ensuring that each array starts with the required radius and is followed by one or more edge indices to fillet at that radius, as shown in the third example below.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the filleted solid, or the given shape if no matching edges were found.

ParamTypeDescription
[config]objectA configuration object.
[shape]oc.TopoDS_ShapeThe shape to fillet edges within.
[radius]number | Array.<Array.<number>>The radius of the fillet, defaults to 0.
[edges]Array.<number>An array of edge indices to fillet, defaults to all edges.

Example

/// Fillet all edges.
const fillet1 = PD.OCC.fillet({
     shape: PD.OCC.cuboid({ size: [ 2000, 2000, 1000 ] }),
     radius: 200
});

/// Fillet 4 vertical edges.
const fillet2 = PD.OCC.fillet({
     shape: PD.OCC.cuboid({ size: [ 2000, 2000, 1000 ] }),
     edges: [ 0, 2, 4, 6 ],
     radius: 200
});

/// Fillet with different radii.
const fillet3 = PD.OCC.fillet({
     shape: PD.OCC.cuboid({ size: [ 2000, 2000, 1000 ] }),
     radius: [
         [ 200, 0, 2, 4,  6 ],
         [ 100, 1, 5, 9, 11 ]
     ]
});

OCC.chamfer([config], [shape], [distance], [edges]) ⇒ oc.TopoDS_Solid

Applies a flat 45deg chamfer to one or more edges in a shape.

For simple chamfers all at the same size, the config.edges array should contain a flat list of edge indices and the distance value should give the size size of the chamfer to use on those edges.

If you want to chamfer different edges with different distances, calling this method more than once is a very inefficient way of doing it and makes keeping track of the edges to chamfer almost impossible. Instead, you can include multiple arrays within the config.edges property, ensuring that each array starts with the required chamfer distance and is followed by one or more edge indices to chamfer at that distance, as shown in the third example below.

If you want to chamfer different edges with different sizes, calling this method more than once is a very inefficient way of doing it and makes keeping track of the edges indexes after each iteration almost impossible. Instead, you can include the config.distance property as an array of size/edges arrays, ensuring that each array starts with the required size and is followed by one or more edge indices to chamfer at that size, as shown in the third example below.

Kind: static method of OCC
Returns: oc.TopoDS_Solid - Returns the chamfered solid, or the given shape if no matching edges were found.

ParamTypeDescription
[config]objectA configuration object.
[shape]oc.TopoDS_ShapeThe shape to chamfer edges within.
[distance]number | Array.<Array.<number>>The distance of the chamfer, defaults to 0.
[edges]Array.<number>An array of edge indices to chamfer, defaults to all edges.

Example

/// Chamfer all edges.
const chamfer1 = PD.OCC.chamfer({
     shape: PD.OCC.cuboid({ size: [ 2000, 2000, 1000 ] }),
     distance: 200
});

/// Chamfer 4 vertical edges.
const chamfer2 = PD.OCC.chamfer({
     shape: PD.OCC.cuboid({ size: [ 2000, 2000, 1000 ] }),
     edges: [ 0, 2, 4, 6 ],
     distance: 200
});

/// Chamfer with different sizes.
const chamfer3 = PD.OCC.chamfer({
     shape: PD.OCC.cuboid({ size: [ 2000, 2000, 1000 ] }),
     distance: [
         [ 200, 0, 2, 4,  6 ],
         [ 100, 1, 5, 9, 11 ]
     ]
});

OCC.translate([config], [shapes], [offset]) ⇒ oc.TopoDS_Shape

Translates the given shape(s) by a relative vector.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the translated shape(s).

ParamTypeDescription
[config]objectA configuration object.
[shapes]oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to translate.
[offset]Array.<number>An [x,y,z] vector array defining the translation offset in each axis.

OCC.move([config], [shapes], [offset]) ⇒ oc.TopoDS_Shape

Translates the given shape(s) by a relative vector.

This method is simply an alias for the OCC.translate method.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the translated shape(s).

ParamTypeDescription
[config]objectA configuration object.
[shapes]oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to translate.
[offset]Array.<number>An [x,y,z] vector array defining the translation offset in each axis.

OCC.rotate([config], [shapes], [axis], [about], [degrees], [angle]) ⇒ oc.TopoDS_Shape

Rotates shape(s) around an axis.

When using this method, you should include either a degrees value or an angle value. If you include both, the degrees will be used in preference to the angle value.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the rotated shape(s).

ParamTypeDescription
[config]objectA configuration object.
[shapes]oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to rotate.
[axis]Array.<number> | numberAn [x,y,z] vector array defining the direction of the shape axis, or a number (X:1, Y:2, Z:3), defaults to Z axis.
[about]Array.<number>An [x,y,z] vector array defining the rotation origin.
[degrees]numberThe angle of rotation about the given axis in degrees, defaults to 0.
[angle]numberThe angle of rotation about the given axis in radians, defaults to 0.

OCC.mirror([config], [shapes], [axis], [about]) ⇒ oc.TopoDS_Shape

Mirrors the given shape(s) around a given axis.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the mirrored shape(s).

ParamTypeDescription
[config]objectA configuration object.
[shapes]oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to rotate.
[axis]Array.<number> | numberAn [x,y,z] vector array defining the direction of the shape axis, or a number (X:1, Y:2, Z:3), defaults to XZ axis.
[about]Array.<number>An [x,y,z] vector array defining the position of the axis, defaults to the origin.

OCC.scale([config], [shapes], [scale]) ⇒ oc.TopoDS_Shape

Scales the given shape(s) from the origin.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the scaled shape(s).

ParamTypeDescription
[config]objectA configuration object.
[shapes]oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>A shape or array of shapes to scale.
[scale]numberA relative scale factor to apply in each axis.

OCC.combine([config], [shapes]) ⇒ oc.TopoDS_Shape

Combines the given shape(s) into a single compound shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the compound shape.

ParamTypeDescription
[config]objectA configuration object.
[shapes]Array.<oc.TopoDS_Shape>An array of two or more shapes to combine.

OCC.union([config], [shapes], [tolerance], [keepEdges]) ⇒ oc.TopoDS_Shape

Combines a set of shapes into a single unioned shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the combined shape.

ParamTypeDescription
[config]objectA configuration object.
[shapes]Array.<oc.TopoDS_Shape>An array of two or more shapes to union.
[tolerance]numberThe tolerance to use when unioning, defaults to 0.1.
[keepEdges]booleanWhether or not to keep the original edge(s) in the shape, defaults to false.

OCC.subtract([config], [from], [subtract], [tolerance], [keepEdges]) ⇒ oc.TopoDS_Shape

Subtracts a set of shapes from a main body shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the subtracted shape.

ParamTypeDescription
[config]objectA configuration object.
[from]oc.TopoDS_ShapeThe shape to subtract from.
[subtract]Array.<oc.TopoDS_Shape> | oc.TopoDS_ShapeAn array of shapes to subtract.
[tolerance]numberThe tolerance to use when differencing, defaults to 0.1.
[keepEdges]booleanWhether or not to keep the original edge(s) in the shape, defaults to false.

OCC.intersect([config], [shapes], [tolerance], [keepEdges]) ⇒ oc.TopoDS_Shape

Computes the intersection of a set of shapes.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the intersection shape.

ParamTypeDescription
[config]objectA configuration object.
[shapes]Array.<oc.TopoDS_Shape>An array of shapes to intersect.
[tolerance]numberThe tolerance to use when intersecting, defaults to 0.1.
[keepEdges]booleanWhether or not to keep the original edge(s) in the shape, defaults to false.

OCC.extrude([config], [face], [axis], [height], [vector]) ⇒ oc.TopoDS_Shape

Extrudes a flat polygonal face into a shape.

To extrude the shape, you can provide either an extrusion vector with absolute distances for each axis in the config.vector property, or a direction and height in the config.axis and config.height properties. The extrusion vector will be used in preference to and axis and distance, so you should include only one of the options rather than both.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the extruded shape.

ParamTypeDescription
[config]objectA configuration object.
[face]oc.TopoDS_FaceAn optional closed face to extrude.
[axis]Array.<number> | numberAn [x,y,z] vector array defining the direction to extrude in, or a number (X:1, Y:2, Z:3), defaults to the +Z axis.
[height]numberThe distance to extrude in the local Z axis, defaults to 1000mm (1m).
[vector]Array.<number>An [x,y,z] vector array defining the absolute distances to extrude in each axis.

OCC.offset([config], [shape], [distance], [tolerance]) ⇒ oc.TopoDS_Shape

Offsets the edges and faces of a shape by the given distance.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the offset shape.

ParamTypeDescription
[config]objectA configuration object.
[shape]oc.TopoDS_ShapeThe shape to offset, which can also be a wire.
[distance]numberThe distance to offset the shape by, defaults to 250mm (0.25m).
[tolerance]numberThe tolerance to use when offsetting, defaults to 0.1.

OCC.revolve([config], [shape], [axis], [about], [degrees], [angle], [copy]) ⇒ oc.TopoDS_Shape

Revolves a shape by the given angle and direction.

When using this method, you should include either a degrees value or an angle value. If you include both, the degrees will be used in preference to the angle value.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the revolved shape.

ParamTypeDescription
[config]objectA configuration object.
[shape]oc.TopoDS_ShapeA shape to rotate.
[axis]Array.<number> | numberAn [x,y,z] vector array defining the direction of the shape axis, or a number (X:1, Y:2, Z:3), defaults to the +Z axis.
[about]Array.<number>An [x,y,z] vector array defining the revolution origin, defaults to the origin.
[degrees]numberThe angle of rotation about the given axis in degrees, defaults to 0.
[angle]numberThe angle of rotation about the given axis in radians, defaults to 0.
[copy]booleanWhen true revolves a copy of the given shape, defaults to false.

OCC.extrudeAndRotate([config], [wire], [axis], [height], [degrees], [angle], [steps]) ⇒ oc.TopoDS_Shape

Extrude and rotate a wire into a 3D shape.

When using this method, you should include either a degrees value or an angle value. If you include both, the degrees will be used in preference to the angle value.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the rotated twisted shape(s).

ParamTypeDescription
[config]objectA configuration object.
[wire]oc.TopoDS_WireA wire to rotate and extrude.
[axis]Array.<number> | numberAn [x,y,z] vector array defining the direction of the shape axis, or a number (X:1, Y:2, Z:3), defaults to the +Z axis.
[height]numberThe height of the extrusion, defaults to 1000mm (1m).
[degrees]numberThe angle of rotation in degrees, defaults to 0.
[angle]numberThe angle of rotation in radians, defaults to 0.
[steps]numberThe number of steps in the twisted rotation, defaults to 20.

OCC.loft([config], [wires]) ⇒ oc.TopoDS_Shape

Lofts between a set of two or more wires.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the lofted shape.

ParamTypeDescription
[config]objectA configuration object.
[wires]Array.<oc.TopoDS_Wire>The set of two or more wires to loft between.

OCC.sweep([config], [shape], [path]) ⇒ oc.TopoDS_Shape

Creates a shape by sweeping a shape along a wire path.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the swept shape(s).

ParamTypeDescription
[config]objectA configuration object.
[shape]oc.TopoDS_ShapeA shape to sweep along the path.
[path]oc.TopoDS_WireA wire defining the path to sweep along.

OCC.hollow([config], [shape], [faces], [thickness], [tolerance]) ⇒ oc.TopoDS_Shape

Creates a hollowed out solid from a closed shell.

Kind: static method of OCC
Returns: oc.TopoDS_Shape - Returns the hollowed out shape.

ParamTypeDescription
[config]objectA configuration object.
[shape]oc.TopoDS_ShapeThe shape to hollow out.
[faces]Array.<oc.TopoDS_Face>An array or one or more faces to hollow from.
[thickness]numberThe side wall thickness, defaults to 250mm (0.25m).
[tolerance]numberThe tolerance to use when hollowing, defaults to 0.1.

OCC.iterateSolids(shape, callback) ⇒ number

Invokes a callback function on all the solids in a shape.

The callback function will be invoked with two arguments, the first being the item found and the second being its ordinal index.

Kind: static method of OCC
Returns: number - Returns the number of items found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to iterate.
callbackfunctionThe callback function to invoke.

OCC.getSolidCount(shape) ⇒ number

Retrieve the number of solids within a compound shape.

Kind: static method of OCC
Returns: number - Returns the number of solid found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to examine.

OCC.getSolid(shape, [index]) ⇒ oc.TopoDS_Shape | oc.TopoDS_Solid

Extracts a particular solid from within a compound shape.

Kind: static method of OCC
Returns: oc.TopoDS_Shape | oc.TopoDS_Solid - Returns the solid at the given index, or the given shape if no matching solid was found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to extract the solid from.
[index]numberThe ordinal index of the solid within the shape, defaults to 0.

OCC.iterateShells(shape, callback) ⇒ number

Invokes a callback function on all the shells in a shape.

The callback function will be invoked with two arguments, the first being the item found and the second being its ordinal index.

Kind: static method of OCC
Returns: number - Returns the number of items found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to iterate.
callbackfunctionThe callback function to invoke.

OCC.iterateFaces(shape, callback) ⇒ number

Invokes a callback function on all the faces in a shape.

The callback function will be invoked with two arguments, the first being the item found and the second being its ordinal index.

Kind: static method of OCC
Returns: number - Returns the number of items found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to iterate.
callbackfunctionThe callback function to invoke.

OCC.getFaceCount(shape) ⇒ number

Retrieve the number of faces within a shape.

Kind: static method of OCC
Returns: number - Returns the number of faces found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to examine.

OCC.getFace(shape, [index]) ⇒ oc.TopoDS_Face | oc.TopoDS_Shape

Extracts a particular face from within a shape.

Kind: static method of OCC
Returns: oc.TopoDS_Face | oc.TopoDS_Shape - Returns the solid at the given index, or the given shape if no matching solid was found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to extract the face from.
[index]numberThe ordinal index of the face within the shape, defaults to 0.

OCC.makeTriangleFanFaces(wire) ⇒ Array.<oc.TopoDS_Face>

Generates one or more triangular faces from the geometric center and edges in a wire.

Kind: static method of OCC
Returns: Array.<oc.TopoDS_Face> - Returns one or more faces made from edges in the wire.

ParamTypeDescription
wireoc.TopoDS_WireA wire containing one or more edges.

OCC.makeFacesFromWires(wires, [allowNonPlanar]) ⇒ Array.<oc.TopoDS_Face>

Generates one or more faces from a set of properly oriented wires.

If the face is non-planar and allowNonPlanar is true, the face will be converted into a fan of triangular faces about its center.

Kind: static method of OCC
Returns: Array.<oc.TopoDS_Face> - Returns an array of one or mor faces made from the wires.

ParamTypeDescription
wiresArray.<oc.TopoDS_Wire>An array of one or more wires defining face contours.
[allowNonPlanar]booleanA flag to enable/disable converting non-planar faces to multiple triangular faces, defaults to true.

OCC.isFacePlanar(face, [tolerance]) ⇒ boolean

Determines if the face is planar or not.

Kind: static method of OCC
Returns: boolean - Returns true if the face is planar, false if it is curved.

ParamTypeDescription
faceoc.TopoDS_FaceThe face to check if planar.
[tolerance]numberThe tolerance to use when checking, defaults to 0.1.

OCC.iterateWires(shape, callback) ⇒ number

Invokes a callback function on all the wires in a shape.

The callback function will be invoked with two arguments, the first being the item found and the second being its ordinal index.

Kind: static method of OCC
Returns: number - Returns the number of items found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to iterate.
callbackfunctionThe callback function to invoke.

OCC.getWireCount(shape) ⇒ number

Retrieve the number of wires within a shape.

Kind: static method of OCC
Returns: number - Returns the number of wires found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to examine.

OCC.getWire(shape, [index]) ⇒ oc.TopoDS_Wire | oc.TopoDS_Shape

Extracts a particular wire from within a shape.

Kind: static method of OCC
Returns: oc.TopoDS_Wire | oc.TopoDS_Shape - Returns the wire at the given index, or the given shape if no matching wire was found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to extract the wire from.
[index]numberThe ordinal index of the wire within the shape, defaults to 0.

OCC.makeWiresFromContours(contours, [vertices]) ⇒ Array.<oc.TopoDS_Wire>

Construct an array of wires from one or more boundary contours that store actual vertex positions.

If the face boundary array contains one or more arrays of [x,y,z] vertices then the first will be considered the outer boundary and any subsequent boundaries will be treated as holes within the face. If the face boundary is a flat array of [ x,y,z] vertices, it will be considered as an outer boundary with no holes.

To be valid, each boundary and hole array must containing at least three (3) or more planar [x,y,z] vertices defining each of its corners.

Kind: static method of OCC
Returns: Array.<oc.TopoDS_Wire> - Returns a face created from multiple wires.

ParamTypeDescription
contoursArray.<Array.<Array.<number>>>An array of boundary contours, each containing 3 or more [x,y,z] vector arrays defining the face outlines.
[vertices]Array.<Array.<number>>An optional array of [x,y,z] vector arrays to use if contours use vertex indices not actual vertexes.

OCC.iterateEdges(shape, callback) ⇒ number

Invokes a callback function on all the edges in a shape.

The callback function will be invoked with two arguments, the first being the item found and the second being its ordinal index.

Kind: static method of OCC
Returns: number - Returns the number of items found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to iterate.
callbackfunctionThe callback function to invoke.

OCC.getEdgeCount(shape) ⇒ number

Retrieve the number of edges within a shape.

Kind: static method of OCC
Returns: number - Returns the number of edges found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to examine.

OCC.getEdge(shape, [index]) ⇒ oc.TopoDS_Edge | oc.TopoDS_Shape

Extracts a particular edge from within a shape.

Kind: static method of OCC
Returns: oc.TopoDS_Edge | oc.TopoDS_Shape - Returns the edge at the given index, or the given shape if no matching edge was found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to extract the edge from.
[index]numberThe ordinal index of the edge within the shape, defaults to 0.

OCC.iterateVertices(shape, callback) ⇒ number

Invokes a callback function on all the vertices in a shape.

The callback function will be invoked with two arguments, the first being the item found and the second being its ordinal index.

Kind: static method of OCC
Returns: number - Returns the number of items found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to iterate.
callbackfunctionThe callback function to invoke.

OCC.getVertexCount(shape) ⇒ number

Retrieve the number of edges within a shape.

Kind: static method of OCC
Returns: number - Returns the number of edges found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to examine.

OCC.getVertex(shape, [index]) ⇒ oc.TopoDS_Vertex | null

Extracts a particular vertex from within a shape.

Kind: static method of OCC
Returns: oc.TopoDS_Vertex | null - Returns the vertex at the given index, or the given shape if no matching vertex was found.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to extract the vertices from.
[index]numberThe ordinal index of the vertex within the shape, defaults to 0.

OCC.getVertexPos(vertex) ⇒ Array.<number>

Extracts the vertex position as an [x,y,z] vector array.

Kind: static method of OCC
Returns: Array.<number> - Returns the coordinates as an [x,y,z] vector array.

ParamTypeDescription
vertexoc.TopoDS_VertexThe vertex to get the coordinates from.

OCC.processJSON(json) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> | null

Parses a JSON geometry node.

Kind: static method of OCC
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> | null - Returns a shape or null if json is invalid.

ParamTypeDescription
jsonobject | ArrayA parsed JSON object or array of objects.

OCC.checkToConvertFromJSON(shapes, [ignoreSolids]) ⇒ oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

Checks for JSON data and converts to OpenCascade shapes.

Kind: static method of OCC
Returns: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape> - Returns TopoDS_Shape(s).

ParamTypeDescription
shapesArray.<object> | Array.<oc.TopoDS_Shape>A JSON or shape array.
[ignoreSolids]booleanWhen true, solids will not be converted, defaults to false.

OCC.shapeToMesh(shape, maxDeviation, fullShapeEdgeHashes, fullShapeFaceHashes) ⇒ Array.<Array>

Converts a shape, or composite shape to a mesh.

Kind: static method of OCC
Returns: Array.<Array> - Returns the faces and edges that make up the shape.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to convert.
maxDeviationnumberThe tolerance for linear and angle deflection, defaults to 0.5.
fullShapeEdgeHashesobjectAn object containing edge hashes.
fullShapeFaceHashesobjectAn object containing face hashes

OCC.getFaceTriangulation(shape, maxDeviation) ⇒ Array.<Array>

Compute the triangular tesselation from a shape.

Kind: static method of OCC
Returns: Array.<Array> - Returns the faces and edges that make up the shape.

ParamTypeDescription
shapeoc.TopoDS_ShapeThe shape to convert.
maxDeviationnumberThe tolerance for linear and angle deflection, defaults to 1.0.

OCC.progressOperation(level, [operation])

Check first if processing has been cancelled and, if not, format the operation and add it to the progress log.

The movement of the progress bar should not be affected by the current log level so, if the log level is less than the level of this operation, we still need to send undefined to the host application to increment it.

Kind: static method of OCC Throws:

  • Error Throws and error if process cancelled.
ParamTypeDescription
levellevelThe log level of the operation.
[operation]stringThe name of the operation to log.

PD.Shape

A simple and efficient class for defining manifold facetted shapes.

This class is a much simpler and leaner version of the PD.BRep and PD.Shell classes. Shapes are assembled from a set of spatial vertices defined as [x,y,z] vector arrays that are shared by the boundaries of planar faces that reference them by index. These planar faces should typically form a topologically closed (manifold) shape that completely bounds an internal volume of space.

It is possible to create shapes that are not topologically closed, do not have planar faces or do not share common vertices between connected faces. However, many of the analysis and modifier methods in this class, as well as the external computations that use them, do assume that manifold conditions will be met as the ability to create and manipulate closed faceted shapes really is the core raison d’etre of this class.

Thus, you can use this class any way you wish for interim geometry or to store data temporarily, but if you want to use the built-in modifiers or have the shape participate in computations or analysis, you should strive to ensure that the final result is topologically closed, uses shared vertices and has planar facets.

Topologically Closed

To be topologically closed means that the shape completely bounds an internal volume with faces that are all connected together at their edges and share common vertices. This is also called a manifold shape and means that every vertex must be shared by at least three edges and every edge must be shared by exactly two faces. Each face must be defined by a single outer boundary loop of vertex indices. A face in a shape cannot contain internal hole boundaries, but must instead be broken down into a series of separate faces that bound the hole.

Array-Based Vertices

A very important characteristic of this class is that all vertices are and must be stored as [x,y,z] vector arrays rather than point objects. Using array-based vertices and faces actually makes this data structure enormously flexible and efficient as an interim format for creating, modifying and storing closed faceted shapes. Obviously primitive shapes are at its core, but this also includes those with highly faceted curved surfaces and forms derived from volumetric grids.

This is mainly because each triangle or quad is just an array of three or four integer ordinal indexes, and every vertex is spatially unique and just an array of three numbers. Also, as long as the first three entries in each vertex array always remain as its x, y and z coordinates, external processes can append additional entries to the array for things like vertex normals, colors, UV and even extra coordinates to morph the shape between. Obviously this additional information will not always be retained if you then go on to apply any modifier(s) that changes the geometry of the shape.

Another important point is that this class does not provide any built-in way to reuse its existing memory, and does not store face normals, triangulation or shared edge data. These are all calculated when required by calling the normals, edges and vertexNormals methods. This makes it not well suited for storing geometry that needs to be regularly converted to a renderable mesh. This is what the PD.BRep and PD.Shell classes are intended for.

Also, whilst you can compute and store per-vertex normals if you really want to, this is not a particularly good class for working with multiple connected smoothly curved surfaces. Many of its core applications rely on having unique vertices shared between polygonal faces as a way to determine inter-connection relationships. As a vertex can only store a single normal direction, those shared by faces with sharply different normal directions will only be able to represent one of them, or have an averaged normal that actually reflects none of them. This can be useful for offsetting 3D geometry, but not for displaying it. The only option is to have separate vertices for each face, but that will break all inter-connection calculations.

As a result, this class is mainly used by the framework for creating interim geometry that can take advantage of the unique characteristics of this format and its ability to efficiently modify, process and transform basic shapes, that is then converted to and stored as either a PD.BRep and PD.Shell. When used this way, you can iteratively create amazing and complex geometric forms and only have to compute surface normals, extents and other metrics on the final shape.

To assist with the array-based vector math involved in the creation, modification and transformation of these kinds of forms, the framework provides the VectorArray, PlaneArray, QuaternionArray and MatrixArray classes. The framework also links to a set of array-based vector geometry libraries for generating 2D and 3D convex hulls, surface triangulations and noise generation.

Kind: static class of PD
Author: drajmarsh

new PD.Shape([vertices], [faces], [name])

Constructor for an empty shape.

ParamTypeDescription
[vertices]Array.<Array.<number>>A flat array of [x,y,z] vertex coordinates.
[faces]Array.<Array.<number>>An array of face boundary arrays, each containing three or more vertex indices.
[name]stringA human-readable name for the shape.

shape.name : string

A human-readable name for the shape.

Kind: instance property of Shape

shape.vertices : Array.<Array.<number>>

A flat array of vertex coordinates stored as [x,y,z] vector arrays.

Each vertex is an array of three (3) numbers representing the X, Y and Z coordinates of a spatial point, referred to as an [x,y,z] vector array. These vertices are assembled into edges and boundaries by the faces array.

Kind: instance property of Shape

shape.faces : Array.<Array.<number>>

An array of face boundary arrays, each containing three or more vertex indices.

Each face is an array of ordinal indices of the vertexes in the vertices array that form its boundary.

Kind: instance property of Shape

shape.colors : Array.<number> | Array.<Array.<number>>

An array of [r,g,b] face colors.

This array is only valid if it is exactly the same length as the faces array. Each entry in this array is the color associated with the corresponding face in the faces array.

Kind: instance property of Shape

shape.isShape : boolean

A flag identifying this object as a shape.

Kind: instance property of Shape
Read Only: true

shape.toJSON([data]) ⇒ object

Converts the object instance to a simple POJO for JSON storage.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

NOTE: As vertexes are simple [x,y,z] vector arrays and each face is just an array of ordinal vertex indexes, both the faces and vertices arrays are used directly by the JSON object rather than being copied. This makes converting shapes to JSON very fast and efficient, which is important as this class is used quite a lot for data exchange. If you want to deep copy the data arrays, see the example code below:

Kind: instance method of Shape
Returns: object - Returns a JSON object.

ParamTypeDescription
[data]objectAn optional parent object to append this data to.

Example

const shallow_copy = shape.toJSON();
const deep_copy = shape.clone().toJSON();

shape.fromJSON(data) ⇒ Shape

Safely copy properties from a source object.

NOTE: If vertexes are given as [x,y,z] vector arrays, and faces as arrays of ordinal indexes, then both the faces and vertices data arrays are used directly rather than copied to the shape. This makes creating shapes from JSON very fast and efficient, which is important as this class is used quite a lot for data exchange. If you want to deep copy the data arrays, see the example code below:

Kind: instance method of Shape
Returns: Shape - Returns this instance to support method chaining.

ParamTypeDescription
dataobjectThe source object containing data to copy.

Example

const shallow_copy = new PD.Shape().fromJSON(data);
const deep_copy = new PD.Shape().fromJSON(data).clone();

shape.clone() ⇒ Shape

Creates a deep copy of this shape.

Kind: instance method of Shape
Returns: Shape - Returns a new shape. Example

const shape = PD.Shape.prism(9, 1500, 1000).ortho();
CAD.add(shape.clone().inflate(200));
CAD.add(shape);

shape.copy(shape) ⇒ Shape

Performs a shallow copy of the data in the given shape.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
shapeShapeThe shape to copy from.

shape.makeDefaultShape() ⇒ Shape

Makes this shape a 4-sided unit tetrahedron as the default shape for empty shapes.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

shape.hasContent() ⇒ boolean

Determines whether or not the shape has any content.

This method does a very simple check to see if there are any vertices and any faces. It doesn’t do any validity or sanity checking, just looks for content.

Kind: instance method of Shape
Returns: boolean - Returns true if shape has one or more valid edge/facet.

shape.addVertex(vertex) ⇒ number

Retrieves the next reusable vertex in the surface, or creates and adds a new one.

The argument to this method can be either a simple [x,y,z] vector array or an {x,y,z} object such as a THREE.Vector3, PD.Point or similar object class. This method fetches from or creates vertices in vertexList by incrementing an internal counter that is reset to zero when the reuseStart() method is called.

Kind: instance method of Shape
Returns: number - Returns the index of the added vertex in the vertices list.

ParamTypeDescription
vertexArray.<number>The [x,y,z] vector array to add to the vertex list.

shape.edges() ⇒ Array.<Array.<number>>

Computes a non-redundant list of the shape’s edges.

The edges of a shape are simply arrays containing two integer values, being the ordinal indices of the start and end vertices of the edge within the vertices array.

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Returns an array of unique edges. Example

const poly = new PD.Polyhedron('D8:tk').scale(2000);

/// Display polyhedron as wires.
for (const edge of poly.edges()) {
    const points = edge.map(index => poly.vertices[index]);
    CAD.addWire(points, false);
}

/// Cut section and display as a face.
const section = PD.Shape.generateSection(poly, [ -1, -1, 4, -200 ]);
if (section?.faces) {
    CAD.addShell(section);
}

shape.centers() ⇒ Array.<Array.<number>>

Computes a list of face center points.

The center of each face is returned as an [x,y,z] vector array defining its spatial position in each major axis.

The order and index of center points in the returned list match the order and index of corresponding faces in the faces list.

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Returns an array of face centers. Example

const shape = PD.Shape.domeGeodesic(4, 2000)

/// Find bottom face.
let bottom_face_index = -1;
let bottom_face_min_z = Infinity;
const face_centers = shape.centers();
for (let ii = 0; ii < face_centers.length; ++ii) {
    if (bottom_face_min_z > face_centers[ii][2]) {
        bottom_face_min_z = face_centers[ii][2];
        bottom_face_index = ii;
    }
}

/// Show bottom face as face.
if (bottom_face_index >= 0) {
    const points = shape.faces[bottom_face_index].map(index => shape.vertices[index]);
    CAD.addPolygon(points);
}

shape.normals() ⇒ Array.<Array.<number>>

Computes a list of face normal vectors.

The normal vector of each face is returned as an [x,y,z] vector array of unit length (normalized) defining its spatial direction in each major axis.

The order and index of normals in the returned list match the order and index of corresponding faces in the faces list.

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Return an array of face normals. Example

const distance = 250;
const face_normals = shape.normals();
for (let ii = 0; ii < shape.faces.length; ++ii) {
    for (const index of shape.faces[ii]) {
        hull_vertices.push(
            PD.VectorArray.translateInVectorDirection([], shape.vertices[index], face_normals[ii], distance)
        );
    }
}

shape.vertexNormals() ⇒ Array.<Array.<number>>

Computes the averaged surface normal for each vertex.

The normal vector of each vertex in the shape is returned as an [x,y,z] vector array of unit length (normalized) defining its spatial direction in each major axis. Vertex normals are calculated as the average of all the face normals from faces that contain that vertex.

The order and index of vertex normals in the returned list match the order and index of corresponding vertices in the vertices list.

To allow further processing, additional information is appended to each normal array. Assuming the vertex is shared by N faces, each normal array has the following form:

[ normalX, normalY, normalZ, N, faceIndex1, faceIndex2, …, faceIndexN ]

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Returns an array of averages vertex normals. Example

const distance = 250;
const vertex_normals = shape.vertexNormals();
for (let ii = 0; ii < shape.vertices.length; ++ii) {
    hull_vertices.push(
        PD.VectorArray.translateInVectorDirection([], shape.vertices[ii], vertex_normals[ii], distance)
    );
}

shape.extents([min], [max]) ⇒ Array.<Array.<number>>

Computes the minimum and maximum extents of the shape.

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Return a [min,max] array of two [x,y,z] vector arrays.

ParamTypeDescription
[min]Array.<number>An optional [x,y,z] vector array to receive the minimum extents.
[max]Array.<number>An optional [x,y,z] vector array to receive the maximum extents.

Example

/// Create cylinder with 12 sides and 20 segments.
const shape = PD.Shape.cylinder(12, 2000, 5000, 20);

/// Compute range values in Z axis.
const [ min, max ] = shape.extents();
const bot_z = min[2] + ((max[2] - min[2]) * 0.25);
const top_z = min[2] + ((max[2] - min[2]) * 0.90);

/// Apply a scaling factor over the range.
shape.scaleByAxis(2, bot_z, top_z, 2.0, PD.Easing.inOutQuart);
CAD.add(shape);

shape.connections() ⇒ Array.<Array.<Array.<number>>>

Computes and assembles the connection relationships between faces, edges and vertices.

This method returns an object with two arrays as properties:

  • vertices: An array of vertices with the indexes of each of the other vertices they connect to via an edge. This array is in the form [ v1, v2, v3, … ] and uses the same ordinal indexes as the vertices array.

  • edges An array of edges with two vertex indices followed by the indexes of the two faces they share. This array is in the form [ v1, v2, f1, f2 ].

The vertex indexes in the edges array are ordered such that the lowest ordinal index always comes first (array[0]) followed by the highest ordinal (array[1]). The face indexes are ordered such that, in the first face (array[2]), the direction of travel along the edge is from first vertex to second. In the second face (array[3]), the direction of travel is from the second vertex (array[1]) back to the first (array[0]).

Kind: instance method of Shape
Returns: Array.<Array.<Array.<number>>> - Returns an array of vertex and edge connections.

shape.openEdgeLoops() ⇒ Array.<Array.<number>>

Collects all edges that are not shared by two faces and assembles them into an array of one or more loops.

This method relies on all coincident edges sharing the same vertices, which means that the shape cannot have ‘T’ junctions where two faces meet somewhere along the edge of another face where it doesn’t have a vertex. If you are not absolutely sure of the inter-connection state of your shape, call the weld method first.

The loops generated by this method will likely be closed but not be planar. If the shape is more like an open surface, you should end up with one big outer boundary loop. If the shape is mostly closed, but has some holes within it, you should end up with loops for each hole.

You will need to work out how best to close a shape if you find that it has open edges.

The vertex indexes in the edges array are ordered such that the lowest ordinal index always comes first (array[0]) followed by the highest ordinal (array[1]).

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Returns an array of open edge loops. Example

/// Collect open edges and fill in top and bottom holes.
const super_shape = PD.Shape.superFormula({ innerRadius: 0.5, unfoldZ: 0.125 });
super_shape.scale(500).setRadiusXY(5000).weld();
const open_edges = super_shape.openEdgeLoops();
for (const loop of open_edges) {
    super_shape.faces.push(loop);
}

CAD.add(super_shape);

shape.faceCenter(face, [target]) ⇒ Array.<number>

Compute the geometric center of the given face.

The center of the face is returned as an [x,y,z] vector array defining its spatial position in each major axis.

Kind: instance method of Shape
Returns: Array.<number> - Return an [x,y,z] vector array defining the face center.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.
[target]Array.<number>An optional [x,y,z] vector array to receive the calculated center, defaults to a new vector array.

Example

const shape = PD.Shape.domeGeodesic(4, 2000)

/// Display shape as wires.
for (const edge of shape.edges()) {
    const points = edge.map(index => shape.vertices[index]);
    CAD.addWire(points, false);
}

/// Find bottom face.
const center = [ 0, 0, 0 ];
let bottom_face_index = -1;
let bottom_face_value = Infinity;
for (let ii = 0; ii < shape.faces.length; ++ii) {
    shape.faceCenter(ii, center);
    if (bottom_face_value > center[2]) {
        bottom_face_value = center[2];
        bottom_face_index = ii;
    }
}

/// Show bottom face as face.
if (bottom_face_index >= 0) {
    const points = shape.faces[bottom_face_index].map(index => shape.vertices[index]);
    CAD.addPolygon(points);
}

shape.faceNormal(face, [target]) ⇒ Array.<number>

Compute the surface normal of the given face.

The normal vector of the face is returned as an [x,y,z] vector array of unit length (normalized) defining its spatial direction in each major axis.

Kind: instance method of Shape
Returns: Array.<number> - Returns the modified target if it is given or a new [x,y,z] vector array defining the face normal.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.
[target]Array.<number>An optional [x,y,z] vector array to receive the calculated normal, defaults to a new vector array.

Example

const distance = 250;
const face_normal = [];
for (let ii = 0; ii < shape.faces.length; ++ii) {
    for (const index of shape.faces[ii]) {
        hull_vertices.push(
            PD.VectorArray.translateInVectorDirection([], shape.vertices[index], face_normals[ii], distance)
        );
    }
}

shape.faceVertices(face) ⇒ Array.<Array.<number>>

Retrieves the face as an array of actual vertices, being the [x,y,z] vector arrays representing each point on the face boundary.

NOTE: This method returns the actual vertex arrays from the shape vertex list, so any changes you make to the vertex arrays will propagate across all faces that share the same vertices.

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Return an array of [x,y,z] vector array points the define the face boundary.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.

Example

const shape = PD.Shape.domeGeodesic(4, 2000)

/// Find bottom face and show as filled polygon.
const bot_face = shape.findExtremeFace([ 0, 0, -1 ]);
if (bot_face.index >= 0) {
    const points = shape.faceVertices(bot_face.index);
    CAD.addPolygon(points);
}

/// Show rest of shape as wires.
for (const edge of shape.edges()) {
    const points = edge.map(index => shape.vertices[index]);
    CAD.addWire(points, false);
}

shape.faceInset(face, [inset], [offset], [normal]) ⇒ Array.<Array.<number>>

Computes a set of vertices inset from the edges of the given face.

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Return an array of new inset/offset vertices.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.
[inset]numberAn inset distance from each edge in model units, defaults to 0 (no inset).
[offset]numberAn optional distance from face surface, defaults to 0 (no offset).
[normal]Array.<number>An optional [x,y,z] vector array to receive the calculated face normal so you don’t need to compute it again.

shape.faceExtrude(face, distance, [direction], [segments]) ⇒ Array.<Array.<number>>

Extrudes the given face in the given direction and distance.

This method displaces the given face and adds extruded side faces. If the optional segments argument has an integer value of greater than one (1), the extrusion will be done in a series of that many segments.

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Return an array of all the new faces just added.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.
distancenumberThe total distance to extrude, in model units.
[direction]Array.<number>The direction to extrude in as an [x,y,z] vector array. defaults to the face’s surface normal.
[segments]numberThe number of segments to extrude the face in, defaults to 1.

Example

const cut_faces = [];
const cut_plane = [ 0, 0, 1, 0 ];
const poly = new PD.Polyhedron('D8:jeh(0.15,0.025)ajS9000');
const dome_with_holes = PD.Shape.cutAt(poly, cut_plane, 1, cut_faces).translate([ 0, 0, 3000 ]);
for (const face of cut_faces) {
    dome_with_holes.faceExtrude(face, -3000, cut_plane, 3);
}
CAD.add(dome_with_holes);

shape.computeCentroid() ⇒ Array.<number>

Computes the geometric center point of the shape by averaging all of its vertices.

Kind: instance method of Shape
Returns: Array.<number> - Returns the centroid as an [x,y,z] vector arrays.

shape.closestAndFarthestFromPlane(plane) ⇒ Array.<Array.<number>>

Computes the vertex positions that are closest to and farthest away from the given plane.

Kind: instance method of Shape
Returns: Array.<Array.<number>> - Returns a [closest,farthest] array of [x,y,z] vector arrays.

ParamTypeDescription
planenumber | Array.<number>A [a,b,c,d] plane array or vertical height value in the Z axis to slice the shape at.

Example

const slices = 4;
const plane = [  1,  0.25,  0,  10000 ];
const shape = PD.Shape.cuboid(4000, 2000, 1000);
const [ closest, farthest ] = shape.closestAndFarthestFromPlane(plane);
const start = -PD.VectorArray.dot(closest, plane);
const end = -PD.VectorArray.dot(farthest, plane);
const inc = (end - start) / (slices + 1);

for (let ii = 1; ii <= slices; ++ii) {
    plane[3] = start + (ii * inc);
    shape.cutAt(plane, 0);
}

CAD.addSolid(shape);
const frame = PD.Shape.frame(shape, 50, 50);
CAD.add(frame);

shape.findExtremeFace([normal]) ⇒ object

Finds the face with a centre point at the extreme edge of the shape in one of the major cartesian axis.

This method is used to find a reference face to use for orienting all others. To be facing ‘outwards’, the normal of the most extreme face in one of the major axis must point in the same direction as that axis.

Kind: instance method of Shape
Returns: object - Returns an object with face, extreme.index and extreme.axis properties, being the actual face, its index in the faces array and the axis (0, 1 or 2).

ParamTypeDescription
[normal]Array.<number>An optional [x,y,z] vector array giving the direction to search in, defaults to any.

Example

const { face, index, axis } = shape.findExtremeFace();

/// Ensure extreme face normal points in same direction as extreme axis.
PD.VectorArray.calcNormalFromIndexedPathNewellMethod(normal, face, this.vertices);
if (normal[axis] < 0) {
     face.reverse();
}

Example

const shape = PD.Shape.domeGeodesic(4, 2000)

/// Find bottom face and show as filled polygon.
const bot_face = shape.findExtremeFace([ 0, 0, -1 ]);
if (bot_face.index >= 0) {
    const points = shape.faceVertices(bot_face.index);
    CAD.addPolygon(points);
}

/// Display shape as wires.
for (const edge of shape.edges()) {
    const points = edge.map(index => shape.vertices[index]);
    CAD.addWire(points, false);
}

shape.translate(offset) ⇒ Shape

Applies a [dx,dy,dz] translation to this shape.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
offsetArray.<number>A [x,y,z] vector array to move by.

shape.rotate(origin, axis, angle) ⇒ Shape

Rotates the shape around the given origin/axis by the given angle.

The origin is effectively the point about which the rotation should take place. It is subtracted from each point prior to the rotation, then added back afterwards.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
originArray.<number>The [x,y,z] vector array defining the origin point to rotate about.
axisArray.<number>The [x,y,z] vector array defining the axial vector to rotate around.
anglenumberThe angle of rotation, in radians.

shape.scale(scale) ⇒ Shape

Applies a scaling factor to this shape.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
scalenumber | Array.<number>A scale factor or [sx,sy,sz] vector array to multiple vertices by.

shape.scaleByAxis(axis, from, to, scale, [easing]) ⇒ Shape

Scales the shape in the other two axis by an amount that varies over a range within the given axis.

If the from and to values are both in the range 0 to 1, then they are considered to be fractions of the size of the shape in the given axis. If either value is outside the range 0 to 1, then they are both considered to be in absolute model units along the axis.

You can use the extents method if you want to find out the size range of your specific shape in each axis.

If the scale is given as a single number, it represents the maximum scale at the to point on the axis, varying from 1 at the from point. If given as a [fromScale, toScale] array, you can specify the scales to use at both the from and to points. You can specify an easing function if you wish to make it a non-linear variation.

If you choose the Z axis, then the varying scale will be applied to the X and Y components of each vertex in the shape. If you choose the X axis the scale will be applied in Y and Z, and for the Y axis, it will be applied in X and Z.

If you wish to scale vertexes in a non-Cartesian axis or about a point other than the origin, use the PD.AxisArray#scalePointsInXY method instead.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
axisnumberThe axis to scale in (0:X, 1:Y or 2:Z).
fromnumberA value on the given axis to start scaling from ,in model units.
tonumberA value on the given axis to finish scaling at, in model units.
scalenumber | Array.<number>The scale at or above the to value, or a [fromScale,toScale] array, defaults to 1 (no scale).
[easing]functionAn easing function to use, defaults to linear.

Example

/// Scale cylinder with 12 sides and 20 segments.
const shape = PD.Shape.cylinder(12, 2000, 5000, 10);
shape.scaleByAxis(2, 0, 1, 2.0, PD.Easing.inOutQuint);
CAD.add(shape);

const frame = PD.Shape.frame(shape, 25, 50);
CAD.add(frame);

shape.stretchByAxis(axis, from, to, [scale], [easing]) ⇒ Shape

Stretches the vertices of shape over a range in the given axis.

If the from and to values are both in the range 0 to 1, then they are considered to be fractions of the size of the shape in the given axis. If either value is outside the range 0 to 1, then they are both considered to be in absolute model units along the axis.

You can use the extents method if you want to find out the size range of your specific shape in each axis.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
axisnumberThe X, Y or Z axis to use (0:X, 1:Y, 2:Z).
fromnumberA value on the given axis to start stretching from in model units.
tonumberA value on the given axis to finish stretching at in model units.
[scale]numberThe amount to scale the axis range area by, defaults to 1 (no scale).
[easing]functionAn easing function to use, defaults to linear.

Example

/// Stretch cylinder with 12 sides and 20 segments.
const shape = PD.Shape.cylinder(12, 2000, 2500, 10);
shape.stretchByAxis(2, 0.25, 1.0, 2.0, PD.Easing.inOutCubic);
CAD.add(shape);

const frame = PD.Shape.frame(shape, 25, 50);
CAD.add(frame);

Example

/// Stretch cylinder with 24 sides and 10 segments.
const shape = PD.Shape.cylinder(24, 2000, 2500, 10);
shape.stretchByAxis(0, 0, 1, 4.0, PD.Easing.inOutQuint);
shape.stretchByAxis(2, 0, 1, 2.0, PD.Easing.outCubic);
shape.meta().cutAt(1700, 1).cutAt(7000, -1).translate([ 0, 0, -1700 ]);
CAD.add(shape);

const frame = PD.Shape.frame(shape, 25, 25).expand().ambo().join();
CAD.add(frame);

shape.twistByAxis(axis, from, to, angle, [easing]) ⇒ Shape

Rotates the shape in the other two axis by an angle that varies over a range within the given axis.

If the from and to values are both in the range 0 to 1, then they are considered to be fractions of the size of the shape in the given axis. If either value is outside the range 0 to 1, then they are both considered to be in absolute model units along the axis.

You can use the extents method if you want to find out the size range of your specific shape in each axis.

If the angle is given as a single number, it represents the maximum twist angle at the to point on the axis, varying from 0 at the from point. If given as a [fromAngle, toAngle] array, you can specify the angles to use at both the from and to points. You can specify an easing function if you wish to make it a non-linear variation.

If you choose the Z axis, then the twist will be applied to the X and Y components of each vertex in the shape. If you choose the X axis the twist will be applied in Y and Z, and for the Y axis, it will be applied in X and Z.

If you wish to scale vertexes in a non-Cartesian axis or about a point other than the origin, use the PD.AxisArray#twistPointsInXY method instead.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
axisnumberThe axis to twist in (0:X, 1:Y or 2:Z).
fromnumberA value on the given axis to start twisting from ,in model units.
tonumberA value on the given axis to finish twisting at, in model units.
anglenumber | Array.<number>The angle at or above the to value, or a [fromAngle,toAngle] array, defaults to 0 (no twist).
[easing]functionAn easing function to use, defaults to linear.

Example

/// Twist cylinder with 12 sides and 20 segments.
const shape = PD.Shape.cylinder(12, 2000, 5000, 10);
shape.twistByAxis(2, 0.1, 0.95, Math.PI / 4, PD.Easing.inOutSine);
CAD.add(shape);

const frame = PD.Shape.frame(shape, 25, 50);
CAD.add(frame);

Example

const shape = PD.Shape.dome(8, 6, 4000);
shape.extrudeBase(5000, 5).triakis(0, -100);
shape.twistByAxis(2, -5000, 4000, Math.PI / 3, PD.Easing.inOutSine);
CAD.add(shape);

const frame = PD.Shape.frame(shape).expand().join().join();
CAD.add(frame);

shape.align([alignX], [alignY], [alignZ], [point]) ⇒ Shape

Moves this shape to align it in each axis with the given point.

The axial alignment values are given as fractions of the shape’s extents in that axis. A value of zero in any axis means that the shape will align centrally at the point. A value of 1 means that shape will align its minimum edge at the point, and a value of -1 means that it will align its maximum edge. You can use any fractional values (eg: 0.5) or even multiples (eg: 2.5) in any axis.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[alignX]numberThe X axis alignment factor (-1 to 1), defaults to 0.
[alignY]numberThe Y axis alignment factor (-1 to 1), defaults to alignX.
[alignZ]numberThe Z axis alignment factor (-1 to 1), defaults to alignX.
[point]Array.<number>An [x,y,z] vector array for the point to align with, defaults to origin [0,0,0].

Example

const box = PD.Shape.cuboid(3000, 2000, 1000);
CAD.add(box.align(1, 1, 1));

shape.setSize([sizeX], [sizeY], [sizeZ]) ⇒ Shape

Rescales all vertices so that the dimensions of the shape’s bounding box in each of the X, Y and Z axis is as given.

This method differs from setRadius in that it is based on the bounding box (extents) of the shape rather than the distance of vertices from its centre.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[sizeX]numberThe width of the shape in the X-axis, defaults to 1.
[sizeY]numberThe depth of the shape in the Y-axis, defaults to width.
[sizeZ]numberThe height of the shape in the X-axis, defaults to width.

Example

const super_shape = PD.Shape.superFormula();
super_shape.setSize(5000, 5000, 3500);
CAD.add(super_shape);

shape.setRadius([radius]) ⇒ Shape

Rescales all vertices so that the maximum radius of the shape from the origin in all axis is equal to the given radius.

If you want to set the size based on the actual extents of the shape, use the setRadius method instead.

NOTE: This method assumes that the shape is centred at the origin.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[radius]numberThe radius to normalise shape to, defaults to 1.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.bevel(poly).setRadius(3440));
CAD.add(poly);

shape.setRadiusXY([radius], [height]) ⇒ Shape

Rescales all vertices so that the maximum radius of the shape in the X and Y axis is equal to the given radius.

If you provide the optional height argument, the height of the shape in the Z axis will be normalised to that too,

NOTE: This method assumes that the shape is centred at the origin.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[radius]numberThe radius to normalise shape to, defaults to 1.
[height]numberThe height to normalise shape to, defaults to 1.

Example

const super_shape = PD.Shape.superFormula();
super_shape.setHeight(2500).setRadiusXY(3500);
CAD.add(super_shape);

shape.setHeight([height]) ⇒ Shape

Rescales all vertices so that the maximum range of the shape in the Z axis is equal to the given height.

NOTE: This method assumes that the shape is centred at the origin.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[height]numberThe height to normalise shape to, defaults to 1.

Example

const super_shape = PD.Shape.superFormula();
super_shape.setHeight(2500).setRadiusXY(3500);
CAD.add(super_shape);

shape.setColor(color) ⇒ Shape

Assigns a single color to all faces of the shape.

This method is a convenience method for setting the colors array to a single color value.

NOTE: This method overwrites any existing data in the colors array.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
colorArray.<number>The color to assign all faces, as an [r,g,b] array.

shape.reverse() ⇒ Shape

Reverses the orientation of all faces in the shape.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

shape.weld([decimals]) ⇒ Shape

Iterates the shape to merge vertices that share the same positions and ensure that adjacent edges share the same vertices.

This also ensures that all faces are oriented outwards relative to the geometric centre of the shape.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[decimals]numberThe number of decimal places when comparing millimeter coordinates, defaults to 1 (0.1mm).

Example

const config = {
    params: [ 1, 4, 0, 0, 0, 0, 2, -3 ],
    innerRadius: 0.5,
    unfoldZ: 0.75
};

const half_shape = PD.Shape.sphericalHarmonics(config).scale(400);
half_shape.cutAt(0, 1).cutAt(4500, -1).weld().join().expand();
CAD.add(half_shape);

shape.ensureOutwardOrientation() ⇒ Shape

Iterates the shape to ensure that all faces are oriented outwards relative to the geometric centre of the shape.

A face normal is considered to be pointing inwards if the dot product of its vector towards the centroid is positive, in which case the face is reversed.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

shape.ensureOutwardOrientation_MoreRobust() ⇒ Shape

Iterates the shape to ensure that all faces are oriented outwards by referencing a known good face.

This method uses a reference face as a reference and compares all other to it. The reference face is determined as the one with a centre point at the most extreme edge in one of the major cartesian axis. To be facing ‘outwards’, the normal of the most extreme face in must point in the same direction as that axis. Once this condition is met, all other faces can be oriented relative to that one.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

shape.applyMatrix(matrix) ⇒ Shape

Applies a transformation matrix to this shape.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
matrixArray.<number>The 16-item (4x4) column-major matrix to apply.

shape.applyQuaternion(quaternion) ⇒ Shape

Applies a rotational quaternion to this shape.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
quaternionArray.<number>The [x,y,z,w] quaternion to apply.

shape.applyAxis(axis) ⇒ Shape

Aligns this shape with the local coordinate axis.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
axisAxisArrayThe local coordinate axis to apply.

Example

const segments = 12;

/// Create base shape to work on.
const cyl = PD.Shape.cylinder(segments, 1000, 500);

/// Create local coordinates.
const axis = new PD.AxisArray();
axis.moveOrigin(0, 2000, 0);
axis.rotateZ(Math.PI / 4);
cyl.applyAxis(axis);

/// Create different positive/negative scales.
const scale_positive = [3.50, 1.5, 1.0];
const scale_negative = [1.25, 1.5, 1.0];

/// Extract the bottom ring of vertices.
const base = cyl.vertices.slice(0, segments);

/// Apply both scales about the origin.
axis.scalePoints(base, scale_positive, scale_negative);
CAD.add(cyl);

shape.inflate(distance, [checkPlanes]) ⇒ Shape

Expand all vertices in the direction of their surface normals by the given distance.

Expansion is different from offsetting in that the given distance refers to the movement of each vertex rather than to each face. Vertices move in the direction of their average surface normals, which is effectively the normalised sum of each face normal that the vertex is shared by. Movement is outwards if the distance is positive or inwards if it is negative.

The result is a set of vertices that are exactly the given distance away from their original positions. Depending on the number of faces shared by each vertex, and their relative orientations, this may result in faces changing orientation slightly and not being parallel to their original position. In some rare cases it may even result in faces that are no longer planar.

If you want to specify the exact perturbation distance of faces rather than vertices use the offset method instead.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
distancenumberThe expansion distance, defaults to 0.
[checkPlanes]numberExtra checks (0:None, 1:OnePlane, 2:AllPlanes), defaults to 0.

Example

const shape = PD.Shape.prism(9, 1500, 1000).ortho();
CAD.add(shape.clone().inflate(200));
CAD.add(shape);

shape.offset(distance, [detail]) ⇒ Shape

Modifies the shape by expanding all facets in the direction of their surface normals by the given distance, but maintaining their exact shape and surface area.

This process moves existing faces outwards and adds additional faces to cover the now open gaps and seams between them. The benefit of this method is that you can offset any convex shape by any positive amount, even many thousands of times its radius, and still have a valid shape shape.

Unfortunately this isn’t true of concave shapes or when the distance value is negative. In these cases, maintaining the shape and area of facets isn’t possible as they simply have to shrink in order to fit. As a result, this method will redirect to the expand method when the given distance is less than zero.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
distancenumberThe explosion distance as a positive value, defaults to 0 (no change).
[detail]numberThe geometric detail at each corner (0 to 2), defaults to 2.

shape.offsetHull(distance, [detail]) ⇒ Shape

Modifies the shape by generating a convex hull offsetting all vertices, edges and facets by their surface normals, but maintaining the exact shape and surface area of each facet.

This process modifies this shape by creating new vertex positions for all faces, but they will be the same size and orientation, just offset by the given distance. It also adds additional vertices and faces to fill in the seams and gaps between the exploded faces.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape.

ParamTypeDescription
distancenumberThe explosion distance, defaults to 0.
[detail]numberThe geometric detail at each corner (0 to 32), defaults to 1.

shape.cutAt(plane, [keep], [cutFaces]) ⇒ Shape

Cuts the faces of this shape by the given plane and either keeps all of them or just those in the front or behind.

Defining a Plane

This method uses an infinite plane to cut the shape, defined by an [a,b,c,d] plane array based on the Ax + Bx + Cz + D = 0 equation for a 3D plane. This means providing an array with four numbers that define the A, B, C and D components of the equation.

Alternatively, if you just want to cut a shape with a horizontal plane, you can pass a single number rather than a plane array. This number is used as the height on the Z axis of a cutting plane that faces towards the +Z axis.

The first three values in the plane array define its normal direction, which also defines the front and rear sides of the plane. Anything on the same side as the normal is pointing is in front, and anything on the other side is behind.

To make this method easier to use, the directional component of any given plane array does not need to be normalised as this will be done automatically. Thus, you could provide a plane array such as [ 1, 1, 1, -500 ] and it will be automatically normalized to [ 0.5773503, 0.5773503, 0.5773503, -500 ].

NOTE: When providing just a single number instead of a plane, it is important to remember that the number represents the plane height rather than the D component. Thus, a numeric value of 250 is equivalent to specifying [0,0,1,-250] as the plane array.

Which Side

You can choose to retain faces on both sides of the cut, or just those in front of or behind the cutting plane. To do this, set the value of keep to a positive number (usually 1) for faces in front of the plane, a negative number (usually -1) for faces behind the plane, or exactly zero (0) to keep both sides.

Accessing Cut Faces

If the value of keep is not zero, faces will be added to ‘fill in’ any openings created in the shape by the cut. If you set the value of cutFaces to an existing array, the new faces will be added to this array instead of directly to the shape. These faces will still reference vertices within the shape (which are shared by the existing faces that were actually cut), but this allows you an opportunity to discard or post-process them before adding them to the shape.

One action that is regularly performed on shapes is to do a cut and then extrude the ‘fill in’ faces in the opposite direction to create a base. As a result, this method provides a shortcut for for you to do this as part of the cutting process by passing a numeric value for cutFaces instead of an array. This numeric value must be positive, as shown in the second example below.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
planeArray.<number> | numberAn [a,b,c,d] plane array to cut the shape at or a height value in the +Z axis.
[keep]numberWhich side(s) of the plane to retain (0:Both, 1:Front, -1:Rear), defaults to 0 (both).
[cutFaces]Array | numberAn optional array in which to store any newly added cut faces. If given as a positive number instead of an array, it gives a distance by which to create a base by extruding cut surfaces in the opposite direction of the cutting plane.

Example

const cut_faces = [];
const cut_plane = [ 0, 0, 1, 0 ];
const dome_with_holes = new PD.Polyhedron('D12:jh(0.15,0.025)ajejS9000');
dome_with_holes.cutAt(cut_plane, 1);
CAD.add(dome_with_holes);

Example

/// Extrude cut faces to form support columns.
const cut_faces = [];
const cut_plane = [ 0, 0, 1, 0 ];
const poly = new PD.Polyhedron('D8:jeh(0.15,0.025)ajS9000');
const dome_with_holes = PD.Shape.cutAt(poly, cut_plane, 1, cut_faces).translate([ 0, 0, 3000 ]);
for (const face of cut_faces) {
    dome_with_holes.faceExtrude(face, -3000, cut_plane, 3);
}
CAD.add(dome_with_holes);

shape.extrudeBase(height, [segments]) ⇒ Shape

Searches for the bottom-most face whose normal points in the -Z direction and extrudes it downwards by the given distance (height) and in the given number of segments.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
heightnumberThe height of the base to add to the shape, in model units.
[segments]numberThe number of segments to extrude the base in, defaults to 1.

shape.ambo([offset]) ⇒ Shape

The Conway ambo operation is essentially the truncation of a shape by marking the midpoints of all its edges and cutting its vertices at those points.

The best way to think of the ambo operator is as a topological ’tween’ between a polyhedron and its dual polyhedron. Thus the ambo of a dual polyhedron is the same as the ambo of the original.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[offset]numberThe distance of the pyramid apex away from the face center in model units, defaults to 0.

Example

/// Cupola-based space frame.
const poly = PD.Shape.cupola(9).scale(6000);
poly.ambo().ambo().triakis(9, 2000).join();
poly.translate([ 0, 0, -1800 ]).scale([ 1, 1, 2 ]).cutAt(0, 1);
const frame = PD.Shape.frame(poly, 250, 150);
CAD.add(frame);

shape.dual() ⇒ Shape

The Conway dual operation creates a new shape in which the centroid of each face in the original shape becomes a new vertex in the dual, and each vertex in the original becomes the centroid of a new face.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining. Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(poly.dual());

shape.snub() ⇒ Shape

The Conway snub operation creates a new shape which is basically a gyro operation performed on the dual of the shape. It creates a new face for each vertex, which is then twisted slightly and two new triangular faces added to replace each edges and fill the gaps.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining. Example

const shape = new PD.Polyhedron('D12:S5000');
CAD.add(shape.clone().snub().scale(1.2835));
CAD.add(shape);

shape.triakis([sides], [offset]) ⇒ Shape

The Conway triakis operation divides specified faces into triangles to form a pyramid with its apex at the center of the face.

If the sides argument is less than 3, all faces in the shape will be divided. If 3 or more, only those faces with a matching number of sides will be divided.

If an offset value is given, then the apex of the pyramid will be positioned that far away from the geometric centre of the face in the direction of its surface normal.

This method differs from the Conway Polyhedron Notation version in that the offset distance is given in model units rather than as a fraction of shape radius.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]Array.<number> | numberAn array or face indexes or the number of sides a face must have to be affected, defaults to 0.
[offset]numberThe distance of the pyramid apex away from the face center in model units, defaults to 0.

Example

/// Cupola-based space frame.
const poly = PD.Shape.cupola(9).scale(12000);
poly.join().expand().triakis(9, 2000).join();
poly.translate([ 0, 0, -6700 ]).scale([ 1, 1, 3 ]).cutAt(0, 1);
const frame = PD.Shape.frame(poly, 250, 150);
CAD.add(frame);

shape.bevel([sides]) ⇒ Shape

The Conway bevel operation truncates the shape at its edges and vertices, creating a new facet in place of each edge and of each vertex.

If the sides argument is less than 3, all faces in the shape will be bevelled. If 3 or more, only those faces with a matching number of sides will be bevelled.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(poly.clone().bevel().setRadius(3440));
CAD.add(poly);

shape.gyro([offset], [fraction]) ⇒ Shape

The Conway gyro operation creates a new shape in which a new face is created at each vertex of its dual, which is then twisted slightly and two new triangular faces added to replace each edges and fill the gaps.

NOTE: When using an offset value not equal to zero, this operation will often create non-planar faces. If that is detected, then the resulting faces will be automatically triangulated.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[offset]numberThe distance of the center apex away from the face center in model units, defaults to 0.
[fraction]numberThe face rotation fraction (0.001 to 0.999), defaults to 1/3.

Example

const shape = PD.Shape.cuboid();
shape.gyro().triangulate().scale(5000);
CAD.add(shape);

shape.propellor([fraction]) ⇒ Shape

The Conway propellor extended operation creates new skewed faces by making new points along each edge, 1/3rd the distance from v1- > v2, then connecting these into a new inset face. This breaks any rotational symmetry about the faces.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[fraction]numberThe face rotation fraction (0.001 to 0.999), defaults to 1/3.

Example

const shape = PD.Shape.anticupola(9).scale(9000);
shape.propellor();
CAD.add(shape);

shape.expand() ⇒ Shape

The Conway expand operation is basically a double ambo operation, which is the truncation of a shape by marking the midpoints of all its edges and cutting its vertices at those points.

Kind: instance method of Shape
Returns: Shape - Returns this shape to support method chaining. Example

/// Cupola-based space frame.
const poly = PD.Shape.anticupola(9).scale(9000);
poly.triakis(9, 2000).expand().join();
poly.translate([ 0, 0, -6700 ]).scale([ 1, 1, 3 ]).cutAt(0, 1);
const frame = PD.Shape.frame(poly, 250, 150);
CAD.add(frame);

shape.join() ⇒ Shape

The Conway join operation is basically an ambo operation performed on the dual of the original shape, then converted back to a dual.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining. Example

/// Cupola-based space frame.
const poly = PD.Shape.cupola(9).scale(12000);
poly.join().expand().triakis(9, 2000).join();
poly.translate([ 0, 0, -6700 ]).scale([ 1, 1, 3 ]).cutAt(0, 1);
const frame = PD.Shape.frame(poly, 250, 150);
CAD.add(frame);

shape.meta([sides]) ⇒ Shape

The Conway meta operation is basically the join of a triakis operation.

If the sides argument is less than 3, all faces in the shape will be bevelled. If 3 or more, only those faces with a matching number of sides will be bevelled.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.

shape.ortho() ⇒ Shape

The Conway ortho operation is effectively a double join operation.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

shape.truncate([sides]) ⇒ Shape

The Conway truncate operation is a triakis operation performed of the dual of the original shape, then converted back to a dual.

If the sides argument is less than 3, all faces in the shape will be bevelled. If 3 or more, only those faces with a matching number of sides will be bevelled.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.

shape.loft([sides], [inset], [offset]) ⇒ Shape

The loft operation insets each edge of the specified faces and creates new quad faces to fill the gap.

If the sides argument is less than 3, all faces in the shape will be lofted. If 3 or more, only those faces with a matching number of sides will be lofted.

If an inset value is given, then the apex of the pyramid will be positioned that far away from the geometric centre of the face in the direction of its surface normal.

This method differs from the Conway Polyhedron Notation version in that the inset and offset distances are given in model units rather than as a fraction of shape radius.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.
[inset]numberAn inset distance from each edge in model units, defaults to 0 (no inset).
[offset]numberAn optional distance from face surface in model units, defaults to 0 (no offset).

shape.triangulate([sides]) ⇒ Shape

The triangulate operation divides specified faces into a triangular fan centered at the first vertex.

If the sides argument is less than 3, all faces in the shape will be divided. If 3 or more, only those faces with a matching number of sides will be divided.

To produce a useable result, this method requires that each face be convex in shape as dividing a concave face this way will result in overlapping triangular faces.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.

shape.perlinNoise([amplitude], [scale], [offset]) ⇒ Shape

The Perlin noise operation applies some spatial variation to each vertex in the shape based on the amplitude, scale and offset values.

The amplitude, scale and offset values are all applied to the Perlin noise function when it is run for each vertex. You can specify the scale and offset as either [x,y,z] vector arrays to control the variation in each axis, or as single numbers which will be applied equally to all axis.

This method differs from the Conway Polyhedron Notation version in that the amplitude, scale and offset distances are all given in model units rather than as a fraction of shape radius.

To have a noticeable effect, the amplitude and scale values cannot be too small relative to the shape size, so you will typically need to experiment a bit with this.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[amplitude]numberEffectively the magnitude of the spatial variation in model units, defaults to 250mm.
[scale]number | Array.<number>A scale factor or [sx,sy,sz] vector array in model units, defaults to 1000mm (1m).
[offset]number | Array.<number>A phase offset as a number or [dx,dy,dz] vector array in model units, defaults to 0 (no offset).

Example

const shape = PD.Shape.cylinder(72, 2000, 5000, 36);
shape.perlinNoise(5000, 3000, 5000).setRadiusXY(6000);
CAD.add(shape);

shape.noiseXY([amplitude], [scale], [offset]) ⇒ Shape

The noiseXY operation applies some X and Y axis spatial variation to each vertex in the shape based on the amplitude, scale and offset values.

The amplitude, scale and offset values are all applied to the Perlin noise function when it is run for each vertex. You can specify the scale and offset as either [x,y,z] vector arrays to control the variation in each axis, or as single numbers which will be applied equally to all axis.

This method differs from the Conway Polyhedron Notation version in that the amplitude, scale and offset distances are all given in model units rather than as a fraction of shape radius.

To have a noticeable effect, the amplitude and scale values cannot be too small relative to the shape size, so you will typically need to experiment a bit with this.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[amplitude]numberEffectively the magnitude of the spatial variation in model units, defaults to 250mm.
[scale]number | Array.<number>A scale factor or [sx,sy,sz] vector array in model units, defaults to 1000mm (1m).
[offset]number | Array.<number>A phase offset as a number or [dx,dy,dz] vector array in model units, defaults to 0 (no offset).

Example

const shape = PD.Shape.cylinder(72, 2000, 5000, 36);
shape.noiseXY(5000, 3000, 5000).setRadiusXY(6000);
CAD.add(shape);

shape.frame([inset], [thickness], [glazing]) ⇒ Shape

The frame operation essentially hollows out the shape and generates a structural frame with bars running along each of its edges.

Kind: instance method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[inset]numberThe inset width of framing bars, defaults to 25mm.
[thickness]numberThe framing bar thickness as a positive value, defaults to 50mm.
[glazing]booleanWhether or not to generate glazing panes between frames.

Example

/// Cupola-based space frame.
const shape = PD.Shape.anticupola(9).scale(9000);
shape.scale([1, 1, 3]).triakis(9, 2000).expand().join();
shape.translate([0, 0, -7500]).cutAt(0, 1);
shape.frame(250, 150);
CAD.add(shape);

shape.copyToBRep(brep, [scale]) ⇒ boolean

Copies the shape to the given BRep.

Ideally, adding a Shape to a PD.BRep should be done in the PD.BRep class as the PD.Shape class is lower level in the framework. However, not every applications that includes BRep needs to include PD.Shape, so this method is is only required when an application actually includes and uses PD.Shape.

Kind: instance method of Shape
Returns: boolean - Returns true if geometry was added to the BRep.

ParamTypeDescription
brepPD.BRepThe BRep to add the shape to.
[scale]numberAn optional scale factor for the shape, defaults to 1000mm (1m).

Shape.Shells

A factory for generating a range of different cylindrical, spherical and hemispherical surface shapes based on the Shape class.

Shell constructs are a bit different from shape shapes in that they start out being not completely manifold. This is mainly because the top and bottom edges are initially open, which allows them to be unwrapped.

Kind: static class of Shape
Author: drajmarsh

Shape.Roofs

A factory for generating a range of different roof forms and shapes based on the Shape class.

Kind: static class of Shape
Author: drajmarsh

Roofs.gable([config], [vertices], [size], [base], [angle], [radians]) ⇒ Shape

Generates a simple gable roof.

A gable roof consists of two inclined planes that meet in the middle of a base quadrilateral to form a raised central ridge.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral, with the order of vertices as shown below. This final shape actually requires six (6) points, or ten (10) if it has a gutter (), where the 4 and 5 will be automatically computed based on the roof pitch angle.

You can specify the roof pitch angle in degrees using config.angle or in radians using config.radians. This method will use config.angle over config.radians, so you should only include one or the other, not both.

    9                                     8
     3-----------------------------------2
      \                                _/
       \                             _/
        5---------------------------4                   _.-._
         \                        _/               _.-'       '-._
          \                     _/            _.-'                 '-._
           0-------------------1            1  -  -  -  -   -  -  -  -  2 - + -
          6                     7           +---------------------------+ - + - base

Kind: static method of Roofs
Returns: Shape - Returns a new gable roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[angle]numberThe roof pitch in degrees (0.1 to 75deg), defaults to 30deg.
[radians]numberThe roof pitch in radians, defaults to 0.5236rad.

Roofs.butterfly([config], [vertices], [size], [base], [angle], [radians], [valleyWidth], [valleyDepth]) ⇒ Shape

Creates simple butterfly roof, which is basically an inverted gable.

A butterfly roof consists of two inclined planes that meet in the middle of a base quadrilateral to form a central valley. As opposed to a gable roof, the planes are generated from the center value and incline upwards towards the sides.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral, with the order of vertices as shown below. This final shape actually requires six (6) points, or ten (10) if it has a gutter (), where the 4 and 5 will be automatically computed based on the roof pitch angle.

You can specify the roof pitch angle in degrees using config.angle or in radians using config.radians. This method will use config.angle over config.radians, so you should only include one or the other, not both.

    9                                     8
     3-----------------------------------2
      \                                _/
       \                             _/
        5---------------------------4      (1)._                 _.(2)
         \                        _/        :    '-._       _.-'    :
          \                     _/          :         '-4-'         :
           0-------------------1            1  -  -  -  -  -  -  -  2 - + -
          6                     7           7-----------------------8 - + - base

Kind: static method of Roofs
Returns: Shape - Returns a new butterfly roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[angle]numberThe roof pitch in degrees (0.1 to 75deg), defaults to 30deg.
[radians]numberThe roof pitch in radians, defaults to 0.5236rad.
[valleyWidth]numberThe width of the valley gutter in the middle, defaults to 0.
[valleyDepth]numberThe depth of the valley gutter in the middle, defaults to 100mm.

Roofs.hip([config], [vertices], [size], [base], [angle], [radians], [angleEnd], [radiansEnd]) ⇒ Shape

Generates a simple hip roof.

A hip roof consists of four inclined planes that meet in the middle of a base quad to form a central ridge. The angle of inclination for all planes is typically the same, unless the two end triangular planes intersect each other in which case their angles are modified to create a pyramid shape.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral, with the order of vertices as shown below. This final shape actually requires six (6) points, or ten (10) if it has a gutter (), where the 4 and 5 will be automatically computed based on the roof pitch angle.

You can specify the roof pitch angle(s) in degrees using config.angle or in radians using config.radians. This method will use config.angle over config.radians, so you should only include one or the other, not both.

   9                       8
    3---------------------2
     \''..              _/ \
      \   ''..        _/    \
       \      _5-----4.      \                  _______
        \   _/         ''..   \            _.-'         '-._
         \ /               ''..\      _.-'                   '-._
          0---------------------1    0----------------------------1 - + -
         6                       7   6----------------------------7 - + - base

Kind: static method of Roofs
Returns: Shape - Returns a new hip roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[angle]numberThe side roof pitch angle in degrees (0.1 to 75deg), defaults to 30deg.
[radians]numberThe side roof pitch angle in radians, defaults to 0.5236rad.
[angleEnd]numberThe end roof pitch angle in degrees(0.1 to 89.9deg), defaults to 30deg.
[radiansEnd]numberThe end roof pitch angle in radians, defaults to 0.5236rad.

Roofs.hippedGable([config], [vertices], [size], [base], [angle], [radians], [angleEnd], [radiansEnd], [fraction]) ⇒ Shape

Generates a simple hipped gable roof.

A hipped gable roof consists of four inclined planes that meet in the middle of a base quad to form a central ridge. The angle of inclination for all planes is typically the same, unless the two end triangular end planes intersect each other in which case their angles are modified to create a pyramid shape.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral, with the order of vertices as shown below. This final shape actually requires six (6) points, or ten (10) if it has a gutter (), where the 4 and 5 will be automatically computed based on the roof pitch angle.

You can specify the roof pitch angle(s) in degrees using config.angle or in radians using config.radians. This method will use config.angle over config.radians, so you should only include one or the other, not both.

 13                      12
   3---------------------2
    \                     \
     8.                   _7
      \''-.              /  \
       \   '5-----------4.   \              _____________________
        \ .'              ''..\           _/                     \_
         9                    '6        _/                         \_
          \                     \      :                             :
           0---------------------1     0-----------------------------1
          10                     11    10---------------------------11 - + - base

Kind: static method of Roofs
Returns: Shape - Returns a new hipped gable roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[angle]numberThe side roof pitch angle in degrees (0.1 to 75deg), defaults to 30deg.
[radians]numberThe side roof pitch angle in radians, defaults to 0.5236rad.
[angleEnd]numberThe end roof pitch angle in degrees(0.1 to 89.9deg), defaults to 30deg.
[radiansEnd]numberThe end roof pitch angle in radians, defaults to 0.5236rad.
[fraction]numberThe fractional ridge offset of the hip triangles (0 to 1), defaults to 0.5.

Roofs.gambrel([config], [vertices], [size], [base], [angle], [radians], [angleUpper], [radiansUpper], [height]) ⇒ Shape

Generates a simple gambrel roof.

A gambrel roof consists of four inclined planes, where the bottom two planes are inclined at different angles to the top two planes.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral, with the order of vertices as shown below. This final shape actually requires six (6) points, or ten (10) if it has a gutter (), where the 4 and 5 will be automatically computed based on the roof pitch angle.

You can specify the roof pitch angle(s) in degrees using config.angle or in radians using config.radians. This method will use config.angle over config.radians, so you should only include one or the other, not both.

   13                                    12
    3------------------------------------2
    |                                    |
    6------------------------------------7
    |                                    |                 _.-'-._
    8------------------------------------9            _.-'         '-._
    |                                    |          +                   +
    4------------------------------------5        _/                     \_
    |                                    |      _/                         \_
    0------------------------------------1     1  -  -  -  -  -  -  -  -  -  2 - + -
   10                                    11    11---------------------------12 - + - base

Kind: static method of Roofs
Returns: Shape - Returns a new gambrel roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[angle]numberThe lower roof pitch in degrees (0.1 to 75deg), defaults to 60deg.
[radians]numberThe lower roof pitch in radians, defaults to 0.5236rad.
[angleUpper]numberThe upper roof pitch in degrees (0.1 to 75deg), defaults to 30deg.
[radiansUpper]numberThe upper roof pitch in radians, defaults to 0.5236rad.
[height]numberThe height of the lower roof portion, defaults to 1000mm.

Roofs.mansard([config], [vertices], [size], [base], [angle], [radians], [angleUpper], [radiansUpper], [dutchGable], [height]) ⇒ Shape

Generates a simple mansard roof.

A mansard roof consists of eight inclined planes, where the bottom four planes are inclined at different angles to the top four planes. A Dutch gable is where the end triangle planes (5,6,8 and 7,4,9) are vertical.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral, with the order of vertices as shown below. This final shape actually requires six (6) points, or ten (10) if it has a gutter (), where the 4 and 5 will be automatically computed based on the roof pitch angle.

You can specify the roof pitch angle(s) in degrees using config.angle or in radians using config.radians. This method will use config.angle over config.radians, so you should only include one or the other, not both.

    3------------------------------------2
    |'.                                .'|
    |   7----------------------------6   |                      ____________
    |   | '.                      .' |   |                 _.-'              '-._
    |   |   9--------------------8   |   |            _.-'                        '-._
    |   | .'                      '. |   |          +----------------------------------+
    |   4----------------------------5   |        _/                                    \_
    |.'                                '.|      _/                                        \_
    0------------------------------------1     0--------------------------------------------1 - + -
                                               +--------------------------------------------+ - + - base

Kind: static method of Roofs
Returns: Shape - Returns a new mansard roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[angle]numberThe lower roof pitch in degrees (0.1 to 75deg), defaults to 60deg.
[radians]numberThe lower roof pitch in radians, defaults to 0.5236rad.
[angleUpper]numberThe upper roof pitch in degrees (0.1 to 75deg), defaults to 30deg.
[radiansUpper]numberThe upper roof pitch in radians, defaults to 0.5236rad.
[dutchGable]numberThe factor for turning the mansard shape into a Dutch gable (0 to 1), defaults to 0.
[height]numberThe height of the lower roof portion, defaults to 1000mm.

Roofs.pavilion([config], [vertices], [size], [base], [angle], [radians]) ⇒ Shape

Generates a simple pavilion roof.

A pavilion roof consists of four inclined planes that all meet at a central apex point to form a pyramid.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral, with the order of vertices as shown below. This final shape actually requires six (6) points, or ten (10) if it has a gutter (), where the 4 and 5 will be automatically computed based on the roof pitch angle.

You can specify the roof pitch angle(s) in degrees using config.angle or in radians using config.radians. This method will use config.angle over config.radians, so you should only include one or the other, not both.

    3---------------2
     \''..        _/ \
      \   ''..  _/    \
       \      _4       \
        \   _/   ''..   \             _.-'-._
         \ /         ''..\       _.-'         '-._
          0---------------1    0-------------------1 - + -
                               +-------------------+ - + - gutter

Kind: static method of Roofs
Returns: Shape - Returns a new pavilion roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[angle]numberThe lower roof pitch in degrees (0.1 to 75deg), defaults to 60deg.
[radians]numberThe lower roof pitch in radians, defaults to 0.5236rad.

Roofs.conical([config], [vertices], [size], [base], [sides], [radius], [radiusTop], [height]) ⇒ Shape

Generates a simple conical roof.

A cone is a cylindrical shaped roof with the top radius that different from the bottom radius, often being just a single point, and formed from a series of facets that approximate its curved shape.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral. If you provide just one point, it will be used as the center of the cone. If you provide two points, the second is assumed to define a point on the circumference of the cone, so is used to compute the radius. If you provide three or four points, these will be used to generate the radius such that the circumference is tangential to all two/three lines.

All conical shapes generated by this class use facets to approximate the curved shape of the dome. To generate smoothly curved algorithmic domed surfaces, use the OpenCascade engine or the PD.BRep class. You can control the facet density using the detail or points configuration properties described below.

Kind: static method of Roofs
Returns: Shape - Returns a new domed roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[sides]numberThe number of side facets (3 to 360), defaults to 36.
[radius]numberThe radius of the base of the cone, defaults to given size.
[radiusTop]numberThe radius of the top of the cone, defaults to 0.
[height]numberThe height to the top of the cone, defaults to 1000mm.

Roofs.barrel([config], [vertices], [size], [base], [facets], [isRainbow]) ⇒ Shape

Generates a simple barrel vault roof.

A barrel vault roof is formed from a series of planes that form a semicircular arch at each end. The number of planes is determined by the facet resolution. A rainbow roof is very similar, but forms a pointed arch instead of a semicircular one.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral, with the order of vertices as shown below. This final shape actually requires six (6) points, or ten (10) if it has a gutter (), where the 4 and 5 will be automatically computed based on the roof pitch angle.

You can specify the roof pitch angle(s) in degrees using config.angle or in radians using config.radians. This method will use config.angle over config.radians, so you should only include one or the other, not both.

    3------------------------------------2
    +------------------------------------+
    |                                    |
    +------------------------------------+
    |                                    |
    |                                    |
    +------------------------------------+
    |                                    |               , - ~ ' ~ - ,
    |                                    |           , '               ' ,
    +------------------------------------+         ,                       ,
    |                                    |        ,                         ,
    +------------------------------------+       ,                           ,
    0------------------------------------1       1  -  -  -  -   -  -  -  -  2 - + -
                                                 +---------------------------+ - + - gutter

Kind: static method of Roofs
Returns: Shape - Returns a new barrel vaulted roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[facets]numberThe number of facets (2 to 72), defaults to 12.
[isRainbow]booleanWhether to generate a ridged rainbow roof instead of a barrel, defaults to false.

Roofs.dome([config], [vertices], [size], [base], [detail], [points], [type]) ⇒ Shape

Generates a simple dome roof.

A dome is a hemispherical shaped roof formed from a series of facets that approximate its curved shape.

The config.vertices property is an array that you can pre-fill with up to four initial points defining the corners of the base. These points must define a convex coplanar quadrilateral. If you provide just one point, it will be used as the center of the dome. If you provide two points, the second is assumed to define a point on the circumference of the dome, so is used to compute the radius. If you provide three or four points, these will be used to generate the radius such that the circumference is tangential to all two/three lines.

All dome shapes generated by this class use facets to approximate the curved shape of the dome. To generate smoothly curved algorithmic domed surfaces, use the OpenCascade engine or the PD.BRep class. You can control the facet density using the detail or points configuration properties described below.

               , - ~ ' ~ - ,                        , - ~ ' ~ - ,
           , '               ' ,                , '               ' ,
         ,                       ,            ,                       ,
        ,                         ,          ,                         ,
       ,                           ,        ,                           ,
       +  -  -  -  - 0 -  -  -  -  1        +  -  -  -  -   -  -  -  -  + - + -
                                            +---------------------------+ - + - base

Kind: static method of Roofs
Returns: Shape - Returns a new domed roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[detail]numberThe level of geometric detail (0 to 32), defaults to 8.
[points]numberThe number of points in random and Fibonacci domes (2 to 1024), defaults to 128.
[type]number | stringWhat type of dome to create (0:latLng, 1:Geodesic, 2: random), defaults to 0.

Roofs.rotunda([config], [vertices], [size], [base], [detail], [points], [type]) ⇒ Shape

Generates a pentagonal rotunda roof.

As this shape always has 10 sides in its base, the sides value refers to the number of unit-sized cylindrical segments to add to its base.

Kind: static method of Roofs
Returns: Shape - Returns a new rotunda roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[detail]numberThe level of geometric detail (0 to 32), defaults to 8.
[points]numberThe number of points in random and Fibonacci domes (2 to 1024), defaults to 128.
[type]number | stringWhat type of dome to create (0:latLng, 1:Geodesic, 2: random), defaults to 0.

Roofs.cupola([config], [vertices], [size], [base], [detail], [points], [type]) ⇒ Shape

Generates a cupola-shaped roof.

A cupola is a shape formed by joining two polygons, one (the base) with twice as many edges as the other, by an alternating band of isosceles triangles and rectangles.

Kind: static method of Roofs
Returns: Shape - Returns a new cupola roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[detail]numberThe level of geometric detail (0 to 32), defaults to 8.
[points]numberThe number of points in random and Fibonacci domes (2 to 1024), defaults to 128.
[type]number | stringWhat type of dome to create (0:latLng, 1:Geodesic, 2: random), defaults to 0.

Roofs.anticupola([config], [vertices], [size], [base], [detail], [points], [type]) ⇒ Shape

Generates a anticupola-shaped roof.

An anticupola is a shape formed by joining two polygons, one (the base) with twice as many edges as the other and rotated slightly by half a segment, joined to the top by a band of isosceles triangles.

Kind: static method of Roofs
Returns: Shape - Returns a new anticupola roof shape.

ParamTypeDescription
[config]objectA configuration object.
[vertices]Array.<Array.<number>>An array of 1 to 4 [x,y,z] vector array initial corner points.
[size]number | Array.<number>The base size as a number or [sizeX,sizeY] vector array, defaults to 2000mm.
[base]numberThe height of the base/gutter at the bottom, defaults to 150mm.
[detail]numberThe level of geometric detail (0 to 32), defaults to 8.
[points]numberThe number of points in random and Fibonacci domes (2 to 1024), defaults to 128.
[type]number | stringWhat type of dome to create (0:latLng, 1:Geodesic, 2: random), defaults to 0.

Shape.indexerDecimals : number

The default number of decimal places when creating an indexer to amalgamate coincident vertices.

This value defaults to 1 decimal place, which will ‘weld’ vertices that are within 0.1mm of each other.

However, the Polyhedron class typically works with shapes that have a radius of 1, so it will temporarily set this value to 6 or more during its operations.

Kind: static property of Shape

Shape.newInstance([vertices], [faces], [name]) ⇒ Shape

This is used to allow subclasses to create instance of their own class when using static generators.

Kind: static method of Shape
Returns: Shape - Returns a new shape.

ParamTypeDescription
[vertices]Array.<Array.<number>>An array of [x,y,z] vertex coordinates.
[faces]Array.<Array.<number>>An array of face boundary arrays, each containing three or more vertex indices.
[name]stringA human-readable name for the shape.

Shape.sortPointsAntiClockwise(center, points) ⇒ Array.<Array.<number>>

This method is used to order the offset points of each face around a vertex so that it can join them up into a triangle or quad.

            3        |            1
    0       +   2    |    2       +   0
    +           +    |    +           +
       center        |        center
          +          |           +
                 4   |                 4
     1           +   |     3           +
     +               |     +
        BEFORE       |         AFTER

Kind: static method of Shape
Returns: Array.<Array.<number>> - Returns an array with the given points sorted anti-clockwise around center.

ParamTypeDescription
centerArray.<number>The [x,y,z] coordinate array of a central point.
pointsArray.<Array.<number>>An array of [x,y,z] coordinate arrays defining points around the center.

Shape.checkForSidesArray(faces, [sides]) ⇒ Array.<Array.<number>>

Checks whether the sides argument is given as an array of face indices or the number of sides

Kind: static method of Shape
Returns: Array.<Array.<number>> - Returns a list of faces to process.

ParamTypeDescription
facesArray.<Array.<number>>The list of faces in the shape.
[sides]Array.<number> | numberAn optional array of face indexes or the number of sides a face must have to be affected, defaults to 0 (all faces).

Example

function processShape(shape, sides) {

    const facesToProcess = PD.Shape.checkForSidesArray(shape.faces, sides);

    sides = (Array.isArray(sides)) ? 0 : PD.Utils.toInteger(sides, 0);

    for (const face of facesToProcess) {
        if ((sides < 3) || (face.length == sides)) {
            processFace(face);
        }
    }

};

Shape.tesselateSphericalArc(center, v1, v2, angularResolution, [stepsOverride]) ⇒ Array.<Array.<number>>

Progressively tessellates a line between two points on the surface of a unit sphere until the given angular resolution is reached.

NOTE: This method requires that the points be normalised vectors, which basically means being coordinates of points on the surface of a unit sphere (having radius of 1) and centered at the origin ([0,0,0]).

Kind: static method of Shape
Returns: Array.<Array.<number>> - An array of segmented points as [x,y,z] coordinate arrays.

ParamTypeDescription
centerArray.<number>The center of the sphere as an [x,y,z] coordinate array.
v1Array.<number>The first normalised surface point as an [x,y,z] coordinate array.
v2Array.<number>The second normalised surface point as an [x,y,z] coordinate array.
angularResolutionnumberThe minimum angular resolution for subdivision.
[stepsOverride]numberAn optional number of absolute subdivisions to use instead of the angular resolution.

Shape.tesselateSphericalTriangle(v1, v2, v3, angularResolution, [stepsOverride]) ⇒ Array.<Array.<number>>

Progressively tessellates a triangle of points on the surface of a unit sphere until the given angular resolution is reached.

NOTE: This method requires that the points be normalised vectors, which basically means being coordinates of points on the surface of a unit sphere (having radius of 1) and centered at the origin ([0,0,0]).

Kind: static method of Shape
Returns: Array.<Array.<number>> - An array of normalised triangles, each with three [x,y,z] coordinate arrays.

ParamTypeDescription
v1Array.<number>The first normalised surface point as an [x,y,z] vector array.
v2Array.<number>The second normalised surface point as an [x,y,z] coordinate array.
v3Array.<number>The third normalised surface point as an [x,y,z] coordinate array.
angularResolutionnumberThe minimum angular resolution for subdivision.
[stepsOverride]numberAn optional number of absolute subdivisions to use instead of the angular resolution.

Shape.tesselateSphericalQuad(v1, v2, v3, v4, angularResolution, [stepsOverride]) ⇒ Array.<Array.<number>>

Progressively tessellates a quadrilateral of points on a unit sphere until the given angular resolution is reached.

NOTE: This method requires that the points be normalised vectors, which basically means being coordinates of points on the surface of a unit sphere (having radius of 1) and centered at the origin ([0,0,0]).

Kind: static method of Shape
Returns: Array.<Array.<number>> - An array of quads, each with four [x,y,z] coordinate arrays.

ParamTypeDescription
v1Array.<number>The first normalised surface point as an [x,y,z] coordinate array.
v2Array.<number>The second normalised surface point as an [x,y,z] coordinate array.
v3Array.<number>The third normalised surface point as an [x,y,z] coordinate array.
v4Array.<number>The fourth normalised surface point as an [x,y,z] coordinate array.
angularResolutionnumberThe minimum angular resolution for subdivision.
[stepsOverride]numberAn optional number of absolute subdivisions to use instead of the angular resolution.

Shape.inflate(shape, distance, [checkPlanes]) ⇒ Shape

Expand all vertices in the direction of their surface normals by the given distance.

Expansion is different from offsetting in that the given distance refers to the movement of each vertex rather than to each face. Vertices move in the direction of their average surface normals, which is effectively the normalised sum of each face normal that the vertex is shared by. Movement is outwards if the distance is positive or inwards if it is negative.

The result is a set of vertices that are exactly the given distance away from their original positions. Depending on the number of faces shared by each vertex, and their relative orientations, this may result in faces changing orientation slightly and not being parallel to their original position. In some rare cases it may even result in faces that are no longer planar.

If you want to specify the exact perturbation distance of faces rather than vertices use the offset method instead.

Kind: static method of Shape
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
shapeShapeThe shape to expand from.
distancenumberThe expansion distance, defaults to 0.
[checkPlanes]numberExtra checks (0:None, 1:AngleWeighted, 2:FirstPlane, 3:AllPlanes), defaults to 0.

Example

const shape = PD.Shape.prism(9, 1500, 1000).ortho();
CAD.add(PD.Shape.inflate(shape, 200));
CAD.add(shape);

Shape.offset(shape, distance, [detail], [useAbsoluteSteps]) ⇒ Shape

Expand all facets in the direction of their surface normals by the given distance, but maintaining their exact shape and planar area.

This process creates a new shape which copies all faces in the given shape, moves them outwards and adds additional faces to cover the now open seams and gaps between them. The benefit of this method is that you can offset any convex shape by any positive amount, even by many thousands of times its radius, and still have a valid shape.

Unfortunately this isn’t true of concave shapes or when the distance value is negative. In these cases, maintaining the shape and area of facets isn’t possible as they simply have to shrink in order to fit. As a result, this method will redirect to the expand method when the given distance is less than zero. When working with concave shapes, you are just going to have to experiment.

Kind: static method of Shape
Returns: Shape - Returns a new shape if the distance is non-zero, or the given shape.

ParamTypeDefaultDescription
shapeShapeThe shape to offset from.
distancenumberThe face offset distance as a positive value, defaults to 0 (no change).
[detail]numberThe geometric detail at each corner (-1 to 32), defaults to 2.
[useAbsoluteSteps]booleanfalseWhen true, the offset uses detail as the absolute number of subdivisions regardless of spherical angle, defaults to false.

Example

const offset = 500;
const spacing = 4000;
const shape = PD.Shape.cuboid(1000, 1500, 1000);
CAD.add(PD.Shape.offset(shape, offset, -1).translate([ -spacing, -spacing, 0 ]));
CAD.add(PD.Shape.offset(shape, offset,  0).translate([ -spacing,        0, 0 ]));
CAD.add(PD.Shape.offset(shape, offset,  1).translate([ -spacing,  spacing, 0 ]));
CAD.add(PD.Shape.offset(shape, offset,  2).translate([        0,  spacing, 0 ]));
CAD.add(PD.Shape.offset(shape, offset,  3).translate([  spacing,  spacing, 0 ]));
CAD.add(PD.Shape.offset(shape, offset,  8).translate([  spacing,        0, 0 ]));
CAD.add(PD.Shape.offset(shape, offset, 16).translate([  spacing, -spacing, 0 ]));
CAD.translate(CAD.offset(CAD.addSolid(shape), offset), [      0, -spacing, 0 ]);
CAD.add(shape);

Shape.offsetHull(shape, distance, [detail]) ⇒ Shape

Generate a convex hull by offsetting all vertices, facets and edges in the a shape by their surface normals, but maintaining the exact shape and planar area of each facet in the original.

This process creates a new shape that has faces that are the same size and orientation as the given shape, just offset by the given distance and with additional faces to fill in the seams and gaps between offset facets.

Kind: static method of Shape
Returns: Shape - Returns a new exploded shape.

ParamTypeDescription
shapeShapeThe shape to offset from.
distancenumberThe explosion distance, defaults to 0.
[detail]numberThe geodesic detail at each corner (1 to 32), defaults to 1.

Example

const offset = 500;
const spacing = 4000;
const shape = PD.Shape.cuboid(1000, 1500, 1000);
CAD.add(PD.Shape.offsetHull(shape, offset, -1).translate([ -spacing, -spacing, 0 ]));
CAD.add(PD.Shape.offsetHull(shape, offset,  0).translate([ -spacing,        0, 0 ]));
CAD.add(PD.Shape.offsetHull(shape, offset,  1).translate([ -spacing,  spacing, 0 ]));
CAD.add(PD.Shape.offsetHull(shape, offset,  2).translate([        0,  spacing, 0 ]));
CAD.add(PD.Shape.offsetHull(shape, offset,  3).translate([  spacing,  spacing, 0 ]));
CAD.add(PD.Shape.offsetHull(shape, offset,  8).translate([  spacing,        0, 0 ]));
CAD.add(PD.Shape.offsetHull(shape, offset, 16).translate([  spacing, -spacing, 0 ]));
CAD.translate(CAD.addHull(PD.Shape.offsetHull(shape, offset,  6).vertices), [0, -spacing, 0 ]);
CAD.add(shape);

Shape.frame(shape, [inset], [thickness], [glazing]) ⇒ Shape

Generates a structural frame by hollowing out the shape and creating a structural frame with bars running along each of its edges.

This process creates a new shape with bars of the given width and thickness along each edge.

Kind: static method of Shape
Returns: Shape - Returns a new framing shape.

ParamTypeDescription
shapeShapeThe shape to generate frame from.
[inset]numberThe inset width of frame elements, defaults to 25mm.
[thickness]numberThe frame thickness as a positive value, defaults to 50mm.
[glazing]booleanWhether or not to generate glazing panes between frames.

Example

/// Cupola-based space frame.
const shape = PD.Shape.anticupola(9).scale(9000);
shape.triakis(9, 2000).expand().join().scale([1, 1, 3]);
shape.translate([ 0, 0, -7500 ]).cutAt(0, 1);
CAD.add(shape);

const frame = PD.Shape.frame(shape, 250, 150);
CAD.add(frame);

Shape.ambo(shape) ⇒ Shape

The Conway ambo operation is essentially the truncation of a shape by marking the midpoints of all its edges and cutting its vertices at those points.

The best way to think of the ambo operator is as a topological ’tween’ between a polyhedron and its dual polyhedron. Thus the ambo of a dual polyhedron is the same as the ambo of the original.

Kind: static method of Shape
Returns: Shape - Returns a new shape generated from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.ambo(poly));
CAD.add(poly);

Shape.bevel(shape, [sides], [offset]) ⇒ Shape

The Conway bevel operation truncates the shape at its edges and vertices, creating a new facet in place of each edge and of each vertex.

If the sides argument is less than 3, all faces in the shape will be bevelled. If 3 or more, only those faces with a matching number of sides will be bevelled.

Kind: static method of Shape
Returns: Shape - Returns a new modified shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.
[sides]Array.<number> | numberAn optional array of face indexes or the number of sides a face must have to be affected, defaults to 0 (all faces).
[offset]numberThe distance of the triakis apex away from the face center in model units, defaults to 0.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.bevel(poly).setRadius(3440));
CAD.add(poly);

Shape.dual(shape) ⇒ Shape

The Conway dual operation creates a new shape in which the centroid of each face in the original shape becomes a new vertex in the dual, and each vertex in the original becomes the centroid of a new face.

Kind: static method of Shape
Returns: Shape - Returns a new shape generated from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.dual(poly));
CAD.add(poly);

Shape.expand(shape) ⇒ Shape

The Conway expand operation is basically a double ambo operation, which is the truncation of a shape by marking the midpoints of all its edges and cutting its vertices at those points.

Kind: static method of Shape
Returns: Shape - Returns a new shape generated from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.expand(poly));
CAD.add(poly);

Shape.gyro(shape, [offset], [fraction]) ⇒ Shape

The Conway gyro operation creates a new shape in which a new face is created at each vertex of its dual, which is then twisted slightly and two new triangular faces added to replace each edges and fill the gaps.

NOTE: When using an offset value not equal to zero, this operation will often create non-planar faces. If that is detected, then the resulting faces will be automatically triangulated.

Kind: static method of Shape
Returns: Shape - Returns a new shape generated from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.
[offset]numberThe distance of the center apex away from the face center in model units, defaults to 0.
[fraction]numberThe face rotation fraction (0.001 to 0.999), defaults to 1/3.

Example

const shape = PD.Shape.cuboid(5000);
CAD.add(PD.Shape.gyro(shape));

Shape.join(shape) ⇒ Shape

The Conway join operation is basically an ambo operation performed on the dual of the original shape, then converted back to a dual.

Kind: static method of Shape
Returns: Shape - Returns a new shape generated from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.join(poly).setRadius(3489));
CAD.add(poly);

Example

/// Cupola-based space frame.
const poly = PD.Shape.cupola(9).scale(12000);
poly.join().expand().triakis(9, 2000).join();
poly.translate([ 0, 0, -6700 ]).scale([ 1, 1, 3 ]).cutAt(0, 1);
const frame = PD.Shape.frame(poly, 250, 150);
CAD.add(frame);

Shape.meta(shape, [sides]) ⇒ Shape

The Conway meta operation is basically the join of a triakis operation.

If the sides argument is less than 3, all faces in the shape will be bevelled. If 3 or more, only those faces with a matching number of sides will be bevelled.

Kind: static method of Shape
Returns: Shape - Returns a new shape generated from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.
[sides]Array.<number> | numberAn optional array of face indexes or the number of sides a face must have to be affected, defaults to 0 (all faces).

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.meta(poly).setRadius(3489));
CAD.add(poly);

Shape.ortho(shape) ⇒ Shape

The Conway ortho operation is effectively a double join operation.

Kind: static method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
shapeShapeThe shape to base the operation on.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.ortho(poly).setRadius(3489));
CAD.add(poly);

Shape.propellor(shape, [fraction]) ⇒ Shape

The Conway propellor extended operation creates new skewed faces by making new points along each edge, 1/3rd the distance from v1- > v2, then connecting these into a new inset face. This breaks any rotational symmetry about the faces.

Kind: static method of Shape
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
shapeShapeThe shape to base the operation on.
[fraction]numberThe face rotation fraction (0.001 to 0.999), defaults to 1/3.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.propellor(poly).setRadius(3489));
CAD.add(poly);

Shape.snub(shape) ⇒ Shape

The Conway snub operation creates a new shape which is basically a gyro operation performed on the dual of the shape. It creates a new face for each vertex, which is then twisted slightly and two new triangular faces added to replace each edges and fill the gaps.

Kind: static method of Shape
Returns: Shape - Returns a new shape generated from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.

Example

const shape = new PD.Polyhedron('D12:S5000');
CAD.add(PD.Polyhedron.snub(shape).scale(1.28225));
CAD.add(shape);

Shape.triakis(shape, [sides], [offset]) ⇒ Shape

The Conway triakis operation divides specified faces into triangles to form a pyramid with its apex at the center of the face.

If the sides argument is less than 3, all faces in the shape will be divided. If 3 or more, only those faces with a matching number of sides will be divided.

If an offset value is given, then the apex of the pyramid will be positioned that far away from the geometric centre of the face in the direction of its surface normal.

This method differs from the Conway Polyhedron Notation version in that the offset distance is given in model units rather than as a fraction of shape radius.

Kind: static method of Shape
Returns: Shape - Returns a new shape generated from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.
[sides]Array.<number> | numberAn optional array of face indexes or the number of sides a face must have to be affected, defaults to 0 (all faces).
[offset]numberThe distance of the pyramid apex away from the face center in model units, defaults to 0.

Shape.truncate(shape, [sides], [offset]) ⇒ Shape

The Conway truncate operation is a triakis operation performed on the dual of the original shape, then converted back to a dual.

If the sides argument is less than 3, all faces in the shape will be bevelled. If 3 or more, only those faces with a matching number of sides will be bevelled.

Kind: static method of Shape
Returns: Shape - Returns a new shape generated from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the operation on.
[sides]Array.<number> | numberAn optional array of face indexes or the number of sides a face must have to be affected, defaults to 0 (all faces).
[offset]numberThe distance of the triakis apex away from the face center in model units, defaults to 0.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.truncate(poly).setRadius(3765));
CAD.add(poly);

Shape.generateSection(shape, plane) ⇒ Shape | null

Computes sectional contour(s) through the shape as cut by the given plane.

To make this method easier to use, the directional component of any given plane equation does not need to be normalised as this will be done automatically. Thus, you could provide a plane array such as [ 1, 1, 1, -500 ] and it will be automatically converted to [ 0.5773503, 0.5773503, 0.5773503, -500 ].

Kind: static method of Shape
Returns: Shape | null - Returns a new shape with vertices and faces on the cutting plane, or null if no intersection.

ParamTypeDescription
shapeShapeThe shape to generate the section through.
planenumber | Array.<number>A [a,b,c,d] plane array or vertical height value in the Z axis to section the shape at.

Example

const poly = new PD.Polyhedron('D8:tk').scale(2000);

const section = PD.Shape.generateSection(poly, [ -1, -1, 4, -200 ]);
if (section?.faces) {

    /// Add as face(s).
    CAD.addShell(section);

    /// Add as wire(s).
    for (const face of section.faces) {
        const points = face.map(index => section.vertices[index]);
        CAD.addWire(points, true);
    }

}

/// Shrink polyhedron a bit.
CAD.add(poly.inflate(-100));

Shape.cutAt(shape, plane, keep, [cutFaces]) ⇒ Shape

Cuts the faces of the given shape by the given plane and either keeps all of them or just those in the front or rear of the plane.

To make this method easier to use, the directional component of any given plane equation does not need to be normalised as this will be done automatically. Thus, you could provide a plane array such as [ 1, 1, 1, -500 ] and it will be automatically converted to [ 0.5773503, 0.5773503, 0.5773503, -500 ].

Kind: static method of Shape
Returns: Shape - Returns a new shape cut from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the cutting on.
planenumber | Array.<number>A height value in the Z axis or an [a,b,c,d] plane array to cut the shape at.
keepnumberWhich side(s) to retain (0:Both, 1:Front, -1:Rear), defaults to 0 (both).
[cutFaces]Array | numberAn optional array in which to store any newly added cut faces. If given as a number instead of an array, it gives a distance by which a base is created by extruding cut surfaces in the opposite direction of the cutting plane.

Example

const cut_faces = [];
const cut_plane = [ 0, 0, 1, 0 ];
const base_poly = new PD.Polyhedron('D8:th(0.15,0.025)ajeS9000');
const dome_with_holes = PD.Shape.cutAt(base_poly, cut_plane, 1, cut_faces).translate([ 0, 0, 3000 ]);
for (const face of cut_faces) {
    dome_with_holes.faceExtrude(face, -3000, cut_plane, 6);
}

CAD.add(dome_with_holes);

Shape.sliceAt(shape, plane) ⇒ Array.<Shape>

Slices a shape into two new shapes by cutting it with the given plane.

This method returns an array of two shapes, the first being created from those faces in front of the plane and the second from those behind. If the plane does not actually intersect the given shape, one of the two will be empty.

Defining a Plane

This method uses an infinite plane to cut the shape, defined by an [a,b,c,d] plane array based on the Ax + Bx + Cz + D = 0 equation for a 3D plane. This means providing an array with four numbers that define the A, B, C and D components of the equation.

Alternatively, if you just want to cut a shape using a horizontal plane, you can pass a single number rather than a plane array. This number is used as the height on the Z axis of a cutting plane that faces towards the +Z axis.

The first three values in the plane array define its normal direction, which also defines the front and rear sides of the plane. Anything on the same side as the normal is pointing is in front, and anything on the other side is behind.

To make this method easier to use, the directional component of any given plane array does not need to be normalised as this will be done automatically. Thus, you could provide a plane array such as [ 1, 1, 1, -500 ] and it will be automatically normalized to [ 0.5773503, 0.5773503, 0.5773503, -500 ].

NOTE: When providing just a single number instead of a plane, it is important to remember that the number represents the plane height rather than the D component. Thus, a numeric value of 250 is equivalent to specifying [0,0,1,-250] as the plane array.

Kind: static method of Shape
Returns: Array.<Shape> - Returns an array iof two new shapes sliced from the given shape.

ParamTypeDescription
shapeShapeThe shape to base the slicing on.
planenumber | Array.<number>A height value in the Z axis or an [a,b,c,d] plane array to cut the shape at.

Example

/// Slice cylinder into two separate halves.
const shape = PD.Shape.cylinder(12, 2000, 5000);
const [ top, bot ] = PD.Shape.sliceAt(shape, [ 1, 1, 4, -2500 ]);
CAD.add(top.translate([ 0, 0, 500 ]));
CAD.add(bot);

Shape.sliceUp(shape, plane, [slices], [increment]) ⇒ Array.<Shape>

Slice a shape up into a set of new shapes by cutting it into multiple segments using the given plane.

This method returns an array of shapes created by successively slicing the given base shape the given number of times by moving the cutting plane incrementally in its normal direction.

Defining a Plane

This method uses an infinite plane to cut the shape, defined by an [a,b,c,d] plane array based on the Ax + Bx + Cz + D = 0 equation for a 3D plane. This means providing an array with four numbers that define the A, B, C and D components of the equation.

Alternatively, if you just want to cut a shape using a horizontal plane, you can pass a single number rather than a plane array. This number is used as the height on the Z axis of a cutting plane that faces towards the +Z axis.

The first three values in the plane array define its normal direction, which also defines the front and rear sides of the plane. Anything on the same side as the normal is pointing is in front, and anything on the other side is behind.

To make this method easier to use, the directional component of any given plane array does not need to be normalised as this will be done automatically. Thus, you could provide a plane array such as [ 1, 1, 1, -500 ] and it will be automatically normalized to [ 0.5773503, 0.5773503, 0.5773503, -500 ].

NOTE: When providing just a single number instead of a plane, it is important to remember that the number represents the plane height rather than the D component. Thus, a numeric value of 250 in the Z axis is equivalent to specifying [0,0,1,-250] as the plane array.

Defining Slices

It is important to point out here that ‘slice’ can be used as both an adjective and a noun, which will likely cause some initial confusion when using this modifier. If you slice a cake once, you end up wth two slices. If you slice it twice radially across its diameter, you end up with 4 slices. If you do two parallel slices across it, you end up with three slices.

To avoid all such issues, when used in this context, the terms ‘slice’ and slices refer to the number of cuts made rather than the number of chunks that might result.

Also, slicing up shapes is complex, so a modifier like this needs to be quite flexible in its specification of where each slice is taken.

The simplest way to slice up a shape is to give just the plane equation and the number of slices to take. In this case, this method will compute the near and far extents of the shape in the line of the plane and generate the given number of uniform slices over its extents.

If slices is given as an array, each value in the array is taken as an absolute offset from the given plane at which to take a slice. In this case, the values will be sorted in ascending order and the incrementvalue ignored. Again, offset values are given as distances in in the direction of the surface normal of the plane, not as the D value of the plane equation. Thus, to cut three slices, the first being 3m, then 2m and 1, use [3000,5000,6000].

If you wish to specify increments for each slice instead of absolute offsets, include the number of slices you want and then use an array of increments for each slice as the increment argument. Thus, to cut three slices, the first being 3m, then 2m and 1, use [3000,2000,1000]. If there are less values in the array than there are slices, the last increment is simply repeated. If there are more values in the array than there are slices, only the number of slices are used. An invalid array will end up cutting at just the plane.

Kind: static method of Shape
Returns: Array.<Shape> - Returns an array of new shapes as slices of the given shape.

ParamTypeDescription
shapeShapeThe shape to base the slicing on.
planenumber | Array.<number>A height value in the Z axis or an [a,b,c,d] plane array to cut the shape at.
[slices]number | Array.<number>The number of slices to cut through the shape (1 to 1024) or an array of slice distances, defaults to 1.
[increment]numberThe distance to move the plane on each slice, defaults to extents() / (slices + 1).

Example

/// Cut cylinder using 4 slices.
const shape = PD.Shape.cylinder(12, 2000, 5000);
const slices = PD.Shape.sliceUp(shape, [ 1, 1, 4, -900 ], 4, 1000);

let z = 0;
for (const slice of slices) {
    CAD.add(slice.translate([ 0, 0, z ]));
    z += 500;
}

Example

/// Cut cylinder using 3 absolute slices.
const shape = PD.Shape.cylinder(12, 2000, 5000);
const slices = PD.Shape.sliceUp(shape, [ 1, 1, 4, -900 ], [ 800, 1800, 2400 ]);

let z = 0;
for (const slice of slices) {
    CAD.add(slice.translate([ 0, 0, z ]));
    z += 500;
}

Example

/// Cut cylinder using 3 relative slices.
const shape = PD.Shape.cylinder(12, 2000, 5000);
const slices = PD.Shape.sliceUp(shape, [ 1, 1, 4, -900 ], 3, [ 800, 1000, 600 ]);

let z = 0;
for (const slice of slices) {
    CAD.add(slice.translate([ 0, 0, z ]));
    z += 500;
}

Shape.cuboid(width, [depth], [height], [center]) ⇒ Shape

Generates a rectilinear prism centered at the origin.

           (0,d,h)            (w,d,h)
             7-------------------6
         Z  /|                  /|
         | / |                 / |
         |/  |        (w,0,h) /  | Y
 (0,0,h) 4-------------------5   |/
         |   3---------------|---2 (w,d,0)
         |  /(0,d,0)         |  /
         | /                 | /
         |/                  |/
         0-------------------1 -- -- X
      (0,0,0)             (w,0,0)

              3---------2
              |  back   |
              |    3    |
              |         |
    3---------7---------6---------2
    |  left   |   top   |  right  |
    |    4    |    5    |    2    |
    |         |         |         |
    0---------4---------5---------1
              |  front  |
              |    1    |
              |         |
              0---------1
              | bottom  |
              |    0    |
              |         |
              3---------2

Kind: static method of Shape
Returns: Shape - Returns a new cuboid shape.

ParamTypeDefaultDescription
widthnumberThe size of the cuboid in the X-axis, defaults to 1.
[depth]numberThe size of the cuboid in the Y-axis, defaults to width.
[height]numberThe size of the cuboid in the Z-axis, defaults to width.
[center]booleanfalseWhether or not the shape is centered at the origin rather than its minimum corner, defaults to false.

Shape.wedge(width, [depth], [height], [taperHeight], [taperWidth]) ⇒ Shape

Generates a wedge, which is similar to a cuboid but with an angled top and possibly also sides.

         Z
         |
         |                         Y
         4-------------------5__  /
         |'' 3---------------|---2
         |  /                |  /
         | /                 | /
         |/                  |/
         0-------------------1 -- -- X

A wedge shape tapers in the Y axis direction. It typically tapers in height, but may also taper in X axis width as it travels along the Y axis.

The taper height can be given as a single number or as an array containing the bottom and top heights at the taper end.

The taper width can also be given as a single number or as an array containing the left and right X-axis values at the taper end.

Kind: static method of Shape
Returns: Shape - Returns a new wedge shape.

ParamTypeDescription
widthnumberThe size of the wedge in the X-axis, defaults to 1.
[depth]numberThe size of the wedge in the Y-axis, defaults to width.
[height]numberThe size of the wedge in the Z-axis, defaults to width.
[taperHeight]number | Array.<number>The height at the tapered end in the local Z-axis or a [min_z,max_z] array, defaults to [0,0].
[taperWidth]number | Array.<number>The width at the tapered end in the local X-axis or a [min_x,max_x] array, defaults to [0,width].

Example

const wedge = PD.Shape.wedge(2000, 1500, 1000, 250);
CAD.add(wedge);

Example

const wedge = PD.Shape.wedge(2000, 1500, 1000, 250, 500);
CAD.add(wedge);

Example

const wedge = PD.Shape.wedge(2000, 1500, 1000, [ 250, 500 ], [ 1500, 2000 ]);
CAD.add(wedge);

Shape.prism(sides, [radius], [height]) ⇒ Shape

Generates an extruded prism of unit radius with n sides.

Kind: static method of Shape
Returns: Shape - Returns a new shape.

ParamTypeDescription
sidesnumberThe number of sides in the shape (3+), defaults to 4.
[radius]numberThe radius of the prism in model units, defaults to 1.
[height]numberThe height of the prism in model units, defaults to side length for square sides.

Shape.antiprism(sides, [radius], [height]) ⇒ Shape

Generates an extruded antiprism of the given radius with n sides.

Kind: static method of Shape
Returns: Shape - Returns a new shape.

ParamTypeDescription
sidesnumberThe number of sides in the shape (3+), defaults to 4.
[radius]numberThe radius of the prism in model units, defaults to 1.
[height]numberThe height of the prism in model units, defaults to side length for square sides.

Shape.bipyramid(sides, [radius], [height], [elongation]) ⇒ Shape

Generates a bipyramid of unit radius with n sides.

Kind: static method of Shape
Returns: Shape - Returns a new shape.

ParamTypeDescription
sidesnumberThe number of sides in the shape (3+), defaults to 4.
[radius]numberThe radius of the bipyramid in model units, defaults to 1.
[height]numberThe height of the bipyramid in model units, defaults to radius.
[elongation]numberAn optional size for a prism between the two pyramids, defaults to zero.

Shape.cupola(sides, [alpha], [height], [topRadius]) ⇒ Shape

Generates a cupola shape of unit radius.

A cupola is a shape formed by joining two polygons, one (the base) with twice as many edges as the other, by an alternating band of isosceles triangles and rectangles.

The alpha argument can be used to bias either the triangles (>0) of the rectangles (<0).

By default, the height of the cupola is set so that the side triangles and rectangles are regular. You can change this by specifically setting the height argument. You can set it to null or undefined to use the default setting.

You can also adjust the radius of the top face using the radius argument. This defaults to 0.5, but you can also use 0 for a conical shape, 1 for a cylindrical shape, or greater than 1 for an inverted shape.

Kind: static method of Shape
Returns: Shape - Returns a new shape.

ParamTypeDescription
sidesnumberThe number of sides in the shape (3 to 1024), defaults to 4.
[alpha]numberAn optional base spacing factor (-1 to 1), defaults to zero (0).
[height]numberThe fractional height of the cupola top, defaults to height required for regular sided polygons.
[topRadius]numberThe fractional radius of the cupola top (0 to 1), defaults to 0.5.

Shape.anticupola(sides, [alpha], [height], [topRadius]) ⇒ Shape

Generates an anticupola shape of unit radius.

Kind: static method of Shape
Returns: Shape - Returns a new shape.

ParamTypeDescription
sidesnumberThe number of sides in the shape (3 to 1024), defaults to 4.
[alpha]numberAn optional base spacing factor (-1 to 1), defaults to zero (0).
[height]numberThe height of the cupola top, defaults to height required for regular sided polygons.
[topRadius]numberThe fractional radius of the cupola top (0 to 1), defaults to 0.5.

Shape.cylinder(sides, [radius], [height], [segments]) ⇒ Shape

Generates a cylindrical prism of unit radius with n sides and segments.

Kind: static method of Shape
Returns: Shape - Returns a new polyhedron.

ParamTypeDescription
sidesnumberThe number of sides in the shape (3 to 1024), defaults to 4.
[radius]numberThe radius of the shape in model units, defaults to 1.
[height]numberThe height of the shape in model units, defaults to side length for square sides.
[segments]numberThe number of vertical segments in the shape, defaults to 1.

Example

const cyl = PD.Shape.cylinder(36, 1000, 500);
CAD.add(cyl);

Example

const segments = 12;

/// Create base shape to work on.
const cyl = PD.Shape.cylinder(segments, 1000, 500);

/// Create local coordinates.
const axis = new PD.AxisArray();
axis.moveOrigin(0, 2000, 0);
axis.rotateZ(Math.PI / 4);
cyl.applyAxis(axis);

/// Create different positive/negative scales.
const scale_positive = [3.50, 1.5, 1.0];
const scale_negative = [1.25, 1.5, 1.0];

/// Extract the bottom ring of vertices.
const base = cyl.vertices.slice(0, segments);

/// Apply both scales about the origin.
axis.scalePoints(base, scale_positive, scale_negative);
CAD.add(cyl);

Shape.pyramid(sides, [radius], [height], [segments]) ⇒ Shape

Generates a pointed polyhedron of unit radius with n triangular sides.

Kind: static method of Shape
Returns: Shape - Returns a new polyhedron.

ParamTypeDescription
sidesnumberThe number of sides in the pyramid (3 to 1024), defaults to 4.
[radius]numberThe radius of the pyramid in model units, defaults to 1.
[height]numberThe height of the pyramid in model units, defaults to radius.
[segments]numberThe number of vertical segments in the shape, defaults to 1.

Example

const shape = PD.Shape.pyramid(9, 6000, 12000);
shape.frame(150, 150);
CAD.add(shape);

Shape.rotunda(side, [radius], [height]) ⇒ Shape

Generates a pentagonal rotunda of unit radius.

As this shape always has 10 sides in its base, the sides value is ignored, but retained for comparability with other spherical generator methods.

Kind: static method of Shape
Returns: Shape - Returns a new shape.

ParamTypeDescription
sidenumberThis argument is there for compatibility with other generators, but ignored.
[radius]numberThe radius of the shape in model units, defaults to 1.
[height]numberThe height of the shape in model units, defaults to (radius * 0.850650808).

Shape.dome([latRings], [lngRings], [radius]) ⇒ Shape

Generates a hemispheric shape from lat/lng points.

Kind: static method of Shape
Returns: Shape - Returns a new hemispherical shape.

ParamTypeDescription
[latRings]numberThe number of longitudinal divisions (1 to 178), defaults to 8.
[lngRings]numberThe number of latitudinal divisions (3 to 360), defaults to 16.
[radius]numberThe radius of the point distribution, defaults to 1.

Example

/// Create a dome.
const shape1 = PD.Shape.dome(18, 9, 5000);
shape1.translate([ -1000, 0, 0 ]);

/// Create sphere.
const shape2 = PD.Shape.sphere(18, 9, 3000);
shape2.translate([ 1000, 0, 3500 ]);

/// Convert to CAD shapes.
const solid1 = CAD.addSolid(shape1);
const solid2 = CAD.addSolid(shape2);

CAD.translate(CAD.union([ solid1, solid2 ]), [ 0, -6000, 0 ]);
CAD.translate(CAD.subtract(solid1, solid2), [ 0, 6000, 0 ]);

Shape.sphere([latRings], [lngRings], [radius]) ⇒ Shape

Generates a spherical shape from lat/lng points.

Kind: static method of Shape
Returns: Shape - Returns a new spherical shape.

ParamTypeDescription
[latRings]numberThe number of longitudinal divisions (1 to 178), defaults to 8.
[lngRings]numberThe number of latitudinal divisions (3 to 360), defaults to 16.
[radius]numberThe radius of the point distribution, defaults to 1.

Example

/// Create a dome.
const shape1 = PD.Shape.dome(18, 9, 5000);
shape1.translate([ -1000, 0, 0 ]);

/// Create sphere.
const shape2 = PD.Shape.sphere(18, 9, 3000);
shape2.translate([ 1000, 0, 3500 ]);

/// Convert to CAD shapes.
const solid1 = CAD.addSolid(shape1);
const solid2 = CAD.addSolid(shape2);

CAD.translate(CAD.union([ solid1, solid2 ]), [ 0, -6000, 0 ]);
CAD.translate(CAD.subtract(solid1, solid2), [ 0, 6000, 0 ]);

Shape.domeRandom([num_pts], [radius]) ⇒ Shape

Generates a hemispheric shape from random points.

Kind: static method of Shape
Returns: Shape - Returns a new hemispherical shape.

ParamTypeDescription
[num_pts]numberThe number of points to generate (6 to 2048), defaults to 48.
[radius]numberThe radius of the point distribution, defaults to 1.

Example

/// PD.Utils.randomNumber(22783); // Use a specific seed.
const shape = PD.Shape.domeRandom(64, 5000);
CAD.add(shape);

Shape.sphereRandom([num_pts], [radius]) ⇒ Shape

Generates a spherical shape from random points.

Kind: static method of Shape
Returns: Shape - Returns a new spherical shape.

ParamTypeDescription
[num_pts]numberThe number of points to generate (6 to 2048), defaults to 48.
[radius]numberThe radius of the point distribution, defaults to 1.

Example

/// PD.Utils.randomNumber(22783); // Use a specific seed.
const shape = PD.Shape.sphereRandom(128, 5000);
CAD.add(shape);

Shape.domeGeodesic([detail], [radius]) ⇒ Shape

Generates a hemispheric shape from geodesic triangles.

This distribution is generated by progressively dividing into spherical triangles and then inflating the interpolated points to the radius of the sphere.

Kind: static method of Shape
Returns: Shape - Returns a new hemispherical shape.

ParamTypeDescription
[detail]numberThe level of triangulation (0 to 32), defaults to 6.
[radius]numberThe radius of the point distribution, defaults to 1.

Example

/// Create a geodesic dome.
const shape1 = PD.Shape.domeGeodesic(8);
shape1.scale(5000).translate([ -1000, 0, 0 ]);

/// Create sphere from Fibonacci spiral.
const shape2 = PD.Shape.sphereFibonacci(128);
shape2.scale(3500).translate([ 1000, 0, 3500 ]);

/// Convert to CAD shapes.
const solid1 = CAD.addSolid(shape1);
const solid2 = CAD.addSolid(shape2);

CAD.translate(CAD.union([ solid1, solid2 ]), [ 0, -6000, 0 ]);
CAD.translate(CAD.subtract(solid1, solid2), [ 0, 6000, 0 ]);

Shape.sphereGeodesic([detail], [radius]) ⇒ Shape

Generates a spherical shape from geodesic triangles.

This distribution is generated by progressively dividing into spherical triangles and then inflating the interpolated points to the radius of the sphere.

Kind: static method of Shape
Returns: Shape - Returns a new spherical shape.

ParamTypeDescription
[detail]numberThe level of triangulation (0 to 32), defaults to 6.
[radius]numberThe radius of the point distribution, defaults to 1.

Example

/// Create a dome from Fibonacci spiral.
const shape1 = PD.Shape.domeFibonacci(128, 5000);
shape1.translate([ -1000, 0, 0 ]);

/// Create geodesic sphere.
const shape2 = PD.Shape.sphereGeodesic(8, 3000);
shape2.translate([ 1000, 0, 3500 ]);

/// Convert to CAD shapes.
const solid1 = CAD.addSolid(shape1);
const solid2 = CAD.addSolid(shape2);

CAD.translate(CAD.union([ solid1, solid2 ]), [ 0, -6000, 0 ]);
CAD.translate(CAD.subtract(solid1, solid2), [ 0, 6000, 0 ]);

Shape.domeFibonacci(num_pts, [radius]) ⇒ Shape

Generates a hemispheric shape from a Fibonacci spiral.

The distribution of points is based in the Fibonacci spiral which gives a pretty good approximation of equally-spaced points on the surface pf a sphere.

Kind: static method of Shape
Returns: Shape - Returns a new hemispherical shape.

ParamTypeDescription
num_ptsnumberThe number of points to generate (4 to 2048), defaults to 48.
[radius]numberThe radius of the dome, defaults to 1.

Example

/// Create a dome from Fibonacci spiral.
const shape1 = PD.Shape.domeFibonacci(128, 5000);
shape1.translate([ -1000, 0, 0 ]);

/// Create geodesic sphere.
const shape2 = PD.Shape.sphereGeodesic(8, 3000);
shape2.translate([ 1000, 0, 3500 ]);

/// Convert to CAD shapes.
const solid1 = CAD.addSolid(shape1);
const solid2 = CAD.addSolid(shape2);

CAD.translate(CAD.union([ solid1, solid2 ]), [ 0, -6000, 0 ]);
CAD.translate(CAD.subtract(solid1, solid2), [ 0, 6000, 0 ]);

Shape.sphereFibonacci(num_pts, [radius]) ⇒ Shape

Generates a spherical shape from a Fibonacci spiral.

The distribution of points is based in the Fibonacci spiral which gives a pretty good approximation of equally-spaced points on the surface of a sphere.

Kind: static method of Shape
Returns: Shape - Returns a new spherical shape.

ParamTypeDescription
num_ptsnumberThe number of points to generate (4 to 2048), defaults to 48.
[radius]numberThe radius of the sphere, defaults to 1.

Example

/// Create a geodesic dome.
const shape1 = PD.Shape.domeGeodesic(8);
shape1.scale(5000).translate([ -1000, 0, 0 ]);

/// Create sphere from Fibonacci spiral.
const shape2 = PD.Shape.sphereFibonacci(128);
shape2.scale(3500).translate([ 1000, 0, 3500 ]);

/// Convert to CAD shapes.
const solid1 = CAD.addSolid(shape1);
const solid2 = CAD.addSolid(shape2);

CAD.translate(CAD.union([ solid1, solid2 ]), [ 0, -6000, 0 ]);
CAD.translate(CAD.subtract(solid1, solid2), [ 0, 6000, 0 ]);

Shape.sphereDelaunay(points, [radius]) ⇒ Shape

Uses Delaunay triangulation to generate a shape from a series of [azi,alt] polar points.

Kind: static method of Shape
Returns: Shape - Returns a new shape.

ParamTypeDescription
pointsArray.<Array.<number>> | numberAn array of 2D [azi,alt] polar coordinates or the number of random points to generate, defaults to 64.
[radius]numberThe radius of the point distribution, defaults to 1000.

Example

/// const points = PD.VectorArray.polarPoints_Random(64, true);
/// const points = PD.VectorArray.polarPoints_Geodesic(6, false);
const points = PD.VectorArray.polarPoints_Fibonacci(128, false);
const shape = PD.Polyhedron.sphereDelaunay(points, 5000).cutAt(0, 1);
shape.perlinNoise(5000, [ 5000, 5000, 0 ], 900);
CAD.add(shape.weld());

Shape.sphereVoronoi(points, [radius]) ⇒ boolean

Uses Voronoi cellularisation to generate a shape from a series of [azi,alt] polar points.

Kind: static method of Shape
Returns: boolean - Returns true if the triangulation succeeded, otherwise false.

ParamTypeDescription
pointsArray.<Array.<number>> | numberAn array of 2D [azi,alt] polar coordinates or the number of random points to generate, defaults to 64.
[radius]numberThe radius of the point distribution, defaults to 1000.

Example

/// const points = PD.VectorArray.polarPoints_Random(128, false);
/// const points = PD.VectorArray.polarPoints_Geodesic(6, false);
const points = PD.VectorArray.polarPoints_Fibonacci(128, false);
const shape = PD.Polyhedron.sphereVoronoi(points, 5000).cutAt(0, 1);
shape.perlinNoise(5000, [ 5000, 5000, 0 ], 900);
CAD.add(shape.weld());

Shape.convexHull(points, [smoothing], [detail]) ⇒ Shape

Generate a convex hull around the given points.

This process creates a new shape that has faces that are the same size and orientation as the given shape, just offset by the given distance and with additional faces to fill in the seams and gaps between offset facets.

Kind: static method of Shape
Returns: Shape - Returns a new shape hull.

ParamTypeDescription
pointsArray.<Array.<number>> | numberAn array of 3D [x,y,z] coordinates arrays or the number of random points to generate, defaults to 64.
[smoothing]number | Array.<number>An edge smoothing radius or a [min,max] radius array in model units, defaults to 0.
[detail]numberThe geodesic detail at each point when smoothing (0 to 32), defaults to 0.

Example

/// Random hemispherical rock generator.
const points = PD.VectorArray.pointCloud_Random(64, 5000, true);
const rock = PD.Polyhedron.convexHull(points, [ -500, 2000 ], 4);
CAD.add(rock);

Example

/// Rough gemstone generator.
/// PD.Utils.randomNumber(22783); // Use a specific seed.
const points = PD.VectorArray.pointCloud_Random(48, 5000, true);
const rock = PD.Shape.convexHull(points);
rock.perlinNoise(8000, 5000, 0).truncate();
CAD.add(rock);

Shape.sphericalHarmonics([config], [params], [core], [latRings], [lngRings], [normalise], [random], [innerRadius], [helix], [spiralU], [spiralV], [rotationsU], [rotationsV], [scaleXY], [unfoldZ], [usedParams]) ⇒ Shape

Generates a cylindrical surface of unit radius perturbed using spherical harmonics.

Due to the nature of the algorithm, either the latitudinal or longitudinal seams of the generated surface (or both) may not line up. Thus, by default, this method does not try to automatically join them together. In some shapes the seams do line up, in which case you can use the weld method to join the matching seams so that you can use some of the modifiers that require a manifold shape.

Alternatively, as shown in the more detailed example below, you can use the openEdgeLoops method to access the open seams and then manually join them up, in this case using a triangular fan.

Kind: static method of Shape
Returns: Shape - Returns a new shape with a spherical harmonics surface.

ParamTypeDescription
[config]objectA optional configuration object.
[params]Array.<Array.<number>>An array of between 8 (shape) to 16 (shell) parameters.
[core]numberAn inner core radius as a fraction (0 to 1), defaults to 0.
[latRings]numberThe number of latitudinal divisions in 180deg (1 to 178), defaults to 36.
[lngRings]numberThe number of longitudinal divisions in 360deg (3 to 360), defaults to 72.
[normalise]booleanWhen true, ensures the maximum surface radius is 1, defaults to false.
[random]booleanWhen true, generates random shape parameters, defaults to false.
[innerRadius]numberA fraction internal radius (-F to F), defaults to ‘param[8]’ (0).
[helix]numberA helical offset factor with longitude (-F to F), defaults to ‘param[9]’ (0).
[spiralU]numberA spiral inset factor with longitude (-F to F), defaults to ‘param[10]’ (0).
[spiralV]numberA spiral inset factor with latitude (-F to F), defaults to ‘param[11]’ (0).
[rotationsU]numberNumber of longitudinal rotations (0 to R), defaults to ‘param[12]’ (1).
[rotationsV]numberNumber of latitudinal rotations (0 to R), defaults to ‘param[13]’ (1).
[scaleXY]numberA horizontal scale factor (0 to S), defaults to ‘param[14]’ (1).
[unfoldZ]numberA vertical unfolding factor (0 to S), defaults to ‘param[15]’ (0).
[usedParams]Array.<number>An optional array to receive shape parameters after range checks and validation.

Example

const usedParameters = []; // Get validated and range limited parameters.
const shape = PD.Shape.sphericalHarmonics({ random: true }, usedParameters).setRadius(2500);
console.log(usedParameters); // Show parameters actually used.
CAD.add(shape);

Example

const params = [ 1, -3, 1, -4, 0, 0, 1, 1, 0, 0, 0, 0, 1, 1, 1, 0 ];
const shape = PD.Shape.sphericalHarmonics({ params: params, innerRadius: 0.75 }).setRadius(2500);
CAD.add(shape);

Example

const superShapeConfig = {
    params: [ 1, 4, 0, 0, 0, 0, 2, -3 ], // An array of 8 (shape) to 16 (shell) parameters.
    latRings: 18,       // The number of longitudinal divisions (1 to 178), defaults to 36.
    lngRings: 36,       // The number of latitudinal divisions (3 to 360), defaults to 72.
    normalise: false,   // When true, ensures the maximum surface radius is 1, defaults to false.
    random: false,      // When true, generates random shape parameters, defaults to false.
    innerRadius: 0.5,   // A fraction internal radius (-F to F), defaults to 'params[8]' (0).
    helix: 0.0,         // A helical offset factor with longitude (-F to F), defaults to 'params[9]' (0).
    spiralU: 0.0,       // A spiral inset factor with longitude (-F to F), defaults to 'param[10]' (0).
    spiralV: 0.0,       // A spiral inset factor with latitude (-F to F), defaults to 'param[11]' (0).
    rotationsU: 1.0,    // Number of longitudinal rotations (0 to R), defaults to 'param[12]' (1).
    rotationsV: 1.0,    // Number of latitudinal rotations (0 to R), defaults to 'param[13]' (1).
    scaleXY: 1.0,       // A horizontal scale factor (0 to S), defaults to 'param[14]' (1).
    unfoldZ: 0.75       // A vertical unfolding factor (0 to S), defaults to 'param[15]' (0).
};

const shape = PD.Shape.sphericalHarmonics(superShapeConfig).scale(2000);

/// Collect open edges and fill in top/bot holes.
const open_edges = shape.weld().openEdgeLoops();
for (const loop of open_edges) {
    const center = shape.faceCenter(loop);
    const center_index = shape.vertices.push(center) - 1;
    for (let ii = 0, ii_max = loop.length; ii < ii_max; ++ii) {
        shape.faces.push([ center_index, loop[ii], loop[(ii + 1) % ii_max] ]);
    }
}

CAD.add(shape.join());

Shape.superFormula([config], [params], [latRings], [lngRings], [normalise], [random], [innerRadius], [helix], [spiralU], [spiralV], [rotationsU], [rotationsV], [scaleXY], [unfoldZ], [usedParams]) ⇒ Shape

Generates a cylindrical surface of unit radius perturbed using the super-formula.

Kind: static method of Shape
Returns: Shape - Returns a new shape with a super-formula surface.

ParamTypeDescription
[config]objectA optional configuration object.
[params]Array.<Array.<number>>An array of between 8 (shape) to 16 (shell) parameters.
[latRings]numberThe number of latitudinal divisions in 180deg (1 to 178), defaults to 36.
[lngRings]numberThe number of longitudinal divisions in 360deg (3 to 360), defaults to 72.
[normalise]booleanWhen true, ensures the maximum surface radius is 1, defaults to false.
[random]booleanWhen true, generates random shape parameters, defaults to false.
[innerRadius]numberA fraction internal radius (-F to F), defaults to ‘param[8]’ (0).
[helix]numberA helical offset factor with longitude (-F to F), defaults to ‘param[9]’ (0).
[spiralU]numberA spiral inset factor with longitude (-F to F), defaults to ‘param[10]’ (0).
[spiralV]numberA spiral inset factor with latitude (-F to F), defaults to ‘param[11]’ (0).
[rotationsU]numberNumber of longitudinal rotations (0 to R), defaults to ‘param[12]’ (1).
[rotationsV]numberNumber of latitudinal rotations (0 to R), defaults to ‘param[13]’ (1).
[scaleXY]numberA horizontal scale factor (0 to S), defaults to ‘param[14]’ (1).
[unfoldZ]numberA vertical unfolding factor (0 to S), defaults to ‘param[15]’ (0).
[usedParams]Array.<number>An optional array to receive shape parameters after range checks and validation.

Example

const usedParameters = []; // Get validated and range limited parameters.
const super_shape = PD.Shape.superFormula({ random: true }, usedParameters).setRadius(2500);
console.log(usedParameters); // Show parameters actually used.
CAD.add(super_shape);

Example

const params = [ 5, 4, 12, 11, 2, 6, 4, 15, 0, 0, 0, 0, 1, 1, 1, 0 ];
const super_shape = PD.Shape.superFormula({ params }).setRadius(2500);
CAD.add(super_shape);

Example

const shapeConfig = {
    params: [],         // An array of between 8 (shape) to 16 (shell) parameters.
    latRings: 36,       // The number of latitudinal divisions (1 to 178), defaults to 36.
    lngRings: 72,       // The number of longitudinal divisions (3 to 360), defaults to 72.
    normalise: false,   // When true, ensures the maximum surface radius is 1, defaults to false.
    random: false,      // When true, generates random shape parameters, defaults to false.
    innerRadius: 0.5,   // A fraction internal radius (-F to F), defaults to 'params[8]' (0).
    helix: 0.0,         // A helical offset factor with longitude (-F to F), defaults to 'params[9]' (0).
    spiralU: 0.0,       // A spiral inset factor with longitude (-F to F), defaults to 'param[10]' (0).
    spiralV: 0.0,       // A spiral inset factor with latitude (-F to F), defaults to 'param[11]' (0).
    rotationsU: 1.0,    // Number of longitudinal rotations (0 to R), defaults to 'param[12]' (1).
    rotationsV: 1.0,    // Number of latitudinal rotations (0 to R), defaults to 'param[13]' (1).
    scaleXY: 1.0,       // A horizontal scale factor (0 to S), defaults to 'param[14]' (1).
    unfoldZ: 0.75       // A vertical unfolding factor (0 to S), defaults to 'param[15]' (0).
};

const super_shape = PD.Shape.superFormula(shapeConfig).scale(1250);

/// Collect open edges and fill in top/bot holes.
const open_edges = super_shape.weld().openEdgeLoops();
for (const loop of open_edges) {
    super_shape.faces.push(loop);
}

/// Smooth edges, set size and add to CAD model.
super_shape.weld().join().setHeight(5000).setRadiusXY(2500);
CAD.add(super_shape);

Shape.metaballs([config], [balls], [cells], [type], [min], [max], [expansion], [threshold]) ⇒ Shape

Generates an enclosed surface from one or more metaball blobs.

This method first creates a temporary 3D volumetric grid around the extents of all the given balls and computes a signed distance field within it. It then generates a 3D surface at the given threshold using either a Marching Cubes, Surface Nets or Voxelisation algorithm.

You can specify a minimum and/or maximum extends for the volumetric grid,

Kind: static method of Shape
Returns: Shape - Returns a new shape with the blob surfaces.

ParamTypeDescription
[config]objectA configuration object.
[balls]Array.<Array.<number>>An array of one or more [x,y,z,radius] ball definitions.
[cells]number | Array.<number>The number of grid cells in each axis or or a [cellsX,cellsY,cellsZ] array, defaults to 16.
[type]numberThe type of surface (0:Triangular[MarchingCubes], 1:Polygonal[SurfaceNets], 2:Voxelised), defaults to 0.
[min]Array.<number>The [x,y,z] coordinate array of the minimum extents in each axis.
[max]Array.<number>The [x,y,z] coordinate array of the maximum extents in each axis.
[expansion]numberA fraction of the cell size to expand the calculated extents by (0 to 1), defaults to 0.5.
[threshold]numberThe value to generate the iso-surface at, defaults to 0.

Example

const blob = PD.Shape.metaballs({
    type: 1,
    balls: [
        [     0,     0,     0, 3000.0 ],
        [  2000,     0,  2500, 2000.0 ],
        [     0, -2000,  2000, 1500.0 ]
    ]
});

/// Convert to a OCC solid.
const inside = CAD.addSolid(blob);

// Expand the surface by 150mm and cut the top off.
const outside = CAD.addSolid(blob.inflate(150).cutAt(2500, -1));

/// Subtract the insides out.
CAD.subtract(outside, inside);

PD.Polyhedron ⇐ Shape

A class for defining polyhedral shapes simply and efficiently.

This class extends the Shape class by adding support for creating a range of known polyhedra types and implementing methods and techniques for the core Conway polyhedron notation modifiers.

The base requirement for the majority of these modifiers is a manifold shape with connected vertices and edges, which all of the polyhedra creation methods comply with. Some modifiers have more detailed requirements. For example, the inflate modifier assumes that the shape is roughly spherical, whilst some others assume a unit sphere with a radius of close to 1, which means that you really have to experiment with their arguments to get anything viable from larger or differently formed shapes. However, this is such a simple and flexible class that it can be used for many different things, so these restrictions don’t always need to be met if you are not intending to apply those particular modifiers.

What is a Polyhedron

Polyhedra are three dimensional shapes that are formed by the connection of a finite number of closed planar polygons that each share connected edges and completely bound an internal volume. A particular polyhedra shape is referred to as a polyhedron.

Regular polyhedrons are formed from multiple instances of the same regular polygon, in which all sides/edges are straight, equiangular (all internal angles are equal in measure) and equilateral (all sides/edges have the same length).

Irregular polyhedrons can be formed from irregular polygons where each straight edge may be different in length and may even form a concave boundary. Whilst this class focusses mainly on non-self-intersecting polyhedrons, they too may be valid polyhedra.

Generators and Modifiers

This class started out as a means of creating and experimenting with commonly used polyhedron shapes. As a result, it provides static generator methods for Platonic, Archimedean, Catalan and Johnson solids, as well as prisms, anti-prisms, pyramids, cupola, rotunda, domes and spheres.

Something very important to note is that these static generators create shapes in which the radius of the farthest vertex from their geometric centre is equal to or close to 1. This makes them compatible with all of the polyhedron modifier recipes described in Polyhédronisme, but means that you will likely have to use the scale method once you have completed all modifications, or add the S modifier to your notation, If you don’t apply a scale, they will be about 2mm in diameter and unlikely to be visible alongside other geometry within your model.

This scaling does not apply to polyhedra generated using Shape factory methods as their input parameters often require world coordinates or dimensions. However, this makes these shapes less suitable for the application of polyhedron modifiers. Some modifiers will work without issue, but others will likely generate unusable results or require you to experiment heavily with their parameters to get anything useful from them.

As a result, you are encouraged to only scale the polyhedron after you have applied all modifiers. When you use the S modifier, it just sets a scale factor that is applied to the final result at the very end of the modifier sequence for exactly this reason.

Structure and Modifiers

A polyhedron is constructed from a set of spatial vertices that are shared by a series of connected edges which are, in turn, shared by a series of connected faces. To completely bound an internal volume, every vertex is shared by at least three edges and every edge is shared by exactly two faces. Each face is defined by a single outer boundary loop of vertices. A face in a polyhedron cannot contain internal hole boundaries, but must instead be broken down into a series of separate faces that bound the hole.

With the above caveats, there are a series of mathematical operations that can be reliably performed on valid polyhedra to generate incredibly complex and beautiful shapes that are also valid polyhedra. These work by dividing, truncating, expanding, inflating and/or rotating faces and edges. You can apply these operations to any valid polyhedron using the applyModifiers method or the PD.PolyhedronFactory class.

Array-Based Vertices

See the Shape class documentation for more detailed information, but a key aspect of this polyhedron class is that all vertices are and must be stored as [x,y,z] vector arrays rather than point objects. This allows the polyhedron modifiers described in Polyhédronisme to be directly applied and supports the detailed array-based vector math they use.

To assist with the array-based vector math involved in the creation, modification and transformation of these kinds of forms, the framework provides the VectorArray, PlaneArray, QuaternionArray and MatrixArray classes. The framework also links in array-based vector geometry libraries for generating 2D and 3D convex hulls, surface triangulation and noise generation.

Kind: static class of PD
Extends: Shape
Author: drajmarsh

new PD.Polyhedron([vertices], [faces], [name])

Creates a new polyhedron.

ParamTypeDescription
[vertices]string | Array.<Array.<number>>A type/notation string or a flat array of [x,y,z] vertex coordinates.
[faces]Array.<Array.<number>>An array of face boundary arrays, each containing three or more vertex indices.
[name]stringA human-readable name for the shape.

polyhedron.isPolyhedron : boolean

A flag identifying this object as a polyhedron.

Kind: instance property of Polyhedron
Read Only: true

polyhedron.name : string

A human-readable name for the shape.

Kind: instance property of Polyhedron Overrides: name

polyhedron.vertices : Array.<Array.<number>>

A flat array of vertex coordinates stored as [x,y,z] vector arrays.

Each vertex is an array of three (3) numbers representing the X, Y and Z coordinates of a spatial point, referred to as an [x,y,z] vector array. These vertices are assembled into edges and boundaries by the faces array.

Kind: instance property of Polyhedron Overrides: vertices

polyhedron.faces : Array.<Array.<number>>

An array of face boundary arrays, each containing three or more vertex indices.

Each face is an array of ordinal indices of the vertexes in the vertices array that form its boundary.

Kind: instance property of Polyhedron Overrides: faces

polyhedron.colors : Array.<number> | Array.<Array.<number>>

An array of [r,g,b] face colors.

This array is only valid if it is exactly the same length as the faces array. Each entry in this array is the color associated with the corresponding face in the faces array.

Kind: instance property of Polyhedron Overrides: colors

polyhedron.isShape : boolean

A flag identifying this object as a shape.

Kind: instance property of Polyhedron Overrides: isShape
Read Only: true

polyhedron.info() ⇒ string

Get some informative about the polyhedron as a string.

Kind: instance method of Polyhedron
Returns: string - Return basic polyhedra information.

polyhedron.moreInfo() ⇒ string

Get more informative data about the polyhedron as a string.

Kind: instance method of Polyhedron
Returns: string - Return more detailed polyhedra information.

polyhedron.minEdgeLength() ⇒ number

Computes the minimum edge length.

Kind: instance method of Polyhedron
Returns: number - Returns the minimum edge length.

polyhedron.minFaceRadius() ⇒ number

Computes the minimum face radius.

Kind: instance method of Polyhedron
Returns: number - Returns the minimum face radius.

polyhedron.updateColors([method], [sensitivity]) ⇒ Polyhedron

Sets the color of each face of the polyhedra for display.

The available color methods are as follows:

  • ’none’: No color(s) assigned.
  • ’edges’: Group faces by their number of edges.
  • ‘area’: Group faces by similar surface areas.
  • ‘signature’: Group faces by the congruency of their normals.
  • ‘smooth’: Use smooth surface normals.

Kind: instance method of Polyhedron
Returns: Polyhedron - Returns this polyhedron to support method chaining.

ParamTypeDescription
[method]stringThe method to use to assign face colors, defaults to colorMethod.
[sensitivity]stringThe color sensitivity to variation in congruence signature or planar area, defaults to colorSensitivity.

polyhedron.modify(op, …args) ⇒ Polyhedron

Applies a Conway notation modifier to this polyhedron.

See the parseNotation method for details of the supported modifier operations and their arguments.

You can also use the full modifier names

Kind: instance method of Polyhedron
Returns: Polyhedron - Returns this polyhedra to support method chaining.

ParamTypeDescription
opstringThe operational modifier.
…argsnumberThe numeric arguments for the operation.

polyhedron.applyModifiers(modifiers) ⇒ Polyhedron

Applies an array of modifier operations to this polyhedron.

The method performs all the required calculations synchronously, which can block the main thread of your application for several seconds for long modifier chains. To perform the calculations asynchronously with progress updates, use the PD.PolyhedronFactory.fromModifiers method instead.

Each modifier in the list is an object with an op property that is a string defining the operation to be performed and an args property which is an array of any numeric arguments the operation requires.

See the parseNotation method for details of the supported modifier operations and their arguments.

Kind: instance method of Polyhedron
Returns: Polyhedron - Returns this polyhedra to support method chaining.

ParamTypeDescription
modifiersArray.<object>A list of modifier operations.

polyhedron.applyNotation(notation) ⇒ Polyhedron

Applies modifiers from a Conway notation string such as ‘qoh(0.15,0.05)eeuz’.

See the parseNotation method for details of the supported modifier operations and their arguments.

Kind: instance method of Polyhedron
Returns: Polyhedron - Returns this polyhedra to support method chaining.

ParamTypeDescription
notationstringA string containing ‘a(n,n)bcd9’ modifier operations.

polyhedron.copyToBRep(brep, [scale]) ⇒ boolean

Copies polyhedron to the given surface.

Kind: instance method of Polyhedron Overrides: copyToBRep
Returns: boolean - Returns true if geometry was added to the surface. ??? @override -> jsdoc2md - RangeError: Maximum call stack size exceeded.

ParamTypeDescription
brepPD.BRepThe BRep to add the polyhedron faces to.
[scale]numberAn optional scale factor for the polyhedron, defaults to 1000mm (1m).

polyhedron.importGeometry(text, [detectOnly]) ⇒ string

Checks the given text for a recognisable and importable geometry data format and, if found imports it.

Kind: instance method of Polyhedron
Returns: string - Returns a format string such as json, mcc, obj, etc.

ParamTypeDefaultDescription
textstringThe textual content of a geometry file.
[detectOnly]booleanfalseWhen true, only the format is returned without loading the geometry, defaults to false

polyhedron.toFormattedJSON([compact]) ⇒ string

Formats the polyhedron geometry as a compact or human-readable JSON string.

Kind: instance method of Polyhedron
Returns: string - Returns a human-readable JSON string.

ParamTypeDefaultDescription
[compact]stringfalseGenerate a more compact form with edges.

polyhedron.toOBJ(scale) ⇒ string

Produces a simple OBJ file for import into 3D apps.

Kind: instance method of Polyhedron
Returns: string - Returns the contents of an OBJ file representing the polyhedra.

ParamTypeDescription
scaleArray.<number>An [sx,sy,sz] scale array.

polyhedron.fromOBJ(text) ⇒ boolean

Attempts to parse polyhedron data from simple OBJ data.

As the rules for modifying manifold polyhedron geometry are reasonably tight, you should only load relatively simple closed shell geometry if you want standard modifiers to work.

Kind: instance method of Polyhedron
Returns: boolean - Returns true if OBJ data was parsed and the polyhedron geometry was updated.

ParamTypeDescription
textstringA Wavefront OBJ data string.

polyhedron.toSTL(scale) ⇒ string

Produces an STL file for 3D printing.

Kind: instance method of Polyhedron
Returns: string - Returns the contents of an STL files representing the polyhedra.

ParamTypeDescription
scaleArray.<number>An [sx,sy,sz] scale array.

polyhedron.fromSTL(text) ⇒ boolean

Attempts to parse polyhedron data from STL format data.

As the rules for modifying manifold polyhedron geometry are reasonably tight, you should only load relatively simple closed shell geometry if you want standard modifiers to work.

Kind: instance method of Polyhedron
Returns: boolean - Returns true if STL data was parsed and the polyhedron geometry was updated.

ParamTypeDescription
textstringA STL format data string.

polyhedron.toPLY(scale) ⇒ string

Generates the polyhedron in Polygon File Format.

Kind: instance method of Polyhedron
Returns: string - Returns the contents of a PLY files representing the polyhedra.

ParamTypeDescription
scaleArray.<number>An [sx,sy,sz] scale array.

polyhedron.fromPLY(text) ⇒ boolean

Attempts to parse polyhedron data from Polygon File Format data.

As the rules for modifying manifold polyhedron geometry are reasonably tight, you should only load relatively simple closed shell geometry if you want standard modifiers to work.

Kind: instance method of Polyhedron
Returns: boolean - Returns true if PLY data was parsed and the polyhedron geometry was updated.

ParamTypeDescription
textstringA Polygon File Format data string.

polyhedron.toX3D(scale) ⇒ string

Produces an X3D file for 3D printing.

Kind: instance method of Polyhedron
Returns: string - Returns the contents of an X3D files representing the polyhedra.

ParamTypeDescription
scaleArray.<number>An [sx,sy,sz] scale array.

polyhedron.fromX3D(text) ⇒ boolean

Attempts to parse polyhedron data from XML X3D data.

As the rules for modifying manifold polyhedron geometry are reasonably tight, you should only load relatively simple closed shell geometry if you want standard modifiers to work.

Kind: instance method of Polyhedron
Returns: boolean - Returns true if X3D data was parsed and the polyhedron geometry was updated.

ParamTypeDescription
textstringAn XML X3D data string.

polyhedron.toVRML(scale) ⇒ string

Produces an VRML/WRL file for 3D printing.

Kind: instance method of Polyhedron
Returns: string - Returns a the contents of an VRML files representing the polyhedra.

ParamTypeDescription
scaleArray.<number>An [sx,sy,sz] scale array.

polyhedron.fromVRML(text) ⇒ boolean

Attempts to parse polyhedron data from VRML/WRL data.

As the rules for modifying manifold polyhedron geometry are reasonably tight, you should only load relatively simple closed shell geometry if you want standard modifiers to work.

Kind: instance method of Polyhedron
Returns: boolean - Returns true if VRML data was parsed and the polyhedron geometry was updated.

ParamTypeDescription
textstringA VRML/WRL data string.

polyhedron.toDSV([separator]) ⇒ string

Formats the polyhedron geometry as delimiter-separated values.

If no separator is given it defaults to a comma-separated value format.

Kind: instance method of Polyhedron
Returns: string - Returns a DSV string.

ParamTypeDefaultDescription
[separator]string","The delimiter to separate values with, defaults to a comma.

polyhedron.fromDSV(text, [separator], [zeroBased]) ⇒ boolean

Attempts to parse polyhedron data from delimiter-separated values.

NOTE: This method can also be used to parse simple Wavefront OBJ files if they contain a single object/group.

Kind: instance method of Polyhedron
Returns: boolean - Returns true if DSV data was parsed and the polyhedron geometry was updated.

ParamTypeDefaultDescription
textstringA delimiter-separated values data string.
[separator]string","The delimiter to separate values with, defaults to a comma.
[zeroBased]stringtrueWhether or not vertex indices in faces start at zero rather than one, defaults to true.

polyhedron.toMcCooeyFormat() ⇒ string

Formats the polyhedron geometry as per McCooey (https://dmccooey.com/polyhedra/),

Kind: instance method of Polyhedron
Returns: string - Returns a McCooey formatted string.

polyhedron.fromMcCooeyFormat(text) ⇒ boolean

Attempts to parse polyhedron data from McCooey (https://dmccooey.com/polyhedra/).

Kind: instance method of Polyhedron
Returns: boolean - Returns true if McCooey formatted data was parsed and the polyhedron geometry was updated.

ParamTypeDescription
textstringA McCooey formatted data string.

polyhedron.toJSON([data]) ⇒ object

Converts the object instance to a simple POJO for JSON storage.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

NOTE: As vertexes are simple [x,y,z] vector arrays and each face is just an array of ordinal vertex indexes, both the faces and vertices arrays are used directly by the JSON object rather than being copied. This makes converting shapes to JSON very fast and efficient, which is important as this class is used quite a lot for data exchange. If you want to deep copy the data arrays, see the example code below:

Kind: instance method of Polyhedron Overrides: toJSON
Returns: object - Returns a JSON object.

ParamTypeDescription
[data]objectAn optional parent object to append this data to.

Example

const shallow_copy = shape.toJSON();
const deep_copy = shape.clone().toJSON();

polyhedron.fromJSON(data) ⇒ Shape

Safely copy properties from a source object.

NOTE: If vertexes are given as [x,y,z] vector arrays, and faces as arrays of ordinal indexes, then both the faces and vertices data arrays are used directly rather than copied to the shape. This makes creating shapes from JSON very fast and efficient, which is important as this class is used quite a lot for data exchange. If you want to deep copy the data arrays, see the example code below:

Kind: instance method of Polyhedron Overrides: fromJSON
Returns: Shape - Returns this instance to support method chaining.

ParamTypeDescription
dataobjectThe source object containing data to copy.

Example

const shallow_copy = new PD.Shape().fromJSON(data);
const deep_copy = new PD.Shape().fromJSON(data).clone();

polyhedron.clone() ⇒ Shape

Creates a deep copy of this shape.

Kind: instance method of Polyhedron Overrides: clone
Returns: Shape - Returns a new shape. Example

const shape = PD.Shape.prism(9, 1500, 1000).ortho();
CAD.add(shape.clone().inflate(200));
CAD.add(shape);

polyhedron.copy(shape) ⇒ Shape

Performs a shallow copy of the data in the given shape.

Kind: instance method of Polyhedron Overrides: copy
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
shapeShapeThe shape to copy from.

polyhedron.makeDefaultShape() ⇒ Shape

Makes this shape a 4-sided unit tetrahedron as the default shape for empty shapes.

Kind: instance method of Polyhedron Overrides: makeDefaultShape
Returns: Shape - Returns this shape to support method chaining.

polyhedron.hasContent() ⇒ boolean

Determines whether or not the shape has any content.

This method does a very simple check to see if there are any vertices and any faces. It doesn’t do any validity or sanity checking, just looks for content.

Kind: instance method of Polyhedron Overrides: hasContent
Returns: boolean - Returns true if shape has one or more valid edge/facet.

polyhedron.addVertex(vertex) ⇒ number

Retrieves the next reusable vertex in the surface, or creates and adds a new one.

The argument to this method can be either a simple [x,y,z] vector array or an {x,y,z} object such as a THREE.Vector3, PD.Point or similar object class. This method fetches from or creates vertices in vertexList by incrementing an internal counter that is reset to zero when the reuseStart() method is called.

Kind: instance method of Polyhedron Overrides: addVertex
Returns: number - Returns the index of the added vertex in the vertices list.

ParamTypeDescription
vertexArray.<number>The [x,y,z] vector array to add to the vertex list.

polyhedron.edges() ⇒ Array.<Array.<number>>

Computes a non-redundant list of the shape’s edges.

The edges of a shape are simply arrays containing two integer values, being the ordinal indices of the start and end vertices of the edge within the vertices array.

Kind: instance method of Polyhedron Overrides: edges
Returns: Array.<Array.<number>> - Returns an array of unique edges. Example

const poly = new PD.Polyhedron('D8:tk').scale(2000);

/// Display polyhedron as wires.
for (const edge of poly.edges()) {
    const points = edge.map(index => poly.vertices[index]);
    CAD.addWire(points, false);
}

/// Cut section and display as a face.
const section = PD.Shape.generateSection(poly, [ -1, -1, 4, -200 ]);
if (section?.faces) {
    CAD.addShell(section);
}

polyhedron.centers() ⇒ Array.<Array.<number>>

Computes a list of face center points.

The center of each face is returned as an [x,y,z] vector array defining its spatial position in each major axis.

The order and index of center points in the returned list match the order and index of corresponding faces in the faces list.

Kind: instance method of Polyhedron Overrides: centers
Returns: Array.<Array.<number>> - Returns an array of face centers. Example

const shape = PD.Shape.domeGeodesic(4, 2000)

/// Find bottom face.
let bottom_face_index = -1;
let bottom_face_min_z = Infinity;
const face_centers = shape.centers();
for (let ii = 0; ii < face_centers.length; ++ii) {
    if (bottom_face_min_z > face_centers[ii][2]) {
        bottom_face_min_z = face_centers[ii][2];
        bottom_face_index = ii;
    }
}

/// Show bottom face as face.
if (bottom_face_index >= 0) {
    const points = shape.faces[bottom_face_index].map(index => shape.vertices[index]);
    CAD.addPolygon(points);
}

polyhedron.normals() ⇒ Array.<Array.<number>>

Computes a list of face normal vectors.

The normal vector of each face is returned as an [x,y,z] vector array of unit length (normalized) defining its spatial direction in each major axis.

The order and index of normals in the returned list match the order and index of corresponding faces in the faces list.

Kind: instance method of Polyhedron Overrides: normals
Returns: Array.<Array.<number>> - Return an array of face normals. Example

const distance = 250;
const face_normals = shape.normals();
for (let ii = 0; ii < shape.faces.length; ++ii) {
    for (const index of shape.faces[ii]) {
        hull_vertices.push(
            PD.VectorArray.translateInVectorDirection([], shape.vertices[index], face_normals[ii], distance)
        );
    }
}

polyhedron.vertexNormals() ⇒ Array.<Array.<number>>

Computes the averaged surface normal for each vertex.

The normal vector of each vertex in the shape is returned as an [x,y,z] vector array of unit length (normalized) defining its spatial direction in each major axis. Vertex normals are calculated as the average of all the face normals from faces that contain that vertex.

The order and index of vertex normals in the returned list match the order and index of corresponding vertices in the vertices list.

To allow further processing, additional information is appended to each normal array. Assuming the vertex is shared by N faces, each normal array has the following form:

[ normalX, normalY, normalZ, N, faceIndex1, faceIndex2, …, faceIndexN ]

Kind: instance method of Polyhedron Overrides: vertexNormals
Returns: Array.<Array.<number>> - Returns an array of averages vertex normals. Example

const distance = 250;
const vertex_normals = shape.vertexNormals();
for (let ii = 0; ii < shape.vertices.length; ++ii) {
    hull_vertices.push(
        PD.VectorArray.translateInVectorDirection([], shape.vertices[ii], vertex_normals[ii], distance)
    );
}

polyhedron.extents([min], [max]) ⇒ Array.<Array.<number>>

Computes the minimum and maximum extents of the shape.

Kind: instance method of Polyhedron Overrides: extents
Returns: Array.<Array.<number>> - Return a [min,max] array of two [x,y,z] vector arrays.

ParamTypeDescription
[min]Array.<number>An optional [x,y,z] vector array to receive the minimum extents.
[max]Array.<number>An optional [x,y,z] vector array to receive the maximum extents.

Example

/// Create cylinder with 12 sides and 20 segments.
const shape = PD.Shape.cylinder(12, 2000, 5000, 20);

/// Compute range values in Z axis.
const [ min, max ] = shape.extents();
const bot_z = min[2] + ((max[2] - min[2]) * 0.25);
const top_z = min[2] + ((max[2] - min[2]) * 0.90);

/// Apply a scaling factor over the range.
shape.scaleByAxis(2, bot_z, top_z, 2.0, PD.Easing.inOutQuart);
CAD.add(shape);

polyhedron.connections() ⇒ Array.<Array.<Array.<number>>>

Computes and assembles the connection relationships between faces, edges and vertices.

This method returns an object with two arrays as properties:

  • vertices: An array of vertices with the indexes of each of the other vertices they connect to via an edge. This array is in the form [ v1, v2, v3, … ] and uses the same ordinal indexes as the vertices array.

  • edges An array of edges with two vertex indices followed by the indexes of the two faces they share. This array is in the form [ v1, v2, f1, f2 ].

The vertex indexes in the edges array are ordered such that the lowest ordinal index always comes first (array[0]) followed by the highest ordinal (array[1]). The face indexes are ordered such that, in the first face (array[2]), the direction of travel along the edge is from first vertex to second. In the second face (array[3]), the direction of travel is from the second vertex (array[1]) back to the first (array[0]).

Kind: instance method of Polyhedron Overrides: connections
Returns: Array.<Array.<Array.<number>>> - Returns an array of vertex and edge connections.

polyhedron.openEdgeLoops() ⇒ Array.<Array.<number>>

Collects all edges that are not shared by two faces and assembles them into an array of one or more loops.

This method relies on all coincident edges sharing the same vertices, which means that the shape cannot have ‘T’ junctions where two faces meet somewhere along the edge of another face where it doesn’t have a vertex. If you are not absolutely sure of the inter-connection state of your shape, call the weld method first.

The loops generated by this method will likely be closed but not be planar. If the shape is more like an open surface, you should end up with one big outer boundary loop. If the shape is mostly closed, but has some holes within it, you should end up with loops for each hole.

You will need to work out how best to close a shape if you find that it has open edges.

The vertex indexes in the edges array are ordered such that the lowest ordinal index always comes first (array[0]) followed by the highest ordinal (array[1]).

Kind: instance method of Polyhedron Overrides: openEdgeLoops
Returns: Array.<Array.<number>> - Returns an array of open edge loops. Example

/// Collect open edges and fill in top and bottom holes.
const super_shape = PD.Shape.superFormula({ innerRadius: 0.5, unfoldZ: 0.125 });
super_shape.scale(500).setRadiusXY(5000).weld();
const open_edges = super_shape.openEdgeLoops();
for (const loop of open_edges) {
    super_shape.faces.push(loop);
}

CAD.add(super_shape);

polyhedron.faceCenter(face, [target]) ⇒ Array.<number>

Compute the geometric center of the given face.

The center of the face is returned as an [x,y,z] vector array defining its spatial position in each major axis.

Kind: instance method of Polyhedron Overrides: faceCenter
Returns: Array.<number> - Return an [x,y,z] vector array defining the face center.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.
[target]Array.<number>An optional [x,y,z] vector array to receive the calculated center, defaults to a new vector array.

Example

const shape = PD.Shape.domeGeodesic(4, 2000)

/// Display shape as wires.
for (const edge of shape.edges()) {
    const points = edge.map(index => shape.vertices[index]);
    CAD.addWire(points, false);
}

/// Find bottom face.
const center = [ 0, 0, 0 ];
let bottom_face_index = -1;
let bottom_face_value = Infinity;
for (let ii = 0; ii < shape.faces.length; ++ii) {
    shape.faceCenter(ii, center);
    if (bottom_face_value > center[2]) {
        bottom_face_value = center[2];
        bottom_face_index = ii;
    }
}

/// Show bottom face as face.
if (bottom_face_index >= 0) {
    const points = shape.faces[bottom_face_index].map(index => shape.vertices[index]);
    CAD.addPolygon(points);
}

polyhedron.faceNormal(face, [target]) ⇒ Array.<number>

Compute the surface normal of the given face.

The normal vector of the face is returned as an [x,y,z] vector array of unit length (normalized) defining its spatial direction in each major axis.

Kind: instance method of Polyhedron Overrides: faceNormal
Returns: Array.<number> - Returns the modified target if it is given or a new [x,y,z] vector array defining the face normal.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.
[target]Array.<number>An optional [x,y,z] vector array to receive the calculated normal, defaults to a new vector array.

Example

const distance = 250;
const face_normal = [];
for (let ii = 0; ii < shape.faces.length; ++ii) {
    for (const index of shape.faces[ii]) {
        hull_vertices.push(
            PD.VectorArray.translateInVectorDirection([], shape.vertices[index], face_normals[ii], distance)
        );
    }
}

polyhedron.faceVertices(face) ⇒ Array.<Array.<number>>

Retrieves the face as an array of actual vertices, being the [x,y,z] vector arrays representing each point on the face boundary.

NOTE: This method returns the actual vertex arrays from the shape vertex list, so any changes you make to the vertex arrays will propagate across all faces that share the same vertices.

Kind: instance method of Polyhedron Overrides: faceVertices
Returns: Array.<Array.<number>> - Return an array of [x,y,z] vector array points the define the face boundary.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.

Example

const shape = PD.Shape.domeGeodesic(4, 2000)

/// Find bottom face and show as filled polygon.
const bot_face = shape.findExtremeFace([ 0, 0, -1 ]);
if (bot_face.index >= 0) {
    const points = shape.faceVertices(bot_face.index);
    CAD.addPolygon(points);
}

/// Show rest of shape as wires.
for (const edge of shape.edges()) {
    const points = edge.map(index => shape.vertices[index]);
    CAD.addWire(points, false);
}

polyhedron.faceInset(face, [inset], [offset], [normal]) ⇒ Array.<Array.<number>>

Computes a set of vertices inset from the edges of the given face.

Kind: instance method of Polyhedron Overrides: faceInset
Returns: Array.<Array.<number>> - Return an array of new inset/offset vertices.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.
[inset]numberAn inset distance from each edge in model units, defaults to 0 (no inset).
[offset]numberAn optional distance from face surface, defaults to 0 (no offset).
[normal]Array.<number>An optional [x,y,z] vector array to receive the calculated face normal so you don’t need to compute it again.

polyhedron.faceExtrude(face, distance, [direction], [segments]) ⇒ Array.<Array.<number>>

Extrudes the given face in the given direction and distance.

This method displaces the given face and adds extruded side faces. If the optional segments argument has an integer value of greater than one (1), the extrusion will be done in a series of that many segments.

Kind: instance method of Polyhedron Overrides: faceExtrude
Returns: Array.<Array.<number>> - Return an array of all the new faces just added.

ParamTypeDescription
facenumber | Array.<number>The face to process, as an index within the faces array, or the actual array of vertex indices.
distancenumberThe total distance to extrude, in model units.
[direction]Array.<number>The direction to extrude in as an [x,y,z] vector array. defaults to the face’s surface normal.
[segments]numberThe number of segments to extrude the face in, defaults to 1.

Example

const cut_faces = [];
const cut_plane = [ 0, 0, 1, 0 ];
const poly = new PD.Polyhedron('D8:jeh(0.15,0.025)ajS9000');
const dome_with_holes = PD.Shape.cutAt(poly, cut_plane, 1, cut_faces).translate([ 0, 0, 3000 ]);
for (const face of cut_faces) {
    dome_with_holes.faceExtrude(face, -3000, cut_plane, 3);
}
CAD.add(dome_with_holes);

polyhedron.computeCentroid() ⇒ Array.<number>

Computes the geometric center point of the shape by averaging all of its vertices.

Kind: instance method of Polyhedron Overrides: computeCentroid
Returns: Array.<number> - Returns the centroid as an [x,y,z] vector arrays.

polyhedron.closestAndFarthestFromPlane(plane) ⇒ Array.<Array.<number>>

Computes the vertex positions that are closest to and farthest away from the given plane.

Kind: instance method of Polyhedron Overrides: closestAndFarthestFromPlane
Returns: Array.<Array.<number>> - Returns a [closest,farthest] array of [x,y,z] vector arrays.

ParamTypeDescription
planenumber | Array.<number>A [a,b,c,d] plane array or vertical height value in the Z axis to slice the shape at.

Example

const slices = 4;
const plane = [  1,  0.25,  0,  10000 ];
const shape = PD.Shape.cuboid(4000, 2000, 1000);
const [ closest, farthest ] = shape.closestAndFarthestFromPlane(plane);
const start = -PD.VectorArray.dot(closest, plane);
const end = -PD.VectorArray.dot(farthest, plane);
const inc = (end - start) / (slices + 1);

for (let ii = 1; ii <= slices; ++ii) {
    plane[3] = start + (ii * inc);
    shape.cutAt(plane, 0);
}

CAD.addSolid(shape);
const frame = PD.Shape.frame(shape, 50, 50);
CAD.add(frame);

polyhedron.findExtremeFace([normal]) ⇒ object

Finds the face with a centre point at the extreme edge of the shape in one of the major cartesian axis.

This method is used to find a reference face to use for orienting all others. To be facing ‘outwards’, the normal of the most extreme face in one of the major axis must point in the same direction as that axis.

Kind: instance method of Polyhedron Overrides: findExtremeFace
Returns: object - Returns an object with face, extreme.index and extreme.axis properties, being the actual face, its index in the faces array and the axis (0, 1 or 2).

ParamTypeDescription
[normal]Array.<number>An optional [x,y,z] vector array giving the direction to search in, defaults to any.

Example

const { face, index, axis } = shape.findExtremeFace();

/// Ensure extreme face normal points in same direction as extreme axis.
PD.VectorArray.calcNormalFromIndexedPathNewellMethod(normal, face, this.vertices);
if (normal[axis] < 0) {
     face.reverse();
}

Example

const shape = PD.Shape.domeGeodesic(4, 2000)

/// Find bottom face and show as filled polygon.
const bot_face = shape.findExtremeFace([ 0, 0, -1 ]);
if (bot_face.index >= 0) {
    const points = shape.faceVertices(bot_face.index);
    CAD.addPolygon(points);
}

/// Display shape as wires.
for (const edge of shape.edges()) {
    const points = edge.map(index => shape.vertices[index]);
    CAD.addWire(points, false);
}

polyhedron.translate(offset) ⇒ Shape

Applies a [dx,dy,dz] translation to this shape.

Kind: instance method of Polyhedron Overrides: translate
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
offsetArray.<number>A [x,y,z] vector array to move by.

polyhedron.rotate(origin, axis, angle) ⇒ Shape

Rotates the shape around the given origin/axis by the given angle.

The origin is effectively the point about which the rotation should take place. It is subtracted from each point prior to the rotation, then added back afterwards.

Kind: instance method of Polyhedron Overrides: rotate
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
originArray.<number>The [x,y,z] vector array defining the origin point to rotate about.
axisArray.<number>The [x,y,z] vector array defining the axial vector to rotate around.
anglenumberThe angle of rotation, in radians.

polyhedron.scale(scale) ⇒ Shape

Applies a scaling factor to this shape.

Kind: instance method of Polyhedron Overrides: scale
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
scalenumber | Array.<number>A scale factor or [sx,sy,sz] vector array to multiple vertices by.

polyhedron.scaleByAxis(axis, from, to, scale, [easing]) ⇒ Shape

Scales the shape in the other two axis by an amount that varies over a range within the given axis.

If the from and to values are both in the range 0 to 1, then they are considered to be fractions of the size of the shape in the given axis. If either value is outside the range 0 to 1, then they are both considered to be in absolute model units along the axis.

You can use the extents method if you want to find out the size range of your specific shape in each axis.

If the scale is given as a single number, it represents the maximum scale at the to point on the axis, varying from 1 at the from point. If given as a [fromScale, toScale] array, you can specify the scales to use at both the from and to points. You can specify an easing function if you wish to make it a non-linear variation.

If you choose the Z axis, then the varying scale will be applied to the X and Y components of each vertex in the shape. If you choose the X axis the scale will be applied in Y and Z, and for the Y axis, it will be applied in X and Z.

If you wish to scale vertexes in a non-Cartesian axis or about a point other than the origin, use the PD.AxisArray#scalePointsInXY method instead.

Kind: instance method of Polyhedron Overrides: scaleByAxis
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
axisnumberThe axis to scale in (0:X, 1:Y or 2:Z).
fromnumberA value on the given axis to start scaling from ,in model units.
tonumberA value on the given axis to finish scaling at, in model units.
scalenumber | Array.<number>The scale at or above the to value, or a [fromScale,toScale] array, defaults to 1 (no scale).
[easing]functionAn easing function to use, defaults to linear.

Example

/// Scale cylinder with 12 sides and 20 segments.
const shape = PD.Shape.cylinder(12, 2000, 5000, 10);
shape.scaleByAxis(2, 0, 1, 2.0, PD.Easing.inOutQuint);
CAD.add(shape);

const frame = PD.Shape.frame(shape, 25, 50);
CAD.add(frame);

polyhedron.stretchByAxis(axis, from, to, [scale], [easing]) ⇒ Shape

Stretches the vertices of shape over a range in the given axis.

If the from and to values are both in the range 0 to 1, then they are considered to be fractions of the size of the shape in the given axis. If either value is outside the range 0 to 1, then they are both considered to be in absolute model units along the axis.

You can use the extents method if you want to find out the size range of your specific shape in each axis.

Kind: instance method of Polyhedron Overrides: stretchByAxis
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
axisnumberThe X, Y or Z axis to use (0:X, 1:Y, 2:Z).
fromnumberA value on the given axis to start stretching from in model units.
tonumberA value on the given axis to finish stretching at in model units.
[scale]numberThe amount to scale the axis range area by, defaults to 1 (no scale).
[easing]functionAn easing function to use, defaults to linear.

Example

/// Stretch cylinder with 12 sides and 20 segments.
const shape = PD.Shape.cylinder(12, 2000, 2500, 10);
shape.stretchByAxis(2, 0.25, 1.0, 2.0, PD.Easing.inOutCubic);
CAD.add(shape);

const frame = PD.Shape.frame(shape, 25, 50);
CAD.add(frame);

Example

/// Stretch cylinder with 24 sides and 10 segments.
const shape = PD.Shape.cylinder(24, 2000, 2500, 10);
shape.stretchByAxis(0, 0, 1, 4.0, PD.Easing.inOutQuint);
shape.stretchByAxis(2, 0, 1, 2.0, PD.Easing.outCubic);
shape.meta().cutAt(1700, 1).cutAt(7000, -1).translate([ 0, 0, -1700 ]);
CAD.add(shape);

const frame = PD.Shape.frame(shape, 25, 25).expand().ambo().join();
CAD.add(frame);

polyhedron.twistByAxis(axis, from, to, angle, [easing]) ⇒ Shape

Rotates the shape in the other two axis by an angle that varies over a range within the given axis.

If the from and to values are both in the range 0 to 1, then they are considered to be fractions of the size of the shape in the given axis. If either value is outside the range 0 to 1, then they are both considered to be in absolute model units along the axis.

You can use the extents method if you want to find out the size range of your specific shape in each axis.

If the angle is given as a single number, it represents the maximum twist angle at the to point on the axis, varying from 0 at the from point. If given as a [fromAngle, toAngle] array, you can specify the angles to use at both the from and to points. You can specify an easing function if you wish to make it a non-linear variation.

If you choose the Z axis, then the twist will be applied to the X and Y components of each vertex in the shape. If you choose the X axis the twist will be applied in Y and Z, and for the Y axis, it will be applied in X and Z.

If you wish to scale vertexes in a non-Cartesian axis or about a point other than the origin, use the PD.AxisArray#twistPointsInXY method instead.

Kind: instance method of Polyhedron Overrides: twistByAxis
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
axisnumberThe axis to twist in (0:X, 1:Y or 2:Z).
fromnumberA value on the given axis to start twisting from ,in model units.
tonumberA value on the given axis to finish twisting at, in model units.
anglenumber | Array.<number>The angle at or above the to value, or a [fromAngle,toAngle] array, defaults to 0 (no twist).
[easing]functionAn easing function to use, defaults to linear.

Example

/// Twist cylinder with 12 sides and 20 segments.
const shape = PD.Shape.cylinder(12, 2000, 5000, 10);
shape.twistByAxis(2, 0.1, 0.95, Math.PI / 4, PD.Easing.inOutSine);
CAD.add(shape);

const frame = PD.Shape.frame(shape, 25, 50);
CAD.add(frame);

Example

const shape = PD.Shape.dome(8, 6, 4000);
shape.extrudeBase(5000, 5).triakis(0, -100);
shape.twistByAxis(2, -5000, 4000, Math.PI / 3, PD.Easing.inOutSine);
CAD.add(shape);

const frame = PD.Shape.frame(shape).expand().join().join();
CAD.add(frame);

polyhedron.align([alignX], [alignY], [alignZ], [point]) ⇒ Shape

Moves this shape to align it in each axis with the given point.

The axial alignment values are given as fractions of the shape’s extents in that axis. A value of zero in any axis means that the shape will align centrally at the point. A value of 1 means that shape will align its minimum edge at the point, and a value of -1 means that it will align its maximum edge. You can use any fractional values (eg: 0.5) or even multiples (eg: 2.5) in any axis.

Kind: instance method of Polyhedron Overrides: align
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[alignX]numberThe X axis alignment factor (-1 to 1), defaults to 0.
[alignY]numberThe Y axis alignment factor (-1 to 1), defaults to alignX.
[alignZ]numberThe Z axis alignment factor (-1 to 1), defaults to alignX.
[point]Array.<number>An [x,y,z] vector array for the point to align with, defaults to origin [0,0,0].

Example

const box = PD.Shape.cuboid(3000, 2000, 1000);
CAD.add(box.align(1, 1, 1));

polyhedron.setSize([sizeX], [sizeY], [sizeZ]) ⇒ Shape

Rescales all vertices so that the dimensions of the shape’s bounding box in each of the X, Y and Z axis is as given.

This method differs from setRadius in that it is based on the bounding box (extents) of the shape rather than the distance of vertices from its centre.

Kind: instance method of Polyhedron Overrides: setSize
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[sizeX]numberThe width of the shape in the X-axis, defaults to 1.
[sizeY]numberThe depth of the shape in the Y-axis, defaults to width.
[sizeZ]numberThe height of the shape in the X-axis, defaults to width.

Example

const super_shape = PD.Shape.superFormula();
super_shape.setSize(5000, 5000, 3500);
CAD.add(super_shape);

polyhedron.setRadius([radius]) ⇒ Shape

Rescales all vertices so that the maximum radius of the shape from the origin in all axis is equal to the given radius.

If you want to set the size based on the actual extents of the shape, use the setRadius method instead.

NOTE: This method assumes that the shape is centred at the origin.

Kind: instance method of Polyhedron Overrides: setRadius
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[radius]numberThe radius to normalise shape to, defaults to 1.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(PD.Shape.bevel(poly).setRadius(3440));
CAD.add(poly);

polyhedron.setRadiusXY([radius], [height]) ⇒ Shape

Rescales all vertices so that the maximum radius of the shape in the X and Y axis is equal to the given radius.

If you provide the optional height argument, the height of the shape in the Z axis will be normalised to that too,

NOTE: This method assumes that the shape is centred at the origin.

Kind: instance method of Polyhedron Overrides: setRadiusXY
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[radius]numberThe radius to normalise shape to, defaults to 1.
[height]numberThe height to normalise shape to, defaults to 1.

Example

const super_shape = PD.Shape.superFormula();
super_shape.setHeight(2500).setRadiusXY(3500);
CAD.add(super_shape);

polyhedron.setHeight([height]) ⇒ Shape

Rescales all vertices so that the maximum range of the shape in the Z axis is equal to the given height.

NOTE: This method assumes that the shape is centred at the origin.

Kind: instance method of Polyhedron Overrides: setHeight
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[height]numberThe height to normalise shape to, defaults to 1.

Example

const super_shape = PD.Shape.superFormula();
super_shape.setHeight(2500).setRadiusXY(3500);
CAD.add(super_shape);

polyhedron.setColor(color) ⇒ Shape

Assigns a single color to all faces of the shape.

This method is a convenience method for setting the colors array to a single color value.

NOTE: This method overwrites any existing data in the colors array.

Kind: instance method of Polyhedron Overrides: setColor
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
colorArray.<number>The color to assign all faces, as an [r,g,b] array.

polyhedron.reverse() ⇒ Shape

Reverses the orientation of all faces in the shape.

Kind: instance method of Polyhedron Overrides: reverse
Returns: Shape - Returns this shape to support method chaining.

polyhedron.weld([decimals]) ⇒ Shape

Iterates the shape to merge vertices that share the same positions and ensure that adjacent edges share the same vertices.

This also ensures that all faces are oriented outwards relative to the geometric centre of the shape.

Kind: instance method of Polyhedron Overrides: weld
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
[decimals]numberThe number of decimal places when comparing millimeter coordinates, defaults to 1 (0.1mm).

Example

const config = {
    params: [ 1, 4, 0, 0, 0, 0, 2, -3 ],
    innerRadius: 0.5,
    unfoldZ: 0.75
};

const half_shape = PD.Shape.sphericalHarmonics(config).scale(400);
half_shape.cutAt(0, 1).cutAt(4500, -1).weld().join().expand();
CAD.add(half_shape);

polyhedron.ensureOutwardOrientation() ⇒ Shape

Iterates the shape to ensure that all faces are oriented outwards relative to the geometric centre of the shape.

A face normal is considered to be pointing inwards if the dot product of its vector towards the centroid is positive, in which case the face is reversed.

Kind: instance method of Polyhedron Overrides: ensureOutwardOrientation
Returns: Shape - Returns this shape to support method chaining.

polyhedron.ensureOutwardOrientation_MoreRobust() ⇒ Shape

Iterates the shape to ensure that all faces are oriented outwards by referencing a known good face.

This method uses a reference face as a reference and compares all other to it. The reference face is determined as the one with a centre point at the most extreme edge in one of the major cartesian axis. To be facing ‘outwards’, the normal of the most extreme face in must point in the same direction as that axis. Once this condition is met, all other faces can be oriented relative to that one.

Kind: instance method of Polyhedron Overrides: ensureOutwardOrientation_MoreRobust
Returns: Shape - Returns this shape to support method chaining.

polyhedron.applyMatrix(matrix) ⇒ Shape

Applies a transformation matrix to this shape.

Kind: instance method of Polyhedron Overrides: applyMatrix
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
matrixArray.<number>The 16-item (4x4) column-major matrix to apply.

polyhedron.applyQuaternion(quaternion) ⇒ Shape

Applies a rotational quaternion to this shape.

Kind: instance method of Polyhedron Overrides: applyQuaternion
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
quaternionArray.<number>The [x,y,z,w] quaternion to apply.

polyhedron.applyAxis(axis) ⇒ Shape

Aligns this shape with the local coordinate axis.

Kind: instance method of Polyhedron Overrides: applyAxis
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
axisAxisArrayThe local coordinate axis to apply.

Example

const segments = 12;

/// Create base shape to work on.
const cyl = PD.Shape.cylinder(segments, 1000, 500);

/// Create local coordinates.
const axis = new PD.AxisArray();
axis.moveOrigin(0, 2000, 0);
axis.rotateZ(Math.PI / 4);
cyl.applyAxis(axis);

/// Create different positive/negative scales.
const scale_positive = [3.50, 1.5, 1.0];
const scale_negative = [1.25, 1.5, 1.0];

/// Extract the bottom ring of vertices.
const base = cyl.vertices.slice(0, segments);

/// Apply both scales about the origin.
axis.scalePoints(base, scale_positive, scale_negative);
CAD.add(cyl);

polyhedron.inflate(distance, [checkPlanes]) ⇒ Shape

Expand all vertices in the direction of their surface normals by the given distance.

Expansion is different from offsetting in that the given distance refers to the movement of each vertex rather than to each face. Vertices move in the direction of their average surface normals, which is effectively the normalised sum of each face normal that the vertex is shared by. Movement is outwards if the distance is positive or inwards if it is negative.

The result is a set of vertices that are exactly the given distance away from their original positions. Depending on the number of faces shared by each vertex, and their relative orientations, this may result in faces changing orientation slightly and not being parallel to their original position. In some rare cases it may even result in faces that are no longer planar.

If you want to specify the exact perturbation distance of faces rather than vertices use the offset method instead.

Kind: instance method of Polyhedron Overrides: inflate
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
distancenumberThe expansion distance, defaults to 0.
[checkPlanes]numberExtra checks (0:None, 1:OnePlane, 2:AllPlanes), defaults to 0.

Example

const shape = PD.Shape.prism(9, 1500, 1000).ortho();
CAD.add(shape.clone().inflate(200));
CAD.add(shape);

polyhedron.offset(distance, [detail]) ⇒ Shape

Modifies the shape by expanding all facets in the direction of their surface normals by the given distance, but maintaining their exact shape and surface area.

This process moves existing faces outwards and adds additional faces to cover the now open gaps and seams between them. The benefit of this method is that you can offset any convex shape by any positive amount, even many thousands of times its radius, and still have a valid shape shape.

Unfortunately this isn’t true of concave shapes or when the distance value is negative. In these cases, maintaining the shape and area of facets isn’t possible as they simply have to shrink in order to fit. As a result, this method will redirect to the expand method when the given distance is less than zero.

Kind: instance method of Polyhedron Overrides: offset
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
distancenumberThe explosion distance as a positive value, defaults to 0 (no change).
[detail]numberThe geometric detail at each corner (0 to 2), defaults to 2.

polyhedron.offsetHull(distance, [detail]) ⇒ Shape

Modifies the shape by generating a convex hull offsetting all vertices, edges and facets by their surface normals, but maintaining the exact shape and surface area of each facet.

This process modifies this shape by creating new vertex positions for all faces, but they will be the same size and orientation, just offset by the given distance. It also adds additional vertices and faces to fill in the seams and gaps between the exploded faces.

Kind: instance method of Polyhedron Overrides: offsetHull
Returns: Shape - Returns this modified shape.

ParamTypeDescription
distancenumberThe explosion distance, defaults to 0.
[detail]numberThe geometric detail at each corner (0 to 32), defaults to 1.

polyhedron.cutAt(plane, [keep], [cutFaces]) ⇒ Shape

Cuts the faces of this shape by the given plane and either keeps all of them or just those in the front or behind.

Defining a Plane

This method uses an infinite plane to cut the shape, defined by an [a,b,c,d] plane array based on the Ax + Bx + Cz + D = 0 equation for a 3D plane. This means providing an array with four numbers that define the A, B, C and D components of the equation.

Alternatively, if you just want to cut a shape with a horizontal plane, you can pass a single number rather than a plane array. This number is used as the height on the Z axis of a cutting plane that faces towards the +Z axis.

The first three values in the plane array define its normal direction, which also defines the front and rear sides of the plane. Anything on the same side as the normal is pointing is in front, and anything on the other side is behind.

To make this method easier to use, the directional component of any given plane array does not need to be normalised as this will be done automatically. Thus, you could provide a plane array such as [ 1, 1, 1, -500 ] and it will be automatically normalized to [ 0.5773503, 0.5773503, 0.5773503, -500 ].

NOTE: When providing just a single number instead of a plane, it is important to remember that the number represents the plane height rather than the D component. Thus, a numeric value of 250 is equivalent to specifying [0,0,1,-250] as the plane array.

Which Side

You can choose to retain faces on both sides of the cut, or just those in front of or behind the cutting plane. To do this, set the value of keep to a positive number (usually 1) for faces in front of the plane, a negative number (usually -1) for faces behind the plane, or exactly zero (0) to keep both sides.

Accessing Cut Faces

If the value of keep is not zero, faces will be added to ‘fill in’ any openings created in the shape by the cut. If you set the value of cutFaces to an existing array, the new faces will be added to this array instead of directly to the shape. These faces will still reference vertices within the shape (which are shared by the existing faces that were actually cut), but this allows you an opportunity to discard or post-process them before adding them to the shape.

One action that is regularly performed on shapes is to do a cut and then extrude the ‘fill in’ faces in the opposite direction to create a base. As a result, this method provides a shortcut for for you to do this as part of the cutting process by passing a numeric value for cutFaces instead of an array. This numeric value must be positive, as shown in the second example below.

Kind: instance method of Polyhedron Overrides: cutAt
Returns: Shape - Returns this shape to support method chaining.

ParamTypeDescription
planeArray.<number> | numberAn [a,b,c,d] plane array to cut the shape at or a height value in the +Z axis.
[keep]numberWhich side(s) of the plane to retain (0:Both, 1:Front, -1:Rear), defaults to 0 (both).
[cutFaces]Array | numberAn optional array in which to store any newly added cut faces. If given as a positive number instead of an array, it gives a distance by which to create a base by extruding cut surfaces in the opposite direction of the cutting plane.

Example

const cut_faces = [];
const cut_plane = [ 0, 0, 1, 0 ];
const dome_with_holes = new PD.Polyhedron('D12:jh(0.15,0.025)ajejS9000');
dome_with_holes.cutAt(cut_plane, 1);
CAD.add(dome_with_holes);

Example

/// Extrude cut faces to form support columns.
const cut_faces = [];
const cut_plane = [ 0, 0, 1, 0 ];
const poly = new PD.Polyhedron('D8:jeh(0.15,0.025)ajS9000');
const dome_with_holes = PD.Shape.cutAt(poly, cut_plane, 1, cut_faces).translate([ 0, 0, 3000 ]);
for (const face of cut_faces) {
    dome_with_holes.faceExtrude(face, -3000, cut_plane, 3);
}
CAD.add(dome_with_holes);

polyhedron.extrudeBase(height, [segments]) ⇒ Shape

Searches for the bottom-most face whose normal points in the -Z direction and extrudes it downwards by the given distance (height) and in the given number of segments.

Kind: instance method of Polyhedron Overrides: extrudeBase
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
heightnumberThe height of the base to add to the shape, in model units.
[segments]numberThe number of segments to extrude the base in, defaults to 1.

polyhedron.ambo([offset]) ⇒ Shape

The Conway ambo operation is essentially the truncation of a shape by marking the midpoints of all its edges and cutting its vertices at those points.

The best way to think of the ambo operator is as a topological ’tween’ between a polyhedron and its dual polyhedron. Thus the ambo of a dual polyhedron is the same as the ambo of the original.

Kind: instance method of Polyhedron Overrides: ambo
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[offset]numberThe distance of the pyramid apex away from the face center in model units, defaults to 0.

Example

/// Cupola-based space frame.
const poly = PD.Shape.cupola(9).scale(6000);
poly.ambo().ambo().triakis(9, 2000).join();
poly.translate([ 0, 0, -1800 ]).scale([ 1, 1, 2 ]).cutAt(0, 1);
const frame = PD.Shape.frame(poly, 250, 150);
CAD.add(frame);

polyhedron.dual() ⇒ Shape

The Conway dual operation creates a new shape in which the centroid of each face in the original shape becomes a new vertex in the dual, and each vertex in the original becomes the centroid of a new face.

Kind: instance method of Polyhedron Overrides: dual
Returns: Shape - Returns this modified shape to support method chaining. Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(poly.dual());

polyhedron.snub() ⇒ Shape

The Conway snub operation creates a new shape which is basically a gyro operation performed on the dual of the shape. It creates a new face for each vertex, which is then twisted slightly and two new triangular faces added to replace each edges and fill the gaps.

Kind: instance method of Polyhedron Overrides: snub
Returns: Shape - Returns this modified shape to support method chaining. Example

const shape = new PD.Polyhedron('D12:S5000');
CAD.add(shape.clone().snub().scale(1.2835));
CAD.add(shape);

polyhedron.triakis([sides], [offset]) ⇒ Shape

The Conway triakis operation divides specified faces into triangles to form a pyramid with its apex at the center of the face.

If the sides argument is less than 3, all faces in the shape will be divided. If 3 or more, only those faces with a matching number of sides will be divided.

If an offset value is given, then the apex of the pyramid will be positioned that far away from the geometric centre of the face in the direction of its surface normal.

This method differs from the Conway Polyhedron Notation version in that the offset distance is given in model units rather than as a fraction of shape radius.

Kind: instance method of Polyhedron Overrides: triakis
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]Array.<number> | numberAn array or face indexes or the number of sides a face must have to be affected, defaults to 0.
[offset]numberThe distance of the pyramid apex away from the face center in model units, defaults to 0.

Example

/// Cupola-based space frame.
const poly = PD.Shape.cupola(9).scale(12000);
poly.join().expand().triakis(9, 2000).join();
poly.translate([ 0, 0, -6700 ]).scale([ 1, 1, 3 ]).cutAt(0, 1);
const frame = PD.Shape.frame(poly, 250, 150);
CAD.add(frame);

polyhedron.bevel([sides]) ⇒ Shape

The Conway bevel operation truncates the shape at its edges and vertices, creating a new facet in place of each edge and of each vertex.

If the sides argument is less than 3, all faces in the shape will be bevelled. If 3 or more, only those faces with a matching number of sides will be bevelled.

Kind: instance method of Polyhedron Overrides: bevel
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.

Example

const poly = new PD.Polyhedron('D12:S4000');
CAD.add(poly.clone().bevel().setRadius(3440));
CAD.add(poly);

polyhedron.gyro([offset], [fraction]) ⇒ Shape

The Conway gyro operation creates a new shape in which a new face is created at each vertex of its dual, which is then twisted slightly and two new triangular faces added to replace each edges and fill the gaps.

NOTE: When using an offset value not equal to zero, this operation will often create non-planar faces. If that is detected, then the resulting faces will be automatically triangulated.

Kind: instance method of Polyhedron Overrides: gyro
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[offset]numberThe distance of the center apex away from the face center in model units, defaults to 0.
[fraction]numberThe face rotation fraction (0.001 to 0.999), defaults to 1/3.

Example

const shape = PD.Shape.cuboid();
shape.gyro().triangulate().scale(5000);
CAD.add(shape);

polyhedron.propellor([fraction]) ⇒ Shape

The Conway propellor extended operation creates new skewed faces by making new points along each edge, 1/3rd the distance from v1- > v2, then connecting these into a new inset face. This breaks any rotational symmetry about the faces.

Kind: instance method of Polyhedron Overrides: propellor
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[fraction]numberThe face rotation fraction (0.001 to 0.999), defaults to 1/3.

Example

const shape = PD.Shape.anticupola(9).scale(9000);
shape.propellor();
CAD.add(shape);

polyhedron.expand() ⇒ Shape

The Conway expand operation is basically a double ambo operation, which is the truncation of a shape by marking the midpoints of all its edges and cutting its vertices at those points.

Kind: instance method of Polyhedron Overrides: expand
Returns: Shape - Returns this shape to support method chaining. Example

/// Cupola-based space frame.
const poly = PD.Shape.anticupola(9).scale(9000);
poly.triakis(9, 2000).expand().join();
poly.translate([ 0, 0, -6700 ]).scale([ 1, 1, 3 ]).cutAt(0, 1);
const frame = PD.Shape.frame(poly, 250, 150);
CAD.add(frame);

polyhedron.join() ⇒ Shape

The Conway join operation is basically an ambo operation performed on the dual of the original shape, then converted back to a dual.

Kind: instance method of Polyhedron Overrides: join
Returns: Shape - Returns this modified shape to support method chaining. Example

/// Cupola-based space frame.
const poly = PD.Shape.cupola(9).scale(12000);
poly.join().expand().triakis(9, 2000).join();
poly.translate([ 0, 0, -6700 ]).scale([ 1, 1, 3 ]).cutAt(0, 1);
const frame = PD.Shape.frame(poly, 250, 150);
CAD.add(frame);

polyhedron.meta([sides]) ⇒ Shape

The Conway meta operation is basically the join of a triakis operation.

If the sides argument is less than 3, all faces in the shape will be bevelled. If 3 or more, only those faces with a matching number of sides will be bevelled.

Kind: instance method of Polyhedron Overrides: meta
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.

polyhedron.ortho() ⇒ Shape

The Conway ortho operation is effectively a double join operation.

Kind: instance method of Polyhedron Overrides: ortho
Returns: Shape - Returns this modified shape to support method chaining.

polyhedron.truncate([sides]) ⇒ Shape

The Conway truncate operation is a triakis operation performed of the dual of the original shape, then converted back to a dual.

If the sides argument is less than 3, all faces in the shape will be bevelled. If 3 or more, only those faces with a matching number of sides will be bevelled.

Kind: instance method of Polyhedron Overrides: truncate
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.

polyhedron.loft([sides], [inset], [offset]) ⇒ Shape

The loft operation insets each edge of the specified faces and creates new quad faces to fill the gap.

If the sides argument is less than 3, all faces in the shape will be lofted. If 3 or more, only those faces with a matching number of sides will be lofted.

If an inset value is given, then the apex of the pyramid will be positioned that far away from the geometric centre of the face in the direction of its surface normal.

This method differs from the Conway Polyhedron Notation version in that the inset and offset distances are given in model units rather than as a fraction of shape radius.

Kind: instance method of Polyhedron Overrides: loft
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.
[inset]numberAn inset distance from each edge in model units, defaults to 0 (no inset).
[offset]numberAn optional distance from face surface in model units, defaults to 0 (no offset).

polyhedron.triangulate([sides]) ⇒ Shape

The triangulate operation divides specified faces into a triangular fan centered at the first vertex.

If the sides argument is less than 3, all faces in the shape will be divided. If 3 or more, only those faces with a matching number of sides will be divided.

To produce a useable result, this method requires that each face be convex in shape as dividing a concave face this way will result in overlapping triangular faces.

Kind: instance method of Polyhedron Overrides: triangulate
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[sides]numberThe number of sides as face must have to be affected, defaults to 0.

polyhedron.perlinNoise([amplitude], [scale], [offset]) ⇒ Shape

The Perlin noise operation applies some spatial variation to each vertex in the shape based on the amplitude, scale and offset values.

The amplitude, scale and offset values are all applied to the Perlin noise function when it is run for each vertex. You can specify the scale and offset as either [x,y,z] vector arrays to control the variation in each axis, or as single numbers which will be applied equally to all axis.

This method differs from the Conway Polyhedron Notation version in that the amplitude, scale and offset distances are all given in model units rather than as a fraction of shape radius.

To have a noticeable effect, the amplitude and scale values cannot be too small relative to the shape size, so you will typically need to experiment a bit with this.

Kind: instance method of Polyhedron Overrides: perlinNoise
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[amplitude]numberEffectively the magnitude of the spatial variation in model units, defaults to 250mm.
[scale]number | Array.<number>A scale factor or [sx,sy,sz] vector array in model units, defaults to 1000mm (1m).
[offset]number | Array.<number>A phase offset as a number or [dx,dy,dz] vector array in model units, defaults to 0 (no offset).

Example

const shape = PD.Shape.cylinder(72, 2000, 5000, 36);
shape.perlinNoise(5000, 3000, 5000).setRadiusXY(6000);
CAD.add(shape);

polyhedron.noiseXY([amplitude], [scale], [offset]) ⇒ Shape

The noiseXY operation applies some X and Y axis spatial variation to each vertex in the shape based on the amplitude, scale and offset values.

The amplitude, scale and offset values are all applied to the Perlin noise function when it is run for each vertex. You can specify the scale and offset as either [x,y,z] vector arrays to control the variation in each axis, or as single numbers which will be applied equally to all axis.

This method differs from the Conway Polyhedron Notation version in that the amplitude, scale and offset distances are all given in model units rather than as a fraction of shape radius.

To have a noticeable effect, the amplitude and scale values cannot be too small relative to the shape size, so you will typically need to experiment a bit with this.

Kind: instance method of Polyhedron Overrides: noiseXY
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[amplitude]numberEffectively the magnitude of the spatial variation in model units, defaults to 250mm.
[scale]number | Array.<number>A scale factor or [sx,sy,sz] vector array in model units, defaults to 1000mm (1m).
[offset]number | Array.<number>A phase offset as a number or [dx,dy,dz] vector array in model units, defaults to 0 (no offset).

Example

const shape = PD.Shape.cylinder(72, 2000, 5000, 36);
shape.noiseXY(5000, 3000, 5000).setRadiusXY(6000);
CAD.add(shape);

polyhedron.frame([inset], [thickness], [glazing]) ⇒ Shape

The frame operation essentially hollows out the shape and generates a structural frame with bars running along each of its edges.

Kind: instance method of Polyhedron Overrides: frame
Returns: Shape - Returns this modified shape to support method chaining.

ParamTypeDescription
[inset]numberThe inset width of framing bars, defaults to 25mm.
[thickness]numberThe framing bar thickness as a positive value, defaults to 50mm.
[glazing]booleanWhether or not to generate glazing panes between frames.

Example

/// Cupola-based space frame.
const shape = PD.Shape.anticupola(9).scale(9000);
shape.scale([1, 1, 3]).triakis(9, 2000).expand().join();
shape.translate([0, 0, -7500]).cutAt(0, 1);
shape.frame(250, 150);
CAD.add(shape);

Polyhedron.cancelProgress : boolean

A flag to cancel any current computation.

Kind: static property of Polyhedron

Polyhedron.updateProgress : function

An assignable callback method for updating progress.

Kind: static property of Polyhedron

Polyhedron.finalScale : Array.<number>

Stores a global [sx,sy,sz] scale vector set by the scale() modifier and applied only once all other modifiers have been processed.

Kind: static property of Polyhedron

Polyhedron.maintainUnitRadius : boolean

Whether or not polyhedron processing should rescale to a unit radius after modifiers have been applied.

Some polyhedron modifiers work on the assumption that the shape is close to a unit sphere, and apply their factors based on that. You will quickly work out which ones they are as you apply them.

Set this to true if you want to apply those modifiers that work with a world-scale shape and not have it scaled in the process.

Kind: static property of Polyhedron

Polyhedron.colorMethod : string

Stores the current face color method.

Options are: ‘area’, ’edges’, ‘signature’, ’none’.

Kind: static property of Polyhedron

Polyhedron.colorSensitivity : number

Stores the color sensitivity to variation in congruence signature or planar area.

Kind: static property of Polyhedron

Polyhedron.modifierKey : number

Stores the current unique modifier key used to identify modifier objects in lists.

Kind: static property of Polyhedron

Polyhedron.POLYHEDRA_TYPES : object

Shortcuts for known polyhedra types.

Kind: static property of Polyhedron

Polyhedron.POLYHEDRA_NAMES : Array.<Array.<string>>

Stores the names and type abbreviations for each type of known polyhedra and Johnson solids.

These include the five Platonic solids (0 to 4), the twelve Archimedean solids (5 to 17), Prisms (18 to 25), Antiprisms (26 to 33) and Johnson solids (34 to 126).

Each item in the list is a [name,type] array, where the name entry is a string containing the full name of the polyhedra and the type is a short string containing the code for that polyhedra that can be used with the fromType static method.

Kind: static property of Polyhedron

Polyhedron.modifierLog : Array.<string>

Stores a log of app;lied modifier descriptions.

Kind: static property of Polyhedron

Polyhedron.newInstance([vertices], [faces], [name]) ⇒ Shape

This is used to allow subclasses to create instance of their own class when using static generators.

Kind: static method of Polyhedron
Returns: Shape - Returns a new polyhedron.

ParamTypeDescription
[vertices]Array.<Array.<number>>An array of [x,y,z] vertex coordinates.
[faces]Array.<Array.<number>>An array of face boundary arrays, each containing three or more vertex indices.
[name]stringA human-readable name for the polyhedron.

Polyhedron.tetrahedron() ⇒ Polyhedron

Generates a 4-sided unit tetrahedron.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a new Platonic solid.

Polyhedron.cube() ⇒ Polyhedron

Generates a 6-sided cube.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a new Platonic solid.

Polyhedron.octahedron() ⇒ Polyhedron

Generates a 8-sided unit octahedron.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a new Platonic solid.

Polyhedron.dodecahedron() ⇒ Polyhedron

Generates a 12-sided unit dodecahedron.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a new Platonic solid.

Polyhedron.icosahedron() ⇒ Polyhedron

Generates a 20-sided unit icosahedron.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a new Platonic solid.

Polyhedron.catalanSolid(n) ⇒ Polyhedron

Generates one of the 13 Catalan solid polyhedrons.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a new polyhedron.

ParamTypeDescription
nnumberThe numeric index of the Catalan solid (1 to 13).

Polyhedron.archimedeanSolid(n) ⇒ Polyhedron

Generates one of the 13 Archimedean solid polyhedrons.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a new polyhedron.

ParamTypeDescription
nnumberThe numeric index of the Archimedean solid (1 to 13).

Polyhedron.johnsonSolid(n) ⇒ Polyhedron

Generates one of 92 different Johnson solid polyhedrons.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a new polyhedron.

ParamTypeDescription
nnumberThe numeric index of the Johnson Solid (1 to 92).

Polyhedron.fromData(vertices, faces, name)

Generates a new polyhedron from the given faces and vertices.

Kind: static method of Polyhedron

ParamTypeDescription
verticesArray.<Array.<number>>A flat array of [x,y,z] vertex coordinates.
facesArray.<Array.<number>>An array of face boundary arrays, each containing three or more vertex indices.
namestringA human-readable name for the shape.

Polyhedron.fromType(type, sides)

Generates a new polyhedron of a known type.

The supported types are as follows:

  • ‘T’|‘D4’: Tetrahedron
  • ‘C’|‘D6’: Cube
  • ‘O’|‘D8’: Octahedron
  • ‘D’|‘D12’: Dodecahedron
  • ‘I’|‘D20’: Icosahedron
  • ‘J’: Johnson Solid (1 to 92)
  • ‘L’: Catalan Solid (1 to 13)
  • ‘M’: Archimedean Solid (1 to 13)
  • ‘P’: Prism (number_of_sides)
  • ‘A’: Antiprism (number_of_sides)
  • ‘Y’: Pyramid (number_of_sides)
  • ‘B’: Bipyramid (number_of_sides)
  • ‘R’: Pentagonal Rotunda
  • ‘U’: Cupola (number_of_sides)
  • ‘V’: Anticupola (number_of_sides)
  • ‘G’: Geodesic Dome (subdivisions)
  • ‘F’: Fibonacci Dome (density)

Kind: static method of Polyhedron

ParamTypeDescription
typestringThe type of polyhedron to create, defaults to ‘T’ for a Tetrahedron.
sidesnumberThe number of sides, where appropriate, defaults to 4.

Polyhedron.getSupportedTypes([category]) ⇒ Array.<Array.<string>>

Retrieves a list of the names and type abbreviations for each supported type of polyhedra and Johnson solids.

These include the five Platonic solids (0 to 4), the twelve Archimedean solids (5 to 17), Prisms (18 to 25), Anti-prisms (26 to 33) and Johnson solids (34 to 126).

Each item in the list is a [name,type] array, where the name entry is a string containing the full name of the polyhedra and the type is a short string containing the code for that polyhedra that can be used with the fromType static method.

Kind: static method of Polyhedron
Returns: Array.<Array.<string>> - Returns a list of [name,type] arrays.

ParamTypeDescription
[category]stringAn optional category to restrict the list to (‘platonic’, archimedean’, ‘prism’, ‘antiprism’, ‘johnson’).

Polyhedron.getModifierLog() ⇒ string

Retrieves the modifier event log.

The event log is cleared each time a generator method that takes modifiers is called, so contains only events generated during the previous processing of modifiers.

Kind: static method of Polyhedron
Returns: string - Returns the current event log as a multi-line string,

Polyhedron.cancel()

Requests the cancellation of any current modification or calculation process.

Kind: static method of Polyhedron

Polyhedron.fromModifiers(poly, modifiers) ⇒ Polyhedron

Generates polyhedron from an array of modifier operations.

The method performs all the required calculations synchronously, which can block the main thread of your application for several seconds for long modifier chains. To perform the calculations asynchronously with progress updates, use the applyModifiers method instead.

Each modifier in the list is an object with an op property that is a string defining the operation to be performed and an args property which is an array of any arguments the operation requires.

See the PD.PolyhedronFactory.parseNotation method for details of the supported modifier operations and their arguments.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a modified polyhedra.

ParamTypeDescription
polyPolyhedronThe polyhedron to process.
modifiersArray.<object>A list of modifier operations.

Polyhedron.formatModifier(modifier) ⇒ string

Checks for a valid modifier and formats its arguments to become part of a Conway Polyhedron Notation string.

Kind: static method of Polyhedron
Returns: string - Returns a formatted modifier string.

ParamTypeDescription
modifierobjectAn {op,args} modifier object.

Polyhedron.parseNotation(poly, notation, [modifiers]) ⇒ Array.<object>

Generates a list of modifier operations and their arguments from a Conway polyhedron notation string such as ‘qoh(0.15,0.05)eeuz’.

The supported modifier operations are as follows:

  • ‘a’: ambo()
  • ‘b’: bevel()
  • ‘c’: chamfer(detail, distance)
  • ’d’: dual()
  • ’e’: expand()
  • ‘f’: frame(inset, thickness)
  • ‘g’: gyro()
  • ‘h’: hollow(inset_dist, thickness)
  • ‘i’: inflate(degree)
  • ‘j’: join()
  • ‘k’: triakis(sides, offset)
  • ’l’: loft(sides, inset)
  • ’m’: meta(sides, offset)
  • ’n’: insetN(sides, inset, offset)
  • ‘o’: ortho()
  • ‘p’: propellor()
  • ‘q’: quinto()
  • ‘r’: reflect(axis)
  • ’s’: snub()
  • ’t’: truncate(sides)
  • ‘u’: trisub(divisions)
  • ‘w’: whirl()
  • ‘x’: extrudeN(edge_count, pop_out_distance)
  • ‘z’: triangulate(sides, set_colors),
  • ‘A’: adjustXYZ(iterations),
  • ‘C’: canonicalize(iterations),
  • ‘F’: triangularFan(sides, offset)
  • ‘J’: jitter(seed, radial_fraction, spatial_fraction)
  • ‘N’: noise(amplitude, scale, offset)
  • ‘P’: stellation()
  • ‘R’: rotate(rx, ry, rz)
  • ‘S’: scale(sx, sy, sz)
  • ‘T’: translate(dx, dy, dz)
  • ‘U’: unitRadius(radius)
  • ‘V’: unitSize(size)
  • ‘W’: wrinkle(seed, radial_fraction, spatial_fraction)

As the Polyhedron class supports almost any conceivable polyhedron type, the inclusion of specific polyhedron types within the notation string is not recommended as the seed polygon is almost always supplied to this method by the calling function.

It is still supported, but rather than simply appending it as a capital letter at the end of the notation string, you must include it at the start of the string and separate it from from main notation string with a full colon. For example, you can override the given polyhedron with the string C:kee for a cube or J32:ggd for a particular Johnson solid.

Kind: static method of Polyhedron
Returns: Array.<object> - Returns a list of {op,args} modifiers.

ParamTypeDescription
polyPolyhedronThe polyhedron to process, which may be changed if a type modifier is included.
notationstringA string containing ‘a(n,n)bcd’ modifier operations.
[modifiers]Array.<object>An optional list of modifiers to update and reuse.

Polyhedron.fromNotation(poly, notation) ⇒ Polyhedron

Create polyhedron from a Conway notation string such as ‘qoh(0.15,0.05)eeuz’.

See the parseNotation method for details of the supported modifier operations and their arguments.

Kind: static method of Polyhedron
Returns: Polyhedron - Returns a modified polyhedra.

ParamTypeDescription
polyPolyhedronThe polyhedron to process.
notationstringA string containing ‘a(n,n)bcd9’ modifier operations.

Polyhedron.adjustColorPalette(factor)

Lighten or darken the color palette to suit the color scheme.

Kind: static method of Polyhedron

ParamTypeDescription
factornumberThe fraction to multiply the color pallette by.

PD.VectorArray

A helper class for performing vector math using array-based points, directions, matrices and quaternions.

When using this class, spatial positions, direction vectors and surface normals can be stored as arrays of 3 scalar numeric values in the form [x,y,z]. As some external geometry libraries are based on [x,y,z] arrays, and the fact that GPU and vertex attribute buffers are all eventually just flat arrays, it is sometimes more convenient and efficient to work directly with vector arrays rather than having to constantly convert them to and from {x,y,z} point objects.

Thus, this helper class is intended to allow vector math to be performed directly on vector arrays. The intent is to closely replicate the API of the THREE.Vector3 class, but passing in an initial vector array as the first argument of all methods in order to receive the results, rather than updating this as THREE.js does.

Along with this class, you can use the PlaneArray, MatrixArray, QuaternionArray, AxisArray and VolumeArray classes for a full suit of array-based vector math.

NOTE: Any Float32Array with at least three items in the same [x,y,z] format can also be used entirely interchangeably as both output or input in all vector array methods.

Kind: static class of PD
Author: drajmarsh

VectorArray.ORIGIN : Array.<number>

A useful definition of the global origin ([0,0,0]).

Kind: static property of VectorArray

VectorArray.X_AXIS : Array.<number>

A useful definition of the global X axis ([1,0,0]).

Kind: static property of VectorArray

VectorArray.Y_AXIS : Array.<number>

A useful definition of the global Y axis ([0,1,0]).

Kind: static property of VectorArray

VectorArray.Z_AXIS : Array.<number>

A useful definition of the global Z axis ([0,0,1]).

Kind: static property of VectorArray

VectorArray.create(x, y, z) ⇒ Array.<number>

Creates a new 3D vector array with the given x, y and z components.

This method offers some flexibility in terms of the arguments it accepts. You can provide 3 separate numeric values, an [x,y,z] vector array, a point-like {x,y,z} object or even no arguments at all to create a zero vector.

Kind: static method of VectorArray
Returns: Array.<number> - Returns a new [x,y,z] vector array.

ParamTypeDescription
xnumber | Array.<number>The X-axis component, an [x,y,z] vector array, or zero if not defined.
ynumberThe Y-axis component, or zero if not defined.
znumberThe Z-axis component, or zero if not defined.

VectorArray.validate(out) ⇒ Array.<number>

Ensures that the given vector array is a valid array with numeric x, y and z values in the first three entries.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns a valid [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to validate.

VectorArray.validateAs2D(out, [Z]) ⇒ Array.<number>

Ensures that the given vector array is a valid array with three numeric values, but with the third set to Z.

Use this method when you require a valid 2D point that still has x, y and z entries, but where you need to control the z value.

NOTE: This method changes values within the out parameter, with the first two array items being converted to their numeric values and the third item being replaced with the numeric value of Z.

Kind: static method of VectorArray
Returns: Array.<number> - Returns a valid [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to validate.
[Z]numberThe value to set the third array item, defaults to zero.

VectorArray.set(out, x, y, z) ⇒ Array.<number>

Sets the new values for a vector to the given components.

This method offers some flexibility in terms of the arguments it accepts. You can provide 3 separate numeric values or just a single [x,y,z] vector array, a point-like {x,y,z} object or even no arguments at all to create a zero vector.

If you are setting 3 component values, you can optionally use the setComponents() method instead which is a little faster as it does no type checking. If you definitely know that you have a vector array, then you can use the copy() method or, if a vector object, the copyFromPoint() method.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the resulting out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
xnumberEither the X-axis component, a [x,y,z] vector array, a {x,y,z} vector object, or zero if not defined.
ynumberThe Y-axis component, or zero if not defined.
znumberThe Z-axis component, or zero if not defined.

VectorArray.setScalar(out, scalar) ⇒ Array.<number>

Set the three vector array components to the given scalar value.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
scalarnumberThe number to set each component to.

VectorArray.setX(out, x) ⇒ Array.<number>

Set the X-axis vector array component to the given scalar value.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
xnumberThe new value for the X-axis component.

VectorArray.setY(out, y) ⇒ Array.<number>

Set the Y-axis vector array component to the given scalar value.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
ynumberThe new value for the Y-axis component.

VectorArray.setZ(out, y) ⇒ Array.<number>

Set the Z-axis vector array component to the given scalar value.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
ynumberThe new value for the Z-axis component.

VectorArray.setComponent(out, index, value) ⇒ Array.<number>

Set the vector array component index to the given scalar value.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
indexnumberThe index of the component to set (0 to 2).
valuenumberThe new value for the component index.

VectorArray.getComponent(out, index) ⇒ number

Retrieves the value of the vector array at component index.

Kind: static method of VectorArray
Returns: number - Returns the value at the given component index.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to get results from.
indexnumberThe index of the component to get (0 to 2).

VectorArray.setComponents(out, x, y, z) ⇒ Array.<number>

Sets the vector to the given components.

This method differs from the set() method in that you must provide the 3 components as separate numeric values. It does not perform any type checking, which makes it a bit faster in situations where you can reliably provide separate component values.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the resulting out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
xnumberThe X-axis component, or zero if not defined.
ynumberThe Y-axis component, or zero if not defined.
znumberThe Z-axis component, or zero if not defined.

VectorArray.copy(out, v) ⇒ Array.<number>

Copies the first three components of v to out.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to copy from.

VectorArray.copyFromPoint(out, pnt) ⇒ Array.<number>

Copies the x, y and z components of p1 to out.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
pntobjectThe point-like {x,y,z} object to copy components from.

VectorArray.copyAtOffset(out, v, [offset]) ⇒ Array.<number>

Copies the first three components of v to out with the given offset.

The optional offset argument allows you to copy the three values to a different part of the out array. It defines the index in the output array at which to start copying the three values.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to copy from.
[offset]numberThe array index at which to copy the values, defaults to 0.

VectorArray.clone(out) ⇒ number

Creates a copy of the given vector array.

This method simply returns out.slice() but is included for API compatibility.

Kind: static method of VectorArray
Returns: number - Returns a new copied vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to clone.

VectorArray.add(out, v) ⇒ Array.<number>

Adds the first three components of v to out.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to add.

VectorArray.addScalar(out, scalar) ⇒ Array.<number>

Adds the given scalar value to the 3 components of out.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
scalarnumberThe scalar numeric value to add.

VectorArray.addVectors(out, a, b) ⇒ Array.<number>

Sets out to the addition of the vectors a and b.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
aArray.<number>The first [x,y,z] vector array to add.
bArray.<number>The second [x,y,z] vector array to add.

VectorArray.addScaledVector(out, v, scalar) ⇒ Array.<number>

Add v multiplied by s to the three components of out.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to add.
scalarnumberThe scalar value to multiply v by.

VectorArray.sub(out, v) ⇒ Array.<number>

Subtracts the first three components of v from out.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to subtract.

VectorArray.subScalar(out, scalar) ⇒ Array.<number>

Subtracts the given scalar value from the 3 components of out.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
scalarnumberThe scalar numeric value to subtract.

VectorArray.subVectors(out, a, b) ⇒ Array.<number>

Sets out to the subtraction of the vectors a and b.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
aArray.<number>The [x,y,z] vector array to subtract from.
bArray.<number>The [x,y,z] vector array to subtract.

VectorArray.multiply(out, v) ⇒ Array.<number>

Multiplies the components of out by v.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to multiply by.

VectorArray.multiplyScalar(out, scalar) ⇒ Array.<number>

Multiplies the components of out by the given scalar value.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
scalarnumberThe scalar numeric value to multiply by.

VectorArray.multiplyVectors(out, a, b) ⇒ Array.<number>

Sets out to the multiplication of the vectors a and b.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
aArray.<number>The first [x,y,z] vector array to multiply.
bArray.<number>The second [x,y,z] vector array to multiply.

VectorArray.multiplyVectorByScalar(out, v, scalar) ⇒ Array.<number>

Sets out to the multiplication of a vector v and scalar scale.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to be multiplied.
scalarnumberThe scalar numeric value to multiply by.

VectorArray.divide(out, v) ⇒ Array.<number>

Divided the components of out by v.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to divide by.

VectorArray.divideScalar(out, scalar) ⇒ Array.<number>

Divides the components of out by the given scalar value.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
scalarnumberThe scalar numeric value to divide by.

VectorArray.min(out, v) ⇒ Array.<number>

Sets out to the minimum of its components compared to v.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to check minimum values of.

VectorArray.max(out, v) ⇒ Array.<number>

Sets out to the maximum of its component compared to v.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to check maximum values of.

VectorArray.minOf(out, …args) ⇒ Array.<number>

Sets out to the minimum components of each of the given vectors.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
…argsArray.<number>Two or more [x,y,z] vector array to get minimum values of.

VectorArray.maxOf(out, …args) ⇒ Array.<number>

Sets out to the maximum components of each of the given vectors.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
…argsArray.<number>Two or more [x,y,z] vector array to get maximum values of.

VectorArray.clamp(out, min, max) ⇒ Array.<number>

Limits the components of out to be within the given range.

NOTE: This method changes values within the out parameter and assumes that min < max in each component.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
minArray.<number>The [x,y,z] vector array defining the minimum bounds.
maxArray.<number>The [x,y,z] vector array defining the maximum bounds.

VectorArray.clampScalar(out, min, max) ⇒ Array.<number>

Limits each component of out to be within the given range.

NOTE: This method changes values within the out parameter and assumes that minValue < maxValue.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
minnumberThe minimum bounds value.
maxnumberThe maximum bounds value.

VectorArray.clampLength(out, min, max) ⇒ Array.<number>

Limits the length of out to be within the given range.

NOTE: This method changes values within the out parameter and assumes that minValue < maxValue.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to limit.
minnumberThe minimum length value.
maxnumberThe maximum length value.

VectorArray.floor(out) ⇒ Array.<number>

Converts each component of out to an integer using Math.floor().

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to be converted.

VectorArray.ceil(out) ⇒ Array.<number>

Converts each component of out to an integer using Math.ceil().

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to be converted.

VectorArray.round(out) ⇒ Array.<number>

Rounds each component of out to an integer using Math.round().

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to be rounded.

VectorArray.roundToZero(out) ⇒ Array.<number>

Rounds each component of out to an integer towards zero (up if negative, down if positive).

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to be rounded.

VectorArray.negate(out, [v]) ⇒ Array.<number>

Reverses the sign of each component of a vector array.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as v or simply give one argument to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out 3D vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
[v]Array.<number>The [x,y,z] vector array to negate, set to out if not supplied.

VectorArray.applyMatrix3(out, mtx) ⇒ Array.<number>

Multiplies out by the given 3x3 column-major matrix m.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
mtxArray.<number>The 3x3 matrix array to multiply out by.

VectorArray.applyMatrix4(out, mtx) ⇒ Array.<number>

Multiplies out by the given 4x4 column-major matrix m.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
mtxArray.<number>The 4x4 matrix array to multiply out by, based on THREE.matrix4#elements.

VectorArray.applyQuaternion(out, qut) ⇒ Array.<number>

Multiplies out by the [x,y,z,w] quaternion q.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
qutArray.<number>The [x,y,z,w] quaternion array to multiply out by.

VectorArray.lengthSq(v) ⇒ number

Computes the square of the magnitude of the given vector.

Kind: static method of VectorArray
Returns: number - Returns the square of the vector length.

ParamTypeDescription
vArray.<number>The [x,y,z] vector array to compute.

VectorArray.length(v) ⇒ number

Computes the magnitude of the given vector.

Kind: static method of VectorArray
Returns: number - Returns the vector length.

ParamTypeDescription
vArray.<number>The [x,y,z] vector array to compute.

VectorArray.manhattanLength(v) ⇒ number

Computes the Manhattan length of the given.

Kind: static method of VectorArray
Returns: number - Returns the Manhattan distance.

ParamTypeDescription
vArray.<number>The [x,y,z] vector array to compute.

VectorArray.normalize(out, [v]) ⇒ Array.<number>

Resizes a vector array to unit length (len == 1.0).

NOTE: This method changes values within the out parameter, however it is safe to use the same array as v or simply give one argument to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
[v]Array.<number>The [x,y,z] vector array to normalize, set to out if not supplied.

VectorArray.setLength(out, length) ⇒ Array.<number>

Sets a new magnitude for the out vector.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to set.
lengthnumberThe new magnitude of the vector array.

VectorArray.lerp(out, v, t) ⇒ Array.<number>

Linearly interpolates along the vector’s length.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as v to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the resulting out vector.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the calculated result.
vArray.<number>The [x,y,z] vector array to interpolate.
tnumberThe fractional value along the vector (0 to 1).

VectorArray.lerpVectors(out, v1, v2, t) ⇒ Array.<number>

Linearly interpolates between two 3D positions.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as v1 or v2 to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the resulting out vector.

ParamTypeDescription
outArray.<number>The [x,y,z] coordinate array to receive the calculated result.
v1Array.<number>The first [x,y,z] coordinate array.
v2Array.<number>The second [x,y,z] coordinate array.
tnumberThe fractional value between the two positions ( 0 to 1).

VectorArray.slerpVectors(out, v1, v2, t) ⇒ Array.<number>

Spherical linear interpolation between two 3D positions.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as v1 or v2 to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the resulting out vector.

ParamTypeDescription
outArray.<number>The [x,y,z] coordinate array to receive the calculated result.
v1Array.<number>The first [x,y,z] coordinate array.
v2Array.<number>The second [x,y,z] coordinate array.
tnumberThe fractional value between the two positions ( 0 to 1).

VectorArray.dot(v1, v2) ⇒ number

Calculates the dot product of two vector arrays.

Kind: static method of VectorArray
Returns: number - Returns the dot product of the two vectors.

ParamTypeDescription
v1Array.<number>The first [x,y,z] vector array.
v2Array.<number>The second [x,y,z] vector array.

VectorArray.cross(out, v) ⇒ Array.<number>

Crosses out with v and copies the result to out.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
vArray.<number>The [x,y,z] vector array to cross out with.

VectorArray.crossVectors(out, v1, v2) ⇒ Array.<number>

Sets out to the cross product of two 3D vector arrays.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as a or b.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
v1Array.<number>The first [x,y,z] vector array.
v2Array.<number>The second [x,y,z] vector array.

VectorArray.angleTo(v1, v2) ⇒ number

Calculates the angle between the given vector arrays, in radians.

Kind: static method of VectorArray
Returns: number - Returns the angle between vector array, in radians.

ParamTypeDescription
v1Array.<number>The first [x,y,z] vector array to calculate angle from.
v2Array.<number>The second [x,y,z] vector array to calculate angle to.

VectorArray.distanceTo(p1, p2) ⇒ number

Calculate the distance between the two given coordinates.

Kind: static method of VectorArray
Returns: number - Returns the distance between the coordinates, in model units.

ParamTypeDescription
p1Array.<number>The first [x,y,z] coordinate array.
p2Array.<number>The second [x,y,z] coordinate array.

VectorArray.distanceToSquared(p1, p2) ⇒ number

Calculate the squared distance between the two given coordinates.

Kind: static method of VectorArray
Returns: number - Returns the squared distance.

ParamTypeDescription
p1Array.<number>The first [x,y,z] coordinate array.
p2Array.<number>The second [x,y,z] coordinate array.

VectorArray.manhattanDistanceTo(p1, p2) ⇒ number

Computes the Manhattan distance between the two coordinates.

Kind: static method of VectorArray
Returns: number - Returns the Manhattan distance.

ParamTypeDescription
p1Array.<number>The first [x,y,z] coordinate array.
p2Array.<number>The second [x,y,z] coordinate array.

VectorArray.equals(v1, v2) ⇒ boolean

Determines if the two vector arrays have exactly the same values.

This method checks each of the X, Y and Z axis components to see if they are exactly equal (using the === operator). If you want to use some tolerance range, use the closeTo or manhattanDistanceTo methods instead.

Kind: static method of VectorArray
Returns: boolean - Returns true if they are the same.

ParamTypeDescription
v1Array.<number>The first [x,y,z] vector array.
v2Array.<number>The second [x,y,z] vector array.

VectorArray.closeTo(v1, v2, [tolerance]) ⇒ boolean

Determines whether each axial component of the two vector arrays are within the given tolerance value of each other.

This method checks the absolute value of the difference between each of the first three array items to determine if they are not greater than the given tolerance. If any are greater, it returns false. If none are greater, it returns true.

Kind: static method of VectorArray
Returns: boolean - Returns true if all three axis are within tolerance.

ParamTypeDescription
v1Array.<number>The first [x,y,z] vector array.
v2Array.<number>The second [x,y,z] vector array.
[tolerance]numberThe tolerance value to use, defaults to 1e-6.

VectorArray.random(out) ⇒ Array.<number>

Generate a set of random random values between 0 and 1.

This method will set the first three items in the vector array to a decimal value between 0 and 1, representing the representing the X, Y and Z axis components. This method uses Math.random().

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.

VectorArray.randomDirection(out) ⇒ Array.<number>

Sets out to a random normalized direction vector.

This method uses a randomisation method designed to produce better spherical distributions of points. it will set the first three items in the vector array to a decimal value between 0 and 1, representing the X, Y and Z axis components.

This method uses the randomNumber method so you can seed it if you need to generate repeatable number sequences.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.

VectorArray.bezier(out, startPt, ctrlPt1, ctrlPt2, endPt, t) ⇒ Array.<number>

Cubic Bezier interpolation between two 3D positions and governed by two control points.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] coordinate array to receive the calculated result.
startPtArray.<number>The [x,y,z] coordinate array of the curve start point.
ctrlPt1Array.<number>The [x,y,z] coordinate array of the first control point.
ctrlPt2Array.<number>The [x,y,z] coordinate array of the second control point.
endPtArray.<number>The [x,y,z] coordinate array of the curve end point.
tnumberThe fractional value between the two positions ( 0 to 1).

VectorArray.addRandomness(out, factor) ⇒ Array.<number>

Applies the given randomisation factor to the given vector in each axis.

The factor argument determines the maximum amount of variation to apply to each axial component, where variation is taken to mean the difference between the highest and lowest possible random value.

As an example, if you have a point at the position [1000, 12000, 0], and you use a randomisation factor of 100, then the resulting X axis value could vary anywhere from 950 to 1050 (1050 - 950 = 100). Similarly, the Y axis value could vary anywhere from 11950 to 12050, and the Z axis value from -50 to 50.

This method uses the randomNumber method so you can seed it if you need to generate repeatable number sequences.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to modify.
factornumberThe randomisation amount to apply in model units.

VectorArray.randomColor([modifier], [result]) ⇒ Array.<number>

Returns a random color array.

This method will set the first three items in the color array to a decimal value between 0 and 1, representing the red, green and blue components of the color. This method uses Math.random.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the given array or a new array with a random colours assigned.

ParamTypeDescription
[modifier]numberA dark/light modifier value (-0.9 to 0.9).
[result]Array.<number>An optional array to receive the randomised results.

VectorArray.swapAxis(out, axis) ⇒ Array.<number>

Swaps the component values of a point in plane of the given axis.

To swap the Y and Z axis, use 1:PD.AXIS.X_POS or -1:PD.AXIS.X_NEG as the argument. To swap the X and Y axis, use 3:PD.AXIS.Z_POS or -3:PD.AXIS.Z_NEG as the argument. To swap the X and Z axis, use 2:PD.AXIS.Y_POS or -2:PD.AXIS.Y_NEG as the argument. To swap the axis back, simply use the same call with the same axis argument.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to modify.
axisPD.AXISThe axis of the plane to swap components in.

VectorArray.fitExtents(min, max, pt)

Extends the min and max vector arrays to fit the given pt.

NOTE: This method may change values within the min and max parameters.

Kind: static method of VectorArray

ParamTypeDescription
minArray.<number>The [x,y,z] coordinate array defining the minimum bounds.
maxArray.<number>The [x,y,z] coordinate array defining the maximum bounds.
ptArray.<number>The [x,y,z] coordinate array to extend bounds to include.

VectorArray.fitExtentsToSphere(min, max, center, radius)

Extends the min and max vector arrays to fit a sphere.

NOTE: This method may change values within the min and max parameters.

Kind: static method of VectorArray

ParamTypeDescription
minArray.<number>The [x,y,z] coordinate array defining the minimum bounds.
maxArray.<number>The [x,y,z] coordinate array defining the maximum bounds.
centerArray.<number>The [x,y,z] coordinate array of the sphere center.
radiusArray.<number>The radius of the sphere.

VectorArray.fitExtentsToPoints(min, max, points)

Extends the min and max vector arrays to fit all of the given points.

NOTE: This method may change values within the min and max parameters.

Kind: static method of VectorArray

ParamTypeDescription
minArray.<number>The [x,y,z] coordinate array defining the minimum bounds.
maxArray.<number>The [x,y,z] coordinate array defining the maximum bounds.
pointsArray.<Array.<number>>An array of one or more [x,y,z] coordinate arrays to extend bounds to.

VectorArray.scale(out, v, scale) ⇒ Array.<number>

Multiplies each component of a vector by the given scale factor.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as v to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the resulting out vector.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the calculated result.
vArray.<number>The [x,y,z] vector array to scale.
scalenumber | Array.<number>The scale factor to multiply by, or an [sx,sy,sz] vector array.

VectorArray.vectorBetween(out, p1, p2) ⇒ Array.<number>

Calculates the vector between two 3D coordinate arrays.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as p1 of p2 to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the resulting out vector.

ParamTypeDescription
outArray.<number>The [x,y,z] coordinate array to receive the calculated result.
p1Array.<number>The first [x,y,z] coordinate array.
p2Array.<number>The second [x,y,z] coordinate array.

VectorArray.normalizedVectorBetween(out, p1, p2) ⇒ Array.<number>

Computes the direction vector between two points and normalises it to unit length (len := 1.0).

NOTE: This method changes values within the out parameter, however it is safe to use the same array as p1 of p2 to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
p1Array.<number>The [x,y,z] coordinate array of the starting point.
p2Array.<number>The [x,y,z] coordinate array of the ending point.

VectorArray.distanceXY(p1, p2) ⇒ number

Calculate the distance between the two given coordinates in the XY plane only.

Kind: static method of VectorArray
Returns: number - Returns the distance between the coordinates in the XY plane, in model units.

ParamTypeDescription
p1Array.<number>The first [x,y,z] coordinate array.
p2Array.<number>The second [x,y,z] coordinate array.

VectorArray.distanceXZ(p1, p2) ⇒ number

Calculate the distance between the two given coordinates in the XZ plane only.

Kind: static method of VectorArray
Returns: number - Returns the distance between the coordinates in the XZ plane, in model units.

ParamTypeDescription
p1Array.<number>The first [x,y,z] coordinate array.
p2Array.<number>The second [x,y,z] coordinate array.

VectorArray.distanceYZ(p1, p2) ⇒ number

Calculate the distance between the two given coordinates in the YZ plane only.

Kind: static method of VectorArray
Returns: number - Returns the distance between the coordinates in the YZ plane, in model units.

ParamTypeDescription
p1Array.<number>The first [x,y,z] coordinate array.
p2Array.<number>The second [x,y,z] coordinate array.

VectorArray.crossProductFromThreePoints(out, p1, p2, p3) ⇒ Array.<number>

Computes the cross product of the three points of a triangle.

This method first computes the vectors p1->p2 and p1->p3, then uses crossVectors to compute the cross product.

 cross
 product
     +          p2
      ,         +
       ,       /
        ,  /\ /
         \/__/
          \ / \
           +------------------+ p3
         p1

NOTE: This method changes values within the out parameter, but it cannot and must not be the same array as p1, p2 or p3.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the calculated normal.
p1Array.<number>The first triangle vertex, given as a [x,y,z] coordinate array.
p2Array.<number>The second triangle vertex, given as a [x,y,z] coordinate array.
p3Array.<number>The third triangle vertex, given as a [x,y,z] coordinate array.

VectorArray.calcNormalFromThreePoints(out, p1, p2, p3) ⇒ Array.<number>

Computes a normal direction from the three points of a triangle.

This is effectively the normalised cross product of the two vectors between three points.

                p2
                +
    normal     /
        ,  /\ /
         \/__/
          \ / \
           +------------------+ p3
         p1

NOTE: This method changes values within the out parameter, but it cannot and must not be the same array as p1, p2 or p3.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the calculated normal.
p1Array.<number>The first triangle vertex, given as a [x,y,z] coordinate array.
p2Array.<number>The second triangle vertex, given as a [x,y,z] coordinate array.
p3Array.<number>The third triangle vertex, given as a [x,y,z] coordinate array.

VectorArray.calcNormalFromTwoPoints(out, p1, p2) ⇒ Array.<number>

Computes a normal direction for two points forming a line.

This method first computes a suitable third point offset from p2 in one of the major axis based on the vector between the two given points. It then computes the normal from those three points.

  3rd
  point
     +
      ,
       ,     normal
        ,  /\ /
         \/__/
          \ / \
        p1 +------------------+ p2

If the vector between p1->p2 is more horizontal that vertical (abs(v[z]) < 0.5), then the +Z axis is used for the third point. If it is more vertical and its magnitude in the X axis is less than in the Y, then the +Y axis is used for the third point. If its magnitude in the Y axis is less, then the +X axis is used for the third point.

NOTE: This method changes values within the out parameter, but it cannot and must not be the same array as p1, or p2.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the calculated normal.
p1Array.<number>The first triangle vertex, given as a [x,y,z] coordinate array.
p2Array.<number>The second triangle vertex, given as a [x,y,z] coordinate array.

VectorArray.calcNormalFromPath(out, path) ⇒ Array.<number>

Calculates a normal direction from multiple points along a path.

This method assumes that all points on the path are pretty close to co-planar and calculates the normal from the average cross-product of each set of three consecutive non-co-linear vertices. This is a robust way of dealing with paths where the first valid triangle may be concave whilst all the rest are convex.

       normal
           \
     [4]----\-----------[3]
      |  .   \  /\      '  \
      |    .  \/__+   '     \
      |      . \ / \'   _ . [2]
      |        '+---+ '     /
      |      .   '         /
      |   .         '     /
      |.              ' /
     [0]---------------[1]

If the path is invalid or the normal cannot be calculated, it will default to the +Z axis.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] normal vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the calculated normal.
pathArray.<number>An array of [x,y,z] coordinate arrays defining a polyline or polygon.

VectorArray.calcNormalFromPathNewellMethod(out, path) ⇒ Array.<number>

Calculates a normal direction from a sequence of points on a path using Newell’s Method.

Newell’s Method provides a very robust way of computing an ‘average’ normal from points which may vary quite considerably from being coplanar. This make it great for curves or situations where you simply don’t know beforehand their coplanarity.

       normal
           \
     [4]----\-----------[3]
      |      \  /\         \
      |       \/__+         \
      |        \ / \        [2]
      |         +---+       /
      |                    /
      |                   /
      |                  /
     [0]---------------[1]

If the path is invalid or the normal cannot be calculated, it will default to the +Z axis.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] normal vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the calculated normal.
pathArray.<number>An array of [x,y,z] coordinate arrays defining a polyline or polygon.

VectorArray.calcNormalFromIndexedPathNewellMethod(out, indices, vertices) ⇒ Array.<number>

Calculates a normal direction from multiple points along an indexed path using Newell’s Method.

Rather than the path consisting of an array of coordinates, an indexed path consists of an array of indexes into a separate array of vertices.

Newell’s Method provides a very robust way of computing an ‘average’ normal from points which may vary quite considerably from being coplanar. This make it great for curves or situations where you simply don’t know beforehand their coplanarity.

       normal
           \
     [4]----\-----------[3]
      |      \  /\         \
      |       \/__+         \
      |        \ / \        [2]
      |         +---+       /
      |                    /
      |                   /
      |                  /
     [0]---------------[1]

If the path is invalid or the normal cannot be calculated, it will default to the +Z axis.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] normal vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the calculated normal.
indicesArray.<number>An array of ordinal indexes to points within the vertices array.
verticesArray.<Array.<number>>An array of [x,y,z] coordinate arrays.

VectorArray.computeMajorAxis(normal) ⇒ number

Determines the axis of maximum distance (±1:X, ±2:±Y, ±3:±Z).

This method assumes that the given vector is a normalized direction rather than a 3D coordinate.

                  Y
                 +
      Z         /
       +       /
        ,  /\ /
         \/__/___
          \ / \ /
           +------+ X
         p1

Kind: static method of VectorArray
Returns: number - Returns the appropriate axis (±1:X, ±2:±Y, ±3:±Z).

ParamTypeDescription
normalArray.<number>The [x,y,z] direction vector to test.

VectorArray.translateInVectorDirection(out, start, direction, distance) ⇒ Array.<number>

Calculates the position distance from start in the given vector direction.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as start to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] coordinate array to receive the result.
startArray.<number>The [x,y,z] coordinate array to begin from.
directionArray.<number>The normalized [x,y,z] vector array giving the direction of movement.
distancenumberThe scalar distance to move in the vector direction.

VectorArray.distanceInVectorDirection(from, direction, to) ⇒ number

Calculates the relative distance along a given vector given a 3D point.

This method is used when dragging something that is restricted to a given vector. It uses the Pythagorean theorem to determine the distance of the closest point between the given 3D position and the ray.

Kind: static method of VectorArray
Returns: number - Returns the distance along the given vector.

ParamTypeDescription
fromArray.<number>The reference [x,y,z] coordinate array to calculate distance from.
directionArray.<number>The normalised [x,y,z] vector array of the measurement direction.
toArray.<number>The [x,y,z] coordinate array of the position to check.

VectorArray.polarToCartesian(azi, alt) ⇒ Array.<number>

Converts 2D polar coordinates to 3D cartesian coordinates.

Kind: static method of VectorArray
Returns: Array.<number> - Returns a 3D [x,y,z] coordinate array.

ParamTypeDescription
azinumberThe horizontal azimuth angle, in radians anti-clockwise from +X axis.
altnumberThe vertical angle, in radians above the horizontal plane.

VectorArray.polarToStereo(azi, alt) ⇒ Array.<number>

Converts spherical polar coordinates to 2D stereographic coordinates.

Kind: static method of VectorArray
Returns: Array.<number> - Returns a 2D [x,y] coordinate array.

ParamTypeDescription
azinumberThe horizontal azimuth angle, in radians anti-clockwise from +X axis.
altnumberThe vertical angle, in radians above the horizontal plane.

VectorArray.stereoToCartesian(stereo) ⇒ Array.<number>

Converts 2D coordinates to cartesian relative to the center.

Kind: static method of VectorArray
Returns: Array.<number> - Returns an [x,y,z] coordinate array.

ParamTypeDescription
stereoArray.<number>An [azi,alt] polar position array.

VectorArray.toSphericalCoordinates(vec) ⇒ Array.<number>

Calculates the azimuth and altitude angle of a direction vector and returns an [azi,alt] array, in radians.

The azimuth angle is returned in radians CCW from the +X axis, and the altitude angle is in radians above the horizontal.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the spherical angles as an [azi,alt,radius] array, in radians.

ParamTypeDescription
vecArray.<number>The [x,y,z] direction vector array.

VectorArray.rotateBySphericalCoordinates(out, about, azi, alt) ⇒ Array.<number>

Rotates the out point around about by the given angles.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The point to rotate.
aboutArray.<number>The [x,y,z] point about which to rotate.
azinumberThe horizontal azimuth angle, in radians anti-clockwise from +X axis.
altnumberThe vertical angle, in radians above the horizontal plane.

VectorArray.translateBySphericalCoordinates(out, start, radius, azi, alt) ⇒ Array.<number>

Moves the out coordinate a distance of radius from start in the given angles.

NOTE: This method changes values within the out parameter, however it is safe to use the same instance as start to change it in-place.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] coordinate array to receive the result.
startArray.<number>The [x,y,z] coordinate array of the position to begin from.
radiusnumberThe distance from the given start point.
azinumberThe horizontal azimuth angle, in radians anti-clockwise from +X axis.
altnumberThe vertical angle, in radians above the horizontal plane.

VectorArray.sphericalInterpolate(v1, v2) ⇒ Array.<number>

Interpolates between two normalised spherical coordinates sitting on the surface of a unit sphere.

Kind: static method of VectorArray
Returns: Array.<number> - Returns the interpolated point as a new normalised [x,y,z] vector array.

ParamTypeDescription
v1Array.<number>The first spherical coordinate as a normalised [x,y,z] vector array.
v2Array.<number>The second spherical coordinate as a normalised [x,y,z] vector array.

VectorArray.rotatePointAroundAxis(out, origin, axis, angle) ⇒ Array.<number>

Rotates a coordinates array around the given origin/axis by the given angle.

Don’t use this method to rotate multiple points by the same values as it initialises a quaternion on every call. Use instead the rotatePointsAroundAxis method.

The origin is effectively the point about which the rotation should take place. It is subtracted from the point prior to the rotation, then added back afterwards.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: Array.<number> - Returns out set to the rotated position.

ParamTypeDescription
outArray.<number>The [x,y,z] coordinate array defining the point to rotate.
originArray.<number>The [x,y,z] coordinate array defining the origin point to rotate about.
axisArray.<number>The [x,y,z] vector array defining the axial vector to rotate around.
anglenumberThe angle of rotation, in radians.

VectorArray.rotatePointsAroundAxis(points, origin, axis, angle) ⇒ Array.<Array.<number>>

Rotates an array of coordinate vectors around the given origin/axis by the given angle.

The origin is effectively the point about which the rotation should take place. It is subtracted from the point prior to the rotation, then added back afterwards.

Kind: static method of VectorArray
Returns: Array.<Array.<number>> - Returns the modified points array.

ParamTypeDescription
pointsArray.<Array.<number>>An array of one or more [x,y,z] coordinate arrays to rotate.
originArray.<number>The [x,y,z] coordinate array defining the origin point to rotate about.
axisArray.<number>The [x,y,z] vector array defining the axial vector to rotate around.
anglenumberThe angle of rotation, in radians.

VectorArray.computePathCenter(out, path) ⇒ number

Calculate the geometric center of the given path.

NOTE: This method changes values within the out parameter.

Kind: static method of VectorArray
Returns: number - Returns the surface area, in model units squared.

ParamTypeDescription
outArray.<number>The [x,y,z] coordinate array to receive the result.
pathArray.<Array.<number>>An array of [x,y,z] coordinate arrays defining a closed polygon.

VectorArray.computePathArea(contours, polygonal) ⇒ number

Calculate the area of one or more closed shapes.

The path argument can be given as as either as a single contour defining the outer boundary of the shape or as multiple contours. When the path contains multiple contours, set the polygonal argument to true to define each subsequent contour as a hole within the boundary contour (the default) whose area is SUBTRACTED from the outer boundary. If set to false, each subsequent contour is considered an additional ‘island’ whose area is ADDED to the outer boundary.

Kind: static method of VectorArray
Returns: number - Returns the surface area, in model units squared.

ParamTypeDescription
contoursArray.<Array.<number>> | Array.<Array.<Array.<number>>>One or more arrays of [x,y,z] coordinate arrays defining a closed polygon/polyline.
polygonalbooleanIf true, any subsequent contours in the path define holes in the first one, defaults to true.

VectorArray.sortSegmentsIntoPaths(segments) ⇒ Array.<Array.<number>>

Converts an unordered list of [start,end] line segments into one or more connected paths or loops.

Each segment must be an array of two [x,y,z] vertexes defining its start and end 3D positions. For this method to work, each 3D spatial position needs to be a unique array - meaning that if you have two segments with coincident start or end points, they must be the same array instance rather than two separate arrays with the same values. You can use a Indexer to ensure that this is the case.

This method is mainly used when cutting or slicing shapes to assemble the cut edges that lie on a cutting plane into faces or profiles.

Kind: static method of VectorArray
Returns: Array.<Array.<number>> - Returns one or more assembled face loops.

ParamTypeDescription
segmentsArray.<Array.<number>>An array of unordered [start,end] line fragments.

VectorArray.intersectLineSegmentsXY(p1, p2, p3, p4, [out]) ⇒ boolean

Calculates if the line segment p1->p2 intersects the line segment p3->p4 in the XY plane.

If the two lines intersect, this method will return true. If an out array is given, it will also set its values to the intersection point. If no intersection is found within the lengths of either line, this method returns false and not set any values in the out argument.

As this is a 2D intersection test, the Z value of the intersection point is computed by interpolating the intersection point between the Z values of p3->p4. This may not always be the most appropriate option, however it can be surprisingly accurate in many common situations. That is why it is done, but you are free to ignore or override the computed Z value.

Kind: static method of VectorArray
Returns: boolean - Returns true if segments intersect, and out modified.

ParamTypeDescription
p1Array.<number>The first point on the first line segment.
p2Array.<number>The second point on the first line segment.
p3Array.<number>The first point on the second line segment.
p4Array.<number>The second point on the second line segment.
[out]Array.<number>An optional point to receive the intersection.

VectorArray.areaOfTriangle(p1, p2, p3) ⇒ number

Calculate the area of a triangle joining the three given coordinates.

Kind: static method of VectorArray
Returns: number - Returns the surface area, in model units squared.

ParamTypeDescription
p1Array.<number>The first [x,y,z] coordinate array of the triangle.
p2Array.<number>The second [x,y,z] coordinate array of the triangle.
p3Array.<number>The third [x,y,z] coordinate array of the triangle.

VectorArray.isInsideTriangle(pt, v1, v2, v3, normal) ⇒ boolean

Returns true if the given 3D point lies within the specified triangle.

This calculation assumes that the hit point and all triangle vertices lie on the same plane, so it is relatively fast as the normal is already given.

Kind: static method of VectorArray
Returns: boolean - Returns true if the pt is inside the triangle.

ParamTypeDescription
ptArray.<number>The intersection [x,y,z] coordinate array to test.
v1Array.<number>The first triangle [x,y,z] coordinate array.
v2Array.<number>The second triangle [x,y,z] coordinate array.
v3Array.<number>The third triangle [x,y,z] coordinate array.
normalArray.<number>The plane normal [nx,ny,nz] vector array.

VectorArray.angleBetweenVectors(v1, v2) ⇒ number

Calculates the 3D angle between the two vector arrays, in radians.

Kind: static method of VectorArray
Returns: number - Returns the 3D angle, in radians.

ParamTypeDescription
v1Array.<number>The first [x,y,z] direction vector array.
v2Array.<number>The second [x,y,z] direction vector array.

VectorArray.angleBetweenPoints(p1, p2, p3) ⇒ number

Calculates the unsigned 3D angle between a line passing through three positions, in radians.

   p1                 p3
     \_ _.-angle-._ _/
       \_         _/
         \_     _/
           \_ _/
            p2

Kind: static method of VectorArray
Returns: number - Returns the 3D angle in the range 0.0 to PI, in radians.

ParamTypeDescription
p1Array.<number>The first [x,y,z] coordinate array.
p2Array.<number>The shared second [x,y,z] coordinate array.
p3Array.<number>The third [x,y,z] coordinate array.

VectorArray.polarPoints_Random([num_pts], [dome]) ⇒ Array.<Array.<number>>

Generates a set of completely random 3D coordinates over the surface of a sphere. Generates a set of completely random [azi,alt] polar coordinates in the range 0 to 360 for azimuth and either 0 to 90 (dome) or -90 to 90 (sphere) for altitude.

To ensure a valid distribution, 6 core points are added to form a random tetrahedron, which is why the minimum number of points is 6.

Kind: static method of VectorArray
Returns: Array.<Array.<number>> - Returns an array of [x,y,z] vector arrays.

ParamTypeDescription
[num_pts]numberThe number of random polar points to generate (6+), defaults to 48.
[dome]booleanGenerate a hemisphere instead of a sphere, defaults to false.

VectorArray.polarPoints_Geodesic([detail], [dome]) ⇒ Array.<Array.<number>>

Generates a set of [azi,alt] polar coordinates for geodesic points distributed over the surface of a dome or sphere.

Polar coordinates are useful for analysing a spherical surface as if it were a flat plane, or for generating spherical surfaces with algorithmically varying radii.

This distribution is generated by progressively dividing into spherical triangles and then inflating the interpolated points to the radius of the sphere.

Kind: static method of VectorArray
Returns: Array.<Array.<number>> - Returns an array of [azi,alt] polar arrays.

ParamTypeDescription
[detail]numberThe level of triangulation (0 to 32), defaults to 6.
[dome]booleanGenerate a hemisphere instead of a sphere, defaults to false.

VectorArray.polarPoints_Fibonacci([num_pts], [dome]) ⇒ Array.<Array.<number>>

Generates a set of [azi,alt] polar coordinates from a Fibonacci spiral over the surface of a dome or sphere.

Polar coordinates are useful for analysing a spherical surface as if it were a flat plane, or for generating spherical surfaces with algorithmically varying radii.

The Fibonacci spiral gives a reasonable approximation of equally-spaced points over a sphere or hemisphere.

Kind: static method of VectorArray
Returns: Array.<Array.<number>> - Returns an array of [azi,alt] polar arrays.

ParamTypeDescription
[num_pts]numberThe number of hemispherical points to generate (4 to 2048), defaults to 48.
[dome]booleanGenerate a hemisphere instead of a sphere, defaults to false.

VectorArray.pointCloud_LatLong([latRings], [lngRings], [radius], [dome]) ⇒ Array.<Array.<number>>

Generates a set of [x,y,z] coordinates distributed equally by angle over the surface of a sphere.

Sphere

For a sphere, the north and south poles are generated as the last two points in the point array. Points are added in concentric latitudinal rings starting at the equator and running towards North and South in alternate rings. Thus, the first lngRings points will be for the equator. The next lngRings points will be for the latitude one increment up from the equator towards the north pole. The next lngRings points will be for the latitude one increment down from the equator towards the south pole, and so on. The total number of points should therefore be (2 * latRings * lngRings) + 2.

            Second last point
              , - ~ ' ~ - ,
          , ' - - - - - - - ' ,     - - - 4th ring
        ,                       ,
       , - - - - - - - - - - - - ,  - - - 2nd ring
      ,             |             ,
      + - - - - - - + - - - - - - + - - - 1st ring
      ,             |             ,
       , - - - - - - - - - - - - ,  - - - 3rd ring
        ,                       ,
          , - - - - - - - - - ,     - - - 5th ring
            ' - , _ _ _ , - '
                Last point

Dome

For a dome, the north pole will be the very last point in the array. Points are added in concentric latitudinal rings starting at the equator and running upwards towards the North pole. Thus, the first lngRings points will be for the equator. The next lngRings points will be for the latitude one increment up from the equator. The next lngRings points will be for the latitude another increment up from the last one, and so on. The total number of points should therefore be (latRings * lngRings) + 2.

                Last point
              , - ~ ' ~ - ,
          , ' - - - - - - - ' ,     - - - 3rd ring
        ,                       ,
       , - - - - - - - - - - - - ,  - - - 2nd ring
      ,             |             ,
      + - - - - - - + - - - - - - + - - - 1st ring

Kind: static method of VectorArray
Returns: Array.<Array.<number>> - Returns an array of [x,y,z] vector arrays.

ParamTypeDescription
[latRings]numberThe number of longitudinal divisions (1 to 178), defaults to 8.
[lngRings]numberThe number of latitudinal divisions (3 to 360), defaults to 16.
[radius]numberThe radius of the point distribution, defaults to 1.
[dome]booleanGenerate a hemisphere instead of a sphere, defaults to false.

VectorArray.pointCloud_Random([num_pts], [radius], [dome]) ⇒ Array.<Array.<number>>

Generates a set of completely random 3D coordinates over the surface of a sphere.

To ensure a valid distribution, 6 core points are added to form a random tetrahedron, which is why the minimum number of points is 6.

Kind: static method of VectorArray
Returns: Array.<Array.<number>> - Returns an array of [x,y,z] vector arrays.

ParamTypeDescription
[num_pts]numberThe number of random points to generate (6+), defaults to 48.
[radius]numberThe radius of the point distribution, defaults to 1.
[dome]booleanGenerate a hemisphere instead of a sphere, defaults to false.

VectorArray.pointCloud_Geodesic([detail], [radius], [dome]) ⇒ Array.<Array.<number>>

Generates a set of 3D geodesic points distributed over the surface of a sphere.

This distribution is generated by progressively dividing into spherical triangles and then inflating the interpolated points to the radius of the sphere.

Kind: static method of VectorArray
Returns: Array.<Array.<number>> - Returns an array of [x,y,z] vector arrays.

ParamTypeDescription
[detail]numberThe level of triangulation (0 to 32), defaults to 6.
[radius]numberThe radius of the point distribution, defaults to 1.
[dome]booleanGenerate a hemisphere instead of a sphere, defaults to false.

VectorArray.pointCloud_Fibonacci([num_pts], [radius], [dome]) ⇒ Array.<Array.<number>>

Generates a set of points distributed over the surface of a sphere based on a Fibonacci spiral.

The Fibonacci spiral gives a reasonable approximation of equally-spaced points over a sphere or hemisphere.

Kind: static method of VectorArray
Returns: Array.<Array.<number>> - Returns an array of [x,y,z] vector arrays.

ParamTypeDescription
[num_pts]numberThe number of hemispherical points to generate (4 to 2048), defaults to 48.
[radius]numberThe radius of the point distribution, defaults to 1.
[dome]booleanGenerate a hemisphere instead of a sphere, defaults to false.

VectorArray.concaveHullXY(points, concavity, lengthThreshold) ⇒ Array.<number>

Calculates the concave hull of an array of vector arrays in the XY plane.

NOTE: This method uses vector arrays in the form [x,y[,z]] rather than point objects. If you need to process an array of THREE.Vector3, THREE.Vector2 or PD.Point objects, use the PD.Utils.concaveHullXY method instead.

The concavity arguments is a relative measure of concavity, where a value of 1.0 results in a relatively detailed shape, and Infinity results in a convex hull. You can use values lower than 1, but they can produce pretty crazy shapes.

When a segment length is less than lengthThreshold, it stops being considered for further decomposition. Higher values result in a simpler shape.

The return value is an ordered array of points that define the line of the concave hull around the point cloud.

This uses concaveman (https://github.com/mapbox/concaveman), a fast algorithm for finding concave and convex hulls in 2D points.

Kind: static method of VectorArray
Returns: Array.<number> - Returns and array of 2D points.

ParamTypeDescription
pointsArray.<number>An array of [x, y[, z]] vector arrays.
concavitynumberA relative measure of concavity, defaults to 1.0.
lengthThresholdnumberThe minimum point radius to consider.

PD.PlaneArray

A helper class for performing vector math using [a,b,c,d] array-based plane equations.

The array entries represent components of the Ax + By + Cz + D = 0 plane equation. When stored this way, the first three entries in the plane array are also a vector array defining the normal direction, and can be used directly in many VectorArray methods.

Any Float32Array with at least four items in the same [a,b,c,d] format can also be used entirely interchangeably as both output or input in all plane array methods.

Kind: static class of PD
Author: drajmarsh

PlaneArray.create([a], [b], [c], [d]) ⇒ Array.<number>

Creates a new [a,b,c,d] plane array with the given components.

The four (4) array entries represent components of the plane equation Ax + By + Cz + D = 0, where the first three (3) entries are also a [x,y,z] vector array representing the surface normal direction.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns a new [a,b,c,d] plane array.

ParamTypeDescription
[a]numberThe A (X-axis) component, or zero if not defined.
[b]numberThe B (Y-axis) component, or zero if not defined.
[c]numberThe C (Z-axis) component, or one if not defined.
[d]numberThe D constant component, or zero if not defined.

PlaneArray.set(out, a, b, c, d) ⇒ Array.<number>

Sets the [a,b,c,d] plane array to the given components.

This method offers some flexibility in terms of the arguments it accepts. You can provide 4 separate numeric values or just a single [a,b,c,d] plane array, a 4D point-like {x,y,z,w} object, or even no arguments at all to create a unit plane.

NOTE: This method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the resulting out [a,b,c,d] plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to receive the result.
anumberThe A (X-axis) component, or zero if not defined.
bnumberThe B (Y-axis) component, or zero if not defined.
cnumberThe C (Z-axis) component, or one if not defined.
dnumberThe D constant component, or zero if not defined.

PlaneArray.setComponents(out, a, b, c, d) ⇒ Array.<number>

Sets the [a,b,c,d] plane array by its individual components.

This method differs from the set() method in that you must provide all 4 components as separate numeric values. It does not perform any type checking, which makes it a bit faster in situations where you can reliably provide the separate component values.

NOTE: This method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the resulting out [a,b,c,d] plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to receive the result.
anumberThe A (X-axis) component, or zero if not defined.
bnumberThe B (Y-axis) component, or zero if not defined.
cnumberThe C (Z-axis) component, or one if not defined.
dnumberThe D constant component, or zero if not defined.

PlaneArray.copy(out, pln) ⇒ Array.<number>

Copies the first four components of p to out.

NOTE: This method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the modified out [a,b,c,d] plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to receive the result.
plnArray.<number>The [a,b,c,d] plane array to copy from.

PlaneArray.clone(out) ⇒ number

Creates a copy of the given plane array.

This method simply returns out.slice() but is included for API compatibility.

Kind: static method of PlaneArray
Returns: number - Returns a new copied plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to clone.

PlaneArray.negate(out, [pln]) ⇒ Array.<number>

Reverses the sign of each component of a plane array.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as p or simply give one argument to change it in-place.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the modified out plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to receive the result.
[pln]Array.<number>The [a,b,c,d] plane array to negate, set to out if not supplied.

PlaneArray.setFromNormalAndCoplanarPoint(out, normal, point) ⇒ Array.<number>

Computes the [a,b,c,d] plane array from with the given normal and passing through the given point.

NOTE: This method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the given [a,b,c,d] plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to set.
normalArray.<number>An [x,y,z] vector array defining the normal, which must be normalized.
pointArray.<number>An [x,y,z] vector array oa point that sits on the plane.

PlaneArray.setFromCoplanarPoints(out, v1, v2, v3) ⇒ Array.<number>

Computes the [a,b,c,d] plane array from three points that lie on the plane.

NOTE: This method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the given [a,b,c,d] plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to set.
v1Array.<number>An [x,y,z] vector array defining the first point on the plane.
v2Array.<number>An [x,y,z] vector array defining the second point on the plane.
v3Array.<number>An [x,y,z] vector array defining the third point on the plane.

PlaneArray.computeFromPath(out, path) ⇒ Array.<number>

Computes the [a,b,c,d] plane array from the surface normal of given array of connected points.

This method calculates the surface normal from multiple points along a path using Newell’s Method, which provides a very robust way of computing an ‘average’ normal from points which may vary quite considerably from being coplanar.

NOTE: This method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the given [a,b,c,d] plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to set.
pathArray.<number>An array of [x,y,z] coordinate arrays defining a polyline or polygon.

PlaneArray.computeFromIndexedPath(out, indices, vertices) ⇒ Array.<number>

Computes the [a,b,c,d] plane array from the surface normal of given array of connected points.

This method calculates the surface normal from multiple points along a path using Newell’s Method, which provides a very robust way of computing an ‘average’ normal from points which may vary quite considerably from being coplanar.

NOTE: This method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the given [a,b,c,d] plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to set.
indicesArray.<number>An array of ordinal indexes to points within the vertices array.
verticesArray.<number>A repository of [x,y,z] coordinate arrays that indices.

PlaneArray.computeInclinedFromLine(out, rayPos, rayDir, angle) ⇒ Array.<number>

Calculates an [a,b,c,d] plane array that is inclined by the given angle from a line that is roughly horizontal.

NOTE: This method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the modified out [a,b,c,d] plane array.

ParamTypeDescription
outArray.<number>The [a,b,c,d] plane array to receive the result.
rayPosArray.<number>The [x,y,z] vector array giving the first point on a line.
rayDirArray.<number>The [x,y,z] vector array giving the second point on a line.
anglenumberThe tilt angle of the plane in radians (0:horizontal to PI/2:vertical).

PlaneArray.inFront(plane, pt) ⇒ boolean

Checks if a 3D points is on the same side of the given plane as its normal is pointing.

Kind: static method of PlaneArray
Returns: boolean - Returns true if point is on same side of plane as its normal.

ParamTypeDescription
planeArray.<number>The [a,b,c,d] plane array to test.
ptArray.<number>The [x,y,z] vector array of the point to check.

PlaneArray.isOnSameSide(plane, p1, p2) ⇒ boolean

Checks if two 3D points are on the same side of the given plane.

Kind: static method of PlaneArray
Returns: boolean - Returns true if both points are on same side of the plane.

ParamTypeDescription
planeArray.<number>The [a,b,c,d] plane array to test.
p1Array.<number>The [x,y,z] vector array of the first point.
p2Array.<number>The [x,y,z] vector array of the second point.

PlaneArray.distanceTo(plane, pt) ⇒ number

Computes the signed distance from a 3D point to given plane.

Kind: static method of PlaneArray
Returns: number - Returns the signed distance to the plane.

ParamTypeDescription
planeArray.<number>The [a,b,c,d] plane array to test.
ptArray.<number>The [x,y,z] vector array of the point.

PlaneArray.projectPoint(out, plane, pt) ⇒ Array.<number>

Projects a point onto the given plane using its normal.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the modified out [x,y,z] coordinate array.

ParamTypeDescription
outArray.<number>The [x,y,z] coordinate array to receive the result.
planeArray.<number>The [a,b,c,d] plane array to project onto.
ptArray.<number>The [x,y,z] coordinate array of the point to project.

PlaneArray.intersectRay(out, rayPos, rayDir, plane, [min]) ⇒ Array.<number>

Calculates the intersection point of a ray and plane.

This method calculates intersections on both sides of the ray, not just in its direction of travel. If you want to only intersect in its direction of travel, set the min argument to 0.

NOTE: If successful, this method changes values within the out parameter to the intersection point. Otherwise it sets it to the ray origin position as that must lie directly on the plane.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
rayPosArray.<number>The [x,y,z] vector array giving the origin point of the ray.
rayDirArray.<number>The [x,y,z] vector array giving the travel direction of the ray.
planeArray.<number>The [a,b,c,d] plane array to intersect the ray with.
[min]numberThe minimum distance along the ray, defaults to -Infinity.

PlaneArray.intersectLine(out, p1, p2, plane, [min]) ⇒ Array.<number>

Calculates the intersection point of a line and plane.

This method calculates intersections beyond both ends of the line, not just inside it. If you want to only intersect in front of p1, set the min argument to 0. If you want to only intersect in front of p2, set the min argument to 1.

NOTE: If successful, this method changes values within the out parameter to the intersection point. Otherwise it sets it to the p1 position as this must lie directly on the plane.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the modified out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z] vector array to receive the result.
p1Array.<number>The [x,y,z] vector array defining the line start position.
p2Array.<number>The [x,y,z] vector array defining the line end position.
planeArray.<number>The [a,b,c,d] plane array to intersect the ray with.
[min]numberThe minimum distance along the line, defaults to -Infinity.

PlaneArray.coplanarPoint(out, plane1) ⇒ Array.<number>

Projects the origin onto the give plane.

NOTE: This method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: Array.<number> - Returns the out [x,y,z] vector array.

ParamTypeDescription
outArray.<number>An [x,y,z] vector array to receive the planar point.
plane1Array.<number>The [a,b,c,d] plane array to project the point onto.

PlaneArray.intersectThreePlanes(out, plane1, plane2, plane3) ⇒ boolean

Computes the point of intersection between three planes.

NOTE: If successful, this method changes values within the out parameter.

Kind: static method of PlaneArray
Returns: boolean - Returns true if a valid intersection point was found and copied to the out argument, otherwise false and out is not set.

ParamTypeDescription
outArray.<number>An [x,y,z] vector array to receive the intersection point.
plane1Array.<number>The first [a,b,c,d] plane array to intersect.
plane2Array.<number>The second [a,b,c,d] plane array to intersect.
plane3Array.<number>The third [a,b,c,d] plane array to intersect.

PD.QuaternionArray

A helper class for performing vector math using [x,y,z,w] array-based quaternions.

Quaternions are a compact representation of the rotation of an object in three dimensions. Quaternions have some advantages over rotation matrices as they are smaller and do not suffer from potential gimbal lock.

Any Float32Array with at least four items in the same [x,y,z.w] format can also be used entirely interchangeably as both output or input in all quaternion array methods.

Kind: static class of PD
Author: drajmarsh

QuaternionArray.create([x], [y], [z], [z]) ⇒ Array.<number>

Creates a new [x,y,z,w] quaternion array with the given components.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns a new [x,y,z,w] quaternion array.

ParamTypeDescription
[x]numberThe X-axis component, or zero if not defined.
[y]numberThe Y-axis component, or zero if not defined.
[z]numberThe Z-axis component, or zero if not defined.
[z]numberThe W component, or zero if not defined.

QuaternionArray.copy(out, q) ⇒ Array.<number>

Copies the first four components of q to out.

NOTE: This method changes values within the out parameter.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the modified out [x,y,z,w] vector array.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to receive the result.
qArray.<number>The [x,y,z,w] quaternion array to copy from.

QuaternionArray.clone(out) ⇒ number

Creates a copy of the given quaternion array.

This method simply returns out.slice() but is included for API compatibility.

Kind: static method of QuaternionArray
Returns: number - Returns a new copied quaternion array.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to clone.

QuaternionArray.set(out, x, y, z, w) ⇒ Array.<number>

Sets the [x,y,z,w] quaternion to the given components.

This method offers some flexibility in terms of the arguments it accepts. You can provide 4 separate numeric values or just a single [x,y,z,w] vector array, a 4D point-like {x,y,z,w} object, or even no arguments at all to create a unit quaternion.

NOTE: This method changes values within the out parameter.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the updates out [x,y,z,w] quaternion array.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to receive the result.
xnumber | Array.<number>The X-axis component, or zero if not defined.
ynumberThe Y-axis component, or zero if not defined.
znumberThe Z-axis component, or zero if not defined.
wnumberThe W component, or zero if not defined.

QuaternionArray.setComponents(out, x, y, z, z) ⇒ Array.<number>

Sets the [x,y,z,w] quaternion by its individual components.

This method differs from the set() method in that you must provide all 4 components as separate numeric values. It does not perform any type checking, which makes it a bit faster in situations where you can reliably provide the separate component values.

NOTE: This method changes values within the out parameter.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the updates out [x,y,z,w] quaternion array.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to receive the result.
xnumberThe X-axis component, or zero if not defined.
ynumberThe Y-axis component, or zero if not defined.
znumberThe Z-axis component, or zero if not defined.
znumberThe W component, or zero if not defined.

QuaternionArray.setFromAxisAngle(out, axis, angle) ⇒ Array.<number>

Computes the [x,y,z,w] quaternion array for rotating around an arbitrary axis.

NOTE: This method changes values within the out parameter.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the given [x,y,z,w] quaternion array.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to set.
axisArray.<number>The [x,y,z] vector array defining the axis, which must be normalized.
anglenumberThe axial rotation angle, in decimal radians.

QuaternionArray.setFromThreeAxis(out, xAxis, yAxis, zAxis) ⇒ Array.<number>

Sets a quaternion based on three axis representing the new coordinate system.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the updated out quaternion.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion to set.
xAxisArray.<number>The normalised [x,y,z] vector array defining the X-axis.
yAxisArray.<number>The normalised [x,y,z] vector array defining the Y-axis.
zAxisArray.<number>The normalised [x,y,z] vector array defining the Z-axis.

QuaternionArray.setFromMatrix(out, matrix) ⇒ Array.<number>

Computes the [x,y,z,w] quaternion array from a 4x4 column-major rotation matrix array.

NOTE: This method changes values within the out parameter.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the given [x,y,z,w] quaternion array.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to set.
matrixArray.<number>The 4x4 (16 item) column-major rotation matrix.

QuaternionArray.setFromUnitVectors(out, v1, v2) ⇒ Array.<number>

Computes the [x,y,z,w] quaternion array required rotate from ‘v1’ to ‘v2’, where both are normalized direction vectors.

NOTE 1: This method changes values within the out parameter.

NOTE 2: Both direction vectors MUST BE normalized.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the given [x,y,z,w] quaternion array.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to set.
v1Array.<number>The normalized [x,y,z] vector array defining the reference direction.
v2Array.<number>The normalized [x,y,z] vector array defining the destination direction.

QuaternionArray.setFromNormal(out, normal) ⇒ Array.<number>

Compute the quaternion required to rotate from the XY plane to given plane.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the out argument with computed values.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to set.
normalArray.<number>The normalised [x,y,z] vector array defining the surface normal of a plane.

QuaternionArray.setToNormal(out, normal) ⇒ Array.<number>

Compute the quaternion required to rotate from the given plane to the XY plane.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the out argument with computed values.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to set.
normalArray.<number>The normalised [x,y,z] vector array defining the surface normal of a plane.

QuaternionArray.multiply(out, a, b) ⇒ Array.<number>

Multiplies two [x,y,z,w] quaternions together and stores the result in out.

NOTE: This method changes values within the out parameter, however it is safe to use the same quaternion as either a or b.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the out argument with computed values.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion to receive the result.
aArray.<number>The first [x,y,z,w] quaternion to multiply.
bArray.<number>The second [x,y,z,w] quaternion to multiply.

QuaternionArray.invert(out, [q]) ⇒ Array.<number>

Inverts the sign of each component of a quaternion.

NOTE: This method changes values within the out parameter, however it is safe to use the same array as v or simply give one argument to change it in-place.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the modified out quaternion array.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to receive the result.
[q]Array.<number>The [x,y,z,w] quaternion array to negate, defaults to out if not supplied.

QuaternionArray.normalize(out, [q]) ⇒ Array.<number>

Resizes a quaternion array to unit length (len == 1.0).

NOTE: This method changes values within the out parameter, however it is safe to use the same array as q or simply give one argument to change it in-place.

Kind: static method of QuaternionArray
Returns: Array.<number> - Returns the modified out quaternion array.

ParamTypeDescription
outArray.<number>The [x,y,z,w] quaternion array to receive the result.
[q]Array.<number>The [x,y,z,w] quaternion array to normalise, defaults to out if not supplied.

PD.MatrixArray

A helper class for performing vector math using array-based matrices.

These are 16-item column-major transformation matrix arrays. This means that, when represented as a table with 4 columns and 4 rows, the X, Y and Z direction each of the local axis are read downwards in the first three columns and the 4th row gives the offset in each of those axis.

Any Float32Array with at least 16 items in the same format can also be used entirely interchangeably as both output or input in all matrix array methods.

Kind: static class of PD
Author: drajmarsh

MatrixArray.create() ⇒ Array.<number>

Creates a new 16-item column-major matrix array.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns a new 16-item column-major matrix array.

MatrixArray.identity(out) ⇒ Array.<number>

Resets a 16-item column-major matrix to identity values.

NOTE: This method changes values within the out parameter.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the updated out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to set.

MatrixArray.setFromThreeAxis(out, xAxis, yAxis, zAxis, [origin]) ⇒ Array.<number>

Sets a 16-item column-major matrix to use the given three axis and origin.

NOTE: This method changes values within the out parameter.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the updated out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to set.
xAxisArray.<number>The normalised [x,y,z] vector array defining the X-axis.
yAxisArray.<number>The normalised [x,y,z] vector array defining the Y-axis.
zAxisArray.<number>The normalised [x,y,z] vector array defining the Z-axis.
[origin]Array.<number>The [x,y,z] vector array position of the origin, defaults to [0,0,0].

MatrixArray.setTranslation(out, translation) ⇒ Array.<number>

Sets a 16-item column-major matrix to the given translation.

Using this method is the same as, but notably faster than, having to separately call the PD.MatrixArray#identity and then PD.MatrixArray#translate methods.

NOTE: This method changes values within the out parameter.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to set.
translationArray.<number>The [x,y,z] vector array defining the spatial translation in each axis.

MatrixArray.setScale(out, scale) ⇒ Array.<number>

Sets a 16-item column-major matrix to the given scaling.

Using this method is the same as, but notably faster than, having to separately call the PD.MatrixArray#identity and then PD.MatrixArray#scale methods.

NOTE: This method changes values within the out parameter.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to set.
scaleArray.<number>The [sx,sy,sz] vector array defining the spatial scaling in each axis.

MatrixArray.setRotation(out, axis, angle) ⇒ Array.<number>

Sets a 16-item column-major matrix to the given rotation.

Using this method is the same as, but notably faster than, having to separately call the PD.MatrixArray#identity and then PD.MatrixArray#rotate methods.

NOTE: This method changes values within the out parameter.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to set.
axisArray.<number>The normalised [x,y,z] vector array defining the axis of rotation.
anglenumberThe angle or rotation in radians.

MatrixArray.getTranslation(vec, mtx) ⇒ Array.<number>

Retrieves the translation vector component of the matrix.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified vec [x,y,z] vector array.

ParamTypeDescription
vecArray.<number>The [x,y,z] vector array to receive the translation.
mtxArray.<number>The 16-item column-major matrix array to get it from.

MatrixArray.getScale(vec, mtx) ⇒ Array.<number>

Retrieves the scaling factor component of a matrix.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified vec [x,y,z] vector array.

ParamTypeDescription
vecArray.<number>The [x,y,z] vector array to receive the scale.
mtxArray.<number>The 16-item column-major matrix array to get it from.

MatrixArray.getRotation(quat, mtx) ⇒ Array.<number>

Retrieves the rotational component of a matrix as a quaternion.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified out [x,y,z,w] quaternion array.

ParamTypeDescription
quatArray.<number>The [x,y,z,w] quaternion array to receive the rotation.
mtxArray.<number>The 16-item column-major matrix array to get it from.

MatrixArray.compose(out, translation, rotation, scale) ⇒ Array.<number>

Composes a flat 4x4 column-major matrix from the given translation, rotation and scaling factors.

Once created, you can use the applyMatrix4 method to modify points and vertices.

NOTE: This method changes values within the out parameter.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to receive the result.
translationArray.<number>The [x,y,z] vector array defining the spatial translation in each axis.
rotationArray.<number>The normalised [x,y,z,w] quaternion array defining the spatial rotation.
scaleArray.<number>The [x,y,z] vector array defining the spatial scaling in each axis.

MatrixArray.decompose(matrix, translation, rotation, scale) ⇒ Array.<number>

Composes a flat 4x4 column-major matrix from the given translation, rotation and scaling factors.

Once created, you can use the applyMatrix4 method to modify points and vertices.

NOTE: This method changes values within the translate, rotate and scale parameters.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the matrix argument.

ParamTypeDescription
matrixArray.<number>The 16-item column-major matrix array to receive the result.
translationArray.<number>The [x,y,z] vector array defining the spatial translation in each axis.
rotationArray.<number>The normalised [x,y,z,w] quaternion array defining the spatial rotation.
scaleArray.<number>The [x,y,z] vector array defining the spatial scaling in each axis.

MatrixArray.translate(out, mtx, translation) ⇒ Array.<number>

Translate a flat 4x4 column-major matrix array by the given vector.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to receive the result.
mtxArray.<number>The 16-item column-major matrix array to translate.
translationArray.<number>The [x,y,z] vector array defining the spatial translation in each axis.

MatrixArray.scale(out, mtx, scale) ⇒ Array.<number>

Scale a flat 4x4 column-major matrix array by the given factors.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to receive the result.
mtxArray.<number>The 16-item column-major matrix array to scale.
scaleArray.<number>The [sx,sy,sz] vector array defining the spatial scaling in each axis.

MatrixArray.rotate(out, mtx, axis, angle) ⇒ Array.<number>

Rotate a flat 4x4 column-major matrix array by the given angle around the given axis.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to receive the result.
mtxArray.<number>The 16-item column-major matrix array to scale.
axisArray.<number>The normalised [x,y,z] vector array defining the axis of rotation.
anglenumberThe angle or rotation in radians.

MatrixArray.multiply(out, mtx2, mtx1) ⇒ Array.<number>

Multiply two 16-item column-major matrices together.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the updated out matrix.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to set.
mtx2Array.<number>The first 16-item column-major matrix array to multiply.
mtx1Array.<number>The second 16-item column-major matrix array to multiply.

MatrixArray.invert(out, [mtx]) ⇒ Array.<number>

Inverts a 4x4 column-major matrix and stores the result in out.

NOTE: This method changes values within the out parameter, however it is safe to use the same array in both arguments, or simply give only one argument to change it in-place.

Kind: static method of MatrixArray
Returns: Array.<number> - Returns the modified out matrix array.

ParamTypeDescription
outArray.<number>The 16-item column-major matrix array to receive the result.
[mtx]Array.<number>The 16-item column-major source matrix array, defaults to out if not supplied.

MatrixArray.determinant(mtx) ⇒ number

Computes the determinant of the given 4x4 column-major matrix.

The determinant of a 4×4 matrix is a unique number calculated from a square matrix using a special formula. There are several formulas that can be used, and this method uses one, but the upshot is that it returns a single numerical value which is used when calculating the inverse or when solving systems of linear equations.

Kind: static method of MatrixArray
Returns: number - Returns the computed determinant.

ParamTypeDescription
mtxArray.<number>The 16-item column-major matrix array.

PD.AxisArray

A helper class for defining local coordinate systems (LCS) for creating and manipulating [x,y,z] vector arrays.

An LCS defines an origin position and the local X, Y and Z axis as [x,y,z] vector arrays within the global cartesian coordinate system. The magnitude of each axis is typically 1, resulting in a direct spatial rotation followed by a translation. Any magnitude other than one represents a scaling in the corresponding axis.

    Z
     +           Y
      \         +
       \       /
        \  /\ /
         \/__/___
          \ / \ /
           +------------------+ X
        origin

This effectively creates a 3x3 row-major transformation matrix with a translation component. This can also be thought of as a 4x4 row-major matrix with the bottom row being [0, 0, 0, 1].

Rather than simply replicate other matrix classes, the aim of this class is to assist with the manual creation of 3D shapes and forms though the overt use of an LCS. This means explicitly setting up the direction of each axis and then creating vertices and edges using a series of moveTo() and moveBy() method calls. To support this, the class also stores a currentPos as a [x,y,z] vector array and updates it with each move.

Kind: static class of PD
Author: drajmarsh

new PD.AxisArray([origin], [xAxis], [yAxis], [zAxis])

Creates a new local coordinate system using vector arrays.

If no arguments are given, the coordinates default to standard cartesian coordinates. You can also use null or undefined for any particular argument to use its default.

ParamTypeDescription
[origin]Array.<number>The new origin of the local coordinate system, defaults to global origin.
[xAxis]Array.<number>The new local X-axis, defaults to the global Cartesian X-axis.
[yAxis]Array.<number>The new local Y-axis, defaults to the global Cartesian Y-axis.
[zAxis]Array.<number>The new local Z-axis, defaults to the global Cartesian Z-axis.

axisArray.origin : Array.<number>

The origin of the local coordinate system as an [x,y,z] vector array, defaults to [0,0,0].

This is the reference position about which all other coordinates are taken.

Kind: instance property of AxisArray

axisArray.xAxis : Array.<number>

The relative X-axis within the local coordinate system as a normalized [dx,dy,dz] vector array, defaults to [1,0,0].

Kind: instance property of AxisArray

axisArray.yAxis : Array.<number>

The relative Y-axis within the local coordinate system as a normalized [dx,dy,dz] vector array, defaults to [0,1,0].

Kind: instance property of AxisArray

axisArray.zAxis : Array.<number>

The relative Z-axis within the local coordinate system as a normalized [dx,dy,dz] vector array, defaults to [0,0,1].

Kind: instance property of AxisArray

axisArray.currentPos : Array.<number>

A temporary position that can be moved around the coordinate system as an [x,y,z] vector array, defaults to [0,0,0].

Kind: instance property of AxisArray

axisArray.bbox : Object

A bounding box aligned with the local axis.

This object has a min and max property, each being an [x,y,z] vector array, that define the minimum and maximum corners of the box in local coordinates.

Kind: instance property of AxisArray

axisArray.isAxisArray : boolean

A flag identifying this object as a local coordinate system.

Kind: instance property of AxisArray
Read Only: true

axisArray.reset() ⇒ AxisArray

Resets the local coordinate system to the global origin ([0,0,0]) and each axis to the corresponding global Cartesian axis.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

axisArray.set([origin], [xAxis], [yAxis], [zAxis]) ⇒ AxisArray

Sets or resets the components of the local coordinate system.

This method sets both the actual and stored origin, and resets the current position to the new origin. If no arguments are given, the coordinates will defaults to normal cartesian coordinates. You can also use null for any particular argument to use its default.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
[origin]Array.<number> | undefinedThe new origin of the local coordinate system, defaults to global origin.
[xAxis]Array.<number> | undefinedThe new local X-axis, defaults to global Cartesian X-axis.
[yAxis]Array.<number> | undefinedThe new local Y-axis, defaults to global Cartesian Y-axis.
[zAxis]Array.<number> | undefinedThe new local Z-axis, defaults to global Cartesian Z-axis.

axisArray.copy(from) ⇒ AxisArray

Copy the given local coordinates to these local coordinates.

Kind: instance method of AxisArray
Returns: AxisArray - Returns these coordinates to support method chaining.

ParamTypeDescription
fromAxisArrayAnother local coordinate system to copy.

axisArray.clone() ⇒ AxisArray

Creates new local coordinates as a direct copy of these local coordinates.

Kind: instance method of AxisArray
Returns: AxisArray - Returns a new local coordinate system.

axisArray.setByAxis([origin], [axis]) ⇒ AxisArray

Aligns the local coordinate system with the given global Cartesian axis.

This method sets both the actual and stored origin, and resets the current position to the new origin. If no arguments are given, the coordinates will defaults to normal global Cartesian coordinates. You can also use null for any particular argument to use its default.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDefaultDescription
[origin]Array.<number> | nullThe new origin of the local coordinate system, defaults to global origin.
[axis]PD.AXIS0The new local Z axis (1:X, 2:Y, 3

axisArray.setByTwoPointsAndNormal(p1, p2, [normal]) ⇒ AxisArray

Aligns the local coordinate system with a vector between two points and an opposing normal.

 normal         Y
     +         :
      \       :
       \  /\ :
        \/  :___
         \ :   /
          +------------------+ X
         p1                  p2

This method sets the origin to p1, the X axis to (p1 -> p2), the Z axis axis to the given normal, and the Y axis to the cross product thew X and Z axis.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
p1Array.<number>The origin of the new axis.
p2Array.<number>A point somewhere on the new +X-axis.
[normal]Array.<number>The new local +Z-axis, defaults to global Cartesian Z-axis.

axisArray.setByThreePoints(p1, p2, p3) ⇒ AxisArray

Aligns the the local coordinate system. with the given three points.

This method sets the origin to p2, the X axis to (p2 -> p3), the Y axis to (p2 -> p1), and the Z axis axis to the cross product the X and Y axis.

    Z           Y
     +         + p1
      \       /
       \  /\ /
        \/  /___
         \ /   /
          +------------------+ X
         p2                  p3

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
p1Array.<number>A point on the +Y-axis.
p2Array.<number>The new origin point.
p3Array.<number>A point on the +X-axis.

axisArray.rotateByLocalAxis(radians, [axis]) ⇒ AxisArray

Rotates the axis of the local coordinate system by an angle.

This method just affects the direction of each axis, not the current position or origin.

NOTE Rotations are cumulative. If you call the same rotation method twice with the same values, it will rotate by twice the given angle.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDefaultDescription
radiansnumberThe angle of rotation, in radians.
[axis]PD.AXIS0The axis to rotate about (1:X, 2:Y, 3

axisArray.rotateLocalX(radians) ⇒ AxisArray

Rotates all axis by the given angle around the current local X axis.

This method just affects the direction of each axis, not the current position or origin.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
radiansnumberThe angle of rotation, in radians.

axisArray.rotateLocalY(radians) ⇒ AxisArray

Rotates the axis by the given angle around the current local Y axis.

This method just affects the direction of each axis, not the current position or origin.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
radiansnumberThe angle of rotation, in radians.

axisArray.rotateLocalZ(radians) ⇒ AxisArray

Rotates the axis by the given angle around the current local Z-axis.

This method just affects the direction of each axis, not the current position or origin.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
radiansnumberThe angle of rotation, in radians.

axisArray.rotateByCartesianAxis(radians, [axis]) ⇒ AxisArray

Rotates the axis of the local coordinate system by an angle around a major cartesian axis.

This method just affects the direction of each axis, not the current position or origin.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDefaultDescription
radiansnumberThe angle of rotation, in radians.
[axis]PD.AXIS0The axis to rotate about (1:X, 2:Y, 3

axisArray.rotateX(radians) ⇒ AxisArray

Rotates the axis by the given angle around the global Cartesian X-axis.

This method just affects the direction of each axis, not the current position or origin.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
radiansnumberThe angle of rotation, in radians.

axisArray.rotateY(radians) ⇒ AxisArray

Rotates the axis by the given angle around the global Cartesian Y-axis.

This method just affects the direction of each axis, not the current position or origin.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
radiansnumberThe angle of rotation, in radians.

axisArray.rotateZ(radians) ⇒ AxisArray

Rotates the axis by the given angle around the global Cartesian Z-axis.

This method just affects the direction of each axis, not the current position or origin.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
radiansnumberThe angle of rotation, in radians.

axisArray.swapAxis(axis) ⇒ AxisArray

Swaps the two axis of the local coordinate system in the plane of the given axis.

This method just affects the direction of each axis, not the current position or origin.

To swap the X and Y axis, use 3:PD.AXIS.Z_POS or -3:PD.AXIS.Z_NEG as the argument. To swap the Y and Z axis, use 1:PD.AXIS.X_POS or -1:PD.AXIS.X_NEG as the argument. To swap the X and Z axis, use 2:PD.AXIS.Y_POS or -2:PD.AXIS.Y_NEG as the argument. To swap the axis back, simply use the same call with the same argument.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
axisPD.AXISThe axis to of the plane to swap in.

axisArray.scaleTo([scale]) ⇒ AxisArray

Sets the scaling factor for each local axis.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
[scale]number | Array.<number>A scale factor or [sx,sy,sz] vector array to scale local axis to, defaults to 1.

axisArray.scaleBy([scale]) ⇒ AxisArray

Applies a scaling factor to each local axis.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
[scale]number | Array.<number>A scale factor or [sx,sy,sz] vector array to scale local axis by, defaults to 1.

axisArray.getCurrentPos() ⇒ Array.<number>

Retrieves the current position of the local origin of the coordinate system.

The current position is a point that starts at the origin and is updated by the moveTo() and moveBy() method.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the local origin position.

axisArray.moveTo(x, [y], [z]) ⇒ Array.<number>

Sets the current position relative to the origin.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the current position.

ParamTypeDefaultDescription
xnumber0The distance from the origin in the local X-axis.
[y]number0The distance from the origin in the local Y-axis, defaults to zero.
[z]number0The distance from the origin in the local Z-axis, defaults to zero.

axisArray.moveBy(dx, [dy], [dz]) ⇒ Array.<number>

Moves the current position by a relative amount in each axis.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the current position.

ParamTypeDefaultDescription
dxnumber0The distance along the local X-axis.
[dy]number0The distance along the local Y-axis, defaults to zero.
[dz]number0The distance along the local Z-axis, defaults to zero.

axisArray.movePointToX(pos, x) ⇒ Array.<number>

Calculates an absolute position in the U-Axis relative to the origin.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the pos argument.

ParamTypeDescription
posArray.<number>The point to receive the new position.
xnumberThe distance from the origin in the local X-axis.

axisArray.movePointToY(pos, y) ⇒ Array.<number>

Calculates an absolute position in the V-Axis relative to the origin.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the pos argument.

ParamTypeDescription
posArray.<number>The point to receive the new position.
ynumberThe distance from the origin in the local Y-axis.

axisArray.movePointToZ(pos, z) ⇒ Array.<number>

Calculates an absolute position in the W-Axis relative to the origin.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the pos argument.

ParamTypeDescription
posArray.<number>The point to receive the new position.
znumberThe distance from the origin in the local Z-axis.

axisArray.movePointTo(pos, x, [y], [z]) ⇒ Array.<number>

Calculates an absolute position in the W-Axis relative to the origin.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the pos argument.

ParamTypeDefaultDescription
posArray.<number>The point to receive the new position.
xnumber0The distance from the origin in the local X-axis.
[y]number0The distance from the origin in the local Y-axis, defaults to zero.
[z]number0The distance from the origin in the local Z-axis, defaults to zero.

axisArray.movePointByX(pos, dx) ⇒ Array.<number>

Moves the given position in the U-Axis relative to itself.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the pos argument.

ParamTypeDescription
posArray.<number>The point to receive the new position.
dxnumberThe distance along the local X-axis.

axisArray.movePointByY(pos, dy) ⇒ Array.<number>

Moves the given position in the V-Axis relative to itself.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the pos argument.

ParamTypeDescription
posArray.<number>The point to set the position of.
dynumberThe distance along the local Y-axis.

axisArray.movePointByZ(pos, dz) ⇒ Array.<number>

Moves the given position in the W-Axis relative to itself.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the pos argument.

ParamTypeDescription
posArray.<number>The point to set the position of.
dznumberThe distance in the Z-axis.

axisArray.movePointBy(pos, [dx], [dy], [dz]) ⇒ Array.<number>

Moves the given position in each axis relative to itself.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the pos argument.

ParamTypeDefaultDescription
posArray.<number>The {x,y,z} point to set the position of.
[dx]number0The distance along the local X-axis, defaults to zero.
[dy]number0The distance along the local Y-axis, defaults to zero.
[dz]number0The distance along the local Z-axis, defaults to zero.

axisArray.translatePoints(points, offset) ⇒ number

Applies a local [dx,dy,dz] translation to the given points.

Kind: instance method of AxisArray
Returns: number - Returns the points array with modified coordinates.

ParamTypeDescription
pointsArray.<Array.<number>>An array of [x,y,z] coordinate arrays to scale in place.
offsetArray.<number>A [x,y,z] vector array to move the points by, in the local axis.

axisArray.scalePoints(points, scale, [negAxisScale]) ⇒ number

Scales a set of points about a local origin and X, Y and Z axis.

You can use the AxisArray to set up a local origin point and re-orient the local X, Y and Z to whatever direction you want. The scale factors you provide are then applied in the direction of these local axis and about the local origin.

This method also allows you to use two separate sets of scaling factors. If you only provide one set, it will be used as the default. However, providing a second set allows you to apply a different scale when a point is on the negative side of the origin compared to the positive side.

           +Z
             +          +Y
              \         +
               \       /
                \  /\ /     [scale]
                 \/__/___
                  \ / \ /
   -X  -  -  -  -  +----------------+ +X
                origin
                 .   '
   [scaleNeg]   .     '
               .       '
              .         '
             .           -Z
           -Y

Kind: instance method of AxisArray
Returns: number - Returns the points array with modified coordinates.

ParamTypeDescription
pointsArray.<Array.<number>>An array of [x,y,z] coordinate arrays to scale in place.
scalenumber | Array.<number>The scale factor or an [sx,sy,sz] vector array to scale in local axis, defaults to 1.
[negAxisScale]number | Array.<number>A optional scale factor or [sx,sy,sz] vector array to apply when points are in the negative local axis, defaults to scalePos.

axisArray.scaleIndexedPoints(indices, vertices, scale, [negAxisScale])

Scales a set of indexed points about a local origin and X, Y and Z axis.

Rather than the points consisting of an array of coordinates, indexed points consist of an array of indexes into a separate array of vertices.

You can use the AxisArray to set up a local origin point and re-orient the local X, Y and Z to whatever direction you want. The scale factors you provide are then applied in the direction of these local axis and about the local origin.

This method also allows you to use two separate sets of scaling factors. If you only provide one set, it will be used as the default. However, providing a second set allows you to apply a different scale when a point is on the negative side of the origin compared to the positive side.

           +Z
             +          +Y
              \         +
               \       /
                \  /\ /     [scale]
                 \/__/___
                  \ / \ /
   -X  -  -  -  -  +----------------+ +X
                origin
                 .   '
   [scaleNeg]   .     '
               .       '
              .         '
             .           -Z
           -Y

Kind: instance method of AxisArray

ParamTypeDescription
indicesArray.<number>An array of ordinal indexes to points in the vertices array.
verticesArray.<Array.<number>>An array of [x,y,z] coordinate arrays.
scalenumber | Array.<number>The scale factor or an [sx,sy,sz] vector array to scale in local axis, defaults to 1.
[negAxisScale]number | Array.<number>A optional scale factor or [sx,sy,sz] vector array to apply when points are in the negative local axis, defaults to scalePos.

axisArray.scalePointsXY(points, fromZ, toZ, scaleXY, [easing]) ⇒ Array.<Array.<number>>

Scales the shape in the local X and Y axis by an amount that varies over a range within the local Z axis.

If the from and to values are both in the range 0 to 1, then they are considered to be fractions of the size of the shape in the local Z axis. If either value is outside the range 0 to 1, then they are both considered to be in absolute model units along the axis.

If the scale is given as a single number, it represents the maximum scale at the to point on the axis, varying from 1 at the from point. If given as a [fromScale, toScale] array, you can specify the scales to use at both the from and to points. You can specify an easing function if you wish to make it a non-linear variation.

Kind: instance method of AxisArray
Returns: Array.<Array.<number>> - Returns the modified points.

ParamTypeDescription
pointsArray.<Array.<number>>An array of [x,y,z] coordinate arrays to scale in place.
fromZnumberA value on the local Z axis to start scaling from, in model units.
toZnumberA value on the local Z axis to finish scaling at, in model units.
scaleXYnumber | Array.<number>The scale at or above the to value, or a [fromScale,toScale] array, defaults to 1 (no scale).
[easing]functionAn easing function to use, defaults to linear.

axisArray.cartesianToLocal(point, [target]) ⇒ Array.<number>

Converts a 3D cartesian point in space to local coordinates.

Local coordinates are the three dimensions relative to the local origin and each of the three axis.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the target point.

ParamTypeDescription
pointArray.<number>The Cartesian point to convert to local coordinates.
[target]Array.<number>The vector array to receive the converted coordinates, defaults to a new array.

axisArray.computeBoundingBox(points) ⇒ Array.<Array.<number>>

Calculates the extents of the points in the current local axis.

Kind: instance method of AxisArray
Returns: Array.<Array.<number>> - Returns the shared computed bounding box.

ParamTypeDescription
pointsArray.<number>An array of one or more 3D point objects.

axisArray.getOrigin() ⇒ Array.<number>

Retrieves the position of the local origin of the coordinate system.

The origin is the reference position about which all other coordinates are taken.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the local origin as an [x,y,z] vector array.

axisArray.moveOrigin(dx, [dy], [dz]) ⇒ Array.<number>

Repositions the origin by a distance in each axis relative to itself.

This method allows you to move the origin within the local coordinate system. To avoid confusion, the current position is also moved to that it maintains its position relative to the origin. If you need to set the origin to a position in absolute global Cartesian coordinates, use the setOrigin() method instead.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the new origin as an [x,y,z] vector array.

ParamTypeDefaultDescription
dxnumber0The distance to move in the local X-axis.
[dy]number0The distance to move in the local Y-axis, defaults to zero.
[dz]number0The distance to move in the local Z-axis, defaults to zero.

axisArray.setOrigin(x, y, z) ⇒ Array.<number>

Repositions the origin to an absolute position in global model space.

To avoid confusion, the current position is also moved to that it maintains its position relative to the origin. If you need to set the origin to a position relative to itself, use the moveOrigin() method instead.

Kind: instance method of AxisArray
Returns: Array.<number> - Returns the new origin as an [x,y,z] vector array.

ParamTypeDefaultDescription
xnumber0The position of the origin in the global Cartesian X-axis.
ynumber0The position of the origin in the global Cartesian Y-axis.
znumber0The position of the origin in the global Cartesian Z-axis.

axisArray.setOriginAndReset([origin]) ⇒ AxisArray

Sets the origin of the local coordinate system.

This method sets both the actual and stored origin, and resets the current position to the new origin. If no argument is given, the origin will be set to the current position.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

ParamTypeDescription
[origin]Array.<number> | nullThe new origin of the local coordinate system, defaults to global origin.

axisArray.storeOrigin() ⇒ AxisArray

Stores the current origin so it can be restored at some later time.

The stored origin position is automatically stored whenever you use and od the setXXX, so the restoreOrigin() method will return the origin to that position without having to call this method. Thus, you only need to use this method if you wish to store any changes that you have made to the origin using the moveOrigin() or moveOriginTo() methods.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

axisArray.restoreOrigin() ⇒ AxisArray

Repositions the origin back to its original position.

The original origin position is the one set using the last call to the reset() method.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

axisArray.storeSnapshot() ⇒ AxisArray

Stores a copy of the current coordinate system.

The snapshot system does not use a stack and is only one level deep, so the stored snapshot will be overwritten each time the storeSnapshot() method is called. This can be useful in situations where you want to store the current state, and then restore it multiple times after a series of operations.

To restore the current coordinate system to the stored snapshot, call the restoreSnapshot() method.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

axisArray.restoreSnapshot() ⇒ AxisArray

Restores the last snapshot copy of the current coordinate system.

The snapshot system does not use a stack and is only one level deep, which means that you can call the restoreSnapshot() method multiple times to return to the last snap-shotted copy.

To create a stored snapshot of the current coordinate system, simply call the storeSnapshot() method.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

axisArray.pushState() ⇒ AxisArray

Stores the current LCS state on the stack.

NOTE: It is important that every call to pushState() has a corresponding subsequent call to popState() to ensure the stack does not grow too large and overflow.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

axisArray.peekState() ⇒ AxisArray

Sets the current coordinate system state to the last state pushed onto the stack.

NOTE: This method can only be called when bookended between calls to pushState() and popState(). It does not affect the stack in any way, so may be called any number of times to reset the current position and origin to the state they were when the last pushState() call was made.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

axisArray.popState() ⇒ AxisArray

Restores the last LCS state pushed onto the stack.

NOTE: It is important that every call to popState() have a corresponding preceding call to pushState() to ensure the stack is not empty.

Kind: instance method of AxisArray
Returns: AxisArray - Returns this LCS to support method chaining.

PD.VolumeArray

Defines a vector-array-based spatial volume of regularly-spaced data points.

Kind: static class of PD
Author: drajmarsh

new PD.VolumeArray([config], [value], [cells], [min], [max], [expansion], [threshold], [useCenter])

Creates a new vector-array-based regular 3D data grid.

ParamTypeDescription
[config]objectAn optional configuration object.
[value]anyThe value to initialise all grid cells to.
[cells]Array.<number> | numberThe number of cells in the grid, either as an array or a number.
[min]Array.<number>The [x,y,z] coordinate array of the minimum extents in each axis.
[max]Array.<number>The [x,y,z] coordinate array of the maximum extents in each axis.
[expansion]numberA fraction for the amount of the cell size to expand the extents by (0 to 1), defaults to 0.
[threshold]numberThe default threshold to generate surfaces and voxels at.
[useCenter]Array.<number> | numberWhether or not to sample values at cell centers instead of at grid points, defaults to false.

volumeArray.type : number

An arbitrary type value defined and used by the host application requirements.

Kind: instance property of VolumeArray

volumeArray.data : Float32Array

A flat array storing the values at each data point.

Kind: instance property of VolumeArray

volumeArray.threshold : number

The default value at which to generate Iso surfaces and voxel shapes, defaults to 1.

Kind: instance property of VolumeArray

volumeArray.setSize([cells], [min], [max], [expansion]) ⇒ VolumeArray

Sets the number of cells in the 3D grid and initialises data array.

Kind: instance method of VolumeArray
Returns: VolumeArray - Returns this volume instance to support method chaining.

ParamTypeDescription
[cells]Array.<number>The [x,y,z] integer array giving the number of data cells in each axis.
[min]Array.<number>The [x,y,z] coordinate array of the minimum in each axis.
[max]Array.<number>The [x,y,z] coordinate array of the maximum in each axis.
[expansion]numberA fraction of the cell size to expand extents by (0 to 1), defaults to 0.

volumeArray.setExtents(min, max, [expansion]) ⇒ VolumeArray

Sets the spatial extents of the 3D grid.

Kind: instance method of VolumeArray
Returns: VolumeArray - Returns this grid instance to support method chaining.

ParamTypeDescription
minArray.<number>The [x,y,z] coordinate array of the minimum in each axis.
maxArray.<number>The [x,y,z] coordinate array of the maximum in each axis.
[expansion]numberA fraction of the cell size to expand extents by (0 to 1), defaults to 0.

volumeArray.getDataIndex(i, j, k) ⇒ number

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by numerical index in each axis. Each coordinate is given as the index of the cell in that particular axis. An error is thrown if any index is less than zero or greater than the number of cells in that axis.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single flat array. Use this method to relate 3D model coordinates to a cell’s index in the data array.

Kind: instance method of VolumeArray
Returns: number - Returns the numeric index. Throws:

  • Error Throws an error if index is outside array bounds.
ParamTypeDescription
inumberThe X-axis index of the cell.
jnumberThe Y-axis index of the cell.
knumberThe Z-axis index of the cell.

volumeArray.getDataIndexByUVW(u, v, w) ⇒ number

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by fractional values in each axis. Each coordinate is given in the range 0 to 1, where zero means the minimum extent in each axis and one is the maximum extent.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single flat array. Use this method to relate unified relative grid coordinates to a cell’s index in the data array.

Kind: instance method of VolumeArray
Returns: number - Returns the numeric index. Throws:

  • Error Throws an error if index is outside array bounds.
ParamTypeDescription
unumberThe relative X-axis position of the cell (0 to 1).
vnumberThe relative Y-axis position of the cell (0 to 1).
wnumberThe relative Z-axis position of the cell (0 to 1).

volumeArray.getDataIndexByPos(x, y, z) ⇒ number

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by actual spatial position. Coordinates are given as an absolute position in space. An error is thrown if the position is outside the spatial extents of the grid.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single flat array. Use this method to relate actual model coordinates within a grid to a cell’s index in the data array.

Kind: instance method of VolumeArray
Returns: number - Returns the numeric index. Throws:

  • Error Throws an error if index is outside array bounds.
ParamTypeDescription
xnumberThe X-axis position of the cell.
ynumberThe Y-axis position of the cell.
znumberThe Z-axis position of the cell.

volumeArray.getDataIndexByPosArray(pos) ⇒ number

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by actual spatial position. Coordinates are given as an absolute position in space. An error is thrown if the position is outside the spatial extents of the grid.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single flat array. Use this method to relate actual model coordinates within a grid to a cell’s index in the data array.

Kind: instance method of VolumeArray
Returns: number - Returns the numeric index. Throws:

  • Error Throws an error if index is outside array bounds.
ParamTypeDescription
posArray.<number>An [x,y,z] coordinate position within the volume.

volumeArray.getData(i, j, k) ⇒ any

Retrieves the data stored for the given cell.

This method addresses the 3D grid by numerical index in each axis. Each coordinate is given as the index of the cell in that particular axis. An error is thrown if any index is less than zero or greater than the number of cells in that axis.

Kind: instance method of VolumeArray
Returns: any - Returns the data in the given cell. Throws:

  • Error Throws an error if index is outside array bounds.
ParamTypeDescription
inumberThe X-axis index of the cell.
jnumberThe Y-axis index of the cell.
knumberThe Z-axis index of the cell.

volumeArray.getDataByUVW(u, v, w) ⇒ number

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by fractional values in each axis. Each coordinate is given in the range 0 to 1, where zero means the minimum extent in each axis and one is the maximum extent.

Kind: instance method of VolumeArray
Returns: number - Returns the numeric index. Throws:

  • Error Throws an error if index is outside array bounds.
ParamTypeDescription
unumberThe relative X-axis position of the cell (0 to 1).
vnumberThe relative Y-axis position of the cell (0 to 1).
wnumberThe relative Z-axis position of the cell (0 to 1).

volumeArray.getDataByPos(x, y, z) ⇒ number

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by actual spatial position. Each coordinate is given as an absolute position in space. An error is thrown if the position is outside the spatial extents of the grid.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single 1 dimensional array. Use this method to relate 3D grid coordinates to the cell’s index in the data array.

Kind: instance method of VolumeArray
Returns: number - Returns the numeric index. Throws:

  • Error Throws an error if index is outside array bounds.
ParamTypeDescription
xnumberThe X-axis position of the cell.
ynumberThe Y-axis position of the cell.
znumberThe Z-axis position of the cell.

volumeArray.interpolateDataByPos(x, y, z) ⇒ number

Retrieves the tri-linearly interpolated value at the given position.

If the point is outside the grid extents, this method returns zero.

Kind: instance method of VolumeArray
Returns: number - Returns the interpolated value, or zero.

ParamTypeDescription
xnumberThe X-axis position of the cell.
ynumberThe Y-axis position of the cell.
znumberThe Z-axis position of the cell.

volumeArray.map(callback) ⇒ VolumeArray

Applies the given function to each cell in the grid.

In this method, the 3D grid is addressed by the numerical index of the cell in each axis.

The callback is invoked with the following four (4) arguments and must return the value it wants stored for that grid cell:

  • i: The X-axis index of the cell.
  • j: The Y-axis index of the cell.
  • k: The Z-axis index of the cell.
  • index: The index of the cell in the data array.

Kind: instance method of VolumeArray
Returns: VolumeArray - Returns this grid instance to support method chaining. Throws:

  • Error Throws an error if callback is not a valid function.
  • Error Throws an error if callback is not a valid function.
ParamTypeDescription
callbackfunctionThe function to be invoked for each cell.

volumeArray.mapByUVW(callback) ⇒ VolumeArray

Applies the given function to each cell in the grid.

In this method, the 3D grid is addressed by fractional values in each axis. Each coordinate in the callback is given in the range 0 to 1, where zero means the minimum extent in each axis and one is the maximum extent.

The callback is invoked with the following four (4) arguments and must return the value it wants stored for that grid cell:

  • u: The fractional X-axis position of the cell (0 to 1).
  • v: The fractional Y-axis position of the cell (0 to 1).
  • w: The fractional Z-axis position of the cell (0 to 1).
  • index: The index of the cell in the data array.

Kind: instance method of VolumeArray
Returns: VolumeArray - Returns this grid instance to support method chaining. Throws:

  • Error Throws an error if callback is not a valid function.
ParamTypeDescription
callbackfunctionThe function to be invoked for each cell.

volumeArray.mapByPos(callback) ⇒ VolumeArray

Applies the given function to each cell in the grid.

In this method, the 3D grid is addressed by actual spatial position. Each coordinate in the callback is given as the absolute position of the center of each cell in 3D space.

The callback is invoked with the following four (4) arguments and must return the value it wants stored for that grid cell:

  • x: The global Cartesian X-axis position of the cell.
  • y: The global Cartesian Y-axis position of the cell.
  • z: The global Cartesian Z-axis position of the cell.
  • index: The index of the cell in the data array.

Kind: instance method of VolumeArray
Returns: VolumeArray - Returns this grid instance to support method chaining. Throws:

  • Error Throws an error if callback is not a valid function.
ParamTypeDescription
callbackfunctionThe function to be invoked for each cell.

volumeArray._copySurfaceToShape(surfaces, [shape]) ⇒ Shape

Copies generate surface geometry to the given or a new shape.

Kind: instance method of VolumeArray
Returns: Shape - Returns the shape with the new iso-surface.

ParamTypeDescription
surfacesobjectThe faces and vertices to add.
[shape]ShapeThe shape to add the surface to, defaults to a new shape if not defined.

volumeArray.getSurface([type], [threshold], [shape]) ⇒ Shape

Extract a surface from the volumetric grid and add it to a given or new shape.

The type of surface created depends on the type parameter, where:

  • 0: Triangulated iso-surface (MarchingCubes),
  • 1: Polygonal iso-surface (SurfaceNet), and
  • 2: Voxelised surface.

Kind: instance method of VolumeArray
Returns: Shape - Returns shape or a new shape with the new iso-surface.

ParamTypeDescription
[type]numberThe type of surface (0:Triangular[MarchingCubes], 1:Polygonal[SurfaceNets], 2:Voxelised), defaults to 0.
[threshold]numberThe value at which to generate the iso-surface, defaults to threshold.
[shape]ShapeThe shape to add the surfaces to, defaults to a new shape if not defined.

volumeArray.getIsoSurface([threshold], [shape]) ⇒ Shape

Extracts a triangulated iso-surface at the given threshold using MarchingCubes and adds it to the given or a new shape.

Kind: instance method of VolumeArray
Returns: Shape - Returns shape or a new shape with the new iso-surface.

ParamTypeDescription
[threshold]numberThe value at which to generate the iso-surface, defaults to threshold.
[shape]ShapeThe shape to add to, defaults to a new shape if not defined.

volumeArray.getSurfaceNets([threshold], [shape]) ⇒ Shape

Extracts a polygonal surface at the given threshold using SurfaceNets and adds it to the given or a new shape.

Kind: instance method of VolumeArray
Returns: Shape - Returns shape or a new shape with the new surface.

ParamTypeDescription
[threshold]numberThe value at which to generate the iso-surface, defaults to threshold.
[shape]ShapeThe shape to add to, defaults to a new shape if not defined.

volumeArray.getVoxels([threshold], [shape]) ⇒ Shape

Extract a voxelised surface at the given threshold using adds it to the given or a new shape.

Kind: instance method of VolumeArray
Returns: Shape - Returns shape or a new shape with the new surface.

ParamTypeDescription
[threshold]numberThe value at which to generate the voxels, defaults to threshold.
[shape]ShapeThe shape to add to, defaults to a new shape if not defined.

volumeArray.copyIsoToPolyMesh(mesh, [threshold]) ⇒ boolean

Adds an iso-surface shape to a renderable mesh.

The method adds both outlines and surface data.

Kind: instance method of VolumeArray
Returns: boolean - Returns true if geometry was added to the mesh.

ParamTypeDescription
meshPD.PolyMeshThe mesh to add the polygon to.
[threshold]numberThe value at which to generate the surface.

volumeArray.copyVoxelsToPolyMesh(mesh, [threshold]) ⇒ boolean

Adds a voxelised iso-surface shape to a renderable mesh.

The method adds both outlines and surface data.

Kind: instance method of VolumeArray
Returns: boolean - Returns true if geometry was added to the mesh.

ParamTypeDescription
meshPD.PolyMeshThe mesh to add the voxels to.
[threshold]numberThe value at which to generate voxels.

volumeArray.toJSON() ⇒ object

Used by JSON.stringify to convert a complex object to a POJO.

Kind: instance method of VolumeArray
Returns: object - Returns a simpler POJO version of this object for JSON formatting.

volumeArray.toString_JSON([indent]) ⇒ string

Retrieves a JSON formatted string containing grid data.

NOTE: toJSON() is different as it returns an object rather than a string, and determines how the volume is converted to JSON.

Kind: instance method of VolumeArray
Returns: string - Returns a JSON formatted string containing volumetric grid data.

ParamTypeDescription
[indent]string | numberAn optional indent string, typically one or more spaces or tabs, or the number of spaces.

volumeArray.toString_CSV() ⇒ string

Retrieves a comma-separated value (CSV) string containing volumetric data.

Kind: instance method of VolumeArray
Returns: string - Returns a formatted string containing volumetric data.

volumeArray.toString_VOX() ⇒ string

Retrieves a string containing voxel information data.

Kind: instance method of VolumeArray
Returns: string - Returns a formatted text string containing volumetric data.

PD.VectorFont

Kind: static class of PD
Author: drajmarsh

new PD.VectorFont()

Generates text using a customisable vector-based font.

Use this class to generate lines that represent text within a model. Whilst you can also use normal fonts to generate text, this method is much more light-weight and creates an effect similar to older-style blueprints and pen-plotter output.

VectorFont.this.fontSize([value]) ⇒ number | VectorFont

Gets/sets the character size of the font in model units.

This value defaults to 100mm and is effectively the height from the bottom to top in thE local Y axis of each character.

Kind: static method of VectorFont
Returns: number | VectorFont - Returns the character size or this line font to support method chaining.

ParamTypeDescription
[value]numberAn optional new value for the font size in model units.

VectorFont.this.lineHeight([value]) ⇒ number | VectorFont

Gets/sets the vertical distance between each text line.

This value is given as a multiplier of the character size and defaults to 2.

Kind: static method of VectorFont
Returns: number | VectorFont - Returns the character size or this line font to support method chaining.

ParamTypeDescription
[value]numberAn optional new value for the line height.

VectorFont.this.averageKerning([value]) ⇒ number | VectorFont

Gets/sets the average horizontal kerning between characters. This value defaults to 1.40 times the character size.

Kind: static method of VectorFont
Returns: number | VectorFont - Returns the kerning value or this line font to support method chaining.

ParamTypeDescription
[value]numberAn optional new value for the kerning to (0.1 - 10.0).

VectorFont.this.wordSpacing([value]) ⇒ number | VectorFont

Gets/sets the horizontal spacing between words. This value defaults to 0.8 times the character size.

Kind: static method of VectorFont
Returns: number | VectorFont - Returns the word spacing or this line font to support method chaining.

ParamTypeDescription
[value]numberAn optional new value for the word spacing to (0.1 - 10.0).

VectorFont.this.aspectRatio(aspect, [charSpacing], [wordSpacing]) ⇒ VectorFont

Gets/sets the aspect ratio of text characters.

Kind: static method of VectorFont
Returns: VectorFont - Returns this line font to support method chaining.

ParamTypeDescription
aspectnumberThe aspect ratio as a decimal value (0.1 - 10.0).
[charSpacing]numberThe relative width of the spacing between each character (0.1 - 10.0).
[wordSpacing]numberThe relative width of the spacing between each word (0.1 - 10.0).

VectorFont.this.italicSlant([value]) ⇒ number | VectorFont

Gets/sets the level of italic slant in the X axis.

Kind: static method of VectorFont
Returns: number | VectorFont - Returns the italic slant or this line font to support method chaining.

ParamTypeDescription
[value]numberAn optional value to set the slant to (-1.0 to 1.0).

VectorFont.this.resetMetrics() ⇒ VectorFont

Resets all font style variable to their default values.

Kind: static method of VectorFont
Returns: VectorFont - Returns this line font to support method chaining.

VectorFont.this.getTextWidth(text) ⇒ number

Retrieves the width of the vector text within the model. The width is always given in relative units, being the effective number of characters wide.

Kind: static method of VectorFont
Returns: number - Returns the width of the text in relative units.

ParamTypeDescription
textstringThe string to calculate the width of.

VectorFont.this.generateText(text, [align], [axis]) ⇒ Array.<Array.<Array.<number>>>

Generates a series of line segments that represent the given text.

Each line segment contains two or more sequentially connected [x,y,z] vector arrays. You don’t have to worry about closed loops as any that are will automatically append their first point at the end.

Kind: static method of VectorFont
Returns: Array.<Array.<Array.<number>>> - Returns An array of line segments defining the text.

ParamTypeDescription
textstringThe text string to display. This is limited to the 7-bit ANSI character set (0-128). !"#$%&’()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`{
[align]ALIGNThe alignment of the text, defaults to 0 (LEFT aligned and sitting on baseline).
[axis]AxisArrayThe local coordinates to use for positioning and rotating the text, defaults to the origin.

Example

const vec_font = new PD.VectorFont();
const local_axis = vec_font.localAxis();
local_axis.rotateX(PD.Utils.HALF_PI);
local_axis.setOrigin(0, 0, 500);

const text_lines = vec_font.generateText('This is some text.', PD.ALIGN.CENTER);
CAD.addWires(text_lines);

PD.TimeZones

Provides utilities for looking up timezones for locations.

This class uses a detailed lookup table of latitude/longitude values to find the timezone for any location on the Earth’s surface. Timezone boundaries are not straightforward and there is no obvious algorithm for accurately determining the timezone for every part of every country. This lookup table is accurate to within 0.5deg in both latitude and longitude, which should be sufficient for most design applications.

Longitude values must be given as Eastings ain degrees. This means that longitudes to the west of the Prime Meridian are negative (America) and those to the east are positive (Europe and Asia).

Latitude values must be given as Northings in degrees. This means that latitudes south of the Equator are negative (Australia and South America) and those to the north are positive (Canada, Europe and Russia).

Kind: static class of PD
Author: drajmarsh

TimeZones.lookup(lat, lng) ⇒ number

Searches for the timezone associated with the given location.

Kind: static method of TimeZones
Returns: number - Returns a timezone offset in decimal hours.

ParamTypeDescription
latnumberThe location latitude in decimal degrees (-90 to 90).
lngnumberThe location longitude in decimal degrees (-180 to 180).

TimeZones.toStandardTimeZone(tz) ⇒ number

Converts the given timezone to a standard time zone.

A standard timezone refers to the nearest region of the world with the given UTC time offset.

Kind: static method of TimeZones
Returns: number - Returns the closest standard timezone.

ParamTypeDescription
tznumberThe selected timezone in decimal time.

TimeZones.getStandardTimeZones() ⇒ Array

Retrieves an array of standard time zone offsets.

Each item in the list is an object with a name and value property, where the name is for display and the value is in decimal hours.

Kind: static method of TimeZones
Returns: Array - Returns an array of standard time zone objects.

TimeZones.getIANA() ⇒ Array

Retrieve a list of world time zones.

Each entry in the list as a name and offset property (in decimal hours), with some also having a dst property giving daylight savings time periods.

This data is maintained by the Internet Assigned Numbers Authority (IANA) for use as a digital standard.

Kind: static method of TimeZones
Returns: Array - Returns an array of IANA timezone data.

PD.DateTime

Defines a specific data and time.

This class defaults to a standard year which always starts on a Monday and is not a leap year. If you assign it a specific year, then that may be a leap year and have an extra day.

The concept of the ‘average’ or standard year is quite important and needs some explanation. As a year with 365 days does not evenly divide into 52 weeks, each consecutive year starts on a different weekday. For example, the first day of the year in 2010 was a Friday, in 2009 it was a Thursday and in 2008 it was a Tuesday. This means that different years may contain a different number of weekends and/or holiday periods and these may occur at slightly different times within each season.

Whilst the effect of this on annual energy use is likely to be quite small, it is an arbitrary and unnecessary variation that may mask other effects that the designer is more interested in. It also presents a problem when designing annual operational or holiday schedules as these would need to be either manually edited to match each test year and locale-specific holiday sequence, or the logic required to apply generic schedules to any particular year and locale would be very complex and extensive indeed.

Thus, an ‘average’ or standard year is used, starting and finishing on a Monday. This is how dedicated energy analysis tools such as DOE-2 and EnergyPlus also work, allowing their users to arrange seven daily schedules into a set of characteristic weekly schedules, and then arrange 52 of these weekly schedules over the year.

This applies also to solar radiation calculations and daylighting where direct comparison between models or options is important without having to worry about slight variations in schedules resulting from different analysts using different years, etc.

Kind: static class of PD
Author: drajmarsh

new PD.DateTime([config], [clockTime], [dayOfMonth], [monthOfYear], [year])

Creates a new date/time value.

ParamTypeDefaultDescription
[config]objectAn optional configuration object.
[clockTime]numberAn optional local clock time, in decimal hours (0.0 to 24.0).
[dayOfMonth]numberAn optional day of the month component of the date (1 to 31).
[monthOfYear]numberAn optional month of the year component of the date (0 to 11).
[year]numberAn optional 4 digit year component of the date (-4712 to 3500).

dateTime.clockTime : number

The local clock time, in decimal hours (0.0 to 24.0).

Kind: instance property of DateTime

dateTime.dayOfYear : number

The ordinal day of the year (0 to 364/365).

Kind: instance property of DateTime

dateTime.dayOfMonth : number

The day of the month component of the date (1 to 31).

Kind: instance property of DateTime

dateTime.monthOfYear : number

The month of the year component of the date (0 to 11).

Kind: instance property of DateTime

dateTime.year : number

The 4 digit year component of the date.

Defaults to 2018, the last non-leap year starting on a Monday.

Kind: instance property of DateTime

dateTime.isDateTime : boolean

A flag identifying this object as a date/time.

Kind: instance property of DateTime
Read Only: true

dateTime.timeOfDay : number

The local clock time, in decimal hours (0.0 to 24.0).

Kind: instance property of DateTime

dateTime.toJSON([data]) ⇒ object

Converts object instance to a simple POJO for conversion to JSON.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

Kind: instance method of DateTime
Returns: object - Returns a Plain Old Javascript Object (POJO).

ParamTypeDescription
[data]objectAn optional parent object to append this data to.

dateTime.fromJSON(data, [clockTime], [dayOfMonth], [monthOfYear], [dayOfYear], [year]) ⇒ DateTime

Extracts date and/or time information from the given object.

Kind: instance method of DateTime
Returns: DateTime - Returns this date/time instance to support method chaining.

ParamTypeDescription
dataobjectAn object that might contain date/time information.
[clockTime]numberAn optional local clock time, in decimal hours (0.0 to 24.0).
[dayOfMonth]numberAn optional day of the month component of the date (1 to 31).
[monthOfYear]numberAn optional month of the year component of the date (0 to 11).
[dayOfYear]numberAn optional day of the year (0 to 364/5) that overrides the dayOfMonth and monthOfYear.
[year]numberAn optional 4 digit year component of the date (-4712 to 3500).

dateTime.setTimeOfDay(value)

Sets the local clock time, in decimal hours (0.0 to 24.0).

Kind: instance method of DateTime

ParamTypeDescription
valuenumberThe local clock time, in decimal hours (0.0 to 24.0).

dateTime.setDayOfYear(value)

Sets the day of the year (0 to 365).

Kind: instance method of DateTime

ParamTypeDescription
valuenumberThe day of the year (0 to 365).

dateTime.getDOY(dayOfMonth, monthOfYear) ⇒ number

Computes the ordinal number of the day within the year.

Kind: instance method of DateTime
Returns: number - Returns the ordinal number of the day within the year (0 to 364/5).

ParamTypeDescription
dayOfMonthnumberThe ordinal day of the month (1-31).
monthOfYearnumberThe ordinal month of the year (0-11).

dateTime.getDateAsString() ⇒ string

Generates a string with the current date.

Kind: instance method of DateTime
Returns: string - Returns a string with the date in ‘dd mmm’ format.

dateTime.copy(from) ⇒ DateTime

Copy the given date/time to this date/time.

Kind: instance method of DateTime
Returns: DateTime - Returns this date/time instance to support method chaining.

ParamTypeDescription
fromDateTimeAnother date/time instance to copy from.

dateTime.updateDate() ⇒ DateTime

Update the month of the year and day of the month from the current day of the year.

Kind: instance method of DateTime
Returns: DateTime - Returns this date/time instance to support method chaining.

DateTime.DAY_INDEX : Array.<number>

An array containing the ordinal index of the first day of each month in a non-leap year.

Kind: static property of DateTime

DateTime.DAY_INDEX_LEAP_YEAR : Array.<number>

An array containing the ordinal index of the first day of each month in a leap year.

Kind: static property of DateTime

DateTime.MONTH_NAMES : Array.<string>

An array containing full month names.

Kind: static property of DateTime

DateTime.MONTH_NAMES_SHORT : Array.<string>

An array containing abbreviated month names.

Kind: static property of DateTime

DateTime.MONTH_NAMES_LETTER : Array.<string>

An array containing just the first letter of each month name.

Kind: static property of DateTime

DateTime.DAYS_IN_MONTH : Array.<number>

An array containing the number of days in each month in a non-leap year.

Kind: static property of DateTime

DateTime.getSiteTime() ⇒ DateTime

Retrieves the global date and time used for the current site.

This method returns the PD.GlobalState.dateTime object that is used by several other classes as the default date/time for the current site.

Kind: static method of DateTime
Returns: DateTime - Returns the global date and time object.

DateTime.JSONSchema() ⇒ object

Retrieves the JSON schema for a date/time object.

Kind: static method of DateTime
Returns: object - Returns a JSON schema object.

DateTime.isBetweenDayRange(dayOfYear, range1, range1) ⇒ boolean

Determines if the given day of the year is within the given range.

This method automatically sorts out whether the range passes over year start/end or is entirely within the bounds of the year.

Kind: static method of DateTime
Returns: boolean - Returns tru if the day is within the range, otherwise false.

ParamTypeDescription
dayOfYearnumberThe ordinal day of the year (0-364/5).
range1numberThe ordinal day of the first range bounds (0-364/5).
range1numberThe ordinal day of the second range bounds (0-364/5).

DateTime.isLeapYear(year) ⇒ boolean

Whether or not the specified year is a leap year.

Kind: static method of DateTime
Returns: boolean - Returns true if the year is a leap year.

ParamTypeDescription
yearnumberA four-digit year number (eg: 2010).

DateTime.getDOY(dayOfMonth, month_of_year, [year]) ⇒ number

Calculate the ordinal number of the day within the year (0-364/5).

Kind: static method of DateTime
Returns: number - Returns the ordinal number of the day within the year (0-364/5).

ParamTypeDescription
dayOfMonthnumberThe ordinal day of the month (1-31).
month_of_yearnumberThe ordinal month of the year (0-11).
[year]numberAn optional four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.getDayAndMonth(dayOfYear, [year]) ⇒ object

Returns an object containing day (1-31) and month (0-11) properties.

Kind: static method of DateTime
Returns: object - Returns an object with day (1-31) and month (0-11) properties.

ParamTypeDescription
dayOfYearnumberThe ordinal day of the year (0-364/5).
[year]numberAn optional four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.getDaysInMonth(monthOfYear, [year]) ⇒ string

Retrieves the number of days in the given month.

If the given month is outside the range zero to eleven, this method will return zero.

Kind: static method of DateTime
Returns: string - Returns a string with the first letter of the month name.

ParamTypeDescription
monthOfYearnumberThe ordinal month of the year (0-11).
[year]numberAn optional four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.getMonthName(monthOfYear) ⇒ string

Retrieves the abbreviated name of the given month.

Kind: static method of DateTime
Returns: string - Returns a string with the abbreviated month name.

ParamTypeDescription
monthOfYearnumberThe ordinal month of the year (0-11).

DateTime.getMonthNameFull(monthOfYear) ⇒ string

Retrieves the full name of the given month.

Kind: static method of DateTime
Returns: string - Returns a string with the full month name.

ParamTypeDescription
monthOfYearnumberThe ordinal month of the year (0-11).

DateTime.getMonthNameLetter(monthOfYear) ⇒ string

Retrieves the first letter of the given month name.

Kind: static method of DateTime
Returns: string - Returns a string with the first letter of the month name.

ParamTypeDescription
monthOfYearnumberThe ordinal month of the year (0-11).

DateTime.generateDateAsFileNameSuffix([date]) ⇒ string

Generates a string of the form ‘2016-12-31-2359’ based on the system date time.

This is primarily used as a file name suffix for uniquely identifying temporary files and automatically named exports.

Kind: static method of DateTime
Returns: string - Returns a string with the year, month, day and time.

ParamTypeDescription
[date]objectAn optional Javascript Date() object, defaults to current date/time.

DateTime.getDayOfTheWeek(dayOfMonth, monthOfYear, [year]) ⇒ number

Returns the day of the week index for the given day, month and year.

The day of the week index refers to Monday(0), Tuesday(1), Wednesday(2), Thursday(3), Friday(4), Saturday(5) and Sunday(6). This differs from the standard JavaScript Date.getDay() method which assumes the week starts on a Sunday. In order to group weekends and public holidays, most analysis tools use Monday as the first day of the week and Sunday as the last.

Kind: static method of DateTime
Returns: number - Returns the day of the week (0 to 6).

ParamTypeDescription
dayOfMonthnumberThe day of the month (1–31).
monthOfYearnumberThe month of the year (0–11).
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.snapToNearestMonth(dayOfYear, [year]) ⇒ number

Returns the ordinal day of the year index at the start of the closest month.

Kind: static method of DateTime
Returns: number - Returns the ordinal number of the day within the year (0-364/5).

ParamTypeDescription
dayOfYearnumberThe ordinal day of the year (0-364/5).
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.getNearestMonth(dayOfYear, [year]) ⇒ number

Returns the index of the month the given day is in.

Kind: static method of DateTime
Returns: number - Returns the ordinal number of the month within the year (0-11).

ParamTypeDescription
dayOfYearnumberThe ordinal day of the year (0-364/5).
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.getMonthStartDay(monthOfYear, [year]) ⇒ number

Retrieves the ordinal index of the start of the given month within the year.

Kind: static method of DateTime
Returns: number - Returns the ordinal number of the day within the year (0-364/5).

ParamTypeDescription
monthOfYearnumberThe ordinal month of the year (0-11).
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.getMonthEndDay(monthOfYear, [year]) ⇒ number

Retrieves the ordinal index of the end of the given month within the year.

Kind: static method of DateTime
Returns: number - Returns the ordinal number of the day within the year (0-364/5).

ParamTypeDescription
monthOfYearnumberThe ordinal month of the year (0-11).
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.getDayIndexArray([year]) ⇒ Array

Retrieves an array of ordinal day indexes for each month of the year.

NOTE: The reason for using this method is that day indices of each month after February will change during a leap year, so this method returns a different array if it detects that the given year is a leap year.

Kind: static method of DateTime
Returns: Array - Returns an array of 12 day indices.

ParamTypeDescription
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.getDaysInYear([year]) ⇒ number

Retrieves the number of days in the year.

NOTE: The reason for using this method is that the number of days in a leap year are different than a normal year, so this method returns 366 instead of 365 if it detects that the given year is a leap year.

Kind: static method of DateTime
Returns: number - Returns the total number of days in the year (365 or 366).

ParamTypeDescription
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.incrementDate(event, increment, dayOfYear, [year]) ⇒ number

Returns the day of the year index incremented by the given value.

This method checks the event/key value to adjust the number of days to increment by, based on sensible defaults.

Kind: static method of DateTime
Returns: number - Returns the ordinal number of the day within the year (0-364/5).

ParamTypeDescription
eventobject | KEYA mouse wheel/scroll event, or modifier key code.
incrementnumberThe amount of increment, positive or negative.
dayOfYearnumberThe ordinal day of the year (0-364/5).
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.incrementEvenlyOverMonth(increment, dayOfMonth, monthOfYear, [year]) ⇒ number

Returns the day of the year index incremented by an even amount each month.

This method tries to start and end the incremented values exactly on month boundaries. If the increment is 3 days, then there are awkward single day steps at the end of each month that contains 31 days. If the increment is close to 4 days (and sometimes 3), then the steps are better, even when a month has just 28 days.

Kind: static method of DateTime
Returns: number - Returns the ordinal number of the day within the year (0-364/5).

ParamTypeDescription
incrementnumberThe amount of increment, positive or negative.
dayOfMonthnumberThe ordinal index of the day in the month (0-31).
monthOfYearnumberThe ordinal index of the month in the year (0-11).
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.formatDate(dayOfYear, [year], [includeYear]) ⇒ string

Returns a string with the given day of the year in ‘dd mmm’ format.

If a valid year value is given and the include_year argument is true, it returns a string in ‘dd mmm YYYY’ format.

Some example returns would be 01 Jan, 15 Apr or 25 Dec. If the year is included, example returns would be 01 Jan 2014, 15 Apr 2015 or 25 Dec 2016.

Kind: static method of DateTime
Returns: string - Returns a formatted date string.

ParamTypeDefaultDescription
dayOfYearnumberThe ordinal day of the year (0-364/5).
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.
[includeYear]booleanfalseWhether or not to include the year, if given.

DateTime.formatAsMMMDD(dayOfYear, [year]) ⇒ string

Returns a string with the given day of the year in ‘mmmdd’ format.

This is mainly used in charts and graphs where space is limited. Some example returns would be Jan01, Apr15 or Dec25.

Kind: static method of DateTime
Returns: string - Returns a formatted date string.

ParamTypeDescription
dayOfYearnumberThe ordinal day of the year (0-364/5).
[year]numberA four-digit year number (eg: 2010), defaults to a non-leap year.

DateTime.formatMonthName(monthOfYear) ⇒ string

Returns a string with the given month abbreviation.

Some example returns would be Jan, Apr or Dec.

Kind: static method of DateTime
Returns: string - Returns a formatted month name string.

ParamTypeDescription
monthOfYearnumberThe ordinal month of the year (0-11).

DateTime.formatTime(clockTime, [seconds]) ⇒ string

Returns a string with the given time in ‘HH:mm’ or ‘HH:mm:ss’ format.

Kind: static method of DateTime
Returns: string - Returns the formatted time string.

ParamTypeDefaultDescription
clockTimenumberThe local time of the day, in decimal hours (0-24).
[seconds]booleanfalseWhen true it displays seconds value, otherwise just rounds to nearest minute.

DateTime.formatDuration(decimalHours, [seconds]) ⇒ string

Returns a string with the given duration in ‘HH:mm’ or ‘HH:mm:ss’ format.

Kind: static method of DateTime
Returns: string - Returns the formatted duration string.

ParamTypeDefaultDescription
decimalHoursnumberThe duration, in decimal hours.
[seconds]booleanfalseWhen true it displays seconds value, otherwise just rounds to nearest minute.

DateTime.formatTimezone(decimalHours) ⇒ string

Returns a string with the given duration in ‘±HH:mm’ or ‘±HH:mm:ss’ format.

Kind: static method of DateTime
Returns: string - Returns the formatted timezone.

ParamTypeDescription
decimalHoursnumberThe time period, in decimal hours (-14 to +14), defaults to current timezone.

DateTime.formatMilliseconds(ms, [decimals]) ⇒ string

Returns a string with formatted milliseconds.

Kind: static method of DateTime
Returns: string - Returns the formatted duration string.

ParamTypeDescription
msnumberThe duration in milliseconds.
[decimals]numberThe number of decimal places to show, defaults to 3.

DateTime.parseTime(timeString) ⇒ Date

Utility for more permissive time parsing.

This method should work with all of the following and more:

1:00 pm, 1:00 p.m., 1:00 p, 1:00pm, 1:00p.m., 1:00p, 1 pm, 1 p.m., 1 p, 1pm, 1p.m., 1p, 13:00 or even 13 and 1300.

Kind: static method of DateTime
Returns: Date - Returns a standard Date object with the parsed hours and minutes.

ParamTypeDescription
timeStringstringA string containing some variant of a time specification.

DateTime.parseTimeToDecimalHours(timeString) ⇒ number

Utility for permissive time parsing to decimal hours in the range 0 to 24.

This method should work with all of the following and more:

1:00 pm, 1:00 p.m., 1:00 p, 1:00pm, 1:00p.m., 1:00p, 1 pm, 1 p.m., 1 p, 1pm, 1p.m., 1p, 13:00 or even 13 and 1300.

Kind: static method of DateTime
Returns: number - Returns a numerical value representing decimal hours in the range 0 to 24.

ParamTypeDescription
timeStringstringA string containing some variant of a time specification.

PD.DateTimeRange

A class that specified some period of the year and times of the day.

Kind: static class of PD
Author: drajmarsh

new PD.DateTimeRange([config], [fromDay], [toDay], [fromTime], [toTime], [timeStep], [sunriseToSunset], [solar], [solar])

Create a new date/time range instance.

ParamTypeDescription
[config]objectA configuration object with the following properties.
[fromDay]numberThe day of the year to start calculating, inclusive (0 to 365/6).
[toDay]numberThe day of the year to end calculating, inclusive (0 to 365/6).
[fromTime]numberThe hour of each day to start calculating, in decimal hours (0.0 to 24.0).
[toTime]numberThe hour of each day to stop calculating, in decimal hours (0.0 to 24.0).
[timeStep]numberThe fractional hour for each calculation step (0 to 1).
[sunriseToSunset]booleanWhether or not to use daily sunrise and sunset as from/to times, defaults to false.
[solar]numberThe solar position to copy the location data from, if not given as an argument.
[solar]SolarPositionIf not part of config, the solar position to copy the location data from.

Example

let day, hour;
let sunrise, sunset;
const period = new PD.DateTimeRange({
    fromDay: 91,
    toDay: 187,
    fromTime: 9.0,
    toTime: 17.5,
    timeStep: 10 / 60.0,
    solar: solar
});

period.sanityCheck();

const from_day = period.fromDay;
const to_day = period.toDay;
if (from_day > to_day) {
    period.toDay += period.daysInTheYear;
}

const from_time = period.fromTime;
const to_time = period.toTime;
if (from_time > to_time) {
    to_time += 24.0;
}

for (let dd = from_day; dd <= to_day; ++dd) {

    /// Check to wrap day-of-year index.
    day = (dd >= period.daysInTheYear) ? dd - period.daysInTheYear : dd;
    solar.setDayOfYear(day);

    /// Get sunrise and sunset times.
    sunrise = solar.sunriseTime();
    sunset = solar.sunsetTime();

    for (let tt = from_time; tt < to_time; tt += period.timeStep) {

        /// Check to wrap clock time.
        hour = (tt >= 24.0) ? tt - 24.0 : tt;
        if ((hour >= sunrise) && (hour < sunset)) {

           solar.setTimeOfDay(hour);

           /// TODO: Do stuff..

         }

     }

 }

dateTimeRange.fromDay : number

The ordinal day of the year the period starts.

Kind: instance property of DateTimeRange

dateTimeRange.toDay : number

The ordinal day of the year the period ends.

Kind: instance property of DateTimeRange

dateTimeRange.fromTime : number

The starting time of day, in decimal hours.

Kind: instance property of DateTimeRange

dateTimeRange.toTime : number

The ending time of day, in decimal hours.

Kind: instance property of DateTimeRange

dateTimeRange.timeStep : number

The incremental time step, in decimal hours (1/60 to 24.0).

Kind: instance property of DateTimeRange

dateTimeRange.sunriseToSunset : boolean

Whether or not to use daily sunrise and sunset as from/to times.

Kind: instance property of DateTimeRange

dateTimeRange.daysInTheYear : number

Stores the number of days in the current year (365 or 366).

Kind: instance property of DateTimeRange

dateTimeRange.solar : SolarPosition

Stores the solar position object used to check days in the year.

Kind: instance property of DateTimeRange

dateTimeRange.isDateTimeRange : boolean

A flag identifying this object as a date/time range.

Kind: instance property of DateTimeRange
Read Only: true

dateTimeRange.toJSON([data]) ⇒ object

Converts object instance to a simple POJO for conversion to JSON.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

Kind: instance method of DateTimeRange
Returns: object - Returns a Plain Old Javascript Object (POJO).

ParamTypeDescription
[data]objectAn optional parent object to append this data to.

dateTimeRange.fromJSON(data, [clockTime], [dayOfMonth], [monthOfYear], [dayOfYear], [year]) ⇒ DateTime

Extracts date and/or time information from the given object.

Kind: instance method of DateTimeRange
Returns: DateTime - Returns this date/time instance to support method chaining.

ParamTypeDescription
dataobjectAn object that might contain date/time information.
[clockTime]numberAn optional local clock time, in decimal hours (0.0 to 24.0).
[dayOfMonth]numberAn optional day of the month component of the date (1 to 31).
[monthOfYear]numberAn optional month of the year component of the date (0 to 11).
[dayOfYear]numberAn optional day of the year (0 to 364/5) that overrides the dayOfMonth and monthOfYear.
[year]numberAn optional 4 digit year component of the date (-4712 to 3500).

dateTimeRange.sanityCheck([solar]) ⇒ DateTimeRange

Checks the period data and ensures that values are reasonable and within range.

Kind: instance method of DateTimeRange
Returns: DateTimeRange - Returns this date/time range object to support method chaining.

ParamTypeDescription
[solar]SolarPositionAn optional solar position object to check for a leap year.

dateTimeRange.set(config, [fromDay], [toDay], [fromTime], [toTime], [timeStep], [sunriseToSunset], [solar], [solar]) ⇒ DateTimeRange

Initialises the information required for a calculation.

Kind: instance method of DateTimeRange
Returns: DateTimeRange - Returns this date/time range object to support method chaining.

ParamTypeDescription
configobjectA configuration object with the following properties.
[fromDay]numberThe day of the year to start calculating, inclusive (0 to 365/6).
[toDay]numberThe day of the year to end calculating, inclusive (0 to 365/6).
[fromTime]numberThe hour of each day to start calculating, in decimal hours (0.0 to 24.0).
[toTime]numberThe hour of each day to stop calculating, in decimal hours (0.0 to 24.0).
[timeStep]numberThe fractional hour for each calculation step (0 to 1).
[sunriseToSunset]booleanWhether or not to use daily sunrise and sunset as from/to times, defaults to false.
[solar]numberAn optional solar position to check for a leap year, if not given as an argument.
[solar]SolarPositionIf not part of options, the solar position to check for a leap year.

PD.DateTimeIterator ⇐ DateTimeRange

A class to iterate over a date/time range.

Kind: static class of PD
Extends: DateTimeRange
Author: drajmarsh

new PD.DateTimeIterator([config], [fromDay], [toDay], [fromTime], [toTime], [timeStep], [callbackCalculate], [callbackOnTimeout], [callbackOnComplete], [solar], [solar])

Create a new date/time iterator.

ParamTypeDescription
[config]objectA configuration object with the following properties.
[fromDay]numberThe day of the year to start calculating, inclusive (0 to 365/6).
[toDay]numberThe day of the year to end calculating, inclusive (0 to 365/6).
[fromTime]numberThe hour of each day to start calculating, in decimal hours (0.0 to 24.0).
[toTime]numberThe hour of each day to stop calculating, in decimal hours (0.0 to 24.0).
[timeStep]numberThe fractional hour for each calculation step (0 to 1).
[callbackCalculate]functionA function called on each iteration with (iterator, options) as parameters.
[callbackOnTimeout]functionA function called on each timeout with (iterator, options) as parameters.
[callbackOnComplete]functionA function called when all the iterations are complete, with just (options) as its parameter.
[solar]numberThe solar position to copy the location data from, if not given as an argument.
[solar]SolarPositionIf not part of options, the solar position to copy the location data from.

dateTimeIterator.dayStartsAt : number

The time that sunrise occurs on the current day.

Kind: instance property of DateTimeIterator

dateTimeIterator.dayEndsAt : number

The time that sunset occurs on the current day.

Kind: instance property of DateTimeIterator

dateTimeIterator.currentTime : number

The current time on the current day, when in progress.

Kind: instance property of DateTimeIterator

dateTimeIterator.currentDay : number

The current ordinal day of the year, when in progress.

Kind: instance property of DateTimeIterator

dateTimeIterator.progressMax : number

The total number of days in the period, when in progress.

Kind: instance property of DateTimeIterator

dateTimeIterator.progress : number

The current number of days already processed, when in progress.

Kind: instance property of DateTimeIterator

dateTimeIterator.cancelled : boolean

Whether or not to cancel processing.

Kind: instance property of DateTimeIterator

dateTimeIterator.working : boolean

Whether or not the range is currently being processed.

Kind: instance property of DateTimeIterator

dateTimeIterator.iterator : DateTimeIterator

Allow this to be its own iterator when used with throttled calculations.

Kind: instance property of DateTimeIterator

dateTimeIterator.callbackCalculate : function

A function called on each iteration with (iterator, options) as parameters.

Kind: instance property of DateTimeIterator

dateTimeIterator.callbackOnTimeout : function

A function called on each timeout with (iterator, options) as parameters.

Kind: instance property of DateTimeIterator

dateTimeIterator.callbackOnComplete : function

A function called when all the iterations are complete, with just (options) as its parameter.

Kind: instance property of DateTimeIterator

dateTimeIterator.isDateTimeIterator : boolean

A flag identifying this object as a date/time range iterator.

Kind: instance property of DateTimeIterator
Read Only: true

dateTimeIterator.fromDay : number

The ordinal day of the year the period starts.

Kind: instance property of DateTimeIterator Overrides: fromDay

dateTimeIterator.toDay : number

The ordinal day of the year the period ends.

Kind: instance property of DateTimeIterator Overrides: toDay

dateTimeIterator.fromTime : number

The starting time of day, in decimal hours.

Kind: instance property of DateTimeIterator Overrides: fromTime

dateTimeIterator.toTime : number

The ending time of day, in decimal hours.

Kind: instance property of DateTimeIterator Overrides: toTime

dateTimeIterator.timeStep : number

The incremental time step, in decimal hours (1/60 to 24.0).

Kind: instance property of DateTimeIterator Overrides: timeStep

dateTimeIterator.sunriseToSunset : boolean

Whether or not to use daily sunrise and sunset as from/to times.

Kind: instance property of DateTimeIterator Overrides: sunriseToSunset

dateTimeIterator.daysInTheYear : number

Stores the number of days in the current year (365 or 366).

Kind: instance property of DateTimeIterator Overrides: daysInTheYear

dateTimeIterator.solar : SolarPosition

Stores the solar position object used to check days in the year.

Kind: instance property of DateTimeIterator Overrides: solar

dateTimeIterator.isDateTimeRange : boolean

A flag identifying this object as a date/time range.

Kind: instance property of DateTimeIterator Overrides: isDateTimeRange
Read Only: true

dateTimeIterator.reset(config, [fromDay], [toDay], [fromTime], [toTime], [timeStep], [solar], [solar]) ⇒ DateTimeIterator

(Re)Initialises the information required for a iterative calculation.

Kind: instance method of DateTimeIterator
Returns: DateTimeIterator - Returns this iterator to support method chaining.

ParamTypeDescription
configobjectA configuration object with the following properties.
[fromDay]numberThe day of the year to start calculating, inclusive (0 to 365/6).
[toDay]numberThe day of the year to end calculating, inclusive (0 to 365/6).
[fromTime]numberThe hour of each day to start calculating, in decimal hours (0.0 to 24.0).
[toTime]numberThe hour of each day to stop calculating, in decimal hours (0.0 to 24.0).
[timeStep]numberThe fractional hour for each calculation step (0 to 1).
[solar]numberThe solar position to copy the location data from, if not given as an argument.
[solar]SolarPositionIf not part of options, the solar position to copy the location data from.

dateTimeIterator.next() ⇒ DateTimeIterator | null

Increments to the next iteration.

Kind: instance method of DateTimeIterator
Returns: DateTimeIterator | null - Returns this iterator to continue, or null to cancel or when complete.

dateTimeIterator.getProgress() ⇒ number

Retrieves the current progress as a fraction (0 to 1).

Kind: instance method of DateTimeIterator
Returns: number - Returns the current progress as a fraction (0 to 1).

dateTimeIterator.toJSON([data]) ⇒ object

Converts object instance to a simple POJO for conversion to JSON.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

Kind: instance method of DateTimeIterator Overrides: toJSON
Returns: object - Returns a Plain Old Javascript Object (POJO).

ParamTypeDescription
[data]objectAn optional parent object to append this data to.

dateTimeIterator.fromJSON(data, [clockTime], [dayOfMonth], [monthOfYear], [dayOfYear], [year]) ⇒ DateTime

Extracts date and/or time information from the given object.

Kind: instance method of DateTimeIterator Overrides: fromJSON
Returns: DateTime - Returns this date/time instance to support method chaining.

ParamTypeDescription
dataobjectAn object that might contain date/time information.
[clockTime]numberAn optional local clock time, in decimal hours (0.0 to 24.0).
[dayOfMonth]numberAn optional day of the month component of the date (1 to 31).
[monthOfYear]numberAn optional month of the year component of the date (0 to 11).
[dayOfYear]numberAn optional day of the year (0 to 364/5) that overrides the dayOfMonth and monthOfYear.
[year]numberAn optional 4 digit year component of the date (-4712 to 3500).

dateTimeIterator.sanityCheck([solar]) ⇒ DateTimeRange

Checks the period data and ensures that values are reasonable and within range.

Kind: instance method of DateTimeIterator Overrides: sanityCheck
Returns: DateTimeRange - Returns this date/time range object to support method chaining.

ParamTypeDescription
[solar]SolarPositionAn optional solar position object to check for a leap year.

dateTimeIterator.set(config, [fromDay], [toDay], [fromTime], [toTime], [timeStep], [sunriseToSunset], [solar], [solar]) ⇒ DateTimeRange

Initialises the information required for a calculation.

Kind: instance method of DateTimeIterator Overrides: set
Returns: DateTimeRange - Returns this date/time range object to support method chaining.

ParamTypeDescription
configobjectA configuration object with the following properties.
[fromDay]numberThe day of the year to start calculating, inclusive (0 to 365/6).
[toDay]numberThe day of the year to end calculating, inclusive (0 to 365/6).
[fromTime]numberThe hour of each day to start calculating, in decimal hours (0.0 to 24.0).
[toTime]numberThe hour of each day to stop calculating, in decimal hours (0.0 to 24.0).
[timeStep]numberThe fractional hour for each calculation step (0 to 1).
[sunriseToSunset]booleanWhether or not to use daily sunrise and sunset as from/to times, defaults to false.
[solar]numberAn optional solar position to check for a leap year, if not given as an argument.
[solar]SolarPositionIf not part of options, the solar position to check for a leap year.

PD.Location

Defines a terrestrial location on the Earth’s surface.

The primary components of a terrestrial location are its latitude, longitude, timezone and North offset angle. An elevation can also be specified, but this has only a minimal effect on solar and energy calculations.

Kind: static class of PD
Author: drajmarsh

new PD.Location([config], [latitude], [longitude], [timezone], [northAngle], [elevation])

Creates a terrestrial location on the Earth’s surface.

NOTE: This defaults to Greenwich Royal Observatory in England.

ParamTypeDescription
[config]objectAn optional configuration object.
[latitude]numberAn optional geographic latitude above the equator, in decimal degrees (-90 to 90).
[longitude]numberAn optional geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
[timezone]numberAn optional local time zone at the current location, in decimal hours.
[northAngle]numberAn optional angle between north and the +Y axis, in decimal degrees.
[elevation]numberAn optional average height of the site above sea level, in metres.

location.latitude : number

The terrestrial latitude of the current location, in decimal degrees.

Kind: instance property of Location

location.longitude : number

The terrestrial longitude of the current location, in decimal degrees.

Kind: instance property of Location

location.timezone : number

The local time zone at the current location, in decimal hours.

Kind: instance property of Location

location.northAngle : number

The angle between north and the +Y axis, in decimal degrees.

Kind: instance property of Location

location.elevation : number

The average height of the site above sea level, in metres.

Kind: instance property of Location

location.isLocation : boolean

A flag identifying this object as a location.

Kind: instance property of Location
Read Only: true

location.toJSON([data]) ⇒ object

Converts object instance to a simple POJO for conversion to JSON.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

Kind: instance method of Location
Returns: object - Returns a Plain Old Javascript Object (POJO).

ParamTypeDescription
[data]objectAn optional parent object to append this data to.

location.fromJSON(data, [latitude], [longitude], [timezone], [northAngle], [elevation]) ⇒

Extracts location information from the given object.

Kind: instance method of Location
Returns: Returns true if any matching data was found, or false if nothing was copied.

ParamTypeDescription
dataobjectAn object that might contain location information.
[latitude]numberAn optional terrestrial latitude of the current location, in decimal degrees.
[longitude]numberAn optional terrestrial longitude of the current location, in decimal degrees.
[timezone]numberAn optional local time zone at the current location, in decimal hours
[northAngle]numberAn optional angle between north and the +Y axis, in decimal degrees.
[elevation]numberAn optional average height of the site above sea level, in metres.

location.copy(from) ⇒ Location

Copy the given location to this location.

Kind: instance method of Location
Returns: Location - Returns this location instance to support method chaining.

ParamTypeDescription
fromLocationAnother location instance to copy from.

location.set(latitude, longitude, timezone) ⇒ Location

Sets the geographic location to calculate solar positions for.

Kind: instance method of Location
Returns: Location - Returns this solar calculator to support method chaining.

ParamTypeDescription
latitudenumberThe geographic latitude above the equator, in decimal degrees (-90 to 90).
longitudenumberThe geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
timezonenumberThe difference between local time at the location and UTC, in decimal hours (-13.0 to 13.0). The value should be positive for all time zone behind/east of UTC and negative for ahead/west.

location.closeTo(latitude, longitude, [timezone]) ⇒ boolean

Determines if this location is sufficiently close to the given location to be considered effectively equal.

This method checks if the given latitude and longitude values are within 1e-6 degrees of this location, and that the timezone (if given) is within 1 minute of this location’s timezone. A threshold of 1e-6 degrees represents a terrestrial distance of about 0.1 metre (4 inches) at sea level.

Kind: instance method of Location
Returns: boolean - Returns true if the given values are very close (within 1e-6 degrees).

ParamTypeDescription
latitudenumberThe geographic latitude above the equator, in decimal degrees (-90 to 90).
longitudenumberThe geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
[timezone]numberThe timezone in decimal hours (-12 to +13), ignored if not given.

location.distanceTo(loc) ⇒ number

Estimates the terrestrial distance to the given location on the Earth’s surface.

This uses the static terrestrialDistance method which is based on the haversine formula for calculating the great-circle distance between two given terrestrial locations. This is basically the shortest distance over the Earth’s surface ‘as-the-crow-flies’ between the two locations, ignoring any hills or valleys they may fly over.

Kind: instance method of Location
Returns: number - Returns the computed distance ‘as-the-crow-flies’ over the Earth’s surface, in metres.

ParamTypeDescription
locLocationThe target location.

location.distanceToLatLng(latitude, longitude) ⇒ number

Estimates the terrestrial distance to the given location on the Earth’s surface.

This uses the static terrestrialDistance method which is based on the haversine formula for calculating the great-circle distance between two given terrestrial locations. This is basically the shortest distance over the Earth’s surface ‘as-the-crow-flies’ between the two locations, ignoring any hills or valleys they may fly over.

Kind: instance method of Location
Returns: number - Returns the computed distance ‘as-the-crow-flies’ over the Earth’s surface, in metres.

ParamTypeDescription
latitudenumberThe target geographic latitude above the equator, in decimal degrees (-90 to 90).
longitudenumberThe target geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).

Location.getSiteLocation() ⇒ Location

Retrieves the global geographic location used for the current site.

This method returns the PD.GlobalState.location object that is used by several other classes as the default location for the current site.

Kind: static method of Location
Returns: Location - Returns the global default site location object.

Location.JSONSchema() ⇒ object

Retrieves the JSON schema for a location object.

Kind: static method of Location
Returns: object - Returns a JSON schema object.

Location.computeTimezone(latitude, longitude) ⇒ number

Calculates a time zone from geographic location.

This method checks for TimeZones and, if available, does a detailed lookup. If not available, it does a simple estimation based only on longitude.

Kind: static method of Location
Returns: number - Returns the difference between local time at the location and UTC in decimal hours (-13 to +13),

ParamTypeDescription
latitudenumberThe geographic latitude above the equator, in decimal degrees (-90 to 90).
longitudenumberThe geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).

Location.terrestrialDistance(lat1, lng1, lat2, lng2) ⇒ number

Estimates the terrestrial distance between the two locations on the Earth’s surface.

This uses the haversine formula to calculate the great-circle distance between two given terrestrial locations. This is basically the shortest distance over the Earth’s surface ‘as-the-crow-flies’ between the two locations, ignoring any hills or valleys they may fly over.

Kind: static method of Location
Returns: number - Returns the computed distance ‘as-the-crow-flies’ over the Earth’s surface, in metres. See: https://www.movable-type.co.uk/scripts/latlong.html

ParamTypeDescription
lat1numberThe start geographic latitude above the equator, in decimal degrees (-90 to 90).
lng1numberThe start geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).
lat2numberThe end geographic latitude above the equator, in decimal degrees (-90 to 90).
lng2numberThe end geographic longitude west of the prime meridian, in decimal degrees (-180 to 180).

PD.SolarPosition

Creates a terrestrial solar position calculator.

This class calculates the position of the Sun relative to a horizontal plane positioned at a specific location on the surface of the Earth.

Kind: static class of PD
Author: drajmarsh

new PD.SolarPosition([config], [latitude], [longitude], [timezone], [northAngle], [interpolateDeclination], [clockTime], [dayOfMonth], [monthOfYear], [year])

Creates a terrestrial solar position calculator.

ParamTypeDescription
[config]objectAn optional configuration object.
[latitude]numberThe terrestrial latitude, in decimal degrees.
[longitude]numberThe terrestrial longitude, in decimal degrees.
[timezone]numberThe local time zone at the location, in decimal hours.
[northAngle]numberThe angle between north and the +Y axis, in clockwise decimal degrees.
[interpolateDeclination]booleanWhether or not to interpolate declinations over each day.
[clockTime]numberAn optional local clock time, in decimal hours (0.0 to 24.0).
[dayOfMonth]numberAn optional day of the month component of the date (1 to 31).
[monthOfYear]numberAn optional month of the year component of the date (0 to 11).
[year]numberAn optional 4 digit year component of the date (-4712 to 3500).

solarPosition.isSolarPosition : boolean

A flag identifying this object as a solar position calculator.

Kind: instance property of SolarPosition
Read Only: true

solarPosition.latitudeInDegrees : number

The geographic latitude relative to the equator, in decimal degrees (-89.9 to 89.9).

Kind: instance property of SolarPosition

solarPosition.latitudeInRadians : number

The geographic latitude relative to the equator, in radians (-PI/2 to PI/2).

Kind: instance property of SolarPosition

solarPosition.longitudeInDegrees : number

The geographic longitude relative to the prime meridian, in decimal degrees (-180 to 180).

Kind: instance property of SolarPosition

solarPosition.longitudeInRadians : number

The geographic longitude relative to the prime meridian, in radians (-PI to PI).

Kind: instance property of SolarPosition

solarPosition.timezone : number

The local time zone offset from UTC, in decimal hours (-14.0 to 14.0).

Kind: instance property of SolarPosition

solarPosition.northAngleInDegrees : number

The angle of North in a clockwise direction from the positive Y angle, in decimal degrees (-180 to 180).

Kind: instance property of SolarPosition

solarPosition.northAngleInRadians : number

The angle of North in a clockwise direction from the positive Y angle, in decimal degrees (-180 to 180).

Kind: instance property of SolarPosition

solarPosition.dayOfMonth : number

The ordinal day of the month (1 to 31).

Kind: instance property of SolarPosition

solarPosition.monthOfYear : number

The ordinal month within the year (0 to 11).

Kind: instance property of SolarPosition

solarPosition.year : number

The year of the calculation as an integer (ie: 2014 or 2021).

Kind: instance property of SolarPosition

solarPosition.dayOfYear : number

The ordinal day of the year (0 to 364/5).

Kind: instance property of SolarPosition

solarPosition.clockTime : number

The local clock time at which to calculate, in decimal hours (0.0 to 24.0).

Kind: instance property of SolarPosition

solarPosition.clockTimeUTC : number

The time in Coordinated Universal Time (UTC), in decimal hours (0.0 - 24.0).

Kind: instance property of SolarPosition

solarPosition.solarTime : number

The current solar time, in decimal hours (0.0 - 24.0).

Kind: instance property of SolarPosition

solarPosition.solarTimeUTC : number

The solar time in Coordinated Universal Time, in decimal hours (0.0 - 24.0).

Kind: instance property of SolarPosition

solarPosition.getLatitudeInDegrees() ⇒ number

Retrieves the geographic latitude relative to the equator, in decimal degrees.

Kind: instance method of SolarPosition
Returns: number - Returns the latitude in decimal degrees (-89.9 to 89.9).

solarPosition.setLatitudeInDegrees(degrees) ⇒ SolarPosition

Sets the geographic latitude relative to the equator, in decimal degrees.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
degreesnumberThe new latitude in decimal degrees (-89.9 to 89.9).

solarPosition.getLatitudeInRadians() ⇒ number

Retrieves the geographic latitude relative to the equator, in radians.

Kind: instance method of SolarPosition
Returns: number - Returns the latitude in radians (-PI/2 to PI/2).

solarPosition.setLatitudeInRadians(radians) ⇒ SolarPosition

Sets the geographic latitude relative to the equator, in decimal degrees.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
radiansnumberThe new latitude in radians (-PI/2 to PI/2).

solarPosition.getLongitudeInDegrees() ⇒ number

Retrieves the geographic longitude relative to the prime meridian, in radians.

Kind: instance method of SolarPosition
Returns: number - Returns the longitude in decimal degrees (-180 to 180).

solarPosition.setLongitudeInDegrees(degrees) ⇒ SolarPosition

Sets the geographic longitude relative to the prime meridian, in decimal degrees.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
degreesnumberThe new longitude in decimal degrees (-180 to 180).

solarPosition.getLongitudeInRadians() ⇒ number

Retrieves the geographic longitude relative to the prime meridian, in radians.

Kind: instance method of SolarPosition
Returns: number - Returns the longitude in radians (-PI to PI).

solarPosition.setLongitudeInRadians(radians) ⇒ SolarPosition

Sets the geographic longitude relative to the prime meridian, in radians.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
radiansnumberThe new longitude in radians (-PI to PI).

solarPosition.getTimezone() ⇒ number

Retrieves the local time zone offset from UTC, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the time zone offset in decimal hours (-14.0 to 14.0).

solarPosition.setTimezone(hours) ⇒ SolarPosition

Sets the local time zone offset from UTC, in decimal hours.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
hoursnumberThe time zone offset in decimal hours (-14.0 to 14.0).

solarPosition.getNorthAngleInDegrees() ⇒ number

Retrieves the angle of North in a clockwise direction from the positive Y angle, in decimal degrees.

Kind: instance method of SolarPosition
Returns: number - Returns the angle of North, in decimal degrees (-180 to 180)

solarPosition.setNorthAngleInDegrees(degrees) ⇒ SolarPosition

Sets the angle of North in a clockwise direction from the positive Y angle, in decimal degrees.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
degreesnumberThe angle of North in decimal degrees (-180 to 180).

solarPosition.getNorthAngleInRadians() ⇒ number

Retrieves the angle of North in a clockwise direction from the positive Y angle, in radians.

Kind: instance method of SolarPosition
Returns: number - Returns the angle of North, in radians (-PI to PI).

solarPosition.setNorthAngleInRadians(radians) ⇒ SolarPosition

Sets the angle of North in a clockwise direction from the positive Y angle, in radians.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
radiansnumberThe angle of North in radians (-PI to PI).

solarPosition.getDayOfMonth() ⇒ number

Retrieves the ordinal day of the month.

Kind: instance method of SolarPosition
Returns: number - Returns the ordinal day of the month (1 to 31).

solarPosition.setDayOfMonth(day) ⇒ SolarPosition

Sets the ordinal day of the month.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
daynumberThe ordinal day of the month (1 to 31).

solarPosition.getMonthOfYear() ⇒ number

Retrieves the ordinal month within the year.

Kind: instance method of SolarPosition
Returns: number - Returns the ordinal month within the year (0 to 11).

solarPosition.setMonthOfYear(month) ⇒ SolarPosition

Sets the ordinal month within the year.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
monthnumberThe ordinal month within the year (0 to 11).

solarPosition.getYear() ⇒ number

Retrieves the year of the calculation as an integer (ie: 2014 or 2021).

Kind: instance method of SolarPosition
Returns: number - Returns the year of the calculation as an integer (-4712 to 3500).

solarPosition.setYear(year) ⇒ SolarPosition

Sets the year of the calculation as an integer (ie: 2014 or 2021).

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
yearnumberThe year of the calculation as an integer (-4712 to 3500).

solarPosition.getDayOfYear() ⇒ number

Retrieves the ordinal day of the year.

Kind: instance method of SolarPosition
Returns: number - Returns the ordinal day of the year (0 to 364/5).

solarPosition.setDayOfYear(day, [year]) ⇒ SolarPosition

Sets the date based on the ordinal index of day within the year.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
daynumberThe ordinal day of the year (0 to 364/5).
[year]numberAn optional four-digit year number (eg: 2014 or 2021).

solarPosition.getClockTime() ⇒ number

Retrieves the local clock time at which to calculate, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the local clock time, in decimal hours (0.0 to 24.0).

solarPosition.setClockTime(time) ⇒ SolarPosition

Sets the local clock time at which to calculate, in decimal hours.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
timenumberThe local clock time, in decimal hours (0.0 to 24.0).

solarPosition.getClockTimeUTC() ⇒ number

Retrieves the time in Coordinated Universal Time (UTC), in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the local clock time, in decimal hours (0.0 to 24.0).

solarPosition.setClockTimeUTC(time_utc) ⇒ SolarPosition

Sets the time in Coordinated Universal Time (UTC), in decimal hours.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
time_utcnumberThe time in Coordinated Universal Time (UTC), in decimal hours (0.0 to 24.0).

solarPosition.getSolarTime() ⇒ number

Retrieves the current solar time, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the current solar time, in decimal hours (0.0 to 24.0).

solarPosition.setSolarTime(time_solar) ⇒ SolarPosition

Sets a new solar time, in decimal hours.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
time_solarnumberThe new solar time, in decimal hours (0.0 to 24.0).

solarPosition.getSolarTimeUTC() ⇒ number

Retrieves the current solar time in Coordinated Universal Time, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the current UTC solar time, in decimal hours (0.0 to 24.0).

solarPosition.setSolarTimeUTC(time_solar_utc) ⇒ SolarPosition

Sets a new solar time in Coordinated Universal Time, in decimal hours.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
time_solar_utcnumberThe new UTC solar time, in decimal hours (0.0 to 24.0).

solarPosition.isLeapYear() ⇒ boolean

Determines if the current year is a leap year.

Kind: instance method of SolarPosition
Returns: boolean - Returns true if the current year is a leap year.

solarPosition.getDateAsString() ⇒ string

Retrieves the date in the format ‘dd M YYYY’.

Kind: instance method of SolarPosition
Returns: string - Returns the date in the format ‘dd M YYYY’.

solarPosition.getClockTimeAsString() ⇒ string

Retrieves the time in the format ‘HH:mm’.

Kind: instance method of SolarPosition
Returns: string - Returns the time in the format ‘HH:mm’.

solarPosition.getDateTimeAsString() ⇒ string

Retrieves the date/time in the format ‘HH:mm DD MMM YYYY’.

Kind: instance method of SolarPosition
Returns: string - Returns the date/time in the format ‘HH:mm DD MMM YYYY’.

solarPosition.getTimezoneAsString() ⇒ string

Retrieves the time zone in the format ‘+/-HH:mm’.

Kind: instance method of SolarPosition
Returns: string - Returns the time zone in the format ‘+/-HH:mm’.

solarPosition.getTimezoneCorrection() ⇒ number

Retrieves the correction factor due to the difference between actual longitude and the references longitude (based on timezone), as well as daylight savings, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the correction factor, in decimal hours.

solarPosition.getSunriseTime() ⇒ number

Retrieves the local clock time of sunrise on the current day, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the local clock time of sunrise, in decimal hours.

solarPosition.getSunsetTime() ⇒ number

Retrieves the local clock time of sunset on the current day, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the local clock time at sunset, in decimal hours.

solarPosition.getSolarNoonTime() ⇒ number

Retrieves the local clock time when the Sun is directly overhead, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the local clock time at solar noon, in decimal hours.

solarPosition.getSunAzimuthInDegrees() ⇒ number

Retrieves the azimuth angle of the calculated Sun position, in decimal degrees clockwise from North.

Kind: instance method of SolarPosition
Returns: number - Returns the azimuth angle of the Sun, in decimal degrees.

solarPosition.getSunAzimuthInRadians() ⇒ number

Retrieves the azimuth angle of the calculated Sun position, in radians clockwise from North.

Kind: instance method of SolarPosition
Returns: number - Returns the azimuth angle of the Sun, in radians.

solarPosition.getSunAltitudeInDegrees() ⇒ number

Retrieves the altitude angle of the calculated Sun position, in decimal degrees above the horizon.

Kind: instance method of SolarPosition
Returns: number - Returns the altitude angle of the Sun, in decimal degrees.

solarPosition.getSunAltitudeInRadians() ⇒ number

Retrieves the altitude angle of the calculated Sun position, in radians above the horizon.

Kind: instance method of SolarPosition
Returns: number - Returns the altitude angle of the Sun, in radians.

solarPosition.getDeclinationInDegrees() ⇒ number

Retrieves the current declination angle from the equator, in decimal degrees.

This is the first component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Kind: instance method of SolarPosition
Returns: number - Returns the declination angle, in decimal degrees.

solarPosition.getDeclinationInRadians() ⇒ number

Retrieves the current declination angle from the equator, in radians.

This is the first component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Kind: instance method of SolarPosition
Returns: number - Returns the declination angle, in radians.

solarPosition.getHourAngleInDegrees() ⇒ number

Retrieves the current solar hour angle offset, in decimal degrees.

This is the second component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Kind: instance method of SolarPosition
Returns: number - Returns the solar hour angle, in decimal degrees.

solarPosition.getHourAngleInRadians() ⇒ number

Retrieves the current solar hour angle offset, in radians.

This is the second component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Kind: instance method of SolarPosition
Returns: number - Returns the solar hour angle, in radians.

solarPosition.getSolarHourAngleInDegreesUTC() ⇒ number

Retrieves the current solar hour angle offset in Universal Coordinated Time, corrected for time zone and daylight savings, in decimal degrees.

This is the second component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Kind: instance method of SolarPosition
Returns: number - Returns the UTC solar hour angle, in degrees.

solarPosition.getSolarHourAngleInRadiansUTC() ⇒ number

Retrieves the current solar hour angle offset in Universal Coordinated Time, corrected for time zone and daylight savings, in radians.

This is the second component of the equatorial coordinate system used to give the direction of the Sun on the solar sphere.

Kind: instance method of SolarPosition
Returns: number - Returns the UTC solar hour angle, in radians.

solarPosition.getEquationOfTime() ⇒ number

Retrieves the current equation of time, in minutes.

Kind: instance method of SolarPosition
Returns: number - Returns the solar hour angle, in minutes.

solarPosition._calculateDate()

Calculates all date-based properties.

Do this in preparation for one or more subsequent time-of-day-based calculations.

Kind: instance method of SolarPosition

solarPosition.copy(sunPos) ⇒ SolarPosition

Copies all solar position data from the given instance.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position calculator to support method chaining.

ParamTypeDescription
sunPosSolarPositionThe solar position calculator instance to copy from.

solarPosition.calculate() ⇒ SolarPosition

(Re)Calculate the solar position based on the current settings.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

solarPosition.getSunAnglesAsArray([array]) ⇒ Array

Retrieves the azimuth and altitude angles of the Sun at the previously set date, time and location.

Kind: instance method of SolarPosition
Returns: Array - Returns an array with the first value being the solar azimuth (in decimal degrees clockwise from North), and the second being solar altitude (in decimal degrees above the horizon).

ParamTypeDescription
[array]ArrayAn optional array to receive the two values.

solarPosition.getSunAnglesAsObject([obj]) ⇒ object

Retrieves the azimuth and altitude angles of the Sun at the current date, time and location.

Kind: instance method of SolarPosition
Returns: object - Returns an object with the ‘azi’ property being the solar azimuth (in decimal degrees clockwise from North), and the ‘alt’ property being solar altitude (in decimal degrees above the horizon).

ParamTypeDescription
[obj]objectAn optional object on which to set the azi and alt properties.

solarPosition.getSunDirectionAsArray([array]) ⇒ Array

Retrieves an [x,y,z] vector array giving the direction of the Sun at the current date, time and location.

NOTE: The vector returned by this method is also rotated by the the current North offset angle. To get a vector relative to North if there is a non-zero North offset angle, use the getSunDirectionFromNorthAsArray method.

Kind: instance method of SolarPosition
Returns: Array - Returns the given vector array, or a new one.

ParamTypeDescription
[array]ArrayAn optional [x,y,z] vector array to receive the results.

solarPosition.getSunDirectionFromNorthAsArray([array]) ⇒ Array

Retrieves an [x,y,z] vector array giving the direction of the Sun at the current date, time and location.

NOTE: The vector returned by this method is given relative to North. To get a vector in world coordinates if there is a non-zero North offset angle, use the getSunDirectionAsArray method.

Kind: instance method of SolarPosition
Returns: Array - Returns the given vector array, or a new one.

ParamTypeDescription
[array]ArrayAn optional [x,y,z] vector array to receive the results.

solarPosition.getSunDirectionAsObject(vector) ⇒ object

Retrieves a vector array giving the direction of the Sun at the previously set date, time and location.

NOTE: The vector returned by this method is also rotated by the the current North offset angle.

Kind: instance method of SolarPosition
Returns: object - Returns the given vector object.

ParamTypeDescription
vectorobjectAn object with {x,y,z} properties to receive the results.

solarPosition.getSunDirectionFromNorthAsObject(vector) ⇒ object

Retrieves a vector array giving the direction of the Sun at the current date, time and location.

NOTE: The vector returned by this method is given relative to North. To get a vector in world coordinates if there is a non-zero North offset angle, use the getSunDirectionAsObject() method.

Kind: instance method of SolarPosition
Returns: object - Returns the given vector object.

ParamTypeDescription
vectorobjectAn object with {x,y,z} properties to receive the results.

solarPosition.getDateObject() ⇒ object

Retrieves the calculation date and time as a JavaScript Date object.

Kind: instance method of SolarPosition
Returns: object - Returns a JavaScript Date() object.

solarPosition.copyLocation(src) ⇒ SolarPosition

Copies any geographic location data from the given source object.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
srcSolarPosition | LocationA PD.SolarPosition or PD.Location object to copy data from.

solarPosition.setLocation(latitude, longitude, timezone) ⇒ SolarPosition

Sets the geographic location to calculate solar positions for.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
latitudenumberThe geographic latitude relative to the equator, in decimal degrees (-180 to 180).
longitudenumberThe geographic longitude relative to the prime meridian, in decimal degrees (-90 to 90).
timezonenumberThe difference between local time at the location and UTC, in decimal hours (-13.0 to 13.0). The value should be positive for all time zone behind/east of UTC and negative for ahead/west.

solarPosition.setDateTime(date_time) ⇒ SolarPosition

Sets the day, month, year and local time using the given Date() object.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar position instance to support method chaining.

ParamTypeDescription
date_timeDateTimeAn object containing the date and time for solar calculations.

solarPosition.setDateTimeFromJSDate(jsDate) ⇒ SolarPosition

Sets the day, month, year and local time using the given Date() object.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
jsDateobjectA JavaScript Date() object containing the date and time for solar calculations.

solarPosition.setDateFromJSDate(jsDate) ⇒ SolarPosition

Sets only the day, month and year using the given Date() object.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
jsDateobjectA JavaScript Date() object containing the day, month and year for solar calculations.

solarPosition.setTimeFromJSDate(jsDate) ⇒ SolarPosition

Sets only the local time using the given Date() object.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
jsDatenumberA Date() object containing the time at which to calculate.

solarPosition.setDayMonthYear(day_of_month, month_of_year, year) ⇒ SolarPosition

Sets up the calculation for the given ordinal day and year.

This method simply pre-calculates a range of values that depend solely on the date and year, allowing subsequent time-based calculations on that date to be much faster and less involved.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
day_of_monthnumberThe ordinal day of the month (1-31).
month_of_yearnumberThe ordinal day of the year (0-11).
yearnumberThe four-digit year number (eg: 2010).

solarPosition.setTimeOfDay(decimal_hours) ⇒ SolarPosition

Sets the local time to calculate the Sun position.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns this solar calculator to support method chaining.

ParamTypeDescription
decimal_hoursnumberThe local time of the day, in decimal hours (0 to 24).

solarPosition.setTimeOfDayAndGetArray(decimal_hours) ⇒ Array

Sets the local time and returns the resulting Sun position.

This combination is provided to support some aspects of D3 charting.

Kind: instance method of SolarPosition
Returns: Array - Returns an array with the first value being the solar azimuth (in decimal degrees clockwise from North), and the second being solar altitude (in decimal degrees above the horizon).

ParamTypeDescription
decimal_hoursnumberThe local time of the day, in decimal hours (0-24).

solarPosition.getSolarPosition(center, radius) ⇒ Array

Retrieves the current Sun position as a coordinate array relative to the given center point.

Kind: instance method of SolarPosition
Returns: Array - A 3D coordinate array in the form [x, y, z].

ParamTypeDescription
centerArrayThe position of the center point, given as a [x,y,z] coordinate array.
radiusnumberThe radius of the sphere on which the Sun path positions should sit.

solarPosition.getDailySunAngles(time_step, [time_start], [time_end]) ⇒ Array

Creates an array of [azimuth, altitude] angles over the current day from -180 to 180 in the steps equal to the given time increment.

Kind: instance method of SolarPosition
Returns: Array - Returns an array of arrays, one for each time step, with the first value of each being the solar azimuth (in decimal degrees clockwise from North), and the second being solar altitude (in decimal degrees above the horizon).

ParamTypeDescription
time_stepnumberThe increment step in decimal hours (1/60.0 to 6hrs).
[time_start]numberAn optional start time in decimal hours, defaulting to sunrise.
[time_end]numberAn optional stop time in decimal hours, defaulting to sunset.

solarPosition.getAnalemmaSunAngles(day_step, [day_start], [day_end]) ⇒ Array

Creates an array of [azimuth, altitude] angles over the whole year at the current time in steps equal to the given day increment.

Kind: instance method of SolarPosition
Returns: Array - Returns an array of arrays, one for each day step, with the first value of each being the solar azimuth (in decimal degrees clockwise from North), and the second being solar altitude (in decimal degrees above the horizon).

ParamTypeDefaultDescription
day_stepnumberThe increment step in days (1 to 90).
[day_start]number0An optional start time in decimal hours, defaulting to 0.0.
[day_end]number365An optional stop time in decimal hours, defaulting to 24.0.

solarPosition.getDailySunPathAsPositions(time_step, center, radius, [results]) ⇒ object

Retrieves an array of 3D Solar positions over the current day from midnight to midnight in the steps equal to the given increment.

Each position is given as an [x,y,z] coordinate array.

Kind: instance method of SolarPosition
Returns: object - Returns the given array or a new one containing connected [x, y, z] coordinate arrays.

ParamTypeDescription
time_stepnumberThe increment step in decimal hours (1/60.0 to 6hrs).
centerArrayThe position of the center point, given as a [x,y,z] coordinate array.
radiusnumberThe radius of the sphere on which the Sun path positions should sit.
[results]ArrayAn optional array to receive the calculated points.

solarPosition.getAnalemmaSunPathAsPositions(day_step, center, radius) ⇒ object

Retrieves an array of 3D solar positions over the whole year at the current time in steps equal to the given increment.

Kind: instance method of SolarPosition
Returns: object - Returns the given array or a new one containing connected [x,y,z] coordinate arrays.

ParamTypeDescription
day_stepnumberThe increment step in days (1 to 90).
centerArrayThe position of the center point, given as a [x,y,z] coordinate array.
radiusnumberThe radius of the sphere on which the Sun path positions should sit.

solarPosition.getSunriseSunsetAsObjectArray(day_step, [array]) ⇒ Array

Retrieves an array of object containing sunrise/sunset and twilight data.

Each object in the array represents the data for a specific day, in the form:

{
    "dayOfYear": 90,
    "solarNoon": 12.366226227429355,
    "sunrise": 5.840749703399434,
    "sunset": 18.891702751459277,
    "civilDawn": 5.237202798554755,
    "civilDusk": 19.495249656303955,
    "nauticalDawn": 4.504181173134206,
    "nauticalDusk": 20.228271281724503,
    "astronomicalDawn": 3.7054231232068187,
    "astronomicalDusk": 21.02702933165189
}

Kind: instance method of SolarPosition
Returns: Array - Returns an array of dawn/dusk objects.

ParamTypeDescription
day_stepnumberThe increment step in days (1 to 90).
[array]ArrayAn optional existing array to append to.

solarPosition.generateAnnualSolarTables() ⇒ Array.<Array.<string>>

Generates a table of solar data for each day of the current year.

This method generates an array of arrays, where each inner array contains the solar data for a specific day.

Each row of daily solar data contains the following:

  • [ 0] Date (in the format “DD MON”)
  • [ 1] Solar Noon (in the format “HH:MM”)
  • [ 2] Solar Noon Altitude (in degrees as “XXX.XX°”)
  • [ 3] Sunrise (in the format “HH:MM”)
  • [ 4] Sunrise Azimuth (in degrees as “XXX.XX°”)
  • [ 5] Sunset (in the format “HH:MM”)
  • [ 6] Sunset Azimuth (in degrees as “XXX.XX°”)
  • [ 7] Day Length (in the format “HH:MM”)
  • [ 8] Day Length Change (in the format “HH:MM”)
  • [ 9] Civil Dawn (in the format “HH:MM”)
  • [10] Civil Dusk (in the format “HH:MM”)
  • [11] Nautical Dawn (in the format “HH:MM”)
  • [12] Nautical Dusk (in the format “HH:MM”)
  • [13] Astronomical Dawn (in the format “HH:MM”)
  • [14] Astronomical Dusk (in the format “HH:MM”)

Kind: instance method of SolarPosition
Returns: Array.<Array.<string>> - Returns an array of arrays, one for each day of the year.

solarPosition.generateDailySolarTables([timeIncr]) ⇒ Array.<Array.<string>>

Generates a table of solar data over the course of the current day.

This method generates an array of arrays, where each inner array contains the solar data for a specific time increment, staring at sunrise.

Each row of daily solar data contains the following:

  • [0] Time (in the format “HH:MM”)
  • [1] Solar Altitude (in degrees as “XXX.XX°”)
  • [2] Solar Azimuth (in degrees as “XXX.XX°”)
  • [3] Horizontal Angle to Sun (in degrees as “XXX.XX°”)
  • 4] Shadow Angle (in degrees as “XXX.XX°”)
  • [5] Shadow Length (in metres or feet/in)

Kind: instance method of SolarPosition
Returns: Array.<Array.<string>> - Returns an array of arrays, one for each time increment over the current day.

ParamTypeDescription
[timeIncr]numberThe time increment over the day, defaults to 5min.

solarPosition.getDuskDawnData(check) ⇒ object

Retrieves the sunrise and sunset time for the current day, as well as all the twilight stages of dawn and dusk.

The returned object represents the data for the current day, in the form:

{
    "dayOfYear": 90,
    "solarNoon": 12.366226227429355,
    "sunrise": 5.840749703399434,
    "sunset": 18.891702751459277,
    "civilDawn": 5.237202798554755,
    "civilDusk": 19.495249656303955,
    "nauticalDawn": 4.504181173134206,
    "nauticalDusk": 20.228271281724503,
    "astronomicalDawn": 3.7054231232068187,
    "astronomicalDusk": 21.02702933165189
}

Kind: instance method of SolarPosition
Returns: object - Returns an object with all the dusk and dawn times.

ParamTypeDefaultDescription
checkbooleantrueWhether or not to check to recalculate, defaults to true.

solarPosition.getDawnTime(stage) ⇒ number

Retrieves the local time at which the specified twilight stage occurs at dawn on the current day, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the specified time, in decimal hours. Throws:

  • Error Throws an error
ParamTypeDescription
stagePD.TWILIGHTA twilight stage definition.

solarPosition.getDuskTime(stage) ⇒ number

Retrieves the local time at which the specified twilight stage occurs at dusk on the current day, in decimal hours.

Kind: instance method of SolarPosition
Returns: number - Returns the specified time, in decimal hours.

ParamTypeDescription
stagenumberA twilight stage definition.

solarPosition.getSkyColor() ⇒ number

Calculates the sky color at the current date and time.

This method uses the current sunrise/sunset times as well as the twilight stages of dawn and dusk to calculate a representative color for the sky.

Kind: instance method of SolarPosition
Returns: number - Returns a hexadecimal color value.

solarPosition.calcDefaultTimezone(longitude) ⇒ number

Calculates the default timezone offset for the given longitude. This is a simple calculation that does not consider regional boundaries and is given in decimal hours (-13 to 13).

Kind: instance method of SolarPosition
Returns: number - Returns the calculated time zone offset, in decimal hours (-13 to 13).

ParamTypeDescription
longitudenumberThe longitude to get the timezone for, in decimal degrees (-180 to 180).

solarPosition.calcDayOfYearIndex(day_of_month, month_of_year, year) ⇒ number

Calculates the ordinal index of the day within the year (0 - 364/5).

Kind: instance method of SolarPosition
Returns: number - Returns the calculated index of the day within the year (0 - 364/5).

ParamTypeDescription
day_of_monthnumberThe ordinal day of the month (1-31).
month_of_yearnumberThe ordinal day of the year (0-11).
yearnumberThe four-digit year number (eg: 2010).

solarPosition.formatAsTime([decimal_hours], [seconds]) ⇒ string

Returns a string with the given time in “HH:mm” or “HH:mm:ss” format.

Kind: instance method of SolarPosition
Returns: string - Returns the formatted time string.

ParamTypeDescription
[decimal_hours]numberThe time period, in decimal hours (0-24), defaults to current time.
[seconds]booleanWhen true it displays seconds value, otherwise just rounds to nearest minute.

solarPosition.formatAsDuration([decimal_hours], [seconds]) ⇒ string

Returns a string with the given duration in “HH:mm” or “HH:mm:ss” format.

Kind: instance method of SolarPosition
Returns: string - Returns the formatted duration string.

ParamTypeDescription
[decimal_hours]numberThe time period, in decimal hours (0-24), defaults to current time.
[seconds]booleanWhen true it displays seconds value, otherwise just rounds to nearest minute.

solarPosition.formatAsTimezone([decimal_hours]) ⇒ string

Returns a string with the given duration in “±HH:mm” or “±HH:mm:ss” format.

Kind: instance method of SolarPosition
Returns: string - Returns the formatted timezone.

ParamTypeDescription
[decimal_hours]numberThe time period, in decimal hours (0-24), defaults to current timezone.

solarPosition.formatAsDate(day_of_year, year) ⇒ string

Returns a string with the given day of the year in “dd mm YYYY” format.

Kind: instance method of SolarPosition
Returns: string - Returns the formatted date string.

ParamTypeDescription
day_of_yearnumberThe ordinal day of the year (0-364/5).
yearnumberThe four-digit year number (eg: 2010).

solarPosition.getMarchEquinox() ⇒ object

Returns the March Equinox as an object containing event data.

The returned object is in the form:

{
    dayOfYear: (0 to 364/5),
    timeOfDay: (0.0 to 24.0),
    month: (0 to 11),
    day: (1 to 31)
};

Kind: instance method of SolarPosition
Returns: object - Returns an object containing event data.

solarPosition.getJuneSolstice() ⇒ object

Returns the June Solstice as an object containing event data.

The returned object is in the form:

{
    dayOfYear: (0 to 364/5),
    timeOfDay: (0.0 to 24.0),
    month: (0 to 11),
    day: (1 to 31)
};

Kind: instance method of SolarPosition
Returns: object - Returns an object containing event data.

solarPosition.getSeptemberEquinox() ⇒ object

Returns the September Equinox as an object containing event data.

The returned object is in the form:

{
    dayOfYear: (0 to 364/5),
    timeOfDay: (0.0 to 24.0),
    month: (0 to 11),
    day: (1 to 31)
};

Kind: instance method of SolarPosition
Returns: object - Returns an object containing event data.

solarPosition.getDecemberSolstice() ⇒ object

Returns the December Solstice as an object containing event data.

The returned object is in the form:

{
    dayOfYear: (0 to 364/5),
    timeOfDay: (0.0 to 24.0),
    month: (0 to 11),
    day: (1 to 31)
};

Kind: instance method of SolarPosition
Returns: object - Returns an object containing event data.

solarPosition.now() ⇒ SolarPosition

Creates a new solar position calculator with the current date, time, site location and sun position.

This method is effectively a shortcut to creating a new SolarPosition instance with its date, time and location taken from PD.GlobalState.dateTime and PD.GlobalState.location.

Kind: instance method of SolarPosition
Returns: SolarPosition - Returns a solar calculator with the current sun position. Example

/// Option 1: Using this method.
 const sun_pos = PD.SolarPosition.now();

 /// Option 2: Doing the same manually.
 const sun_pos = new PD.SolarPosition({
     latitude: PD.GlobalState.location.latitude,
     longitude: PD.GlobalState.location.longitude,
     timezone: PD.GlobalState.location.timezone,
     northAngle: PD.GlobalState.location.northAngle,
     clockTime: PD.GlobalState.dateTime.clockTime,
     dayOfYear: PD.GlobalState.dateTime.dayOfYear,
     year: PD.GlobalState.dateTime.year,
 }).calculate();

SolarPosition.calcJulianCenturies(day_of_year, year) ⇒ number

Calculates the number of Julian centuries since J2000.

A Julian century represents 100 Julian years and is a unit of time defined as exactly 36525 days of 86,400 SI seconds each.

Kind: static method of SolarPosition
Returns: number - Returns the number of Julian centuries since J2000, as a decimal.

ParamTypeDescription
day_of_yearnumberThe ordinal day of the year (0-364/5).
yearnumberThe four-digit year number (eg: 2010).

SolarPosition.calcJulianCenturiesByMonth(day_of_month, month_of_year, year) ⇒ number

Calculates the number of Julian centuries since J2000 using day, month and year.

A Julian century represents 100 Julian years and is a unit of time defined as exactly 36525 days of 86,400 SI seconds each.

Kind: static method of SolarPosition
Returns: number - Returns the number of Julian centuries since J2000, as a decimal.

ParamTypeDescription
day_of_monthnumberThe ordinal day of the month (1-31).
month_of_yearnumberThe ordinal day of the year (0-11).
yearnumberThe four-digit year number (eg: 2010).

SolarPosition.calcSolarDeclination(julian_centuries) ⇒ number

Calculates the angle of the Sun relative to the celestial equator.

Declination in astronomy is comparable to geographic latitude on Earth, but projected onto out onto a larger celestial sphere.

Kind: static method of SolarPosition
Returns: number - Returns the calculated solar declination.

ParamTypeDescription
julian_centuriesnumberThe number of Julian centuries since J2000.

SolarPosition.calcEquationOfTime(julian_centuries) ⇒ number

Calculates the difference between apparent solar time and mean solar time.

The equation of time gives the relative offset of the analemma, a figure-8 curve representing the angular offset of the Sun from its mean position on the celestial sphere as viewed from Earth.

Kind: static method of SolarPosition
Returns: number - Returns the calculated equation of time, in minutes.

ParamTypeDescription
julian_centuriesnumberThe number of Julian centuries since J2000.

PD.Utils

Provides a set of generally useful tools and utilities for working with the framework and its classes.

Kind: static class of PD
Author: drajmarsh

Utils.MAX_CHUNK_SIZE : number

An arbitrary maximum size for pre-allocated array chunks.

Kind: static property of Utils

Utils.simpleHash ⇒ string

Generates a simple string hash value from the given input.

Kind: static property of Utils
Returns: string - Returns an eight (8) character hash string.

ParamTypeDescription
arganyAn argument of any type, string, value array or object.

Utils.EPSILON : number

A relatively small number used to define the threshold below which two values would be effectively considered the same for our needs.

Kind: static constant of Utils

Utils.QTR_PI : number

Stores a quick reference to the value of Math.PI / 4.0.

Kind: static constant of Utils

Utils.HALF_PI : number

Stores a quick reference to the value of Math.PI / 2.0.

Kind: static constant of Utils

Utils.TWO_PI : number

Stores a quick reference to the value of Math.PI * 2.0.

Kind: static constant of Utils

Utils.DEG2RAD : number

The conversion factor for degrees to radians, being Math.PI / 180.

Kind: static constant of Utils

Utils.RAD2DEG : number

The conversion factor for radians to degrees, being 180 / Math.PI.

Kind: static constant of Utils

Utils.nullFunction : function

Defines an empty function that does nothing and returns nothing.

This is typically used to nullify callbacks on objects just before they are disposed or detached, just in case they are shared somewhere.

Kind: static constant of Utils

Utils.sleepFor(ms) ⇒ Promise

Pauses the application execution for the given duration.

Kind: static method of Utils
Returns: Promise - Returns a promise.

ParamTypeDescription
msnumberThe number of milliseconds to wait.

Utils.sign(value) ⇒ number

Returns -1 or 1 based on whether the value is negative or zero/positive.

Kind: static method of Utils
Returns: number - Returns -1 or 1 based on the sign of the given value.

ParamTypeDescription
valuenumberThe value to determine the sign of.

Utils.ceilOrFloor(value) ⇒ number

A replacement for Math.ceil() than handles negative numbers better.

This method basically applies the Math.floor() method to negative numbers and the Math.ceil() method to positive and zero. This is useful when using increment values where you want parity between positive and negative values. For example, just as a positive increment of 2.15 should round up to 3, a negative increment of -2.15 should round down to -3.

Kind: static method of Utils
Returns: number - Returns the signed floor/ceiling of value.

ParamTypeDescription
valuenumberThe value to determine the floor/ceiling of.

Utils.safeDivide(top, bot) ⇒ number

Performs division with divide-by-zero protection.

NOTE: If the denominator bot is within 1e-9 of zero, this function returns zero instead of Infinity. In most geometric applications, a denominator value close to zero is an indicator that two points share the same position. Returning Infinity would result in spurious vectors and invalid projections, which would require additional bounds checking and basically defeat the very purpose of using this function. In comparison, returning zero has very few side effects.

Kind: static method of Utils
Returns: number - Returns the divided result or zero.

ParamTypeDescription
topnumberThe value to divide.
botnumberThe value to divide by.

Utils.closeTo(value, reference, [tolerance]) ⇒ boolean

Determine if two numeric values are within the specified tolerance of each other.

Kind: static method of Utils
Returns: boolean - Returns true if the two values are within threshold, else false.

ParamTypeDescription
valuenumberThe value to test.
referencenumberThe reference value to test against.
[tolerance]numberThe amount above or below that is still considered close.

Utils.closeToZero(value, [tolerance]) ⇒ boolean

Returns true if the given value is within EPSILON of zero.

Kind: static method of Utils
Returns: boolean - Returns true if the given value is close to zero.

ParamTypeDescription
valuenumberThe value to check.
[tolerance]numberThe amount above or below that is still considered close.

Utils.closeToDegrees(angle1, angle2, [tolerance]) ⇒ boolean

Determine if two degree angles are within the specified tolerance of each other.

Angles needs some additional tests as -180 == +180 and -270 == +90, etc.

Kind: static method of Utils
Returns: boolean - Returns true if the two values are within threshold, else false.

ParamTypeDescription
angle1numberThe first angle, in degrees.
angle2numberThe second angle, in degrees.
[tolerance]numberThe amount above or below that is still considered close, defaults to 0.01deg.

Utils.constrainTo(value, range1, range2) ⇒ number

Clamps the given value to the given range.

NOTE: In this function, the minimum/maximum allowable values are automatically calculated from the two given range values. This means that range1 can be greater than, equal to or less than range2.

Kind: static method of Utils
Returns: number - Returns a value between min and max, inclusive.

ParamTypeDescription
valuenumberThe value to trim within the range.
range1numberThe first value in the allowable range.
range2numberThe second value in the allowable range.

Utils.mapTo(value, v_min, v_max, o_min, o_max) ⇒ number

Map a value from one scalar range to another.

Kind: static method of Utils
Returns: number - Returns the mapped value.

ParamTypeDescription
valuenumberThe value to map.
v_minnumberThe start of the input range.
v_maxnumberThe end of the input range.
o_minnumberThe start of the output range.
o_maxnumberThe end of the the output range.

Utils.mapAndConstrainTo(value, v_min, v_max, o_min, o_max) ⇒ number

Map a value from one scalar range to another, but clamped to that range.

Kind: static method of Utils
Returns: number - Returns the mapped value.

ParamTypeDescription
valuenumberThe value to map and constrain.
v_minnumberThe start of the input range.
v_maxnumberThe end of the input range.
o_minnumberThe start of the output range.
o_maxnumberThe end of the the output range.

Utils.snapTo(value, increment) ⇒ number

Utility function to snap to a given value increment.

Kind: static method of Utils
Returns: number - Returns an integer multiple of increment.

ParamTypeDescription
valuenumberThe value to snap.
incrementnumberThe increment value to snap to.

Utils.roundTo(value, increment) ⇒ number

Rounds a number to the given number of decimal places.

This method is not totally accurate as rounding floating point numbers on a CPU/FPU is not trivial (see: https://stackoverflow.com/a/38676273). However, if you know the limitations, then there are always use-cases where something like this is useful.

Kind: static method of Utils
Returns: number - Returns the rounded value.

ParamTypeDescription
valuenumberThe value to round.
incrementnumberThe integer number of decimal places, defaults to 3.

Utils.interpolate(start, stop, t) ⇒ number

Interpolate between two scalar values, where t is a fractional value (0-1).

Kind: static method of Utils
Returns: number - Returns the interpolated value.

ParamTypeDescription
startnumberThe value when t == 0.0.
stopnumberThe value when t == 1.0.
tnumberThe fractional interpolator value (0-1).

Utils.wrapAt(value, min, max, [exclusive]) ⇒ number

Utility function to wrap a value around specific bounds.

Kind: static method of Utils
Returns: number - Returns a value wrapped around to always be within the given bounds.

ParamTypeDescription
valuenumberThe value to wrap if outside bounds.
minnumberThe lowest allowable value in the range.
maxnumberThe highest allowable value in the range.
[exclusive]numberIf true, the max value is not inclusive.

Utils.isBetween(value, range1, range2, [tolerance]) ⇒ boolean

Determine if value is within the given range and tolerance.

This method is exclusive of the range boundaries, but will still work fine if range1 is greater-than or less-than range2. If you want to include the range bounds, simply use a small negative tolerance.

Kind: static method of Utils
Returns: boolean - Returns true if value is between the value range, otherwise false.

ParamTypeDescription
valuenumberThe value to test if within the range.
range1numberThe first value defining the allowable range.
range2numberThe second value defining the allowable range.
[tolerance]numberThe tolerance value at each end of the range, defaults to zero.

Utils.toNumber(value, default_value) ⇒ number

Tries to convert the defined value to a valid number.

If the value is defined and conversion is valid, the converted value is returned. Otherwise the given default value is returned.

Kind: static method of Utils
Returns: number - Returns either the converted value or the given default.

ParamTypeDescription
valuenumberThe value to convert.
default_valuenumberReturned if value is null, undefined or the conversion fails.

Utils.toNumberInRange(value, default_value) ⇒ number

Tries to convert the defined value to a valid number within the given range.

If the value is defined and conversion is valid, the clamped converted value is returned. Otherwise the clamped default value is returned.

Kind: static method of Utils
Returns: number - Returns either the converted value or the given default.

ParamTypeDescription
valuenumberThe value to convert.
default_valuenumberReturned if value is null, undefined or the conversion fails.

Utils.toInteger(value, default_value) ⇒ number

Tries to convert the defined value to a valid integer.

If the value is defined and conversion is valid, the converted value is returned. Otherwise the given default value is returned.

Kind: static method of Utils
Returns: number - Returns either the converted value or the default.

ParamTypeDescription
valuenumberThe value to convert.
default_valuenumberReturned if value is null, undefined or the conversion fails.

Utils.toIntegerInRange(value, default_value, min, max) ⇒ number

Tries to convert the defined value to a valid integer within the given range.

If the value is defined and conversion is valid, the clamped converted value is returned. Otherwise the clamped default value is returned.

Kind: static method of Utils
Returns: number - Returns either the converted value or the default.

ParamTypeDescription
valuenumberThe value to convert.
default_valuenumberReturned if value is null, undefined or the conversion fails.
minnumberThe minimum allowed value.
maxnumberThe maximum allowed value.

Utils.toBoolean(value, default_value) ⇒ boolean

Tries to convert the defined value to a valid boolean.

If the value is defined and the conversion is valid, the converted value is returned. Otherwise the default value is returned.

Kind: static method of Utils
Returns: boolean - Returns either the converted value or the default.

ParamTypeDescription
valuebooleanThe value to convert.
default_valuebooleanReturned if value is null, undefined or the conversion fails.

Utils.toDimension(value, default_inches, [default_mm]) ⇒ boolean

Tries to convert the defined value to a valid dimension in mm based on the current value of PD.DIMENSION.units.

If the value is defined and the conversion is valid, the converted value is returned. Otherwise either the imperial or metric default value is used, based on the current value of PD.DIMENSION.units.

This method exists because the dimensions of many things are often still given in inches to be compatible with US measurements, but rounded to the nearest 50 or 100mm in regions that use in metric units. Thus, rather that have all sorts of tests for imperial units dotted throughout your code, you can simply use this method and solve many of these issues.

If PD.DIMENSION.units are imperial, the first default argument given in inches will be converted directly to millimetres and returned. If the current model units are metric, the second default argument given in millimetres will be returned.

If there is no second default argument, the given number of inches in the the first default argument will be multiplied by 25.0 to give a reasonably rounded metric value.

The term ‘reasonable’ is based on the fact that. if light switches are installed 48" (1,219.2mm) above the floor in the US, this is almost invariably going to be 1200mm in countries that use metric units. Similarly, a 600mm bench depth is almost invariably going to be 2’ (24" or 609.6mm) in the US.

This way, the dimensions of models created using imperial units will snap nicely to the nearest inch, and models created in metric units will snap nicely to the nearest 25, 50 and 100mm. Obviously if you create half the model using imperial units and the other half using metric units, you can’t expect it to land very gently on whatever planet you send it to https://www.simscale.com/blog/2017/12/nasa-mars-climate-orbiter-metric/.

Kind: static method of Utils
Returns: boolean - Returns either the converted value or the appropriate default.

ParamTypeDescription
valuenumberThe value to convert.
default_inchesnumberThe default number of inches to use if imperial.
[default_mm]numberThe default number of millimetres if metric, defaults to inches * 25.

Example

/// Instead of this:
const slab_depth = PD.Utils.toNumber(config.slabDepth, PD.DIMENSION.useImperial ? 203.2 : 200.0); // 8".

/// You can do this to avoid two function calls, specifying both the inches and millimeters.
const slab_depth = PD.Utils.toDimension(config.slabDepth, 8, 200);

/// Or this to, again, do exactly the same thing as the 8" value will converted to an appropriate metric value.
const slab_depth = PD.Utils.toDimension(config.slabDepth, 8);

Utils.imperialOrMetric(inches, [mm]) ⇒ number

Returns either the imperial or metric value based on the current value of PD.DIMENSION.units.

This method allows you to initialise standard items such as bench heights, shelf depths, wall widths and grid sizes with values that are relevant to the current model units and will snap appropriately to reasonable dimensions - for example: inches in imperial and 25mm or 50mm in metric.

This method exists because the dimensions of many things are often still given in inches to be compatible with US measurements, but rounded to the nearest 50 or 100 in regions that use in metric units. Thus, rather that have all sorts of tests for imperial units dotted throughout your code, you can simply use this method and solve many of these issues.

If PD.DIMENSION.units are imperial, the first argument given in inches will be converted directly to millimetres and returned. If the current model units are metric, the second argument given in millimetres will be returned.

If there is no second argument, the given number of inches in the the first argument will be multiplied by 25 to give a reasonably rounded metric value (NOT 25.4).

The term ‘reasonably’ is based on the fact that, if light switches are installed 48" (1,219.2mm) above the floor in the US, this is almost invariably going to be 1200mm in countries that use metric units (as opposed to just rounding it to 1220mm). Similarly, a 600mm bench depth is almost invariably going to be 2’ (609.6mm) in the US (as opposed to 2’ 3/8").

This way, the dimensions of models created using imperial units will snap nicely to the nearest inch, and models created in metric units will snap nicely to the nearest 25, 50 and 100mm. Obviously if you create half the model using imperial units and the other half using metric units, you can’t expect your model to land very gently on whatever planet you send it to https://www.simscale.com/blog/2017/12/nasa-mars-climate-orbiter-metric/.

Kind: static method of Utils
Returns: number - Returns a moderated value in millimetres.

ParamTypeDescription
inchesnumberThe number of inches to use if imperial.
[mm]numberThe number of millimetres to use if metric, defaults to inches * 25.

Example

/// Instead of this...
const defaultSlabDepth = PD.DIMENSION.useImperial ? 203.2 : 200.0; // 8".

/// ...you can do this to do exactly the same thing.
const defaultSlabDepth = PD.Utils.imperialOrMetric(8, 200);

/// Or this to, again, do exactly the same thing.
const defaultSlabDepth = PD.Utils.imperialOrMetric(8);

Utils.computeIncrementValue(direction, key, step, minor, major, isLarge, [largeIncr]) ⇒ number

Computes an increment value for the given parameter data.

This method is used internally by several numeric and color increment methods.

Kind: static method of Utils
Returns: number - Returns the increment/snap value.

ParamTypeDescription
directionnumber1 for increment, -1 for decrement.
keyKEY | WheelEventA scroll wheel event or current Control/Shift/Alt key status.
stepnumberThe smallest allowable increment value.
minornumberThe typical increment value.
majornumberThe large increment value.
isLargenumberWhether to use the large increment by default.
[largeIncr]numberIf both Shift key and isLarge are set, multiply by this value, defaults to 5.

Utils.incrementNumber(value, direction, key, step, minor, major, isLarge, [largeIncr]) ⇒ number

Increments a value given a range of parameters.

This method first determines a value to increment/decrement the value by, then snaps the result to the nearest multiple of that value.

Kind: static method of Utils
Returns: number - Returns the incremented value.

ParamTypeDescription
valuenumberThe value to increment.
directionnumber1 for increment, -1 for decrement.
keyKEY | WheelEventA scroll wheel event or current Control/Shift/Alt key status.
stepnumberThe smallest allowable increment value.
minornumberThe typical increment value.
majornumberThe large increment value.
isLargenumberWhether to use the large increment by default.
[largeIncr]numberIf both Shift key and isLarge are set, multiply by this value, defaults to 5.

Utils.computeTickIncrement(range, max_ticks) ⇒ number

Calculates a reasonable tick increment for the given range.

In this context, a tick is effectively a smaller interval that can be used to divide the given range. This is typically used for charts and graphs to display a reasonable number of ticks or values along an axis.

Kind: static method of Utils
Returns: number - Returns a tick increment value.

ParamTypeDescription
rangenumberThe overall range of values (max - min).
max_ticksnumberThe maximum number of allowable ticks, defaults to 20.

Utils.isObject(obj) ⇒ boolean

Testing if a variable represents a javascript object.

NOTE: This method returns true for built-in pseudo-objects such as Array(), Number() and String() objects. If you want to exclude these, use isPlainObject() instead.

Kind: static method of Utils
Returns: boolean - Returns true if ‘obj’ is a real javascript object.

ParamTypeDescription
objobjectThe variable to check.

Utils.isPlainObject(obj) ⇒ boolean

Testing if a variable represents just a plain old object.

NOTE: This method returns false for built-in pseudo-objects such as Array(), Number() and String() objects. If you want to include these, use isObject() instead.

Kind: static method of Utils
Returns: boolean - Returns true if ‘obj’ is a plain old object.

ParamTypeDescription
objobjectThe variable to check.

Utils.isFunction(fn) ⇒ boolean

Testing if a variable is a function.

Kind: static method of Utils
Returns: boolean - Returns true if ‘str’ is a string.

ParamTypeDescription
fnfunctionThe variable to check.

Utils.isString(str) ⇒ boolean

Testing if a variable is a string value.

Kind: static method of Utils
Returns: boolean - Returns true if ‘str’ is a string.

ParamTypeDescription
strobjectThe variable to check.

Utils.isAlpha(chr) ⇒ boolean

Testing if a single character is alphabetical (A-Z|a-z).

Kind: static method of Utils
Returns: boolean - Returns true if ‘chr’ is alphabetical.

ParamTypeDescription
chrstringThe variable to check.

Utils.isNumeric(value) ⇒ boolean

Determine if given value is or can be easily converted to a valid number less than infinity.

This is needed as the standard function isNaN(null) returns false (technically null != NaN), and isFinite(null) returns true. Thus we need to test for both null and infinity.

Kind: static method of Utils
Returns: boolean - Returns true if numeric.

ParamTypeDescription
valuenumberThe value to test.

Utils.isBoolean(value) ⇒ boolean

Determine if given value is a boolean.

NOTE: This method applies only to boolean values, not Boolean objects which are very different things.

Kind: static method of Utils
Returns: boolean - Returns true if its an actual boolean.

ParamTypeDescription
valuebooleanThe value to test.

Utils.randomRange(min, max) ⇒ number

Generates a random number within the given range.

Kind: static method of Utils
Returns: number - Returns the random value.

ParamTypeDescription
minnumberThe minimum value of the required range.
maxnumberThe maximum value of the required range.

Utils.randomNumber([seed]) ⇒ number

Returns a seeded random number in the range 0 to 1.

Kind: static method of Utils
Returns: number - Returns a seeded random number in the range (0-1).

ParamTypeDescription
[seed]numberAn optional number to use as the generator seed.

Utils.addToArray(value, item) ⇒ boolean

Adds item to the given array if it does not already exist.

NOTE: This function uses array.indexOf() to check if the item already exists in the array. If not, it is added using the array.push() method.

Kind: static method of Utils
Returns: boolean - Returns true if the item was added to the array, otherwise false.

ParamTypeDescription
valueArrayThe array to add the item to.
itemanyThe item to add if not already in the array.

Utils.insertInArray(value, index, item) ⇒ boolean

Inserts item at the given index, if not already in the array.

NOTE: This function uses array.indexOf() to check if the item already exists in the array. If not, it is inserted using the array.splice() method.

Kind: static method of Utils
Returns: boolean - Returns true if the item was added to the array, otherwise false.

ParamTypeDescription
valueArrayThe array to add the item to.
indexnumberThe ordinal index in the array at which to insert.
itemanyThe item to insert if not already in the array.

Utils.removeFromArray(value, item) ⇒ boolean

Removes the item from the given array if it exists.

NOTE: This function uses array.indexOf() to check if the item exists and obtain its index, then array.splice() to remove it.

Kind: static method of Utils
Returns: boolean - Returns true if the item was found in the array and removed, otherwise false.

ParamTypeDescription
valueArrayThe array to remove the item from.
itemanyThe item to remove if it exists in the array.

Utils.resizeTypedArray(array, new_length) ⇒ TypedArray

Creates a new typed array with the new size and a copy of the original data.

Kind: static method of Utils
Returns: TypedArray - Returns a new array with the original data and a new size.

ParamTypeDescription
arrayTypedArrayThe typed array to resize.
new_lengthnumberThe new size of the array.

Utils.convertMapToJSON(map, [ignore]) ⇒ object

Converts a Map to a simple POJO for conversion to JSON.

NOTE: This method assumes that any key name that starts with a $ char is for internal use only and will not include them in the conversion.

Kind: static method of Utils
Returns: object - Returns a Plain Old Javascript Object (POJO).

ParamTypeDescription
mapMapA Javascript Map containing data.
[ignore]ArrayAn optional array of items to ignore.

Utils.copyMap(data, [map]) ⇒ Map

Copies data from a source object/map to a Map, with string-based keys.

NOTE: This method assumes that any key name that startswith a $ char is for internal use only and will not copy them.

Kind: static method of Utils
Returns: Map - Returns the destination Map, or a newly created one.

ParamTypeDescription
dataMap | objectThe Javascript Map or object to copy from.
[map]MapAn optional Javascript Map to copy the data to.

Utils.degToRad() ⇒ number

Returns the value converted from degrees to radians.

Kind: static method of Utils
Returns: number - Returns the converted value in radians. Params: number value The decimal degrees value to convert to radians.

Utils.radToDeg(value) ⇒ number

Returns the value converted from radians to degrees.

Kind: static method of Utils
Returns: number - Returns the converted value in decimal degrees.

ParamTypeDescription
valuenumberThe radians value to convert to decimal degrees.

Utils.sinDegrees(degrees) ⇒ number

Determines Math.sin() based on an angle given in decimal degrees.

Kind: static method of Utils
Returns: number - Returns the trigonometric sine of the given angle.

ParamTypeDescription
degreesnumberThe required angle in decimal degrees.

Utils.cosDegrees(degrees) ⇒ number

Determines Math.cos() based on an angle given in decimal degrees.

Kind: static method of Utils
Returns: number - Returns the trigonometric cosine of the given angle.

ParamTypeDescription
degreesnumberThe required angle in decimal degrees.

Utils.tanDegrees(degrees) ⇒ number

Determines Math.tan() based on an angle given in decimal degrees.

Kind: static method of Utils
Returns: number - Returns the trigonometric tangent of the given angle.

ParamTypeDescription
degreesnumberThe required angle in decimal degrees.

Utils.getSinLookUpTable_15deg() ⇒ Array.<number>

Returns a look up table sine values in 15 degree increments over 180 degrees.

The returned table has 13 values, inclusive of 180deg.

Kind: static method of Utils

Utils.getCosLookUpTable_15deg() ⇒ Array.<number>

Returns a look up table cosine values in 15 degree increments over 180 degrees.

The returned table has 13 values, inclusive of 180deg.

Kind: static method of Utils

Utils.generateSinCosLookUpTable(increments) ⇒ Array.<Array.<number>>

Create a look-up table of [sin,cos] array values.

The number of entries in the table will equal increments+1 as the first entry in the table is repeated at the end to make it easier to close the circular loop.

Kind: static method of Utils
Returns: Array.<Array.<number>> - Returns an array if [sin,cos] values for a unit circle.

ParamTypeDescription
incrementsnumberThe number of circular increments in table (3 to 360).

Utils.startsWith(haystack, needle) ⇒ boolean

Determines if a string starts with the given string.

Kind: static method of Utils
Returns: boolean - Returns true if ‘haystack’ starts with the exact same characters as ’needle’.

ParamTypeDescription
haystackstringThe larger string to be checked.
needlestringThe smaller string to use for checking.

Utils.endsWith(haystack, needle) ⇒ boolean

Determines if a string ends with the given string.

Kind: static method of Utils
Returns: boolean - Returns true if ‘haystack’ ends with the exact same characters as ’needle’.

ParamTypeDescription
haystackstringThe larger string to be checked.
needlestringThe smaller string to use for checking.

Utils.toCamelCase(name) ⇒ string

Converts a kebab-case, snake_case or space separated string to camelCase.

This method converts hyphen, underscore and space separated strings to camelCase, or any combination of hyphens, underscores or spaces. It also trims any whitespace from the start and end of the string.

Kebab-case is a way of joining together multiple words where spaces are replaced with hyphens (-) and all the words are typically lower case. The name comes from the similarity of the words to meat on a kebab skewer.

Snake_case is the same a kebab-case but uses underscores (_) instead of hyphens (-). Space separated is just the normal way of writing.

Camel case is a way of joining together multiple words without using spaces or any other separators, and where the first letter of each after the first word is capitalized. The name comes from the similarity of the capital letters to the humps of a camel’s back.

Kind: static method of Utils
Returns: string - Returns a copy of the string in camelCase.

ParamTypeDescription
namestringThe separated string to convert.

Utils.toKebabCase(name) ⇒ string

Converts a camelCase or PascalCase string to kebab-case.

This method expects either a camelCase

can also convert underscore and space separated strings to camelCase, or any combination of hyphens, underscores or spaces. It also trims any whitespace from the start and end of the string.

Camel case is a way of joining together multiple words without using spaces or any other separators, and where the first letter of each after the first word is capitalized. The name comes from the similarity of the capital letters to the humps of a camel’s back.

PascalCase is the same as camelCase but with the first letter capitalised as well.

Kebab case is a way of joining together multiple words where spaces are replaced with hyphens (-) and all the words are typically lower case. The name comes from the similarity of the words to meat on a kebab skewer.

Kind: static method of Utils
Returns: string - Returns a copy of the string in camelCase.

ParamTypeDescription
namestringThe separated string to convert.

Utils.toStringWithLeadingZeros(value, [size]) ⇒ string

Formats a value with the given number of leading zeros.

This method limits the number of leading zeros to a maximum of 1024 in order to bullet-proof it against rogue input. If you need more than this number of leading zeros, use String.padStart() directly.

Kind: static method of Utils
Returns: string - Returns a string with zeros padding out to the required size.

ParamTypeDefaultDescription
valuenumberThe value to convert to a string.
[size]number2The total number of characters required before the decimal place.

Utils.toStringWithPrecision(value, decimals) ⇒ string

Formats a value with the given number of decimal places.

Kind: static method of Utils
Returns: string - Returns a string formatted with the given precision.

ParamTypeDescription
valuenumberThe value to set the precision of.
decimalsnumberThe number of decimal places of precision.

Utils.formatNumberAsOrdinal(value) ⇒ string

Formats a value as an ordinal string, such as 1st, 2nd, 3rd, etc.

Kind: static method of Utils
Returns: string - Returns a string formatted with the given precision.

ParamTypeDescription
valuenumberThe value to get the ordinal of.

Utils.toStringWithPrecisionRange(value, min_decimals, max_decimals) ⇒ string

Uses a minimum fixed minimum precision but allows greater accuracy up to a given maximum.

Kind: static method of Utils
Returns: string - Returns a string formatted within the precision range. Throws:

  • Error Occurs if min_decimals or min_decimals are invalid or negative.
ParamTypeDescription
valuenumberThe value to convert to a string.
min_decimalsnumberThe minimum number of decimal places of precision.
max_decimalsnumberThe maximum allowed number of decimal places of precision.

Utils.formatFeetAndInches(mm) ⇒ string

Generates an imperial string representation of the given dimension in millimetres.

Kind: static method of Utils
Returns: string - Returns a feet and inches string.

ParamTypeDescription
mmnumberThe dimension in millimetres.

Utils.formatInFractionsOfAnInch(mm) ⇒ string

Generates an imperial string representation of the given very small dimension in millimetres.

Kind: static method of Utils
Returns: string - Returns a string in 1/16, 1/32 or 1.64 of an inch.

ParamTypeDescription
mmnumberThe dimension in millimetres.

Utils.formatInBytes(bytes) ⇒ string

Formats a number of bytes into a human-readable string.

This method uses the shortenBytes() function to convert the number of bytes into a more readable format, such as “157Bytes”, “1.52KB”, “2.31MB”, etc.

Kind: static method of Utils
Returns: string - Returns a string representation of the size in bytes.

ParamTypeDescription
bytesnumberThe number of bytes to format.

Utils.interpolateHexAsRGB(hex1, hex2, t) ⇒ number

Interpolates between two hexadecimal color numbers using their RGB components.

Kind: static method of Utils
Returns: number - Returns an interpolated hexadecimal number.

ParamTypeDescription
hex1numberThe hexadecimal color number when t == 0.0.
hex2numberThe hexadecimal color number when t == 1.0.
tnumberThe fractional interpolation value in the range (0 to 1).

Utils.interpolateHexViaHSL(hex1, hex2, t) ⇒ number

Interpolates between two hexadecimal color numbers using their HSL components.

Kind: static method of Utils
Returns: number - Returns an interpolated hexadecimal number.

ParamTypeDescription
hex1numberThe hexadecimal color number when t == 0.0.
hex2numberThe hexadecimal color number when t == 1.0.
tnumberThe fractional interpolation value in the range (0 to 1).

Utils.incrementHex_Hue(hex, direction, key, step, minor, major, isLarge, [largeIncr]) ⇒ number

Increments the hue of a hexadecimal color number given a range of parameters.

Kind: static method of Utils
Returns: number - Returns the incremented value.

ParamTypeDescription
hexnumberThe hexadecimal color to increment.
directionnumber1 for increment, -1 for decrement.
keyKEYThe current Control/Shift/Alt key status.
stepnumberThe smallest allowable increment value.
minornumberThe typical increment value.
majornumberThe large increment value.
isLargenumberWhether to use the large increment by default.
[largeIncr]numberIf both Shift key and isLarge are set, multiply by this value, defaults to 5.

Utils.incrementHex_Saturation(hex, direction, key, step, minor, major, isLarge, [largeIncr]) ⇒ number

Increments the saturation of a hexadecimal color given a range of parameters.

Kind: static method of Utils
Returns: number - Returns the incremented value.

ParamTypeDescription
hexnumberThe hexadecimal color to increment.
directionnumber1 for increment, -1 for decrement.
keyKEYThe current Control/Shift/Alt key status.
stepnumberThe smallest allowable increment value.
minornumberThe typical increment value.
majornumberThe large increment value.
isLargenumberWhether to use the large increment by default.
[largeIncr]numberIf both Shift key and isLarge are set, multiply by this value, defaults to 5.

Utils.incrementHex_Lightness(hex, direction, key, step, minor, major, isLarge, [largeIncr]) ⇒ number

Increments the lightness of a hexadecimal color given a range of parameters.

Kind: static method of Utils
Returns: number - Returns the incremented value.

ParamTypeDescription
hexnumberThe hexadecimal color to increment.
directionnumber1 for increment, -1 for decrement.
keyKEYThe current Control/Shift/Alt key status.
stepnumberThe smallest allowable increment value.
minornumberThe typical increment value.
majornumberThe large increment value.
isLargenumberWhether to use the large increment by default.
[largeIncr]numberIf both Shift key and isLarge are set, multiply by this value, defaults to 5.

Utils.toHexFromRGB(r, g, b) ⇒ number

Converts color components to a hexadecimal color number.

Kind: static method of Utils
Returns: number - Returns the color as a hexadecimal number.

ParamTypeDescription
rnumberThe red colour component in the range (0 to 1).
gnumberThe green colour component in the range (0 to 1).
bnumberThe blue colour component in the range (0 to 1).

Utils.toHexFromCSS(css) ⇒ number

Converts a ‘#RRGGBB’ CSS color string to a hexadecimal color number.

If the string is not a valid CSS ‘#RRGGBB’ value or a JSON array in the form ‘[r,g,b]’, this method will return zero (black).

Kind: static method of Utils
Returns: number - Returns the color as a hexadecimal number.

ParamTypeDescription
cssstringA CSS color string of the form ‘#RRGGBB’ or ‘[r,g,b]’.

Utils.toHexFromColorObject(obj) ⇒ number

Converts an {r,g,b} color object to a hexadecimal color number.

If the given object does not define a valid {r,g,b} color, this method will return zero (black).

Kind: static method of Utils
Returns: number - Returns the color as a hexadecimal number.

ParamTypeDescription
objColorTypeAn {r,g,b} color object with components in the range (0 to 1).

Utils.toHexFromColorArray(arr) ⇒ number

Converts an [r,g,b] color array to a hexadecimal color number.

If the given array does not define a valid [r,g,b] color, this method will return zero (black).

Kind: static method of Utils
Returns: number - Returns the color as a hexadecimal number.

ParamTypeDescription
arrArray.<number>An [r,g,b] color array with values in the range (0 to 1).

Utils.toHexFromAnyColor(color, [defaultValue]) ⇒ number

Converts a color number, string, {r,g,b} object or [r,g,b] array to a hexadecimal color number.

This method can handle different types of input color values, such as 0x2b362 and ‘#ffc49c’ as well as simple [r,g,b] arrays or {r,g,b} objects whose elements or components are in the range (0 to 1).

As a result, this method must check the type of the argument before converting its value, which adds some overhead to the conversion when compared to using thetoHexFromRGB, toHexFromCSS, toHexFromColorObject or toHexFromColorArray methods directly, assuming that you know its type beforehand.

If the given argument does not define a valid color, this method will return zero (black).

Kind: static method of Utils
Returns: number - Returns the color as a hexadecimal number.

ParamTypeDescription
coloranyA number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
[defaultValue]numberAn optional default hexadecimal color value to use if the given color is invalid, defaults to zero.

Utils.randomColorAsHex([modifier]) ⇒ number

Returns a random hexadecimal color value.

Kind: static method of Utils
Returns: number - Returns a random hexadecimal color value.

ParamTypeDescription
[modifier]numberA dark/light modifier value in the range (-0.9 to 0.9).

Utils.toCSSFromRGB(r, g, b) ⇒ string

Converts color components to a CSS color in ‘#RRGGBB’ format.

Kind: static method of Utils
Returns: string - Returns a CSS color string of the form ‘#RRGGBB’.

ParamTypeDescription
rnumberThe red colour component in the range (0 to 1).
gnumberThe green colour component in the range (0 to 1).
bnumberThe blue colour component in the range (0 to 1).

Utils.toCSSFromHex(hex) ⇒ string

Converts a hexadecimal number to a CSS color in ‘#RRGGBB’ format.

Kind: static method of Utils
Returns: string - Returns a CSS color string of the form ‘#RRGGBB’.

ParamTypeDescription
hexnumberThe color as a hexadecimal number.

Utils.toCSSFromColorObject(obj) ⇒ string

Converts an {r,g,b} color object to a CSS color in ‘#RRGGBB’ format.

If the given argument does not define a valid color, this method will return ’none’.

Kind: static method of Utils
Returns: string - Returns a hexadecimal color string of the form ‘#RRGGBB’.

ParamTypeDescription
objColorTypeAn {r,g,b} color object with components in the range (0 to 1).

Utils.toCSSFromColorArray(arr) ⇒ string

Converts an [r,g,b] color array to a CSS color in ‘#RRGGBB’ format.

If the given argument does not define a valid color, this method will return ’none’.

Kind: static method of Utils
Returns: string - Returns a hexadecimal color string of the form ‘#RRGGBB’.

ParamTypeDescription
arrArray.<number>An [r,g,b] color array with values in the range (0 to 1).

Utils.toCSSFromAnyColor(color, [defaultValue]) ⇒ string

Converts a color number, string, {r,g,b} object or [r,g,b] array to a CSS color value in ‘#RRGGBB’ format.

This method can handle different types of input color values, such as 0x2b362 and ‘#ffc49c’ as well as simple [r,g,b] arrays or {r,g,b} objects whose elements or components are in the range (0 to 1).

As a result, this method must check the type of the argument before converting its value, which adds some overhead to the conversion when compared to using the toCSSFromRGB, toCSSFromHex, toCSSFromColorObject or toCSSFromColorArray methods directly, assuming that you know its type beforehand.

If the given argument does not define a valid color, this method will return ’none’ or the default value.

NOTE: The components or values of any given {r,g,b} color object or [r,g,b] color array must be in the range (0 to 1).

Kind: static method of Utils
Returns: string - Returns a hexadecimal color string of the form ‘#RRGGBB’.

ParamTypeDescription
coloranyA number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
[defaultValue]numberAn optional default hexadecimal color value to use if the given color is invalid, defaults to zero.

Utils.toColorFromRGB(r, g, b, [result]) ⇒ ColorType

Converts a CSS ‘#RRGGBB’ format string to an {r,g,b} color object.

NOTE: The components of the color object will be in the range (0 to 1).

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
rnumberThe red colour component in the range (0 to 1).
gnumberThe green colour component in the range (0 to 1).
bnumberThe blue colour component in the range (0 to 1).
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.toColorFromHex(hex, [result]) ⇒ ColorType

Converts a hexadecimal number to an {r,g,b} color object.

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
hexnumberThe color as a hexadecimal number.
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.toColorFromCSS(css, [result]) ⇒ ColorType

Converts a CSS ‘#RRGGBB’ format string to an {r,g,b} color object.

If the given argument does not define a valid color, this method will set the value all to zero (black).

NOTE: The components of the color object will be in the range (0 to 1).

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
cssstringA hexadecimal CSS color string of the form ‘#RRGGBB’.
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.toColorFromColorArray(arr, [result]) ⇒ ColorType

Converts an [r,g,b] color array to an {r,g,b} color object.

If the given argument does not define a valid color, this method will set the value all to zero (black).

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
arrArray.<number>An [r,g,b] color array with values in the range (0 to 1).
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.toColorFromAnyColor(color, [result]) ⇒ ColorType

Converts a color number, string, {r,g,b} object or [r,g,b] array to an {r,g,b} color object.

This method can handle different types of input color values, such as 0x2b362 and ‘#ffc49c’ as well as simple [r,g,b] arrays or {r,g,b} objects whose elements or components are in the range (0 to 1).

As a result, this method must check the type of the argument before converting its value, which adds some overhead to the conversion.

If the given argument does not define a valid color, this method will set all color components to zero (black).

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
coloranyA number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.randomColorAsObject([modifier], [result]) ⇒ ColorType

Returns a random color as an {r,g,b} object.

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
[modifier]numberA dark/light modifier value (-0.9 to 0.9), defaults to zero.
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.toColorArrayFromHex(hex, [result]) ⇒ Array.<number>

Converts a hexadecimal number to an [r,g,b] color array.

Kind: static method of Utils
Returns: Array.<number> - Returns the given [r,g,b] color array or a newly generated one.

ParamTypeDescription
hexnumberThe color as a hexadecimal number.
[result]Array.<number>An optional [r,g,b] color array to store the result in.

Utils.toColorArrayFromCSS(css, [result]) ⇒ Array.<number>

Converts a ‘#RRGGBB’ format string to an [r,g,b] color array.

NOTE: The elements of the color array will be in the range (0 to 1).

Kind: static method of Utils
Returns: Array.<number> - Returns the given [r,g,b] color array or a newly generated one.

ParamTypeDescription
cssstringA Hexadecimal color string of the form ‘#RRGGBB’.
[result]Array.<number>An optional [r,g,b] color array to store the result in.

Utils.toColorArrayFromAnyColor(color, [result]) ⇒ Array.<number>

Converts a color number, string, {r,g,b} object or [r,g,b] array to an [r,g,b] color array.

This method must check the type of the argument before converting its value, which adds some overhead to the conversion.

If the given argument does not define a valid color, this method will set all array elements to zero (black).

NOTE: The components or values of any given {r,g,b} color object or [r,g,b] color array must be in the range (0 to 1).

Kind: static method of Utils
Returns: Array.<number> - Returns the given [r,g,b] color array or a newly generated one.

ParamTypeDescription
coloranyA number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
[result]Array.<number>An optional [r,g,b] color array to store the result in.

Utils.randomColorAsArray([modifier], [result]) ⇒ ColorType

Returns a random color as an [r,g,b] array.

Kind: static method of Utils
Returns: ColorType - Returns the given [r,g,b] color array or a newly generated one.

ParamTypeDescription
[modifier]numberA dark/light modifier value (-0.9 to 0.9), defaults to zero.
[result]Array.<number>An optional [r,g,b] color array to store the result in.

Utils.colorScaleRainbow(fraction, [result]) ⇒ ColorType

Generates a rainbow color scale.

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
fractionnumberA fractional scale value (0 to 1).
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.colorScaleRainbowArray(fraction, [result]) ⇒ Array

Generates a rainbow color scale.

Kind: static method of Utils
Returns: Array - Returns the given color or a newly generated one.

ParamTypeDescription
fractionnumberA fractional scale value (0 to 1).
[result]ArrayAn optional color array to store the result in.

Utils.colorScaleRedWhiteBlue(fraction, [result]) ⇒ ColorType

Generates a thermal color scale from blue(0) to white(0.5) to red(1).

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
fractionnumberA fractional scale value (0 to 1).
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.colorScaleSepia(fraction, [result]) ⇒ ColorType

Generates a sepia color scale.

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
fractionnumberA fractional scale value (0 to 1).
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.colorScaleEcotect(fraction, [result]) ⇒ ColorType

Generates an Ecotect-themed color scale.

Kind: static method of Utils
Returns: ColorType - Returns the given {r,g,b} color object or a newly generated one.

ParamTypeDescription
fractionnumberA fractional scale value (0 to 1).
[result]ColorTypeAn optional {r,g,b} color object to store the result in.

Utils.normalizeColor(color) ⇒ PD.Utils.ColorObject

Scales the color values to within the range 0 to 1.

Kind: static method of Utils
Returns: PD.Utils.ColorObject - Returns the given color object.

ParamTypeDescription
colorPD.Utils.ColorObjectThe color object to normalise.

Utils.visibleTextColorAsCSS(color, [disabled]) ⇒ string

Returns either black, gray or white as an ‘#RRGGBB’ CSS color string, depending on the relative brightness of the given color.

This method is typically used to ensure that the text of a UI element with varying background color is always visible. It can handle different types of input color values, such as 0x2b362 and ‘#ffc49c’ as well as simple [r,g,b] arrays or {r,g,b} objects whose elements or components are in the range (0 to 1).

As a result, this method must check the type of the argument before converting its value, which adds some overhead to the conversion.

If the given argument does not define a valid color, this method will return either white or gray if the disabled flag is true.

NOTE: The components or values of any given {r,g,b} color object or [r,g,b] color array must be in the range (0 to 1).

Kind: static method of Utils
Returns: string - Returns a hexadecimal color string of the form ‘#RRGGBB’.

ParamTypeDescription
coloranyA number, CSS string, {r,g,b} color object or [r,g,b] color array with components in the range (0 to 1).
[disabled]booleanAn optional flag indicating that the UI element is disabled.

Utils.getUniqueId() ⇒ number

Utility function to generate a consecutive but unique numeric id value.

Kind: static method of Utils
Returns: number - Returns a unique number incremented on each call.

Utils.getUniqueIdAsString([id]) ⇒ string

Utility function to generate a formatted string from a numeric id value.

If this method is called without an argument (or the optional argument is zero, null or undefined), a new unique numeric id value will be generated. It uses the id value to generate a left padded string of at least four (4) characters.

Kind: static method of Utils
Returns: string - Returns the numeric id formatted to string of at least four characters.

ParamTypeDescription
[id]numberThe numeric id value to format, defaults to a new unique value if zero, null or undefined.

Utils.getUniqueIdForDOM([prefix]) ⇒ string

Utility function to generate consecutive but unique DOM id values.

This method generates a string identifier that is unique to the current web page session and can be used for the id attribute of HTML tags. It generates a string value in the form pd-dom-id-XXXX, where XXXX is a four digit number (left padded with zeros) that is incremented on each call.

Kind: static method of Utils
Returns: string - Returns a unique DOM identifier string.

ParamTypeDescription
[prefix]stringAn optional prefix to use, defaults to ‘pd-dom-id’.

Utils.virtualBoundingClientRect([x], [y], [w], [h])

Creates a ‘fake’ dynamic bounding rectangle for use with Bootstrap popovers and tooltips that track virtual elements using Popper.js.

Kind: static method of Utils

ParamTypeDescription
[x]numberThe initial position of the rectangle in the page’s X-axis, defaults to zero.
[y]numberThe initial position of the rectangle in the page’s Y-axis, defaults to zero.
[w]numberThe initial width of the rectangle in the page’s X-axis, defaults to zero.
[h]numberThe initial height of the rectangle in the page’s Y-axis, defaults to zero.

Example

const virtual_rect = new PD.Utils.virtualBoundingClientRect();
 const virtual_element = {
     getBoundingClientRect: virtual_rect.getBoundingClientRectFn(),
 };

 const my_popover = new bootstrap.Popover(virtual_element, {
     content: 'Some Content',
     title: 'Title'
 });

 document.addEventListener('mousemove', (event) => {
     virtual_rect.setPos(event.clientX, event.clientY);
     my_popover.update();
 });

virtualBoundingClientRect.getBoundingClientRectFn() ⇒ function

Generates a function that returns the reusable client rect on demand.

Kind: instance method of virtualBoundingClientRect
Returns: function - Returns a function that return an object that simulates a bounding rectangle.

virtualBoundingClientRect.setPos([x], [y]) ⇒ object

Updates the X and Y axis position of the reusable client rect.

Kind: instance method of virtualBoundingClientRect
Returns: object - Returns the simulated client rectangle.

ParamTypeDescription
[x]numberThe new position of the rectangle in the page’s X-axis, defaults to existing x.
[y]numberThe new position of the rectangle in the page’s Y-axis, defaults to existing y.

virtualBoundingClientRect.setSize([w], [h]) ⇒ object

Updates the size of the reusable client rect.

Kind: instance method of virtualBoundingClientRect
Returns: object - Returns the simulated bounding rectangle.

ParamTypeDescription
[w]numberThe new width of the rectangle in the page’s X-axis, defaults to existing width.
[h]numberThe new height of the rectangle in the page’s Y-axis, defaults to existing height.

virtualBoundingClientRect~_rect : object

A reusable client rect for updating.

Kind: inner constant of virtualBoundingClientRect

Utils.parseCSV(csv, [separator]) ⇒ Array

Parses a line of comma-separated values into an array.

Kind: static method of Utils
Returns: Array - Returns an array of values.

ParamTypeDescription
csvstringA single-line string containing comma-separated values.
[separator]stringThe delimiter to separate values with, defaults to a comma.

Utils.UTF8_to_Base64(str) ⇒ string

Converts a UTF8 encoded string to Base64.

Kind: static method of Utils
Returns: string - Returns the Base64 string. Ref: https://stackoverflow.com/a/30106551

ParamTypeDescription
strstringThe UTF8 string to encode.

Utils.Base64_to_UTF8(str) ⇒ string

Converts a Base64 encoded string to UTF8.

Kind: static method of Utils
Returns: string - Returns the UTF8 string. Ref: https://stackoverflow.com/a/30106551

ParamTypeDescription
strstringThe Base64 string to encode.

Utils.splitStringByLineBreaks(str) ⇒ Array.<string>

Converts a multi-line string to a JSON compatible string array.

Kind: static method of Utils
Returns: Array.<string> - Returns the string array.

ParamTypeDescription
strstringThe multi-line string to convert.

Utils.joinArrayWithLineBreaks(array) ⇒ string

Converts an array of strings to multi-line string.

Kind: static method of Utils
Returns: string - Returns the joined string.

ParamTypeDescription
arrayArray.<string>The multi-line string as an array.

Utils.convertToString(thing) ⇒ string

Converts the given argument to a string, even if it is an array.

Kind: static method of Utils
Returns: string - Returns the argument as a joined string.

ParamTypeDescription
thingstring | Array.<string>A single or multi-line string to convert.

Utils.jsonStringify(obj) ⇒ string

Returns a JSON string with arrays formatted be on the same line.

Kind: static method of Utils
Returns: string - Returns A formatted JSON string.

ParamTypeDescription
objobjectAn object to convert to formatted JSON.

Utils.getNestedProperty(host, path, [defaultValue]) ⇒ any

Retrieve the value of a nested property on a host object using a string path.

A nested property is one where the path contains one or more period (’.’) characters that separate it into a hierarchy of parent/child objects. If the path does not contain a period, then the whole string is treated as a field name on the host object.

As objects and arrays in JavaScript behave in some ways similar, you can use nested properties to access array entries by simply using a number as the field name to represent the ordinal index you want.

Kind: static method of Utils
Returns: any - Returns the property value or undefined if the path does not resolve to a valid property.

ParamTypeDescription
hostobjectThe object containing the nested properties.
pathstringA string containing dot-separated properties.
[defaultValue]anyThe value to return if the property path does not exist, defaults to undefined.

Utils.setNestedProperty(host, path, value)

Set the value of a nested property on a host object using a string path.

A nested property is one where the path contains one or more period (’.’) characters that separate it into a hierarchy of parent/child objects. If the path does not contain a period, then the whole string is treated as a field name on the host object.

As objects and arrays in JavaScript behave in some ways similar, you can use nested properties to access array entries by simply using a number as the field name to represent the ordinal index you want.

Kind: static method of Utils

ParamTypeDescription
hostobjectThe object containing the nested properties.
pathstringA string containing dot-separated properties.
valueanyThe value to set the nested property to if it exists.

Utils.parseValidJSON(text) ⇒ Object | Array | null

Tries to convert the string to a valid JSON object or array.

If the string is not a valid JSON object or array, the method returns nul1.

Kind: static method of Utils
Returns: Object | Array | null - Returns the converted JSON, or null if invalid.

ParamTypeDescription
textStringThe JSON text to parse.

Utils.fromXML(xmlDoc) ⇒ object

Recursively converts an XML document into a simple JSON-based object.

Kind: static method of Utils
Returns: object - Returns a JSON-based object.

ParamTypeDescription
xmlDocXMLDocumentAn XML document obtained from ‘DOMParser().parseFromString()’.

Utils.toXML(jsonObj, rootTag) ⇒ object

Converts a simple JSON-based object to an XML document.

Kind: static method of Utils
Returns: object - Returns an XML DOM object.

ParamTypeDescription
jsonObjobjectA simple JSON-based object.
rootTagstringThe name of the top-level XML tag.

PD.RandomNumberCache

A fast cache of repeating random numbers.

Kind: static class of PD
Author: drajmarsh

new PD.RandomNumberCache([size], [min], [max])

Creates a new cache of repeating random numbers.

If no size is given, the cache will remain empty until the first call to the reset() method. Until then, calls to next() will always return zero.

In terms of size, it is usually best to use a prime number to avoid situations where the repeating pattern becomes visible. The following are some prime examples: 61, 67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151, 157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229, 233, 239, 241, 251, 257, 263, 269, 271, 277, 281, 283 and 293.

ParamTypeDescription
[size]numberThe number of entries in the cache, defaults to 128.
[min]numberThe minimum value of the random number range, defaults to 0.
[max]numberThe maximum value of the random number range, defaults to 1.

randomNumberCache.initialise([size], [min], [max]) ⇒ PF.RandomNumberCache

Rebuilds the cache with new numbers based on the given size and range.

If no range is given, or either value is not a valid number, the range defaults to fractional values between 0 and 1.

In terms of size, it is usually best to use a prime number to avoid situations where the repeating pattern becomes visible. The following are some prime examples: 61, 67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151, 157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229, 233, 239, 241, 251, 257, 263, 269, 271, 277, 281, 283 and 293.

NOTE: To prevent inadvertent memory use, the size of this cache is limited to between 2 and 16384 items.

Kind: instance method of RandomNumberCache
Returns: PF.RandomNumberCache - Returns this cache instance to support method chaining.

ParamTypeDescription
[size]numberThe number of entries in the cache, defaults to 127.
[min]numberThe minimum value of the random number range, defaults to 0.
[max]numberThe maximum value of the random number range, defaults to 1.

randomNumberCache.getCacheSize() ⇒ number

Retrieves the current size of the cache.

Kind: instance method of RandomNumberCache
Returns: number - Returns the number of items in the cache.

randomNumberCache.reset() ⇒ RandomNumberCache

Sets the index back to zero ready to start repeating.

Kind: instance method of RandomNumberCache
Returns: RandomNumberCache - Returns this cache instance to support method chaining.

randomNumberCache.next() ⇒ number

Retrieve the next item in the random number cache.

Each access increments the cache index which will then wrap back once it reaches the end.

Kind: instance method of RandomNumberCache
Returns: number - Returns a the next number from the cache.

PD.Indexer

A tool for identifying unique and non-unique entries within a dataset.

This class generates indices into a list of unique objects from a stream of objects that may contain duplicates. This is useful for generating compact indexed meshes from un-indexed data.

The uniqueness or otherwise of an object depends on how its key is generated. The addById method uses a numeric id which is assigned to each vector array in order to absolutely identify any that the indexer has seen before. The addVectorObject and addVectorArray methods uses a string constructed from the axial components of each vector component, whilst the addObject method uses a unique hash constructed using JSON.stringify.

For each stream, you should only use one of the above methods for indexing objects.

Kind: static class of PD
Author: drajmarsh

new PD.Indexer([decimals])

Creates a new indexer.

ParamTypeDescription
[decimals]numberThe number of decimal places to use when comparing coordinates (0 or more), defaults to 3.

indexer.unique : Array

An array of unique items in the data stream.

Kind: instance property of Indexer

indexer.map : object

An empty object storing the array index of each unique item.

Kind: instance property of Indexer

indexer.indexId : number

The current key value when using the addById method.

Kind: instance property of Indexer

indexer.decimals : number

The number of decimal places to use when encoding vectors (0 or more).

Kind: instance property of Indexer

indexer.clear() ⇒ Indexer

Clears all results from the indexer.

Kind: instance method of Indexer
Returns: Indexer - Returns this indexer to support method chaining.

indexer.getEntryIndex(key, data) ⇒ number

Returns the index of an existing entry for a key, or adds a new entry.

Kind: instance method of Indexer
Returns: number - Returns the index of the key entry within the list.

ParamTypeDescription
keystringThe map key to check for.
dataanyThe object or data to store if no existing entry.

indexer.getEntry(key, data) ⇒ any

Returns the value of an existing entry for a key, or adds a new entry.

Kind: instance method of Indexer
Returns: any - Returns the data associated with of the key.

ParamTypeDescription
keystringThe map key to check for.
dataanyThe object or data to store if no existing entry.

indexer.addEntry(key, data) ⇒ number

Returns the index of an existing entry for a key, or adds a new entry.

Kind: instance method of Indexer
Returns: number - Returns the index of the key entry within the list.

ParamTypeDescription
keystringThe map key to check for.
dataanyThe object or data to store if no existing entry.

indexer.addObject(obj) ⇒ number

Adds the given object if it doesn’t already exist and returns its numeric index in the list.

This method uses a JSON representation of the object as its unique key.

Kind: instance method of Indexer
Returns: number - Returns the index of the object within the list.

ParamTypeDescription
objobjectAn arbitrary object with a viable JSON representation.

indexer.addById(obj) ⇒ number

Checks for an entry and adds it if it doesn’t already exist.

This method adds a new _indexId property to each object and uses that as its unique key. It returns the numeric index of the object in the list.

NOTE: If you use multiple indexers across shared objects, you will need to manually reset the _indexId property of all previously indexed objects back to zero.

Kind: instance method of Indexer
Returns: number - Returns the index of the object within the list.

ParamTypeDescription
objobject | ArrayAn object or array to stamp and index.

indexer.addVectorArray(vec) ⇒ number

Checks for a vector array and adds it if it doesn’t already exist.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: number - Returns the index of the object within the list.

ParamTypeDescription
vecArray.<number>A vector array in the form [x,y,z].

indexer.addVectorObject(pnt) ⇒ number

Checks for a vector object and adds it if it doesn’t already exist.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: number - Returns the index of the object within the list.

ParamTypeDescription
pntobjectAn object with numeric x, y and z properties.

indexer.getUniqueVectorArray(vec) ⇒ Array

Returns a matching vector array or adds it if not found.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: Array - Returns a matching vector array from the list.

ParamTypeDescription
vecArray.<number>A vector array in the form [x,y,z].

indexer.getUniqueVectorObject(pnt) ⇒ object

Returns a matching vector object or adds it if not found.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: object - Returns a matching vector object within the list.

ParamTypeDescription
pntobjectAn object with numeric x, y and z properties.

indexer.getUniqueEntry(key, obj) ⇒ any

Returns a matching vector array in the XY plane or adds it.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: any - Returns an existing or new entry matching the key.

ParamTypeDescription
keystringThe map key to check for.
objanyThe object or data to store if no existing entry.

indexer.getVectorKey3D(pnt) ⇒ string

Returns a key created from the given {x,y,z} point object.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: string - Returns the key for this 3D point.

ParamTypeDescription
pntobjectAn object with numeric x, y and z properties.

indexer.getVectorKey2D(pnt) ⇒ string

Returns a key created from the given {x,y} point object.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: string - Returns the key for this 2D point.

ParamTypeDescription
pntobjectAn object with numeric x and y properties.

indexer.getClipPtKey2D(clipPt) ⇒ string

Returns a key created from the given {X,Y} ClipperLib point object.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: string - Returns the key for this 3D point.

ParamTypeDescription
clipPtobjectAn object with numeric X and Y properties.

indexer.getKey2D(X, Y) ⇒ string

Returns a key created from the given 2D x and y position.

This method uses the decimals property of the Indexer to generate a unique unique key for this position. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: string - Returns the key for XY position.

ParamTypeDescription
XnumberThe 2D X-axis component.
YnumberThe 2D Y-axis component.

indexer.getVectorArrayKey3D(vec) ⇒ string

Returns a key created from the given [x,y,z] vector array.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: string - Returns the key for this 2D vector.

ParamTypeDescription
vecArrayA vector array in the form [x,y[,z]].

indexer.getVectorArrayKey2D(vec) ⇒ string

Returns a key created from the given [x,y] vector array.

This method uses the decimals property of the Indexer to generate each item’s unique key. This defaults to 3 decimal places which should typically be fine as all dimensions are assumed to be in millimetres, so this means accuracy is down to the micrometre.

You can set the decimal places to 0 if you want objects to share coordinates that are within one millimeter of each other.

Kind: instance method of Indexer
Returns: string - Returns the key for this 2D vector.

ParamTypeDescription
vecArrayA vector array in the form [x,y].

indexer.getMeshVertexIndexXY(mesh, vec) ⇒ number

Returns the index of an existing entry for a key, or adds a new entry.

Kind: instance method of Indexer
Returns: number - Returns the index of a matching mesh vertex or -1 if the given vector array is not valid.

ParamTypeDescription
meshPD.PolyMeshThe dynamic mesh to add new vertices to.
vecArrayA vector array in the form [x,y,z] with the position to look for.

indexer.getMeshVertexIndex(mesh, pnt) ⇒ number

Returns a unique mesh vertex index for the given position.

Kind: instance method of Indexer
Returns: number - Returns the index of an existing vertex if the keys match, or adds a new vertex with the key and returns its index.

ParamTypeDescription
meshPD.PolyMeshThe mesh to add new vertices to.
pntPD.Utils.VectorObjectAn {x,y,z} vector with the position to look for.

indexer.getBRepVertex(brep, pnt) ⇒ PD.Utils.VectorObject

Returns a unique vertex index for the given position.

Kind: instance method of Indexer
Returns: PD.Utils.VectorObject - Returns an existing vertex if the keys match, or adds a new vertex with its key.

ParamTypeDescription
brepPD.BRepThe surface to add new vertices to.
pntPD.Utils.VectorObjectAn {x,y,z} vector with the position to look for.

PD.Easing

A static helper class with a range of easing functions.

These were inspired by http://gizma.com/easing/, but only considering the t value for the range [0..1] => [0..1], as per: https://gist.github.com/gre/1650294.

Kind: static class of PD
Author: drajmarsh

Easing.linear(t) ⇒ number

No easing, no acceleration.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inSine(t) ⇒ number

Accelerating from zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outSine(t) ⇒ number

Decelerating to zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutSine(t) ⇒ number

Acceleration until halfway, then deceleration.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutSinePow(t, p) ⇒ number

Acceleration until halfway, then deceleration.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).
pnumberAn optional power value apply to the result, defaults to 2.0.

Easing.inQuad(t) ⇒ number

Accelerating from zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outQuad(t) ⇒ number

Decelerating to zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutQuad(t) ⇒ number

Acceleration until halfway, then deceleration.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inCubic(t) ⇒ number

Accelerating from zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outCubic(t) ⇒ number

Decelerating to zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutCubic(t) ⇒ number

Acceleration until halfway, then deceleration.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inQuart(t) ⇒ number

Accelerating from zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outQuart(t) ⇒ number

Decelerating to zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutQuart(t) ⇒ number

Acceleration until halfway, then deceleration.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inQuint(t) ⇒ number

Accelerating from zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outQuint(t) ⇒ number

Decelerating to zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutQuint(t) ⇒ number

Acceleration until halfway, then deceleration.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inExpo(t) ⇒ number

Accelerating from zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outExpo(t) ⇒ number

Decelerating to zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutExpo(t) ⇒ number

Acceleration until halfway, then deceleration.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inCirc(t) ⇒ number

Accelerating from zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outCirc(t) ⇒ number

Decelerating to zero velocity.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutCirc(t) ⇒ number

Acceleration until halfway, then deceleration.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inBack(t) ⇒ number

A bit of over-run at start.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outBack(t) ⇒ number

A bit of over-run at end.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutBack(t) ⇒ number

A bit of over-run at both start and end.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inBounce(t) ⇒ number

A bit of a bounce at start.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outBounce(t) ⇒ number

A bit of a bounce at end.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutBounce(t) ⇒ number

A bit of a bounce at start and end.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inWobble(t) ⇒ number

A bit of an elastic jelly wobble at the start.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outWobble(t) ⇒ number

A bit of an elastic jelly wobble at the end.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.inOutWobble(t) ⇒ number

A bit of an elastic jelly wobble at the end.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).

Easing.outElastic(t, p) ⇒ number

A bit of an elastic bounce at the end.

Kind: static method of Easing
Returns: number - Returns the modified progress (0-1).

ParamTypeDescription
tnumberThe progress value (0-1).
pnumberAn optional power value apply to the result, defaults to 0.35.

PD.DIMENSION

Enumerates the different types of length dimension formats.

Kind: static enum of PD
Read Only: true
Author: drajmarsh Properties

NameTypeDefaultDescription
DEFAULTnumber0Show default units.
METRIC_MMnumber1Show dimensions in integer millimeters.
METRIC_SInumber2Show dimensions in decimal meters.
IMPERIALnumber3Show dimensions in feet, inches and sixteenths.
_unitsDIMENSION1Stores the preferred format for displaying dimensions.
useImperialbooleanfalseWhether or not imperial dimensions are currently being used.
mmToMetresConverts a distance in millimetres to metres.
mm2ToMetres2Converts an area in square millimetres to square metres.
mm3ToMetres3Converts a volume in cubic millimetres to cubic metres.
metersToFeetConverts a distance in metres to decimal feet.
metersToInchesConverts a distance in metres to decimal inches.
metersToMillimetersConverts a distance in metres to millimetres.
feetToMetersConverts a distance in decimal feet to metres.
feetToMillimetersConverts a distance in decimal feet to mm.
feetToInchesConverts a distance in decimal feet to decimal inches.
inchesToMetersConverts a distance in decimal inches to metres.
inchesToMillimetersConverts a distance in decimal inches to mm.
inchesToFeetConverts a distance in decimal inches to decimal feet.

PD.ALIGN

Defines a set of positional alignment values.

These values are also bit-wise flags that can be used in bit operations. As a result, this object provides a number of methods to check components of a value for just the horizontal (left, center, right) or vertical (bottom, middle, top) components.

Kind: static enum of PD
Read Only: true
Author: drajmarsh Properties

NameTypeDefaultDescription
NONEnumber0No alignment, use absolute positioning.
LEFTnumber1Horizontally align item to the left.
CENTERnumber2Horizontally align item to center.
RIGHTnumber4Horizontally align item to the right.
BOTTOMnumber8Vertically align item to bottom extent.
MIDDLEnumber16Vertically align item to middle.
TOPnumber32Vertically align item to top extent.
BOT_LEFTnumber9Align item to bottom-left corner. Contains bit flags for BOTTOM and LEFT.
BOT_CENTERnumber10Align item to bottom-center edge. Contains bit flags for BOTTOM and CENTER.
BOT_RIGHTnumber12Align item to bottom-right corner. Contains bit flags for BOTTOM and RIGHT.
MID_LEFTnumber17Align item to middle-left edge. Contains bit flags for MIDDLE and LEFT.
MID_CENTERnumber18Align item to middle-center point. Contains bit flags for MIDDLE and CENTER.
MID_RIGHTnumber20Align item to middle-right edge. Contains bit flags for MIDDLE and RIGHT.
TOP_LEFTnumber33Align item to top-left corner. Contains bit flags for TOP and LEFT.
TOP_CENTERnumber34Align item to top-center edge. Contains bit flags for TOP and CENTER.
TOP_RIGHTnumber36Align item to top-right corner. Contains bit flags for TOP and RIGHT.
isTopfunctionDetermines if the given alignment contains the TOP bit flag.
isMiddlefunctionDetermines if the given alignment contains the MIDDLE bit flag.
isBottomfunctionDetermines if the given alignment contains the BOTTOM bit flag.
isLeftfunctionDetermines if the given alignment contains the LEFT bit flag.
isCenterfunctionDetermines if the given alignment contains the CENTER bit flag.
isRightfunctionDetermines if the given alignment contains the RIGHT bit flag.
computeFromUVfunctionCompute alignment from relative fractional UV coordinates.
_UPPERnumber64For 3D application, refers to the maximum Z value.
_MIDWAYnumber128For 3D application, refers to the midway between minimum and maximum Z value.
isUpperfunctionDetermines if the Z-Axis alignment is UPPER.
useUpperfunctionDetermines if the given alignment contains the UPPER bit flag.
isMidwayfunctionDetermines if the given alignment contains the MIDWAY bit flag.
useMidwayfunctionDetermines if the given alignment contains the MIDWAY bit flag.
useLowerfunctionDetermines if the given alignment contains the MIDWAY bit flag.
getAsOptionListRetrieve enumerators as an array of {name, value} objects compatible with a PD.ParamType options list.
getParamTypefunctionRetrieve a selectable enumerator list as a PD.ParamType from global cache.

PD.KEY

Enumerates the keyboard keys that control increment/decrement values.

Kind: static enum of PD
Read Only: true
Author: drajmarsh Properties

NameTypeDefaultDescription
NONEnumber0Applies a minor increment to the value, typically 5 * step.
SHIFTnumber16Applies a major increment to the value, typically 50 * step.
CONTROLnumber17Applies the smallest step increment to the value.