docs

Build on SlicerX

Build on the engine

Call SlicerX's geometry engine, sx-geom, from Rust, a browser, the command line or an AI client.

sx-geom is SlicerX's own geometry engine. It is a Rust crate with no file, network or clock access in the library, so the same code runs natively, on the command line and as WebAssembly in a browser worker. You can build your own CAD app or configurator on it.

The engine is mesh-first. Every body is a closed triangle mesh in millimeters, and every operation takes meshes and returns meshes. Sketches are typed geometry: lines, arcs and circles with sizes and positions. History is a list of operations your app keeps and replays.

WhereHow
RustDepend on the sx-geom crate (packages/geom) and call sx_geom::json::call(op, request_json), or the typed modules (face, push, edge, boolean, sketch) directly.
BrowserBuild packages/geom/wasm with sh packages/geom/wasm/scripts/build.sh and load it with createGeom from packages/geom/wasm/geom.mjs. Calls are synchronous, so run them in a Web Worker.
Command linesx-geom <op> --out-dir DIR < request.json. With --out-dir, meshes in the reply are written as STL files. sx-geom ops lists the operations.
AI clientsThe SlicerX MCP server offers the same operations as slicerx_geom_* tools. See Over MCP.

The CAD tools in the app run on this engine.

Requests and replies

Every way in takes the same JSON: an operation name and a request object, with camelCase keys, millimeters, degrees, Z up and the bed at Z = 0.

{
  "shape": { "type": "rectangle", "widthMm": 40, "heightMm": 30 },
  "placement": { "center": [20, 15] },
  "spec": { "distanceMm": 10 }
}

Meshes go in as {"positions": [x, y, z, ...], "indices": [a, b, c, ...]}, as {"stlBase64": "..."}, or, on the command line only, as {"stlPath": "..."}. A mesh can carry its placement as {"mesh": ..., "transform": [16 numbers]}, column-major and local to world, like three.js Matrix4.elements. The engine works in world coordinates, and a mesh that replaces an input comes back in that input's local frame, so a moved or rotated object keeps its transform.

An error is one plain sentence of the form field: what is wrong, ready to show to a person:

{ "error": "widthMm: between 0 and 10000 mm" }

The operations

OperationWhat it doesRequest
face.pickA flat face: its sketch frame, outline, area and trianglesmesh, triangle, at
edge.pickThe sharp edge of a face nearest a point: whether it can be rounded, the largest radius that fits, its tangent chain and the loop around the facemesh, triangle, at
sketch.checkWhether sketch loops close and do not cross, which are holes, and each problem with its loop and segmentloops
shape.extrudeExtrude a rectangle, circle, slot, polygon, text, free sketch or SVG outline as a new body, joined to a target or cut from itframe, shape, placement, spec, target
sketch.revolveRevolve sketch loops around an axis in their planeframe, loops, axis, angleDeg, operation, target
face.pushMove a flat face along its normal: out adds material, in cutsmesh, triangle, at, distanceMm
booleanUnion, difference or intersection of closed meshesop, a, b
edge.fillet, edge.chamferRound or bevel straight edges between flat facesmesh, edges, radiusMm or distanceMm
sketch.fillet, sketch.chamferRound or bevel sketch corners before extrudingloops, corners, radiusMm or distanceMm
measure.featureThe feature under a pick: a point, edge, circle, plane, cylinder or surfacemesh, pick
measureDistance, angle, radius or area between one or two featuresa, b
dimension.anchorA dimension's end, stored so it can be found again after later editsobject, mesh, pick
dimension.evaluateKept dimensions measured again on the current meshesdimensions, objects, moves

face.push.preview, edge.fillet.preview and edge.chamfer.preview return only the pieces to draw while someone drags or types, without running the boolean. The engine also has mesh tools: cut, split, repair, hollow, emboss and calibration models.

Picking

The engine picks a face by a triangle index and a point on that triangle. A viewport has both from its ray hit. Without a viewport, find the triangle whose plane holds the point and whose normal matches the face you mean, as triangleAt does in the example below.

face.pick returns a frame, {origin, normal, u, v}, and sketch coordinates are [u, v] in it. On the bed and on faces that look up or down, u is +X. On walls, u is horizontal and v points up.

An edge is {a, b, face}: its end points and the outward normal of its first face. edge.pick returns one, and the fillet and chamfer operations find the edge again from those points, so you can store it. An edge counts when two flat faces meet at a fold of more than 30 degrees.

Sketches

A sketch is a plane plus closed loops:

  • {"points": [[u, v], ...]}: straight sides, closed back to the first point.

  • {"type": "circle", "center": [u, v], "diameterMm": d}.

  • {"start": [u, v], "segments": [...]} with lines ({"type": "line", "to": [u, v]}, or lengthMm with angleDeg or turnDeg) and arcs (center and sweepDeg, three points with through, radiusMm with clockwise and large, or tangent with radiusMm and sweepDeg).

A loop inside another loop is a hole. Pass the sketch to shape.extrude as the shape {"type": "sketch", "loops": [...]}.

A worked example

A 40 by 30 by 10 mm plate with a 6 mm hole and its top edges rounded, in a browser worker. The same requests work through sx-geom on the command line and through sx_geom::json::call in Rust.

import { createGeom } from './geom.mjs'

const geom = await createGeom(await WebAssembly.compileStreaming(fetch('sx_geom_wasm.wasm')))

// the triangle that contains `at` and faces `normal`; a viewport gets this from its ray hit
function triangleAt({ positions: p, indices: ix }, at, normal) {
  const v = (i) => [p[3 * i], p[3 * i + 1], p[3 * i + 2]]
  const sub = (a, b) => a.map((x, k) => x - b[k])
  const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]]
  const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
  for (let t = 0; t < ix.length / 3; t++) {
    const [a, b, c] = [0, 1, 2].map((k) => v(ix[3 * t + k]))
    const n = cross(sub(b, a), sub(c, a))
    const len = Math.hypot(...n)
    if (dot(n, normal) < 0.999 * len || Math.abs(dot(n, sub(at, a))) > 1e-3 * len) continue
    if ([[a, b], [b, c], [c, a]].every(([p0, p1]) => dot(cross(sub(p1, p0), sub(at, p0)), n) >= -1e-9 * len)) return t
  }
  throw new Error('no face there')
}

const up = [0, 0, 1]

// 1. extrude a rectangle from the bed
const plate = geom.call('shape.extrude', {
  shape: { type: 'rectangle', widthMm: 40, heightMm: 30 },
  placement: { center: [20, 15] },
  spec: { distanceMm: 10 },
})

// 2. pick the top face
const center = [20, 15, 10]
const top = geom.call('face.pick', { mesh: plate.mesh, triangle: triangleAt(plate.mesh, center, up), at: center })

// 3. cut a hole through it, sketched on the top face (a cut goes into the face)
const drilled = geom.call('shape.extrude', {
  frame: top.frame,
  shape: { type: 'circle', diameterMm: 6 },
  spec: { distanceMm: 10, operation: 'cut' },
  target: plate.mesh,
})

// 4. round the four top edges: pick one, then take the loop around the face
const edgeAt = [20, 0, 10]
const edge = geom.call('edge.pick', { mesh: drilled.mesh, triangle: triangleAt(drilled.mesh, edgeAt, up), at: edgeAt })
const rounded = geom.call('edge.fillet', {
  mesh: drilled.mesh,
  edges: edge.loop.filter((e) => e.supported).map((e) => e.edge),
  radiusMm: 2,
})
// rounded.mesh is watertight and ready to slice: 11,598 mm3, down from 12,000

History in your app

The engine keeps no history of its own. Your app keeps it, and the engine replays it. This is how SlicerX does it:

  • An object keeps its base meshes and an ordered list of steps, {op, params, transform}. params is exactly the request the operation took, with the mesh left out, and transform is the object's placement when the step ran.

  • The current mesh is the replay: start from the base and run each step with {mesh: current, transform} and its params. Moving the object later does not disturb a step, because the engine answers in the object's local frame.

  • References live in the params in the engine's own terms: a face as a point and a normal (find the triangle again on the replayed mesh), an edge as its {a, b, face}, a sketch plane as its frame.

  • To edit step k, change its params and replay from k. A step that fails stops the replay with the engine's sentence, and the object shows the result before it.

// where each operation takes the mesh it changes
const meshKey = { 'face.push': 'mesh', 'edge.fillet': 'mesh', 'edge.chamfer': 'mesh', 'shape.extrude': 'target', 'sketch.revolve': 'target', boolean: 'a' }

function replay(geom, history) {
  let mesh = history.base
  for (const step of history.steps) {
    if (step.suppressed) continue
    const params = { ...step.params }
    // a face is stored as a point and a normal; find its triangle on the mesh as it is now
    if (params.normal) params.triangle = triangleAt(mesh, params.at, params.normal)
    const key = meshKey[step.op]
    const item = { mesh, transform: step.transform }
    mesh = geom.call(step.op, { ...params, [key]: key === 'a' ? [item, ...(params.a ?? []).slice(1)] : item }).mesh
  }
  return mesh
}

This loop assumes the object was never moved, so triangleAt can search the local mesh. For a moved object, bring at and normal into its local frame first.

Over MCP

The SlicerX MCP server (packages/mcp) offers the engine to Claude Code, Cursor and any other MCP client as slicerx_geom_* tools. It runs from the repository: @slicerx/mcp is packaged and not on npm yet. The geometry tools need sx-geom built, and are not offered without it.

ToolsWhat they doKind
slicerx_geom_faces, slicerx_geom_face_pick, slicerx_geom_edge_pick, slicerx_geom_sketch_checkList a model's flat faces (a point on each, its normal, the axis it faces, its area), pick a face for its sketch frame and outline, pick an edge for a fillet or chamfer, and check sketch loops before extrudingReports only
slicerx_geom_extrude, slicerx_geom_revolve, slicerx_geom_push_pull, slicerx_geom_boolean, slicerx_geom_fillet, slicerx_geom_chamferSketch on the bed, any plane or a picked face and extrude it, joined or cut; revolve a sketch; push or pull a flat face; union, subtract or intersect models; round or bevel straight edgesWrites a new STL under the output folder
pnpm install && pnpm --filter @slicerx/mcp build
cargo build -p sx-geom --release
claude mcp add slicerx -- node "$PWD/packages/mcp/dist/cli.js" \
  --allow-dir ~/prints \
  --sx-geom-bin "$PWD/target/release/sx-geom"

The modeling tools fall under the slice permission class, which is allowed and logged by default. To approve each call yourself, set "slice": "ask" in ~/.config/slicerx/mcp-policy.json. The server reads that file at startup, and no tool can change it.

License and credit

sx-geom and its WebAssembly build are Apache-2.0, as is everything else the SlicerX contributors wrote. You can use them in open or closed source products, commercial ones included.

The NOTICE file is part of the license terms (section 4(d)). If you ship the engine or anything built on it, pass the NOTICE on and show this credit wherever your product lists third-party credits, such as an About screen, a credits page or its documentation:

Made with SlicerX (https://slicerx.app)

If your product shows no such credits, put the line in a NOTICE or credits file that ships with it.

Third-party code keeps its own license. The boolean engine uses manifold-rust (Apache-2.0), and the repository vendors i_overlay with SlicerX's changes. STEP import in the app uses occt-import-js (Open CASCADE, LGPL-2.1), which is not part of sx-geom. The name SlicerX and its logo are not covered by the license beyond that credit, so a product built on the engine goes by its own name.