# Procedural, CAD, and what "good enough" means

The generated half of the 3D studio makes a mesh and hopes. The other half —
procedural assemblies, exact CAD solids, measured mesh quality and print
preparation — states a number, measures it, and refuses to call a preview a
proof. This document covers that half, plus the reference views a request
carries and what a critic is allowed to say about a revision.

Code: `@isis/3d-scene-assembly` (assembly plans and builders),
`libs/isis/3d-post-pipeline/src/quality/` (`mesh-quality.ts`,
`quality-profiles.ts`, `print-analysis.ts`),
`libs/isis/workflows/src/three-d-capabilities/request-contract.ts` (views and
the export feature matrix),
`apps/isis/generation-api/src/services/three-d-director/role-outputs.ts`
(critics). Tracker: T.06, T.08.01, T.09, T.16. Evidence:
`docs/agents/isis-3d-studio-evidence.md`.

**State of the world.** C2 (procedural/CAD and hybrid assemblies) is a
`candidate` capability and C10 (mesh/CAD/print exports) is `unavailable`
([capability states](./capability-states-and-admission.md)). The plans, the
builders, the measurements and the profiles below are real and tested against
real Blender 5.2.1, CadQuery 2.8.0 and PrusaSlicer; **no deployment runs them
and the API does not dispatch them yet.**

## 1. Assembly plans

`isis.assembly-plan` v1. A component carries dimensions, materials and **ranged
editable parameters**. Attachments use the connector taxonomy's pairings plus
`rests-on`, `contains` and `fastened`. Mirror and repeat symmetry and an
envelope complete the plan.

**Every length carries a unit, a basis and a tolerance**, and the basis is one
of `measured`, `target` or `inferred`. That is the distinction the whole lane
turns on: a plan that mixes a tape-measure number with a guess, and forgets
which was which, will confidently build the wrong thing.

Validation converts to metres exactly — and, when a length looks wrong, **names
the unit that length would have fitted**, which is usually the actual mistake.
It refuses:

- `rests-on` loops and overfull stacks;
- measured parts that miss a measured envelope;
- asymmetric mirrors;
- openings and repeated holes outside their host;
- oversized tolerances and non-length units.

And it **asks, as questions** rather than refusing, for each class's essential
measurements and for fit-critical lengths that were only inferred. A parameter
edit must stay in range and change one dimension.

A defect this found on the way: plan validation stacked by height alone, so a
floor given by thickness counted as zero. One vertical-extent rule now serves
both validation and building.

**Not claimed:** no general placement solver, and the parameter ranges are
sanity bounds, not standards.

## 2. Procedural builders

`resolveAssemblyBuild` turns a _ready_ assembly plan into an **exact spec in
metres** — shapes, sizes, centres, turns, cuts, repeats. The versioned
`isis.assembly-builder` 1.0.0 Blender script then **only instantiates it**:
named meshes with component extras, live boolean cuts, materials. The script
makes no decisions of its own, which is what makes a build checkable.

The `assembly-build` worker executor runs it sandboxed with auto-run disabled
(see [the sandbox](./stage-graph-budgets-and-sandbox.md) §8) and **fails any
build whose report differs from the spec** in version, plan hash, objects or
cutters.

Measured against real Blender 5.2.1: a chair, a wall with openings, a furnished
room and a drilled bracket each produce a `.blend` and a GLB, and **in every
object the spec, Blender's own measurement and the exported file agree to 1e-5
m**. Rebuilding is byte-identical. A table-top edit changes only the table top.
A lopsided plan and an older builder version are refused with no output.

**Not claimed:** only boxes, cylinders, quarter turns and simple cuts are built.

## 3. The exact CAD lane

`isis.cad-part` describes a box or cylinder base with ranged parameters, holes,
hole patterns, pockets and bosses. It is validated against the cases where exact
analysis would be wrong, then resolved to millimetres with its exact volume,
bounding box and hole count **computed analytically**.

The versioned CadQuery 2.8.0 builder writes STEP, **re-reads it**, and measures
the B-rep: validity, solid count, volume, optimal bounding box, concave
cylindrical faces. It reports a closed tessellated preview **separately** and
keeps the source unchanged.

The rule that matters: **a preview alone is refused as proof.** The `cad-build`
executor fails any build whose B-rep does not certify. A mesh that looks right
is not evidence that the solid is valid, and the lane exists precisely so that
an exact claim rests on exact geometry.

## 4. Mesh quality, measured from real triangles

`measureMeshQuality` takes placed triangle geometry — world-space positions,
indices, and vertex normals where the file has them, one entry per drawn
primitive — and computes every number in its report from those arrays. For GLB,
`readGlbGeometry` in the generation API produces the input.

What it measures, and the care in each:

- **Non-finite vertices and normals.** A non-finite vertex keeps its place in
  the topology, so one bad coordinate does not also _open_ the surface.
  Triangles touching it are unmeasurable: no area, volume, normal, intersection
  or contact is computed for them, and their component is not judged for
  orientation.
- **Welding.** Vertices of one primitive join only where their positions are
  bit-identical — which is how exporters split vertices at UV and normal seams.
  **A crack of any width stays a crack** and shows as an open boundary.
- **Degenerate triangles.** Degenerate when two corners weld together, or when
  the height is at most 1e-6 of the longest edge (below float32 resolution). A
  degenerate triangle with three distinct corners still counts for topology, so
  a zero-area "zipper" does not open a closed surface. Degenerates have no
  plane, so normal and intersection checks skip them.
- **Edges.** Used once → an open boundary, and boundary loops are the connected
  pieces of the boundary. Used more than twice → non-manifold. Used twice in the
  same direction → inconsistent winding.
- **Orientation.** A closed component with consistent winding should enclose
  positive volume — **unless it lies inside another closed component**, where it
  bounds a cavity and should enclose negative volume. Nesting depth is found by
  casting rays along the three axes and counting crossings.

## 5. Quality profiles and certificates

A **profile** is a list of validators over those measured facts, per delivery
target: `rigid`, `deforming`, `architectural`, `web-mobile`, `engine`, `print`.

Each validator has a threshold with a unit, whether it is `required`, and **its
evidence** — a clause of a published standard, or an Isis decision with its
reason. A threshold nobody can justify does not go in a profile.

**There is no score.** A target's ready label comes only from
`certifyMeshQuality`: every required validator passed, on a measurement of the
exact bytes named. **A required validator whose fact was not measured blocks,
exactly as one that failed does** — `unmeasured` is not a pass.

A certificate (`isis.mesh-quality-certificate` v1) records the target, the
profile id and version, **the sha256 of the canonical profile**, the sha256 of
the bytes measured, the sha256 of the canonical facts the validators read, every
validator's result, the list of blocking validators, and `ready`, which is true
only when that list is empty.

**Profiles are immutable once published.** A change is a new version, and
because the certificate carries the profile's hash, **any certificate from
another version reads as stale** rather than being silently honoured.

## 6. Print analysis

`print-analysis.ts` measures what a slicer needs to know before a mesh is sent
to a printer, in millimetres (glTF metres × 1000), judged against a versioned
printer profile (build volume, minimum wall, minimum clearance, support
threshold, slicer presets).

- **Watertightness, self-intersections and fragments** come from the
  mesh-quality measurement above.
- **Wall thickness.** From each triangle's centroid a ray runs inward, against
  the face normal, to the first other surface; that distance is the local
  thickness along the normal. **It is not a medial-axis thickness**, so a wall
  meeting another at an angle can read thicker than its thinnest section. Up to
  200,000 triangles are sampled at an even stride, and the report gives the
  minimum, the 1st and 5th area-weighted percentiles, and the area thinner than
  the profile's minimum wall.
- **Clearance.** Bodies are the connected pieces of the mesh. For every vertex,
  the nearest surface of any other body is searched out to five minimum
  clearances. **Bodies that touch or cross (distance 0) print fused, as the
  geometry intends** — that is not a defect. A gap wider than 0 and below the
  profile's minimum clearance will probably fuse by accident, which is.
  Distances are measured from vertices, so the closest pair of _edges_ can be
  missed.
- **Orientation, build volume and overhangs.** Each of the six axis directions
  is tried as "up". The rotated extents must fit the printer's volume, allowing
  a 90° turn on the bed. A downward-facing triangle needs support when its slope
  from horizontal is below the profile's support threshold, unless it rests on
  the bed. The recommended orientation is the one that fits and needs the least
  support area; ties keep the model's own up (+Y in glTF) first.

Two limits are stated in the module itself rather than left for a user to
discover: **nothing here slices**, so a mesh the analysis passes can still fail
in a slicer — and **a successful slice is not a successful print.** The analysis
is checked against PrusaSlicer in its own spec, which is a comparison, not a
promise.

## 7. Export: what each format can carry

`THREE_D_EXPORT_FORMAT_FEATURES` is the feature-loss matrix over the nine export
formats (`glb`, `gltf`, `fbx`, `obj`, `stl`, `3mf`, `usdz`, `step`, `blend`),
declaring for each whether it carries a skeleton, animation, UVs, CAD features
and printability, and whether its PBR support is `full`, `partial` or `none`.

The request contract computes the **losses** of a requested export up front, so
a request that would silently drop a rig or a material channel is told before it
runs rather than after.

## 8. Reference views, and where each one is used

A request carries **views**, each with a role and a label. The roles are
deliberately narrow:

| Role       | What it conditions                           |
| ---------- | -------------------------------------------- |
| `shape`    | Geometry.                                    |
| `material` | Materials only — **never a geometry input**. |
| `style`    | Art direction only.                          |

Labels are `front`, `back`, `left`, `right`, `top`, `bottom`, `three-quarter` or
`unlabelled`, and `THREE_D_VIEW_DIRECTIONS` gives each labelled view its camera
direction in the canonical frame (+Y up, front +Z; the object's right is −X, so
its left side faces +X).

`viewsForStage` says which views a stage reads: style views for `concept-image`,
shape views for `geometry`, and the material's reference views for `texture` and
`bake`. Everything else reads none.

**The stage graph's dependency hash reads views through that same function**, so
what is hashed and what is traced to the user cannot drift apart.
`threeDViewUse` then reports, per view, exactly which stages consumed it — which
is what makes a result traceable back to the reference that shaped it.

For a supplied camera, `cameraViewDirection` derives the world direction from
the camera's own matrix and convention (−Z of its frame for OpenGL, +Z for
OpenCV) rather than assuming one.

## 9. Critic outputs

Roles are **typed evaluations of one subject revision, not standing agents**.
The roles are `director` plus seven critics: `geometry_critic`,
`topology_critic`, `material_critic`, `rig_critic`, `animation_critic`,
`engine_critic` and `art_direction`. Each critic has its own list of finding
categories, and **a finding outside its role's list is schema-invalid**.

A role output passes **three gates in order**, and a failure at any of them
rejects it. **Nothing is repaired into acceptance.**

1. **Structured output.** The model's JSON is checked against the role's JSON
   Schema, re-prompting on a mismatch and **failing loud when the retries run
   out** — not falling back to a best-effort parse.
2. **Schema parse.** The value is parsed again by the zod schema. Every object
   is **strict**, so a field the schema does not name is refused rather than
   carried along.
3. **Grounding.** `groundRoleOutput` checks the value against the grounding
   context the control plane built — **never against what the model says about
   itself**:
   - every evidence, object, metric and validator it names **exists**;
   - a quoted metric value **restates the measured one**;
   - a claim marked `measured` or `observed` **cites that kind of evidence**;
   - it reviews **the revision it was given**;
   - it proposes only operations **its own role owns**;
   - an `accept` never stands over a failed hard gate or over its own blocker;
   - a role accepting work **it authored** cites independent verification **of
     that exact revision**.

The runner is provider-independent — any `LLMProviderInterface` works, including
the local Ollama and OpenAI-compatible providers the self-hosted profile uses —
but _which_ provider may take a duty is decided beforehand by controller
admission
([capability states and admission](./capability-states-and-admission.md) §5.4),
not by whatever happens to be configured.

## 10. The through-line

Every system in this document answers the same question the same way: **state
what you measured, name what you did not, and never let a cheaper artefact stand
in for the expensive one.** A preview is not a B-rep. A pass is not an
unmeasured. A slicer-clean mesh is not a printed part. A model's confidence is
not evidence. That is why each of these modules writes down its own
approximations — ray-cast wall thickness, vertex-sampled clearance,
bit-identical welding — instead of leaving them to be discovered.
