CSG

The CSG module builds an arrangement of N meshes once and evaluates any boolean expression over them — no chaining of pairwise booleans, no recomputation between queries.

Overview

• Build — tf.csgGraph([...]) computes the arrangement and its domain classification. This is where the heavy work happens; tf.async.csgGraph runs it off the main thread.
• Query — every call after that is cheap and reuses the same build:
  • graph.mesh(expr) — the boolean result mesh for any expression
  • graph.domains() — every kept volumetric domain as its own watertight mesh
  • graph.intersectionCurves() — the seam polylines where surfaces cross

const graph = tf.csgGraph([meshA, meshB, meshC]);

const diff = graph.mesh(tf.op(0).sub(tf.op(1)));   // boolean difference
const { meshes, ids } = graph.domains();            // volumetric decomposition

graph.delete();                                     // explicit lifetime, like Mesh

A sequence of operations costs one arrangement, not one per operation.

Building Expressions

Expressions are built from tf.op(i) leaves — i is the operand's index in the mesh array — combined with builder methods:

Plain integers auto-promote as arguments: tf.op(0).sub(1) works.

const carved = tf.op(0).sub(tf.op(1).or(2));
const shared = tf.op(0).and(1).and(2);
const outside = tf.op(0).or(1).not();

Building the Graph

const graph = tf.csgGraph(meshes, {
  sheets: [2],                 // optional: operands declared as open sheets
  mode: "primitives",          // intersection mode ("sos" or "primitives")
  tolerance: 0,                // predicate tolerance band (0 = exact)
  within: false,               // also self-arrange each operand (see below)
  triangulation: "cdt",        // cut-surface triangulation (see below)
});

// or off the main thread:
const graph = await tf.async.csgGraph(meshes, { triangulation: "refinedCdt" });

All meshes must share the dtype (float32/float64). Structures already built on the meshes (tree, topology) are reused, not rebuilt.

Everything passed at construction is remembered on the graph:

graph.forms            // the input Mesh array, as passed
graph.sheets           // sheet indices, as passed
graph.config           // { mode, tolerance, resolveCrossings, triangulation }
graph.createdPoints    // NDArray [K, 3] of created points, input dtype

Cut-Surface Triangulation

triangulation selects how cut faces are triangulated:

• "cdt" (default) — plain constrained Delaunay per cut loop.
• "refinedCdt" — quality refinement of the cut surface (Ruppert circumcenter insertion). Boundary splits are negotiated globally, so shared loop boundaries stay watertight by construction; refined outputs carry more created points.

Self-Overlapping Operands

within: true also intersects each operand with itself. Use it when an operand can self-overlap — meshes concatenated into one operand, an instanced part whose copies touch. graph.domains() then classifies the overlap pockets structurally, so the extraction matches what the same meshes would produce as separate operands, cell for cell. Boolean expressions still require solid, non-self-overlapping operands.

Sheets

An operand listed in sheets is treated as an oriented open surface that cuts volumes through the same boolean algebra without enclosing one — a terrain horizon splitting a block, for example.

Boolean Meshes

const result = graph.mesh(tf.op(0).sub(tf.op(1)));   // Mesh

With no expression, graph.mesh() returns the full arrangement mesh — every input face, cut at intersections, each surface emitted once.

Face Provenance

const { mesh, tagLabels, faceLabels } =
  graph.mesh(tf.op(0).or(1), { returnSourceIds: true });
// tagLabels[f]  -> which input mesh face f came from
// faceLabels[f] -> the original face id within it

Index Maps

const im = graph.mesh(tf.op(0).sub(1), { returnIndexMap: true });
im.pointTagLabels;   // output point -> input mesh (created -> nTags)
im.pointLabels;      // output point -> input point id
im.faceTagLabels;    // output face  -> input mesh
im.faceLabels;       // output face  -> original face id
im.pointFOffsets;    // forward map blocks: offsets[tag] slices pointFData
im.pointFData;

returnSourceIds and returnIndexMap are exclusive; the index map already carries the face labels. The index-map form requires an expression.

Domain Decomposition

const { meshes, ids } = graph.domains();   // one watertight Mesh per domain

The expression is optional and the options can take its place — no null placeholder needed:

graph.domains();                                     // every kept domain
graph.domains(tf.op(0).and(1));                      // inside the selection
graph.domains({ returnSourceIds: true });            // options only
graph.domains(tf.op(0), { returnIndexMap: true });   // both

The same selection can be made by hand from one full extraction — see Cell Classification below; ids are stable across queries on one graph, so the two routes agree cell for cell.

Options: excludeOuterShell drops the unbounded outside domain; ignoreOpenFragments fuses open fragments (fins, damage) instead of letting them partition volumes. Both default on.

returnSourceIds adds per-cell face-provenance blocks (tagOffsets/tagData, faceOffsets/faceData) parallel to meshes; returnIndexMap adds per-cell face and point maps plus the sentinels (nTags, nOutputPoints, nOriginalPoints) and the inclusion matrix.

Cell Classification

const im = graph.domains({ returnIndexMap: true });

const inc = im.inclusion;      // [nCells, nTags] boolean NDArray, row-major
const d = inc.data;
const onlyA = im.meshes.filter((_, k) =>
  d[k * im.nTags + 0] && !d[k * im.nTags + 1]);   // inside A, outside B

inclusion classifies every cell against every operand, so one extraction answers every selection — a mask picks the same cells the equivalent expression query would return. A sheet operand's column means "behind the sheet's normal".

const all = graph.domains({ excludeOuterShell: false, returnIndexMap: true });
const outer = all.meshes.filter((_, k) =>          // the outer-shell cells
  !all.inclusion.data.slice(k * all.nTags, (k + 1) * all.nTags).some(Boolean));

The outer shell is the space inside no operand — the unbounded outside, plus any void enclosed by nothing. Its cells are exactly the all-false rows, and there can be several: disjoint operand clusters each bound their own patch of the outside. excludeOuterShell: true (the default) drops precisely these rows.

Sheets and Open Fragments

For a sheet, ignoreOpenFragments governs whether its dangling part — fragments that seal nothing, like a knife's rim poking past the solids — partitions space. With the default (True), only the sealed portion of the sheet cuts; the outside stays whole, and with excludeOuterShell: false it returns as one closed inverted cell. With False, the dangling part separates too: the outside splits into a front and a behind half, each an open inverted mesh — and the behind half carries the sheet bit, so excludeOuterShell (which drops all-false rows) keeps it. Sheet bits are half-space indicators for bounded and unbounded regions alike: behind the normal is "inside", everywhere.

Outer Shell

tf.outerShell repairs a self-intersecting mesh into a clean shell: the boundary of the union of everything it encloses.

const shell = tf.outerShell(mesh);
// or off the main thread:
const shell = await tf.async.outerShell(mesh);

The mesh is split at its self-intersection curves, the volumetric domains are labeled, and only the faces bounding the unbounded outside are kept, oriented outward. Internal structure — overlap membranes between interpenetrating parts, faces buried inside the solid, enclosed cavities — is removed. The result is free of self-intersections and suitable as a boolean or csg-graph operand.

const merged = tf.concatenateMeshes([a, b]);   // self-intersecting solid
const shell = tf.outerShell(merged);           // clean union boundary

Options: ignoreOpenFragments masks open fragments (surface pieces carrying boundary edges) out of the region formation instead of letting them partition. Default off.

Intersection Curves

The seam network of the arrangement — the polylines where surfaces of different operands cross; a coincident (coplanar) overlap contributes its contact border while the overlap's interior stays silent:

const curves = graph.intersectionCurves();   // Curves, input dtype
curves.delete();

Async

Every query has an async twin under tf.async, running on the worker pool:

const graph = await tf.async.csgGraph(meshes);
const diff  = await tf.async.csgMesh(graph, tf.op(0).sub(1));
const doms  = await tf.async.csgDomains(graph, { returnSourceIds: true });
const seams = await tf.async.csgIntersectionCurves(graph);

Memory

CsgGraph follows the same lifetime rules as Mesh: call .delete() when done (or use using / [Symbol.dispose]); a FinalizationRegistry backstop releases leaked handles. Meshes returned by queries are independent and need their own .delete().

Many Operations, One Graph

const graph = await tf.async.csgGraph([a, b, c]);

const union = graph.mesh(tf.op(0).or(1).or(2));
const carved = graph.mesh(tf.op(0).sub(1).sub(2));
const { meshes, ids } = graph.domains();

graph.delete();

Three results, one arrangement build. This is the pattern for interactive workflows: build on load (async), query per user action.