API Docs

Class: Solid

PD. Solid

Defines a 3D manifold solid as a collection of bounding triangular facets.

Unlike the PD.Shell, PD.BRep and PD.Shape framework classes, which are used primarily for rendering and visualization so can be quite flexible with the type of geometry and faceting they represent, this class can only represent triangulated manifold solids. Manifold solids are used to perform constructive solid geometry (CSG) operations using the manifold-3d library. As a result, all solids must conform to the requirements of that library.

This means that every edge of every triangle that defines a boundary surface must contain the same two vertices (by index) as exactly one other triangle edge, with the start and end vertices switching places between these two edges. Also, the order of triangle vertices must be counter-clockwise when viewed from the outside of the manifold shape which, using the right-hand rule, means that their surface normals must face outwards.

You can construct conforming solids using the basic primitive methods such as PD.Solid#prism, PD.Solid#tetrahedron, PD.Solid#cylinder and PD.Solid#sphere, or build them from other geometry classes using the PD.Solid#fromBufferGeometry, PD.Solid#fromShell or PD.Solid#fromBRep methods.

Two or more solids can be combined to create more complex solids using the PD.Solid.union, PD.Solid.subtract and PD.Solid.intersect methods, or you can progressively sculpt an existing solid by unioning, subtracting or intersecting it with other solids using the PD.Solid.union, PD.Solid.subtract, and PD.Solid.intersect methods.

new Solid( [manifold])

Creates a new solid ready for constructive solid geometry.

Parameters:
Name Type Argument Description
manifold Manifold <optional>

An optional Manifold object.
Author:
  • drajmarsh

Members

:boolean

isSolid <readonly>

A flag identifying this object as a solid.

Type
  • boolean
:Manifold|null

manifold

A Manifold instance containing the current 3D solid.

Type
  • Manifold | null
:Array.<{time:number, action:string, error:string}>

errorLog <static>

An array of error log entries. Each entry is an object with time, action, and error properties.

Type
  • Array.<{time:number, action:string, error:string}>
:number

maxErrorLog <static>

The maximum number of error messages to store in the error log.

Type
  • number
Default Value:
  • 100

Methods

NEW_toShellWithUnionedFaces( [shell])

Copies the CSG data into the given shell, trying to union together coplanar facets.

Parameters:
Name Type Argument Description
shell PD.Shell <optional>

An optional shell to store the resulting shape.
Returns:

Returns the given shell or a newly created one.

Type
PD.Shell

OLD_toBRepUnioned( [brep])

Copies the CSG data into the given boundary representation, trying to union together coplanar facets.

Parameters:
Name Type Argument Description
brep PD.BRep <optional>

An optional boundary representation to store the result.
Returns:

Returns the given BRep or a newly created one.

Type
PD.BRep

XXX_toBRepUnioned( [brep])

Copies the CSG data into the given boundary representation, trying to union together coplanar facets.

Parameters:
Name Type Argument Description
brep PD.BRep <optional>

An optional boundary representation to store the result.
Returns:

Returns the given BRep or a newly created one.

Type
PD.BRep

addBRep(brep)

Add face triangles from a PD.BRep to this solid.

Parameters:
Name Type Description
brep PD.BRep

the boundary representation containing polygonal faces.
Returns:

Returns this CSG solid to support method chaining.

Type
PD.Solid

addBufferGeometry(geometry)

Add triangles from a THREE.BufferGeometry to this solid.

Parameters:
Name Type Description
geometry THREE.BufferGeometry

The buffer geometry to convert.
Returns:

Returns this CSG solid to support method chaining.

Type
PD.Solid

addPolyMesh(polyMesh)

Add triangles from a PD.PolyMesh to this solid.

Parameters:
Name Type Description
polyMesh PD.PolyMesh

The poly mesh to convert.
Returns:

Returns this CSG solid to support method chaining.

Type
PD.Solid

addShell(shell)

Add facet triangles from a PD.Shell to this solid.

Parameters:
Name Type Description
shell PD.Shell

The shell containing the triangles.
Returns:

Returns this CSG solid to support method chaining.

Type
PD.Solid

dispose()

Releases any resources this solid has within the Manifold WASM module.

This method must be called when the solid is no longer needed as any associated resources in the WASM module will not be automatically freed by the garbage collector.

Returns:

Returns this solid to support method chaining.

Type
PD.Solid

intersect(solid)

Intersects a CSG solid with this solid.

  A.intersect(B)
    +-------+
    |       |
    |   A   |
    |    +--+----+   =   +--+
    +----+--+    |       +--+
         |   B   |
         |       |
         +-------+
Parameters:
Name Type Description
solid PD.Solid | Array.<PD.Solid>

The CSG solid(s) to intersect with this one.
Returns:

Returns this updated CSG solid to support method chaining.

Type
PD.Solid

isEmpty()

Checks if the solid either has no manifold or the manifold is empty.

Returns:

Returns true if this solid is empty.

Type
boolean

replaceManifold(manifold)

Replaces any existing Manifold stored by this solid with the given one.

Parameters:
Name Type Description
manifold Manifold | ManifoldMesh | null

The new Manifold or ManifoldMesh to set.

rotate(euler)

Rotates the solid by the given Euler angles.

Parameters:
Name Type Description
euler Array.<number>

The [rx,ry,rz] Euler angle rotation array.
Returns:

Returns true if the solid was rotated, false if manifold is not valid.

Type
boolean

scale(scale)

Applies the given transformation matrix to the solid.

Parameters:
Name Type Description
scale Array.<number>

The [sx,sy,sz] scale factor array.
Returns:

Returns true if the solid was scaled, false if manifold is not valid.

Type
boolean

splitByPlane(plane)

Splits the solid by the given plane.

Parameters:
Name Type Description
plane THREE.Plane | Array.<number>

The plane to split the solid with, as an [normal,constant] object or an [a,b,c,d] array.
Returns:

Returns an array of two resulting solids, or an empty array if manifold is not valid or not split.

Type
Array.<PD.Solid>

subtract(solid)

Subtracts a CSG solid from this solid.

  A.subtract(B)
    +-------+            +-------+
    |       |            |       |
    |   A   |            |       |
    |    +--+----+   =   |    +--+
    +----+--+    |       +----+
         |   B   |
         |       |
         +-------+
Parameters:
Name Type Description
solid PD.Solid | Array.<PD.Solid>

The CSG solid(s) to subtract with this one.
Returns:

Returns this updated CSG solid to support method chaining.

Type
PD.Solid

toBRep( [brep])

Copies the CSG data into the given boundary representation as individual triangles.

Parameters:
Name Type Argument Description
brep PD.BRep <optional>

An optional boundary representation to store the result.
Returns:

Returns the given BRep or a newly created one.

Type
PD.BRep

toBRepAsFaces( [brep])

Copies the CSG data into the given boundary representation, trying to group triangles into faces by face IDs.

Parameters:
Name Type Argument Description
brep PD.BRep <optional>

An optional boundary representation to store the result.
Returns:

Returns the given BRep or a newly created one.

Type
PD.BRep

toBRepUnioned( [brep])

Copies the CSG data into the given boundary representation, trying to group coplanar triangles into facets.

Parameters:
Name Type Argument Description
brep PD.BRep <optional>

An optional boundary representation to store the result.
Returns:

Returns the given BRep or a newly created one.

Type
PD.BRep

toBufferGeometry()

Converts the current CSG solid to a THREE.BufferGeometry.

Returns:

Returns a new buffer geometry, or null if invalid or empty.

Type
THREE.BufferGeometry | null

toPolyMesh( [polyMesh])

Adds the current CSG data into the given PolyMesh or a new one.

Parameters:
Name Type Argument Description
polyMesh PD.PolyMesh <optional>

An optional PolyMesh to store the resulting shape.
Returns:

Returns the given PolyMesh or a newly created one.

Type
PD.PolyMesh

toShell( [shell])

Copies the CSG data into the given shell.

Parameters:
Name Type Argument Description
shell PD.Shell <optional>

An optional shell to store the resulting shape.
Returns:

Returns the given shell or a newly created one.

Type
PD.Shell

toShellWithUnionedFaces( [shell])

Copies the CSG data into the given shell, trying to union together coplanar facets.

Parameters:
Name Type Argument Description
shell PD.Shell <optional>

An optional shell to store the resulting shape.
Returns:

Returns the given shell or a newly created one.

Type
PD.Shell

transform(matrix)

Applies the given transformation matrix to the solid.

Parameters:
Name Type Description
matrix PD.MatrixArray

The [4x4] transformation matrix.
Returns:

Returns true if the solid was transformed, false if manifold is not valid.

Type
boolean

translate(translate)

Translates the solid by the given vector array.

Parameters:
Name Type Description
translate Array.<number>

The [dx,dy,dz] translation vector array.
Returns:

Returns true if the solid was translated, false if manifold is not valid.

Type
boolean

union(solid)

Adds a CSG solid to this solid by unioning them.

    A.union(B)
    +-------+            +-------+
    |       |            |       |
    |   A   |            |       |
    |    +--+----+   =   |       +----+
    +----+--+    |       +----+       |
         |   B   |            |       |
         |       |            |       |
         +-------+            +-------+
Parameters:
Name Type Description
solid PD.Solid | Array.<PD.Solid>

The CSG solid(s) to union with this one.
Returns:

. Returns this updated CSG solid to support method chaining.

Type
PD.Solid

computeBoundariesFromTriangles(triangles) <static>

Computes one or more outer boundaries from a collection of triangles.

This method analyses a flat triangle array (where every 3 consecutive points form a triangle) and computes the outer boundary loops. Any common points are assumed to be shared by reference, so the same object instance is used.

This method assumes that the triangles form a well-defined shape where the edges of each triangle are either adjacent to another triangle or are part of the outer boundary. Triangles do not need to be coplanar, but they must have the same winding order and form a connected shape where adjacent edges share common point instances in the opposite order. These condition are true for Manifold solids.

This format for storing triangles is common to both the PD.Shell and PD.BRep framework classes. The resulting boundary loops can be used to construct PD.Polygon or PD.BRep.Face objects.

Parameters:
Name Type Description
triangles Array.<PD.Point>

A flat array of point objects, where every 3 consecutive points forms a triangle and common points are shared by reference.
Returns:

Returns an array of boundaries, where each is an array of points ordered to form a closed loop.

Type
Array.<Array.<PD.Point>>

cone( [options]) <static>

Construct a solid cone or pyramid.

Parameters:
Name Type Argument Description
options object <optional>

An optional configuration object.
Properties of options:
Name Type Argument Description
height number <optional>

The height of the cylinder as a single positive number, defaults to 1.
radius number <optional>

The bottom radius of the cylinder as a single positive number, defaults to 1.
segments number <optional>

The number of segments used to approximate the cylinder [3 to 1800], defaults to 18.
centered boolean <optional>

Whether or not the cylinder is centered at the origin rather that it being on its base, defaults to false.
origin Array.<number> <optional>

The [x,y,z] position of the center of the cylinder, defaults to [0,0,0].
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
const cone = PD.Solid.cone({
    radius: 250.0,
    height: 1200.0,
    centered: false,
    origin: [ 0, 0, 0 ],
    segments: 16
});

cuboid( [options]) <static>

Constructs an axis-aligned solid cuboid.

Parameters:
Name Type Argument Description
options object <optional>

An optional configuration object.
Properties of options:
Name Type Argument Description
origin Array.<number> <optional>

The [x,y,z] position of the cube, defaults to [0,0,0].
centered boolean <optional>

Whether or not the cube is centered at the origin rather that it being the minimum corner, defaults to false.
size number | Array.<number> <optional>

The size of the cube, as a single number or [x,y,z] vector array, defaults to 1.
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
const cube = PD.Solid.cube({
    origin: [ 10, 25, 5 ],
    size: [ 5, 3, 1 ],
    centered: true
});

cylinder( [options]) <static>

Construct a solid cylinder.

Parameters:
Name Type Argument Description
options object <optional>

An optional configuration object.
Properties of options:
Name Type Argument Description
height number <optional>

The height of the cylinder as a single positive number, defaults to 1.
botRadius number <optional>

The bottom radius of the cylinder as a single positive number, defaults to 1.
topRadius number <optional>

The top radius of the cylinder as a single positive number, defaults to botRadius.
origin Array.<number> <optional>

The [x,y,z] position of the center of the cylinder, defaults to [0,0,0].
segments number <optional>

The number of segments used to approximate the cylinder [3 to 1800], defaults to 18.
centered boolean <optional>

Whether or not the cylinder is centered at the origin rather that it being on its base, defaults to false.
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
const cylinder = PD.Solid.cylinder({
    origin: [ 0, 0, 0 ],
    topRadius: 250.0,
    botRadius: 250.0,
    height: 1200.0,
    centered: false,
    segments: 16
});

extrude(options) <static>

Construct a solid by extruding 2D shape(s).

Parameters:
Name Type Description
options object

A configuration object.
Properties of options:
Name Type Argument Description
shapes Array.<Array.<Array.<number>>>

An array of one or more 2D shapes to extrude.
height number <optional>

An optional height of the extrusion as a single positive number, defaults to 1.
segments number <optional>

An optional number of extra vertical segments along the extrusion [0 to 1800], defaults to 0.
twistAngle number <optional>

An optional amount of rotational twist about the extrusion axis in decimal degrees, defaults to 0.
topScale Array.<number> <optional>

An optional [sx,sy] scale factor for the top, where [0,0] produces a cone and [1,1] produces a cylinder, defaults to [1,1].
translate Array.<number> <optional>

An optional [dx,dy,dz] translation vector of the base from the origin, defaults to [0,0,0].
centered boolean <optional>

Whether or not the extrusion is centered at the origin rather that it being on its base, defaults to false.
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
const extrusion = PD.Solid.extrude({
    shapes: [
        [ // Shape 1.
            [ 0, 0 ], [ 1, 0 ], [ 1, 1 ], [ 0, 1 ]
        ]
    ],
    centered: true,
    height: 3
});

extrudeAperture(innerContour, outerContour, height) <static>

Extrudes a planar polygon in the opposite direction of its surface normal.

Parameters:
Name Type Description
innerContour Array.<Array.<number>>

The inner contour of the aperture defined by [x,y,z] vector arrays.
outerContour Array.<Array.<number>>

The outer contour of the aperture defined by [x,y,z] vector arrays.
height number

The height of the vertical extrusion.

extrudePolyline(polyline, vector, botOffset, topOffset [, reverse]) <static>

Extrudes a planar polygon in the opposite direction of its surface normal.

                 ^
             _+--|---------+
         _.-' : _| /       :\
     _.-'   ___|_|/        : \
   +'         3- - - - - - 2_.+
   |'.  .  '        __..--''  |
   | .'.    __..--''        ' |
   4    '+''                _.1
    '.   |          __..--''
      '. |  __..--''
        '0''
Parameters:
Name Type Argument Description
polyline PD.Polyline

The polyline to extrude.
vector THREE.Vector3

The normalised direction to extrude the polyline in.
botOffset number

The distance to the bottom along the extrusion vector, defaults to 0.0.
topOffset number

The distance to the top along the extrusion vector, defaults to 1000mm or 3' (36").
reverse boolean <optional>

Whether or not to reverse each polygon, defaults to false.

extrudeProfile(profile, base, height) <static>

Extrudes a planar polygon in the opposite direction of its surface normal.

Parameters:
Name Type Description
profile Array.<Array.<number>>

A closed contour defined by [x,y,z] vector arrays.
base number

The base height of the vertical extrusion.
height number

The height of the vertical extrusion.

fromBRep(brep) <static>

Construct a new solid from a PD.BRep.

If the BRep does not contain a manifold shape, the resulting solid will be empty. You can test for a valid solid by checking the PD.Solid#isEmpty method.

Parameters:
Name Type Description
brep PD.BRep

The BRep containing triangulated faces.
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
/// Create a PD.BRep.
/// Note that BRep must be triangulated and manifold.
/// If not, the resulting solid will be empty.
const brep = new PD.BRep();

/// ... Add vertices and facets to BRep...

/// Convert the PD.BRep to a PD.Solid.
const solid = PD.Solid.fromBRep(brep);
if (!solid.isEmpty()) {
    /// Do something with the solid...
}

fromBufferGeometry(geometry) <static>

Construct a new solid from a THREE.BufferGeometry.

If the buffer geometry does not contain a manifold shape, the resulting solid will be empty. You can test for a valid solid by checking the PD.Solid#isEmpty method.

Parameters:
Name Type Description
geometry THREE.BufferGeometry

The buffer geometry to convert.
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
const geometry = new THREE.BufferGeometry();

/// ... Add vertices, indices, normals, colors, etc to geometry...

const solid = PD.Solid.fromBufferGeometry(geometry);
if (!solid.isEmpty()) {
    /// Do something with the solid...
}

fromShell(shell) <static>

Construct a new solid from a PD.Shell.

If the shell does not contain a manifold shape, the resulting solid will be empty. You can test for a valid solid by checking the PD.Solid#isEmpty method.

Parameters:
Name Type Description
shell PD.Shell

The shell containing triangulated facets.
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
/// Create a PD.Shell.
/// Note that shell must be triangulated and manifold.
/// If not, the resulting solid will be empty.
const shell = new PD.Shell();

/// ... Add vertices and facets to shell...

/// Convert the PD.Shell to a PD.Solid.
const solid = PD.Solid.fromShell(shell);
if (!solid.isEmpty()) {
    /// Do something with the solid...
}

fromThreeMesh(mesh) <static>

Construct a new solid from a THREE.Mesh.

If the mesh geometry does not contain a manifold shape, the resulting solid will be empty. You can test for a valid solid by checking the PD.Solid#isEmpty method.

Parameters:
Name Type Description
mesh THREE.Mesh

The triangulated mesh to convert.
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
/// Create a THREE.Mesh.
/// Note that mesh geometry must be triangulated and manifold.
/// If not, the resulting solid will be empty.
const threeMesh = new THREE.Mesh(geometry, material);

/// Convert the THREE.Mesh to a PD.Solid.
const solid = PD.Solid.fromThreeMesh(threeMesh);
if (!solid.isEmpty()) {
    /// Do something with the solid...
}

intersect(solids) <static>

Returns a new solid as the intersection of all the given solids.

None of the given CSG solids are modified by this method.

 intersect([A,B])
    +-------+
    |       |
    |   A   |
    |    +--+----+   =   +--+
    +----+--+    |       +--+
         |   B   |
         |       |
         +-------+
Parameters:
Name Type Description
solids Array.<PD.Solid>

An array of two or more CSG solids to intersect.
Returns:

Returns a new solid or null if intersection failed.

Type
PD.Solid | null

logError(action, error) <static>

Logs an error message.

Parameters:
Name Type Description
action string

The action being performed when the error occurred.
error string

The error message to log.

revolve( [options]) <static>

Construct a solid by revolving 2D shape(s).

Parameters:
Name Type Argument Description
options object <optional>

An optional configuration object.
Properties of options:
Name Type Argument Description
shapes Array.<Array.<Array.<number>>> <optional>

An array of one or more 2D shapes to revolve.
segments number <optional>

The number of rotational segments [3 to 1800], defaults to 18.
angle number <optional>

The amount of rotation in decimal degrees, defaults to 360.
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
const revolution = PD.Solid.revolve({
    shapes: [
        [ // Shape 1.
            [ 0, -10 ], [ 1, -5 ], [ 1, 5 ], [ 1.5, 7.5 ]
        ]
    ],
    centered: true,
    height: 3
});

sphere( [options]) <static>

Construct a solid sphere.

Parameters:
Name Type Argument Description
options object <optional>

An optional configuration object.
Properties of options:
Name Type Argument Description
origin Array.<number> <optional>

The [x,y,z] position of the center of the sphere, defaults to [0,0,0].
segments number <optional>

The number of segments used to approximate the sphere [3 to 1800], defaults to 18.
size number | Array.<number> <optional>

The radius of the sphere in each axis, as a single number or [x,y,z] vector array, defaults to 1.
Returns:

Returns a new CSG solid.

Type
PD.Solid
Example
const sphere = PD.Solid.sphere({
    origin: [ 0, 0, 0 ],
    size: [ 1, 1.5, 2 ],
    segments: 16
});

subtract(solids) <static>

Returns a new solid as the difference of all subsequent solids in the array from the first solid.

None of the given CSG solids are modified by this method.

  subtract([A,B])
    +-------+            +-------+
    |       |            |       |
    |   A   |            |       |
    |    +--+----+   =   |    +--+
    +----+--+    |       +----+
         |   B   |
         |       |
         +-------+
Parameters:
Name Type Description
solids Array.<PD.Solid>

An array of two or more CSG solids to subtract.
Returns:

Returns a new solid or null if subtraction failed.

Type
PD.Solid | null

union(solids) <static>

Returns a new solid as the union of all the given solids.

None of the given CSG solids are modified by this method.

    union([A,B])
    +-------+            +-------+
    |       |            |       |
    |   A   |            |       |
    |    +--+----+   =   |       +----+
    +----+--+    |       +----+       |
         |   B   |            |       |
         |       |            |       |
         +-------+            +-------+
Parameters:
Name Type Description
solids Array.<PD.Solid>

An array of two or more CSG solids to union.
Returns:

Returns a new solid or null if union failed.

Type
PD.Solid | null