Skip to main content

Solid

ApiNoHistory#

A simple and intuitive javascript based api that incorporates solid operations like shapes, booleans (unions, subtracts, intersections), extrusions, revolves, blends, chamfers, slices, arrays, patterns, offsets, etc. The api is compatible with THREEJS and understands some of its primitives like curves and paths.

npm install @buerli.io/headless
import { Solid } from '@buerli.io/headless'
const cad = new Solid(url)
cad.init(async api => {
// Your code goes here
})

box#

Creates a simple box.

Declaration

(length: number, width: number, height: number) => ID

Params

NameTypeDefaultDescription
lengthnumberLength of the box (x-axis)
widthnumberWidth of the box (y-axis)
heightnumberHeight of the box (z-axis)

Returns ID

Example

// Creates a box with length = 10, width = 25 and height = 15
const boxId = api.box(10,25,15)
const geom = await api.createBufferGeometry(boxId)
const mesh = new THREE.Mesh( geom, new THREE.MeshStandardMaterial({}))

image

clearSolid#

Clears the target solid in the drawing.

Declaration

(solidId: VID) => Promise<void>

Params

NameTypeDefaultDescription
solidIdVIDId of the solid to be deleted

Returns Promise<void>

Example

// Clear a specific solid
const boxId = api.box(10,25,15)
const coneId = api.cone(50,20,10)
api.clearSolid(boxId)
const geom = await api.createBufferGeometry(coneId)
const mesh = new THREE.Mesh( geom, new THREE.MeshStandardMaterial({}))

clearSolids#

Clears all existing solids in the drawing.

Declaration

() => Promise<void>

Returns Promise<void>

Example

// Clears all solids
const boxId = api.box(10,25,15)
const coneId = api.cone(50,20,10)
api.clearSolids()

cone#

Creates a simple cone.

Declaration

(height: number, diameter1: number, diameter2: number) => ID

Params

NameTypeDefaultDescription
heightnumberHeight of the cone (z-axis)
diameter1numberDiameter at the bottom of the cone
diameter2numberDiameter at the top of the cone

Returns ID

Example

// Creates a cone with height = 50, diameter1 = 20 and diameter2 = 10
const coneId = api.cone(50,20,10)
const geom = await api.createBufferGeometry(coneId)
const mesh = new THREE.Mesh( geom, new THREE.MeshStandardMaterial({}))

image

copy#

Creates a copy of the solid.

Declaration

(solidId: VID) => ID

Params

NameTypeDefaultDescription
solidIdVIDId of the solid to create a copy from

Returns ID

Example

// Creates a copy of a solid
const coneId = api.cone(50,20,10)
const copyId = api.copy(coneId)
api.rotateTo(copyId, [Math.PI / 2, 0, 0])
const unionId = api.union(coneId, false, copyId)
const geom = await api.createBufferGeometry(unionId)
const mesh = new THREE.Mesh( geom, new THREE.MeshStandardMaterial({}))

image

createBufferGeometry#

Creates the buffer geometry of the solid.

Declaration

(solidId: VID) => Promise<BufferGeometry | undefined>

Params

NameTypeDefaultDescription
solidIdVIDId of the solid to create buffer geometry from

Returns Promise<BufferGeometry | undefined>

Example

// Creates the buffer geometry
const coneId = api.cone(50,20,10)
const boxId = api.box(10,25,15)
const unionId = api.union(coneId, false, boxId)
const geom = await api.createBufferGeometry(coneId)
const mesh = new THREE.Mesh( geom, new THREE.MeshStandardMaterial({}))

createScene#

Creates ThreeJS scene from the given solids.

Declaration

(solids: VID[], options?: {
meshPerGeometry?: boolean;
}) => Promise<{
scene: Scene;
part: THREE.Group;
solids: THREE.Group[];
meshes: THREE.Mesh[];
}>

Params

NameTypeDefaultDescription
solidsVID[]Ids of the solids to create scene from
options.meshPerGeometry?boolean

Returns Promise<{ scene: Scene; part: THREE.Group; solids: THREE.Group[]; meshes: THREE.Mesh[] }>

cylinder#

Creates a simple cylinder.

Declaration

(height: number, diameter: number) => ID

Params

NameTypeDefaultDescription
heightnumberHeight of the cylinder (z-axis)
diameternumberDiamter of the cylinder

Returns ID

Example

// Creates a cylinder with height = 50 and diameter = 10
const cylinderId = api.cylinder(50,10)
const geom = await api.createBufferGeometry(cylinderId)
const mesh = new THREE.Mesh( geom, new THREE.MeshStandardMaterial({}))

image

edgeLoops#

Returns all adjacent edges of a face or vertex

Declaration

(breps: VIDs) => IDs

Params

NameTypeDefaultDescription
brepsVIDsFace or vertex ids to get the adjacent edges from

Returns IDs

Example

// Returns all edges from the top surface of box and adds a fillet on them
const boxId = api.box(10, 25, 15)
const surface = api.pick(boxId, 'face', [0, 0, 7.5])
const edges = api.edgeLoops(surface)
api.fillet(2, edges)
const geom = await api.createBufferGeometry(boxId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

export#

Writes the current solid or specific solids to a stream in stp data format and returns the data.

Declaration

(solidIds?: VIDs) => Promise<Uint8Array | null>

Params

NameTypeDefaultDescription
solidIds?VIDs[optional] specific solidIds to write to stream

Returns Promise<Uint8Array | null>

Example

// Writes the unified solid to stream
const coneId = api.cone(50,20,10)
const boxId = api.box(10,25,15)
const unionId = api.union(coneId, false, boxId)
const data = api.export()
const geom = await api.createBufferGeometry(coneId)
const mesh = new THREE.Mesh( geom, new THREE.MeshStandardMaterial({}))

extendSolidAtPlane#

The solid is extended at the defined plane with a solid created by extruding the section defined by the plane.

Declaration

(target: VID, point: Vec, normal: Vec, distance: number) => Promise<void>

Params

NameTypeDefaultDescription
targetVID
pointVecPosition of plane
normalVecNormal vector of plane
distancenumberDistance of extension

Returns Promise<void>

Example

// Extends the sphere in its center
const sphereId = api.sphere(10)
api.extendSolidAtPlane(sphereId, [0, 0, 0], [0, 1, 1], 50)
const geom = await api.createBufferGeometry(sphereId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

extrude#

Creates an extrusion.

Declaration

(height: Vec, region: Polyline | THREE.Shape) => ID

Params

NameTypeDefaultDescription
heightVecHeight of extrusion
regionPolyline l THREE.ShapeRegion which will be extruded, defined by Polyline or THREE.Shape

Returns ID

Example

// Extrudes a heart from THREE shape
const shape = new THREE.Shape()
shape.moveTo(25, 25)
shape.bezierCurveTo(25, 25, 20, 0, 0, 0)
shape.bezierCurveTo(-30, 0, -30, 35, -30, 35)
shape.bezierCurveTo(-30, 55, -10, 77, 25, 95)
shape.bezierCurveTo(60, 77, 80, 55, 80, 35)
shape.bezierCurveTo(80, 35, 80, 0, 50, 0)
shape.bezierCurveTo(35, 0, 25, 25, 25, 25)
const heartId = api.extrude([0, 0, 5], shape)
api.rotateTo(heartId, [Math.PI, 0, 0])
const geom = await api.createBufferGeometry(heartId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

fillet#

Creates a fillet at the given edges

Declaration

(radius: number, edges: VIDs) => ID

Params

NameTypeDefaultDescription
radiusnumberRadius of the fillet
edgesVIDsEdges to create fillets on

Returns ID

Example

// Creates a fillet with radius = 2 at the given edge
const boxId = api.box(10, 25, 15)
const edge = api.pick(boxId, 'edge', [5, 0, 7.5])
api.fillet(2, edge)
const geom = await api.createBufferGeometry(boxId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

getDrawing#

Returns the drawing of the current headless-session

Declaration

() => DrawingState

Returns DrawingState
DrawingState

Example

const drawing = api.getDrawing()
// Get all graphic containers
const containers = Object.values(drawing.graphic.containers)
containers.forEach(container => {
// Get all surfaces
const surfaces = container.meshes.map(mesh => mesh.properties.surface)
// Filter non cylindric
const cylinders = surfaces.filter(surface => surface.type === 'cylinder')
// Check if all cylinders have a radius greater than 4
cylinders.forEach(meta => expect(meta.radius).toBeGreaterThanOrEqual(4))
})

getDrawingId#

Returns the drawing id of the current headless-session

Declaration

() => DrawingID

Returns DrawingID
DrawingID

Example

const drawingId = api.getDrawingId()

getState#

Returns the state tree of the current headless-session

Declaration

() => BuerliState

Returns BuerliState
BuerliState

Example

const state = api.getState()

import#

Loads an arraybuffer in stp file format. All solids existing in stp data will be returned in an array. Current drawing will not be overwritten, imports will just be added.

Declaration

(data: ArrayBuffer) => IDs

Params

NameTypeDefaultDescription
dataArrayBufferData as arraybuffer in stp format

Returns IDs

Example

// Imports a stp file
const importIds = await api.import(arraybuffer)
const geom = await api.createBufferGeometry(importIds[0])
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

intersect#

Creates an intersection between solid and bodies.

Declaration

(solidId: VID, keepSolid: boolean, ...bodies: VID[]) => ID

Params

NameTypeDefaultDescription
solidIdVIDId of the solid to intersect
keepSolidbooleanIf true, the solid will be kept and can be used again
bodiesVID[]Bodies to intersect with the solid

Returns ID

Example

// Creates an intersection between a sphere and a cylinder
const sphereId = api.sphere(20)
const cylinderId = api.cylinder(50, 30)
const intersectId = api.intersect(sphereId, false, cylinderId)
const geom = await api.createBufferGeometry(intersectId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

load#

Loads an arraybuffer in native file format. Native file format is 'ofb', if you want to load 'stp' file formats, use import function. Current drawing will be overwritten by loaded data.

Declaration

(data: ArrayBuffer) => IDs

Params

NameTypeDefaultDescription
dataArrayBufferData as arraybuffer in ofb format

Returns IDs

mirror#

Mirrors the solid at the specified plane.

Declaration

(solidId: VID, point: Vec, normal: Vec) => Promise<void>

Params

NameTypeDefaultDescription
solidIdVID
pointVecPosition of the mirror plane
normalVecNormal vector of the mirror plane

Returns Promise<void>

Example

// Mirrors the cone at its bottom surface
const coneId1 = api.cone(50, 20, 0)
api.mirror(coneId1, [0, 0, -25], [0, 0, 1])
const coneId2 = api.cone(50, 20, 0)
const unionId = api.union(coneId1, false, coneId2)
const geom = await api.createBufferGeometry(unionId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

moveTo#

Moves the solid to the given position.

Declaration

(solidId: VID, position: Vec) => Promise<void>

Params

NameTypeDefaultDescription
solidIdVIDId of the solid which will be moved
positionVecPosition to move the solid to

Returns Promise<void>

Example

// Moves the second box to the first box's corner
const boxId1 = api.box(20, 20, 20)
const boxId2 = api.box(20, 20, 20)
api.moveTo(boxId1, [10, 10, 10])
const unionId = api.union(boxId1, false, boxId2)
const geom = await api.createBufferGeometry(unionId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

offset#

Creates an offset of the solid.

Declaration

(solidId: VID, offsetDistance: number) => ID

Params

NameTypeDefaultDescription
solidIdVIDSolid which becomes an offset
offsetDistancenumberDistance of offset

Returns ID

Example

// Creates an offset on the box
const boxId1 = api.box(20, 20, 20)
api.offset(boxId1, 2)
const geom = await api.createBufferGeometry(boxId1)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

pick#

Returns all edges or faces depending on type which matches the points.

Declaration

(solidId: VID, type: 'vertex' | 'edge' | 'face', ...points: Vec[]) => IDs

Params

NameTypeDefaultDescription
solidIdVIDId of the solid to look for edges and faces
type'vertex' l 'edge' l 'face'Type of geometry to look for --> 'edge' or 'face'
pointsVec[]Points where edges and faces will be expected

Returns IDs

Example

// Pick does look for an edge at point [5,0,7.5] and adds a fillet on it if found the edge
const boxId = api.box(10, 25, 15)
const edge = api.pick(boxId, 'edge', [5, 0, 7.5])
api.fillet(2, edge)
const geom = await api.createBufferGeometry(boxId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

revolve#

Revolves the given region.

Declaration

(position: Vec, direction: Vec, angle: number, region: Polyline | THREE.Shape) => ID

Params

NameTypeDefaultDescription
positionVecPosition of rotation axis
directionVecDirection of rotation axis
anglenumberAngle of rotation in rad
regionPolyline l THREE.ShapeRegion which will be revolved, defined by Polyline or THREE.Shape

Returns ID

Example

// Creates a closed polyline from three points and revolves it
const fp0 = { point: new THREE.Vector3(20, 20, 0), radius: 4 }
const fp1 = { point: new THREE.Vector3(40, 0, 0), radius: 2 }
const fp2 = { point: new THREE.Vector3(0, 0, 0), radius: 2 }
const polyline = createPolyline([fp0, fp1, fp2])
const revolveId = api.revolve([-10, 0, 0], [0, 1, 0], 2 * Math.PI, polyline)
const geom = await api.createBufferGeometry(revolveId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

rotateTo#

Rotates the given solid.

Declaration

(solidId: VID, rotationVec: Vec) => Promise<void>

Params

NameTypeDefaultDescription
solidIdVIDId of the solid to rotate
rotationVecVecVector of rotation around x-, y- and z-axis

Returns Promise<void>

Example

// Creates a box and rotates it around its x- and z-axis
const boxId = api.box(10, 10, 10)
api.rotateTo(boxId, [Math.PI / 4, 0, Math.PI / 4])
const geom = await api.createBufferGeometry(boxId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

save#

Writes the current drawing as native file format to a stream and returns the data. Native file is 'ofb', for 'stp' file format use export method.

Important notes about the ofb format:

  • It contains binary geometry blocks.
  • Do not try to convert it to text, the geometry blocks will get damaged!

Declaration

() => Promise<Uint8Array | null>

Returns Promise<Uint8Array | null>

Example

// Creates a rotated box and gets the ofb data.
const boxId = api.box(10, 10, 10)
api.rotateTo(boxId, [Math.PI / 4, 0, Math.PI / 4])
const data = api.save()

scale#

Scales the solid in all or specified axis.

Declaration

(solidId: VID, vectorOrFactor: Vec | number) => Promise<void>

Params

NameTypeDefaultDescription
solidIdVIDId of the solid to scale
vectorOrFactorVec l numberIf factor is defined, the solid will be scaled in all direction with same scale value. Otherwise in the given x, y and z direction of the vector.

Returns Promise<void>

Example

// Creates a box and scales it in x-axis
const boxId = api.box(10, 10, 10)
api.scale(boxId, [2, 1, 1])
const geom = await api.createBufferGeometry(boxId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

setFacetingParameters#

Sets the global faceting parameters that will stick for this drawing. This defines how detailed solids will be displayed and can yield smaller payloads.

Declaration

(distanceTol: number, angleTol: number) => Promise<void>

Params

NameTypeDefaultDescription
distanceTolnumberDistance tolerance
angleTolnumberAngle tolerance

Returns Promise<void>
Void

Example

api.setFacetingParameters(0.1, 0)

setFacetingParams#

Sets the faceting parameters of graphic objects. This defines how detailed solids will be displayed.

Declaration

(distanceTol: number, angleTol: number) => ID

Params

NameTypeDefaultDescription
distanceTolnumberTolerated distance between theoretic and tesselated arc
angleTolnumberTolerated angle between normal vectors of faces which build an arc

Returns ID

Example

// Creates a cylinder with low tessellation
api.setFacetingParams(0.5, 0)
const cylinderId = api.cylinder(50, 20)
const geom = await api.createBufferGeometry(cylinderId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

slice#

Slices the solid at specified plane. Part of solid which is on the positive side of defined plane will be removed.

Declaration

(solidId: VID, point: Vec, normal: Vec) => Promise<void>

Params

NameTypeDefaultDescription
solidIdVIDId of solid to slice
pointVecPosition of plane
normalVecNormal vector of plane

Returns Promise<void>

Example

// Creates a sphere and slice it
const sphereId = api.sphere(20)
api.slice(sphereId, [10, 10, 0], [1, 1, 0])
const geom = await api.createBufferGeometry(sphereId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

sphere#

Creates a simple sphere.

Declaration

(radius: number) => ID

Params

NameTypeDefaultDescription
radiusnumberRadius of the sphere

Returns ID

Example

// Creates a sphere with radius = 10
const sphereId = api.sphere(10)
const geom = await api.createBufferGeometry(sphereId)
const mesh = new THREE.Mesh( geom, new THREE.MeshStandardMaterial({}))

image

subtract#

Creates a subtraction between solid and bodies.

Declaration

(solidId: VID, keepSolid: boolean, ...bodies: VID[]) => ID

Params

NameTypeDefaultDescription
solidIdVIDId of the solid to subtract
keepSolidbooleanIf true, the solid will be kept and can be used again
bodiesVID[]Bodies to subtract from the solid

Returns ID

Example

// Subtracts a box from sphere after
const sphereId = api.sphere(20)
const boxId = api.box(20, 20, 20)
api.moveTo(boxId, [10, 10, 10])
const subId = api.subtract(sphereId, false, boxId)
const geom = await api.createBufferGeometry(subId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

union#

Creates an union between solid and bodies.

Declaration

(solidId: VID, keepSolid: boolean, ...bodies: VID[]) => ID

Params

NameTypeDefaultDescription
solidIdVIDId of the solid to unify
keepSolidbooleanIf true, the solid will be kept and can be used again
bodiesVID[]Bodies to unify with the solid

Returns ID

Example

// Unifies a sphere with a cone
const sphereId = api.sphere(20)
const coneId = api.cone(50, 40, 0)
api.moveTo(coneId, [0, 0, 25])
const unionId = api.union(sphereId, false, coneId)
const geom = await api.createBufferGeometry(unionId)
const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({}))

image

createPolyline#

Creates a polyline from the given fillet points

Declaration

export function createPolyline(fPts: FilletPoint[]): Polyline;

Params

NameTypeDefaultDescription
fPtsFilletPoint[]Points of the polyline with its associated fillet radius

Returns Polyline

Example

// Creates a polyline with three points
const fp0 = { point: new THREE.Vector3(20, 20, 0), radius: 4 }
const fp1 = { point: new THREE.Vector3(40, 0, 0), radius: 2 }
const fp2 = { point: new THREE.Vector3(0, 0, 0), radius: 2 }
const polyline = createPolyline([fp0, fp1, fp2])

FilletPoint#

Point definition where the fillet will be added with a specified radius.

Members

NameTypeDescription
pointVector3Point where the corner of the polyline will be.
radiusnumberRadius of the fillet at the position of point.

Polyline#

Polyline of points and bulges. Bulges define the arc between the current and the next point.

Members

NameTypeDescription
pointsVector3[]Points where the corners of the polyline will be.
bulgesnumber[]Bulges which define the arcs.