Geometry Engine Notes

Optional reading for the curious: this section explains how the studio turns your lines into 3D planes. Skip it if you are focused purely on designing; read it if you like understanding the machinery behind the curtain.

Once the interpreter has a list of facet commands, the geometry engine turns them into a tangible 3D shape. Understanding the broad strokes helps when you fine-tune designs or wonder why a certain cut fails.

The main players

• Faceting machine model – converts angles, indices, and sides into planes, just like the mast on a real machine.
• Gemstone container – stores the current mesh (vertices, faces, metadata) and applies each new plane.
• Polyhedron math – slices the mesh against incoming planes, keeps track of new faces, and preserves manifold geometry.

All of this lives in Rust under src/foundation/ and src/polyhedron/, but you can think of it as a well-behaved virtual slab ready to be cut.

From command to facet

1. Validate the index – must be a whole number, positive or zero.
2. Expand symmetry – figure out every index that should receive the same cut.
3. Build a base plane – depends on the command:
   • Angle + depth: drop the lap to the requested depth.
   • Angle + point: tilt to the angle, then slide until the plane touches the point.
   • Points: draw a plane through two known points.
4. Rotate for symmetry – copy the plane around the mast axis for each repetition.
5. Slice the gemstone – intersect the current shape with each plane and record the resulting face (tier name, indices, frosting flag, etc.).

If a slice would remove the entire stone, the engine stops and reports an error so you can adjust the preceding cuts.

Handling points and helpers

When you reference mp(P1) or an edge computed earlier, the engine resolves those values in the current coordinate space. It can also derive special points (midpoints, edge intersections) through helper functions. If a point is undefined or incompatible, you receive an error with the exact line that referenced it.

Precision and stability

Faceting math is sensitive, so the engine uses adaptive precision routines under the hood. You rarely need to think about it, but it explains why even aggressive symmetry sequences remain stable.

When to peek inside

• You want to add a new facet specifier (e.g., cut to a plane defined by three points).
• You need to debug why a facet disappears after a certain step.
• You are validating that symmetry indices match the printable packet.

In those cases, explore Gemstone::apply_facet_command and related helpers. For everyday design work, it is enough to know that the engine faithfully follows the commands in the order you wrote them.