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

Name	Type	Default	Description
length	number		Length of the box (x-axis)
width	number		Width of the box (y-axis)
height	number		Height 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({}))

clearSolid

Clears the target solid in the drawing.

Declaration

(solidId: VID) => Promise<void>

Params

Name	Type	Default	Description
solidId	VID		Id 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

Name	Type	Default	Description
height	number		Height of the cone (z-axis)
diameter1	number		Diameter at the bottom of the cone
diameter2	number		Diameter 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({}))

copy

Creates a copy of the solid.

Declaration

(solidId: VID) => ID

Params

Name	Type	Default	Description
solidId	VID		Id 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({}))

createBufferGeometry

Creates the buffer geometry of the solid.

Declaration

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

Params

Name	Type	Default	Description
solidId	VID		Id 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

Name	Type	Default	Description
solids	VID[]		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

Name	Type	Default	Description
height	number		Height of the cylinder (z-axis)
diameter	number		Diamter 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({}))

edgeLoops

Returns all adjacent edges of a face or vertex

Declaration

(breps: VIDs) => IDs

Params

Name	Type	Default	Description
breps	VIDs		Face 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({}))

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

Name	Type	Default	Description
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

Name	Type	Default	Description
target	VID
point	Vec		Position of plane
normal	Vec		Normal vector of plane
distance	number		Distance 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({}))

extrude

Creates an extrusion.

Declaration

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

Params

Name	Type	Default	Description
height	Vec		Height of extrusion
region	Polyline l THREE.Shape		Region 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({}))

fillet

Creates a fillet at the given edges

Declaration

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

Params

Name	Type	Default	Description
radius	number		Radius of the fillet
edges	VIDs		Edges 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({}))

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

Name	Type	Default	Description
data	ArrayBuffer		Data 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

Name	Type	Default	Description
solidId	VID		Id of the solid to intersect
keepSolid	boolean		If true, the solid will be kept and can be used again
bodies	VID[]		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({}))

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

Name	Type	Default	Description
data	ArrayBuffer		Data 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

Name	Type	Default	Description
solidId	VID
point	Vec		Position of the mirror plane
normal	Vec		Normal 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({}))

moveTo

Moves the solid to the given position.

Declaration

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

Params

Name	Type	Default	Description
solidId	VID		Id of the solid which will be moved
position	Vec		Position 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({}))

offset

Creates an offset of the solid.

Declaration

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

Params

Name	Type	Default	Description
solidId	VID		Solid which becomes an offset
offsetDistance	number		Distance 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({}))

pick

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

Declaration

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

Params

Name	Type	Default	Description
solidId	VID		Id of the solid to look for edges and faces
type	'vertex' l 'edge' l 'face'		Type of geometry to look for --> 'edge' or 'face'
points	Vec[]		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({}))

revolve

Revolves the given region.

Declaration

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

Params

Name	Type	Default	Description
position	Vec		Position of rotation axis
direction	Vec		Direction of rotation axis
angle	number		Angle of rotation in rad
region	Polyline l THREE.Shape		Region 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({}))

rotateTo

Rotates the given solid.

Declaration

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

Params

Name	Type	Default	Description
solidId	VID		Id of the solid to rotate
rotationVec	Vec		Vector 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({}))

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

Name	Type	Default	Description
solidId	VID		Id of the solid to scale
vectorOrFactor	Vec l number		If 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({}))

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

Name	Type	Default	Description
distanceTol	number		Distance tolerance
angleTol	number		Angle 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

Name	Type	Default	Description
distanceTol	number		Tolerated distance between theoretic and tesselated arc
angleTol	number		Tolerated 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({}))

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

Name	Type	Default	Description
solidId	VID		Id of solid to slice
point	Vec		Position of plane
normal	Vec		Normal 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({}))

sphere

Creates a simple sphere.

Declaration

(radius: number) => ID

Params

Name	Type	Default	Description
radius	number		Radius 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({}))

subtract

Creates a subtraction between solid and bodies.

Declaration

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

Params

Name	Type	Default	Description
solidId	VID		Id of the solid to subtract
keepSolid	boolean		If true, the solid will be kept and can be used again
bodies	VID[]		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({}))

union

Creates an union between solid and bodies.

Declaration

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

Params

Name	Type	Default	Description
solidId	VID		Id of the solid to unify
keepSolid	boolean		If true, the solid will be kept and can be used again
bodies	VID[]		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({}))

createPolyline

Creates a polyline from the given fillet points

Declaration

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

Params

Name	Type	Default	Description
fPts	FilletPoint[]		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

Name	Type	Description
point	Vector3	Point where the corner of the polyline will be.
radius	number	Radius 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

Name	Type	Description
points	Vector3[]	Points where the corners of the polyline will be.
bulges	number[]	Bulges which define the arcs.