API Docs Class: CAD

new 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 PD.CAD.model as they are created, transformed and modified. The PD.CAD.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 PD.CAD is PD.OCC, which provides lower-level methods that interface directly with OpenCascade. In fact, most of the creation, transformation and modification methods in PD.CAD have corresponding lower-level methods with similar names in PD.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 PD.CAD.add and PD.CAD.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 PD.CAD.add and PD.CAD.remove methods to add and remove any generated oc.TopoDS_Shape to/from the CAD model.

Caching

PD.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.

Author:

drajmarsh

Classes

Path

Members

:object|null font <static>

The font to use for 3D text.

Type

object | null

:boolean isCancelled <static>

A flag indicating that user has cancelled process.

Type

boolean

:number logLevel <static>

The level of logging to display.

Type

number

:Array.<oc.TopoDS_Shape>|Array.<PD.Shape> model <static>

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

Shapes created using PD.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 PD.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 PD.CAD.add method to add them. You can also use the PD.CAD.remove to remove shapes from the model.

The PD.CAD.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.

Type

Array.<oc.TopoDS_Shape> | Array.<PD.Shape>

:Array.<LogEntry> processLog <static>

Maintains a log of each operation.

Type

Array.<LogEntry>

:boolean useCache <static>

Whether or not to cache primitives and operations.

Type

boolean

Methods

add(shapes) <static>

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

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape	<repeatable>	One or more shapes to add.

addBox(width, depth, height [, centered]) <static>

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 PD.OCC.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.

Parameters:

Name	Type	Argument	Description
`width`	number		The size of the box in the X-axis, defaults to 1000mm (1m).
`depth`	number		The size of the box in the Y-axis, defaults to 1000mm (1m).
`height`	number		The size of the box in the Z-axis, defaults to 1000mm (1m).
`centered`	boolean	<optional>	An optional flag indicating that the box should be centered at the origin rather than at its bottom-left, defaults to false.

Returns:

Returns a rectangular prism shape.

Type: oc.TopoDS_Shape

addBoxByMinMax(min, min) <static>

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 PD.OCC.cuboid method directly.

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

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

Parameters:

Name	Type	Description
`min`	Array.<number>	An [x,y,z] vector array defining the minimum box extents.
`min`	Array.<number>	An [x,y,z] vector array defining the maximum box extents.

Returns:

Returns a rectangular prism shape.

Type: oc.TopoDS_Shape

addCapsule(radius, height [, endRadius]) <static>

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 PD.OCC.cylinder method directly.

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

Parameters:

Name	Type	Argument	Description
`radius`	number		The distance of the cylinder surface from the centre axis.
`height`	number		The distance between the top and bottom planes.
`endRadius`	number	<optional>	The radius of the rounded end of the capsule (0 to radius), defaults to the cylinder radius.

Returns:

Returns a cylindrical shape.

Type: oc.TopoDS_Shape

addChamfer(shape, distance, edges [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to chamfer.
`distance`	number		The size of the chamfer in model units.
`edges`	Array.<number>		An array of edge indices to apply the chamfer to, with an empty array meaning all edges.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original shape in the model, defaults to false.

Returns:

Returns the chamfered solid, or the given shape if no matching edges were found.

Type: oc.TopoDS_Shape | oc.TopoDS_Solid

addCircle(radius [, outline]) <static>

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

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

Parameters:

Name	Type	Argument	Description
`radius`	number		The radius of the circle.
`outline`	boolean	<optional>	An optional flag for the method to return the outline of the shape as a wire rather than as a shape, defaults to false.

Returns:

Returns a circular shape.

Type: oc.TopoDS_Face | oc.TopoDS_Wire

addCone(radiusBot, radiusTop, height [, centered]) <static>

Construct a conical primitive shape at the origin.

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

Parameters:

Name	Type	Argument	Description
`radiusBot`	number		The radius at the bottom of the cone.
`radiusTop`	number		The radius at the top of the cone, typically 0.
`height`	number		The distance between the top and bottom planes.
`centered`	number	<optional>	An optional flag indicating that the given position represents the center of the cone rather than the bottom-left, defaults to false.

Returns:

Returns a conical shape.

Type: oc.TopoDS_Shape

addCylinder(radius, height [, centered]) <static>

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 PD.OCC.cylinder method directly.

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

Parameters:

Name	Type	Argument	Description
`radius`	number		The distance of the cylinder surface from the centre axis.
`height`	number		The distance between the top and bottom planes.
`centered`	number	<optional>	An 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.

Returns:

Returns a cylindrical shape.

Type: oc.TopoDS_Shape

addDome(radius) <static>

Add a new hemispherical shape at the origin.

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

Parameters:

Name	Type	Description
`radius`	number	The distance of the dome surface from the centre.

Returns:

Returns a hemispherical shape.

Type: oc.TopoDS_Shape

addFacetedShell(facets [, tolerance]) <static>

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.

Parameters:

Name	Type	Argument	Description
`facets`	Array.<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`	number	<optional>	An optional face sewing tolerance, defaults to 1mm.

Returns:

Returns a shape sewn together from facets.

Type: oc.TopoDS_Shape

addFillet(shape, radius [, edges] [, makeCopy]) <static>

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.

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to fillet.
`radius`	number \| Array.<number>		The radius of the fillet in model units or one or more radius/edge arrays.
`edges`	Array.<number>	<optional>	An array of edge indices to apply the fillet to, with an empty array meaning all edges.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original shape in the model, defaults to false.

Returns:

Returns the filleted solid, or the given shape if no matching edges were found.

Type: oc.TopoDS_Shape | oc.TopoDS_Solid

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 ]
    ]
);

addHull(shapes [, tolerance] [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shapes`	Array.<Array.<number>> \| oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		An array of shape(s) and/or [x,y,z] point clouds.
`tolerance`	number	<optional>	An optional face sewing tolerance, defaults to 1mm.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original shape(s) in the model, defaults to false.

Returns:

Returns a solid hull shape sewn from multiple faces.

Type: oc.TopoDS_Shape

addHullChain(shapes [, tolerance] [, makeCopy]) <static>

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.

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape> \| Array.<Array.<Array.<number>>>		A shape or array of shapes/points to create a hull from.
`tolerance`	number	<optional>	An optional face sewing tolerance, defaults to 1mm.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original shape in the model, defaults to false.

Returns:

Returns a hull shape sewn from multiple faces.

Type: oc.TopoDS_Shape

addIndexedShell(points, faces [, tolerance]) <static>

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.

Parameters:

Name	Type	Argument	Description
`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 boundaries and/or contours, each containing ordinal indexes of the vertices that make up each face.
`tolerance`	number	<optional>	An optional face sewing tolerance, defaults to 1mm.

Returns:

Returns a shape sewn together from indexed faces.

Type: oc.TopoDS_Shape

addLogEntry(level, message) <static>

Adds a new entry to the process log.

Parameters:

Name	Type	Description
`level`	number	The log level of this message.
`message`	string	The human-readable message to log.

Returns:

Returns a new log entry instance.

Type: LogEntry

addPolygon(points [, outline]) <static>

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

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

Parameters:

Name	Type	Argument	Description
`points`	Array.<Array.<number>>		An array of [x,y,z] vector arrays defining the vertices of the polygon.
`outline`	boolean	<optional>	An 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.

Returns:

Returns a polygonal shape or the wires that bound it.

Type: oc.TopoDS_Face | Array.<oc.TopoDS_Wire>

addPolyhedron(poly [, tolerance]) <static>

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

Parameters:

Name	Type	Argument	Description
`poly`	PD.Polyhedron \| string		The polyhedron to add or a Conway polyhedron notation string.
`tolerance`	number	<optional>	An optional face sewing tolerance, defaults to 1mm.

Returns:

Returns a solid shape sewn together from multiple faces.

Type: oc.TopoDS_Shape

addPrism(radius, sides, height) <static>

Construct a regular prism at the origin.

Parameters:

Name	Type	Description
`radius`	number	The radius of the regular prism.
`sides`	number	The number of sides of the prism (3 to 256).
`height`	number	The distance between the top and bottom planes.

Returns:

Returns a shape sewn together from multiple faces.

Type: oc.TopoDS_Shape

addPyramid(width, depth, height [, truncate]) <static>

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

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

Parameters:

Name	Type	Argument	Description
`width`	number		The size of the wedge in the X-axis.
`depth`	number		The size of the wedge in the Y-axis.
`height`	number		The size of the wedge in the Z-axis.
`truncate`	number	<optional>	The fractional truncation amount (0 to 1), defaults to 1.0.

Returns:

Returns a wedge shape.

Type: oc.TopoDS_Shape

Examples

CAD.addPyramid(4000, 3000, 2000);

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

addShell(shape [, tolerance]) <static>

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

Parameters:

Name	Type	Argument	Description
`shape`	PD.Shape \| object		The shape to add, or an object with `vertices` and `faces`.
`tolerance`	number	<optional>	An optional face sewing tolerance, defaults to 1mm.

Returns:

Returns a shell shape sewn together from multiple faces.

Type: oc.TopoDS_Solid

addSolid(shape [, tolerance]) <static>

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

Parameters:

Name	Type	Argument	Description
`shape`	PD.Shape \| object		The shape to add, or an object with `vertices` and `faces`.
`tolerance`	number	<optional>	An optional face sewing tolerance, defaults to 1mm.

Returns:

Returns a solid shape sewn together from multiple faces.

Type: oc.TopoDS_Solid

addSphere(radius) <static>

Add a new spherical shape at the origin.

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

Parameters:

Name	Type	Description
`radius`	number	The distance of the spherical surface from the centre.

Returns:

Returns a spherical shape.

Type: oc.TopoDS_Shape

addText(text [, size] [, height]) <static>

Construct a set of primitive shapes representing 3D text.

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

Parameters:

Name	Type	Argument	Description
`text`	string		The characters to be generated.
`size`	number	<optional>	The size of the text in model units, defaults to 36.
`height`	number	<optional>	The extrusion height of the text faces, defaults to 0.15.

Returns:

Returns a complex shape representing the text.

Type: oc.TopoDS_Shape | oc.TopoDS_Solid

addTorus(radiusRing, radiusPipe) <static>

Construct a toroidal primitive shape at the origin.

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

Parameters:

Name	Type	Description
`radiusRing`	number	The distance of the pipe center from main centre.
`radiusPipe`	number	The distance of the pipe surface from the pipe centre.

Returns:

Returns a toroidal shape.

Type: oc.TopoDS_Shape

addWedge(width, depth, height [, taperHeight] [, taperWidth]) <static>

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.

Parameters:

Name	Type	Argument	Description
`width`	number		The size of the wedge in the X-axis.
`depth`	number		The size of the wedge in the Y-axis.
`height`	number		The size of the wedge in the Z-axis.
`taperHeight`	number \| Array.<number>	<optional>	The height of the tapered end as a number or [min,max] array, defaults to [0,0].
`taperWidth`	number \| Array.<number>	<optional>	The width of the tapered end as a number or [min,max] array, defaults to [0,width].

Returns:

Returns a wedge shape.

Type: oc.TopoDS_Shape

Examples

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

/// 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);

/// 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 ]);

addWire(points [, closed]) <static>

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

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

Parameters:

Name	Type	Argument	Description
`points`	Array.<Array.<number>>		An array of [x,y,z] vector arrays defining the vertices of the wire.
`closed`	boolean	<optional>	An optional flag indicating that the wire is a closed loop, defaults to false.

Returns:

Returns a wire.

Type: oc.TopoDS_Wire

addWires(contours) <static>

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.

Parameters:

Name	Type	Description
`contours`	Array.<Array.<Array.<number>>>	An array of lines, each containing at least two [x,y,z] vector arrays defining the vertices of the wire.

Returns:

Returns an array of one or more wires.

Type: Array.<oc.TopoDS_Wire>

Example

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

cancelOperation(state) <static>

Sets or clears the cancel operations flags.

Parameters:

Name	Type	Description
`state`	boolean	The name of the operation.

checkCache(caller, args, generatorFn) <static>

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.

Parameters:

Name	Type	Description
`caller`	string	The name of the calling method.
`args`	Array.<any>	An array of arguments defining the operation.
`generatorFn`	function	A callback function to execute the operation.

Returns:

Returns the results of the cached function.

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

checkCancelToken() <static>

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.

Throws:

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

clearCache() <static>

Removes all items from the cache to clear memory.

combine(shapes [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		An array of shapes to combine.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.

Returns:

Returns the compound shape.

Type: oc.TopoDS_Shape

distribute(shapes, spacing [, columns]) <static>

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.

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		A shape or array of shapes to duplicate.
`spacing`	number \| Array.<number>		A number or [x,y,z] vector array defining the grid cell size in each axis.
`columns`	number	<optional>	The number of columns in the X-axis, defaults to 8.

Returns:

Returns the distributed shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

duplicate(shapes, offset [, copies]) <static>

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

Parameters:

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

Returns:

Returns the duplicated shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

error(message) <static>

Outputs an error message to the host application and console.

Parameters:

Name	Type	Description
`message`	string	The error message to log.

evaluateCode(payload) <static>

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

Parameters:

Name Type Description

payload

object

A container object typically sent from the host application.

Properties of `payload`:

Name	Type	Description
`code`	string	The JavaScript code block to evaluate.
`json`	string	The JSON data block to evaluate.

Returns:

Returns an array of faces and edges, of null if there was invalid input.

Type: Array | null

extrude(face, vector [, makeCopy]) <static>

Extrudes a flat polygonal face into a shape.

Parameters:

Name	Type	Argument	Description
`face`	oc.TopoDS_Shape		A flat face shape to extrude.
`vector`	Array.<number>		An [x,y,z] vector array defining the distances to extrude in each axis.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original face in the model, defaults to false.

Returns:

Returns the extruded shape.

Type: oc.TopoDS_Shape

extrudeAndRotate(wire, height, degrees [, makeCopy]) <static>

Extrude and rotate a wire into a 3D shape.

Parameters:

Name	Type	Argument	Description
`wire`	oc.TopoDS_Shape		The wire to extrude.
`height`	number		The height of the extrusion in model units.
`degrees`	number		The angle of rotation in degrees.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original wire in the model, defaults to false.

Returns:

Returns the extruded shape.

Type: oc.TopoDS_Shape

getFace(shape [, index] [, makeCopy]) <static>

Extracts a particular face from within a shape.

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to extract the face from.
`index`	number	<optional>	The ordinal index of the face within the shape, defaults to 0.
`makeCopy`	boolean	<optional>	Keep the original shape in the model, defaults to false.

Returns:

Returns the solid at the given index, or the given shape if no matching solid was found.

Type: oc.TopoDS_Shape | oc.TopoDS_Face

getShapeGeometry(payload) <static>

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.

Parameters:

Name Type Description

payload

object

A container object typically sent from the host application.

Properties of `payload`:

Name	Type	Description
`maxDeviation`	number	The welding tolerance and mesh resolution of the resulting geometry.

Returns:

Returns a [faces,edges] array if successful, otherwise null.

Type: Array | null

getSolid(shape [, index] [, makeCopy]) <static>

Extracts a particular solid from within a compound shape.

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to extract the solid from.
`index`	number	<optional>	The ordinal index of the solid within the shape, defaults to 0.
`makeCopy`	boolean	<optional>	Keep the original solid compound in the model, defaults to false.

Returns:

Returns the solid at the given index, or the given shape if no matching solid was found.

Type: oc.TopoDS_Shape | oc.TopoDS_Solid

getWire(shape [, index] [, makeCopy]) <static>

Extracts a particular wire from within a shape.

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to extract the wire from.
`index`	number	<optional>	The ordinal index of the wire within the shape, defaults to 0.
`makeCopy`	boolean	<optional>	Keep the original shape in the model, defaults to false.

Returns:

Returns the wire at the given index, or the given shape if no matching wire was found.

Type: oc.TopoDS_Shape | oc.TopoDS_Wire

hollow(shape, faces, thickness [, tolerance] [, makeCopy]) <static>

Creates a hollowed out solid from a closed shell.

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to hollow out.
`faces`	Array.<oc.TopoDS_Face>		An array of one or more faces to remove.
`thickness`	number		The thickness of the walls.
`tolerance`	number	<optional>	The tolerance to use when unioning, defaults to 0.1.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original shape in the model, defaults to false.

Returns:

Returns the hollowed out shape.

Type: oc.TopoDS_Shape

importSTEPorIGES(filename, content) <static>

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

Parameters:

Name	Type	Description
`filename`	string	The name of the file.
`content`	string	The contents of the file.

Returns:

Returns a shape if successfully loaded, otherwise null.

Type: oc.TopoDS_Shape | null

importSTL(filename, content) <static>

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

Parameters:

Name	Type	Description
`filename`	string	The name of the file.
`content`	string	The contents of the file.

Returns:

Returns a shape if successfully loaded, otherwise null.

Type: oc.TopoDS_Shape | null

intersect(shapes [, makeCopy] [, tolerance] [, keepEdges]) <static>

Computes the intersection of a set of shapes.

Parameters:

Name	Type	Argument	Description
`shapes`	Array.<oc.TopoDS_Shape>		An array of shapes to intersect.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.
`tolerance`	number	<optional>	The tolerance to use when intersecting, defaults to 0.1.
`keepEdges`	boolean	<optional>	Whether or not to keep the original edge(s) in the shape, defaults to false.

Returns:

Returns the intersection shape.

Type: oc.TopoDS_Shape

loft(wires [, makeCopy]) <static>

Lofts between a set or wires.

Parameters:

Name	Type	Argument	Description
`wires`	Array.<oc.TopoDS_Shape>		The set of wires to loft between.
`makeCopy`	boolean	<optional>	Apply to copies and keep original wires in the model, defaults to false.

Returns:

Returns the lofted shape.

Type: oc.TopoDS_Shape

log(message) <static>

Logs a message to the host application and console.

Parameters:

Name	Type	Description
`message`	string	The message to log.

mirror(shapes, axis [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		A shape or array of shapes to mirror.
`axis`	Array.<number>		An [x,y,z] vector array defining the normal to the mirror plane.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.

Returns:

Returns the mirrored shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

move(shapes, offset [, makeCopy]) <static>

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

This method is simply an alias for PD.CAD.translate.

Parameters:

Name	Type	Argument	Description
`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.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.

Returns:

Returns the translated shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

offset(shape, distance [, tolerance] [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to offset.
`distance`	number		The distance to offset surfaces in the shape.
`tolerance`	number	<optional>	The tolerance to use when welding offset vertices together, defaults to 0.1.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original shape in the model, defaults to false.

Returns:

Returns the offset shape.

Type: oc.TopoDS_Shape

progress( [operation]) <static>

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.

Parameters:

Name	Type	Argument	Description
`operation`	string	<optional>	The operation name or message.

progressMessage(level [, message]) <static>

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.

Parameters:

Name	Type	Argument	Description
`level`	level		The log level of this message.
`message`	string	<optional>	The message to add to the log.

Throws:

Throws and error if process cancelled.
Type Error

progressOperation(level [, operation]) <static>

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.

Parameters:

Name	Type	Argument	Description
`level`	level		The log level of the operation.
`operation`	string	<optional>	The name of the operation to log.

Throws:

Throws and error if process cancelled.
Type Error

remove(shapes) <static>

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

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape	<repeatable>	One or more shapes to remove.

removeInternalEdges(shape [, makeCopy]) <static>

Unifies a shape by cleaning up internal edges.

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to clean up.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original shape in the model, defaults to false.

Returns:

Returns the unified shape.

Type: oc.TopoDS_Shape

revolve(shape, degrees [, axis] [, about] [, makeCopy]) <static>

Revolves a shape by the given angle and axis.

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to revolve.
`degrees`	number		The angle of revolution in degrees.
`axis`	Array.<number>	<optional>	An [x,y,z] vector array defining the axis of revolution, defaults to [ 0, 0, 1 ].
`about`	Array.<number>	<optional>	An [x,y,z] vector array defining the revolution origin, defaults to the origin.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original shape in the model, defaults to false.

Returns:

Returns the revolved shape.

Type: oc.TopoDS_Shape

rotate(shapes, axis, degrees [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		A shape or array of shapes to rotate.
`axis`	Array.<number>		An [x,y,z] vector array defining the axis of rotation.
`degrees`	number		The angle of rotation in decimal degrees.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.

Returns:

Returns the rotated shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

rotateX(shapes, degrees [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		A shape or array of shapes to rotate.
`degrees`	number		The angle of rotation in decimal degrees.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.

Returns:

Returns the rotated shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

rotateY(shapes, degrees [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		A shape or array of shapes to rotate.
`degrees`	number		The angle of rotation in decimal degrees.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.

Returns:

Returns the rotated shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

rotateZ(shapes, degrees [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		A shape or array of shapes to rotate.
`degrees`	number		The angle of rotation in decimal degrees.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.

Returns:

Returns the rotated shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

saveShapeSTEP( [filename]) <static>

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

Parameters:

Name	Type	Argument	Description
`filename`	string	<optional>	The name of the temporary file, defaults to 'ShapeEditorPart.step'.

Returns:

Returns the STEP file content, or null if the conversion failed.

Type: object | null

scale(shapes, scale [, makeCopy]) <static>

Scales the given shape(s) from the origin.

Parameters:

Name	Type	Argument	Description
`shapes`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		A shape or array of shapes to scale.
`scale`	number		A relative scale factor to apply equally in each axis.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.

Returns:

Returns the scaled shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

setCancelToken( [token]) <static>

Sets the URL token used for cancelling operations.

Parameters:

Name	Type	Argument	Description
`token`	string	<optional>	A revokable URL token.

setLogLevel(level) <static>

Sets or clears the cancel operations flags.

Parameters:

Name	Type	Description
`level`	number	The level to log at (0 to 3).

subtract(mainBody, shapesToSubtract [, makeCopy] [, tolerance] [, keepEdges]) <static>

Subtracts a set of shapes from a main body shape.

Parameters:

Name	Type	Argument	Description
`mainBody`	oc.TopoDS_Shape		The shape to subtract from.
`shapesToSubtract`	oc.TopoDS_Shape \| Array.<oc.TopoDS_Shape>		An array of shapes to subtract.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.
`tolerance`	number	<optional>	The tolerance to use when subtracting, defaults to 0.1.
`keepEdges`	boolean	<optional>	Whether or not to keep the original edge(s) in the shape, defaults to false.

Returns:

Returns the resulting shape.

Type: oc.TopoDS_Shape

sweep(shape, path [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`shape`	oc.TopoDS_Shape		The shape to sweep along the path.
`path`	oc.TopoDS_Wire		A wire defining the path to sweep the shape along.
`makeCopy`	boolean	<optional>	Apply to a copy and keep original shape in the model, defaults to false.

Returns:

Returns the swept shape.

Type: oc.TopoDS_Shape

translate(shapes, offset [, makeCopy]) <static>

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

Parameters:

Name	Type	Argument	Description
`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.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.

Returns:

Returns the translated shape(s).

Type: oc.TopoDS_Shape | Array.<oc.TopoDS_Shape>

union(shapes [, makeCopy] [, tolerance] [, keepEdges]) <static>

Combines a set of shapes into a single unioned shape.

Parameters:

Name	Type	Argument	Description
`shapes`	Array.<oc.TopoDS_Shape>		An array of shapes to combine.
`makeCopy`	boolean	<optional>	Apply to copies and keep original shapes in the model, defaults to false.
`tolerance`	number	<optional>	The tolerance to use when unioning, defaults to 0.1.
`keepEdges`	boolean	<optional>	Whether or not to keep the original edge(s) in the shape, defaults to false.

Returns:

Returns the unioned shape.

Type: oc.TopoDS_Shape