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). 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-onloops 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 §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.
- 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.
- 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.
- Grounding.
groundRoleOutputchecks 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
measuredorobservedcites that kind of evidence; - it reviews the revision it was given;
- it proposes only operations its own role owns;
- an
acceptnever 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 §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.