@code3d/core 0.0.1-alpha.0 → 0.0.1-alpha.11

package/docs/relations.mdx

@@ -0,0 +1,450 @@
+---
+title: Positioning with relations
+description: Position geometry with bound contacts, geometric alignment, and explicit rotations.
+sidebar:
+  order: 4
+---
+
+import ModelExample from '../../web/src/components/ModelExample.astro';
+import SourceCode from '../../web/src/components/SourceCode.astro';
+import ArrowIcon from '../../web/src/components/ArrowIcon.astro';
+import {appUrl, sitePath} from '../../web/src/lib/site';
+import source from '../../app/examples/constraints/combined-constraints.ts?raw';
+import transformations from '../../app/examples/constraints/transformations.ts?raw';
+
+A relation describes how one part sits against another. It is attached to a
+model value and resolved when the parts are composed or their relative geometry is queried. The part keeps its own
+[local coordinates](local-coordinates.md): `originOffset()` changes
+those geometry coordinates, while a relation's `offset()` participates in
+placement. Consecutive constraints are solved together; independent transformations
+then move that joint result.
+
+<ModelExample id="relate" />
+
+## Touch a directional bound
+
+`part.on(base.up)` places the part above the base by translating its matching
+bound into contact. The six target directions are `up` (+Y), `down` (−Y),
+`right` (+X), `left` (−X), `front` (+Z), and `back` (−Z), measured in the base's
+local frame. They describe its finite bounding extent, not particular faces.
+
+The source can also be a selected vertex, edge, or surface. Only that selected
+geometry contributes its extent. A tilted shape still has a support boundary
+in the target direction; `on` never rotates it. Without an offset, its position
+along the boundary plane stays unchanged.
+
+An explicit `offset(x, y, z)` translates self from the original solution in the
+**target reference frame**. Zero leaves the result unchanged; it never adds
+centering constraints. Use explicit point or axis alignment to center parts.
+Consecutive offsets in the same frame add. Offsets and rotations execute in
+call order: a translation before an external-axis rotation moves with that
+rotation; the same translation after it does not.
+`base.up.flip()` reverses the side of contact while keeping that frame and the
+geometry unchanged. Arbitrary models or topology elements are not valid targets.
+
+## Combine conditions
+
+Return an array from `relate()` to solve several relations together:
+
+<SourceCode source={source} file="constraints/combined-constraints.ts" />
+
+<p>
+  <a
+    href={appUrl('constraints/combined-constraints.ts')}
+    target="_blank"
+    rel="noopener"
+  >
+    {'Open this example in the App '}
+    <ArrowIcon />
+  </a>
+</p>
+
+The two contacts place the second box at `[15, -15, 0]`. One determines X,
+the other determines Y, and the free Z position stays unchanged. Conflicting
+position conditions report an error. `on` only solves translation; rotations
+are always authored explicitly.
+
+## Align underlying geometry
+
+Use `align` when the relationship should determine geometry and direction:
+
+```ts
+const post = cylinder(5, 20).relate(self => [
+  self.axis.align(base.axis),
+  self.on(base.up),
+]);
+```
+
+Points coincide or lie on a curve or surface. Curves coincide with one another,
+or lie entirely on a surface. Surfaces coincide with matching normal sense.
+Unlike a bound contact, alignment can rotate self. Lines, circles, ellipses,
+planes, cylinders, and spheres are supported; other underlying geometry types
+report unsupported.
+
+Edges and faces contribute their complete supporting geometry. A point can lie
+on the extension of a short straight edge; two equal-radius arcs can share a
+circle even when their trimmed ranges differ. Endpoints and parameter origins
+are not paired. Use `start`, `midpoint`, `end`, or a vertex when more specific
+positioning is needed. Multiple solutions can remain.
+
+Curve–curve alignment uses the same positive direction. Use `target.reverse()`
+to reverse a line, axis, or edge reference, and `target.flip()` to reverse a
+surface's normal sense. These change direction metadata while preserving the
+reference axes. Point membership ignores direction; a curve lying on a surface
+does not gain an arbitrary heading in that surface.
+
+Constraints do not have offset or rotation methods. To adjust their solved pose,
+add an independent `offset(x, y, z)` array entry. Its direction uses the fixed
+composition axes, regardless of which side of `on` or `align` names self.
+Zero leaves the preceding solution unchanged.
+
+<ModelExample id="expose" />
+
+The pin function exposes its mounting face, tip face and centerline. The cap
+aligns its axis to the pin and touches its tip. These two relations express the
+actual fit; changing the pin's height does not require recomputing the cap position.
+
+Relation curves keep their actual shape and serve as the arrow shaft. Only
+the arrowhead is added at the directed endpoint (or seam for a closed curve),
+following its tangent.
+`reverse()` uses the opposite endpoint and tangent. Axes use one positive
+arrow while inspecting a relation; passive axis references have arrows at
+both ends.
+Arrowheads keep the same screen size as you zoom. Unsupported geometry,
+geometric incompatibility, and numerical nonconvergence have separate errors.
+
+To adjust a multi-constraint result visually, select self. The App edits or adds
+an independent transformation after the joint constraint segment.
+
+## Align coordinate systems
+
+All models, including groups, expose `frame` and `origin` references.
+`model.origin` is the same reference as `model.frame.origin`; neither reference
+adds geometry to the result.
+
+```ts
+const positioned = part.relate(self => self.origin.align(base.origin));
+const mounted = part.relate(self => self.frame.align(base.frame));
+```
+
+Origin alignment leaves orientation free. Frame alignment coincides the origins
+and the corresponding X/Y/Z directions, fixing all six relative degrees of
+freedom. It uses the target's solved placement, including its relations to other
+models. The target can remain a reference dependency without being included in
+the output group. Both constraints participate in the same joint solve as other
+`align` and `on` constraints.
+
+Named frames work the same way: `assembly.expose({mount: part.frame})` provides
+`assembly.mount` and `assembly.mount.origin` in the assembly's coordinates.
+
+## Choose a rotation pivot or axis
+
+```ts
+import {pivot} from '@code3d/core';
+
+const placed = part.relate(self => [
+  self.on(base.up),
+  pivot([50, 0, 0]).rotate(0, 0, 45),
+]);
+```
+
+The pivot is expressed in self's local coordinates. Use `pivotVertex(id)` to
+choose one of self's vertices, or omit the pivot and call `rotate(x, y, z)`
+to rotate around self's origin. Angles are degrees, applied X, then Y, then Z.
+`axisLine(base.axis).rotate(angle)` instead uses a positioned line axis; external
+axes follow their own composition placement. Each selection applies only to
+the next rotation.
+
+To move a reference without losing it, use
+`pivotVertex(id).pivotOffset(dx, dy, dz).rotate(x, y, z)` or
+`axisLine(base.axis).axisOffset(dx, dy, dz).rotate(angle)`. `pivot([...])` also
+accepts `pivotOffset`. The point displacement uses self's local axes; the axis
+displacement uses the selected axis frame. Moving along the axis itself has no
+effect on the rotation. These are reference modifiers, followed by one `rotate`;
+completed transformations remain separate array entries.
+
+Rotations follow the preceding joint constraint solution. Later transformations
+compose in order; a later constraint starts a new segment from that pose.
+Groups move their assembled children as one rigid part.
+
+### Bend a loft with explicit rotations
+
+<ModelExample id="loft" />
+
+The octagonal and rectangular sections first touch the circle's `up` bound,
+then turn 45° and 90° around a pivot 50 units along self's X axis.
+Inspect `sections` to see the positioned profiles, or `loft` to see the solid
+through them. Editing `pivot` or `rotate` changes the same source used here.
+
+## Transform a joint result
+
+Import `offset`, `rotate`, `pivot`, `pivotVertex`, `pivotPoint`, `axisEdge`, or `axisLine` from Core to build
+an independent `Transformation` inside `relate`. It acts on the joint solution
+and can move the part away from its contacts:
+
+<SourceCode source={transformations} file="constraints/transformations.ts" />
+
+<p>
+  <a
+    href={appUrl('constraints/transformations.ts')}
+    target="_blank"
+    rel="noopener"
+  >
+    {'Open the transformation example '}
+    <ArrowIcon />
+  </a>
+</p>
+
+Independent `offset(x, y, z)` uses the composition's fixed axes. Rotating the
+part does not rotate those offset directions. Independent `rotate(x, y, z)`
+uses self's current origin and local axes; `pivot([x, y, z])` changes that center,
+`pivotVertex(id)` chooses a self vertex; `pivotPoint(pointRef)` selects a local or external point while keeping self XYZ axes. `axisEdge(id).rotate(angle)` chooses a straight self edge, and `axisLine(lineRef).rotate(angle)` uses
+the referenced axis in its solved placement. Pivot selections apply to the next
+rotation. Completed transformations cannot be chained: write `[offset(...), rotate(...)]`,
+not `offset(...).rotate(...)`. Only pivot and axis selections expose `rotate` to
+complete that one operation. These constructors describe relative placement;
+they do not add `model.offset()` or change standalone geometry.
+
+Transformation array entries execute in order. A later constraint
+starts a new joint segment: `[align, on, offset, rotate]` solves the two constraints
+then transforms the result; `[align, offset, on]` solves align, moves the result,
+then solves on from that pose. The later segment preserves its unconstrained
+position and orientation from its input. Previous segments do not remain hard
+conditions on that later result. Successive `relate` calls continue the same
+sequence; constraints without an intervening transformation remain one segment.
+
+The fixed composition frame belongs to this assembly. A nested group's existing
+placement and origin rules carry it into the enclosing group; it is not the
+viewport's world frame. Call order remains meaningful, especially around a fixed
+external axis. A fixed-axis translation and a rotation about the current self
+origin can happen to commute without changing the sequencing rule.
+
+## Choose which part moves
+
+`relate` returns a new value and passes it to the callback as `self`. Every
+constraint must involve that value, even when written as `base.on(self.up)`.
+The parameter can have any name; it is its value that identifies the new part.
+External variables always refer to their existing model, so a part can be
+placed against the original value from which it was derived:
+
+```ts
+const side = box(2, 250, 250);
+const leftSide = side;
+const rightSide = side.relate(self => [
+  self.on(leftSide.right),
+  offset(160, 0, 0),
+]);
+const assembly = group([leftSide, rightSide]);
+```
+
+The two panel centers are 162 units apart, with a 160-unit gap. `side` and
+`leftSide` remain unchanged; no intermediate copy is needed.
+
+This identity rule also applies to selected elements and rotation references:
+`pivotPoint(self.center)` follows the new part's center, while
+`pivotPoint(side.center)` rotates around the original part's center.
+`axisLine(self.axis)` and `axisLine(side.axis)` distinguish the same two owners.
+Use `self.surface(id)`, `self.edge(id)`, or `self.vertex(id)` to constrain an
+element of the new part. A reference selected before the callback stays attached
+to its original model.
+
+## Inspect the right scope
+
+The related part on its own still displays in its local frame. Select the
+`group` to see the part positioned against the base, or place the cursor in
+the relation to inspect both participants. Related expressions inside the callback keep the actual participants visible.
+`on` and `align` inspectors show the relevant anchors and finite support bounds.
+Unrelated values keep their ordinary preview, and mixed collections preview all
+of their members. An inner call's own inspector or ordinary result takes
+precedence over the enclosing callback.
+
+The callback parameter in `relate(part => ...)` is the new related model
+value. Place the cursor on its declaration or a use of `part` inside the
+callback to inspect its completed placement segment. Its tools edit the nearest
+following offset or rotation, with the preview including later operations in that segment.
+Even before you write a consuming
+`group` or `loft`, the relation context shows the participants in their solved
+positions. Selecting the related model's standalone binding shows it in its local
+frame. Operations preserve the observable meaning of existing model values.
+
+In a `relate` array, `on` and `align` show the joint solution of their continuous
+constraint segment. Each independent `offset` or `rotate` shows its own result.
+The pivot and axis selectors show the preceding pose with the selected reference.
+Later steps do not move this preview or its handles. Previous segments provide
+the incoming pose; later segments are excluded. An invalid segment reports a
+preview error while keeping the valid final model available.
+
+<p>
+  <a href={sitePath('examples/relate/')}>
+    Step through contact, target, offset, and rotation in the relation preview →
+  </a>
+</p>
+
+## Read the relation highlights
+
+The viewport distinguishes focused targets, other targets, and ambient geometry.
+An inspector declares the complete scene. Targets that are the actual selected
+values receive focus; generated results do not inherit focus from their inputs.
+With focus present, other target markers use 70% of their normal opacity. Without
+focus, all target markers keep their normal opacity. Ambient geometry stays gray.
+
+On the `relate` method name, the completed part is the target and this call's
+actual participants are ambient. Unrelated downstream parts are omitted. Inside
+its callback, related values use the same participants and the selected relation
+stage. Unrelated values use ordinary object preview; a mixed collection falls
+through as a whole so no unrelated member disappears.
+
+`on` and `align` have their own inspectors for the call, receiver and target.
+Selecting a reference emphasizes that reference. Selecting the method name shows
+the participating references without inventing a focused side. In
+`base.on(self.up)`, selecting `self.up` therefore focuses self's bound. Independent
+`offset`, `pivot`, `pivotVertex`, `pivotPoint`, `axisEdge`, `axisLine` and `rotate`
+expressions use the relate stage; their editing handles remain separate from
+passive inspection. See [source inspection](runtime.md#source-inspection) for
+custom JSDoc inspectors and closure contexts.
+
+Model surfaces remain translucent so you can see overlapping references.
+Their opacity is capped for the current role instead of multiplied by the
+material's existing opacity. A model that is already more transparent keeps
+its material; the marker groups still show which side is selected.
+
+A bound face adds translucent fill in the same color as its bounding box.
+If that box is already visible, the face does not add another corner outline.
+When no box is visible, it supplies its own corner brackets. The source of
+`on` shows its complete measured bounding box, since contact is calculated
+from that whole extent. For a selected vertex, edge, or surface, this box
+encloses only the selected geometry. Bounds describe finite extents rather
+than selecting a real topology face.
+
+Face arrows, axis arrowheads, point markers, and spatial controls keep their
+screen size through zoom and viewport resizing. Axis shafts and curved
+highlights still follow their actual geometry.
+
+## Group or fuse
+
+Use `group([base, post])` for separate parts. Use `union([base, post])`
+when you want a single fused solid. Boolean operations also resolve operand
+relations before evaluating geometry.
+
+## Make visual adjustments
+
+Enter an `offset` call in the source to use the position tool. Supported
+parameter changes write back to the defining source values. A unique upstream
+parameter takes priority when the tool can safely preview its uses. If it is
+shared, other affected objects preview the change as well.
+
+Without a safe upstream parameter, dragging preserves the offset expression
+and adjusts it by an increment. For example, an X movement of `2` changes
+`offset((i - 2) * 8, 0, 0)` to `offset((i - 2) * 8 + 2, 0, 0)`.
+Another movement of `3` combines that increment into `+ 5`. Returning by `5`
+removes it. The tool does not change the inner `8` or keep nesting offset calls.
+
+Selecting self shows the complete placement segment. Choosing a tool keeps a
+matching current call, or checks the immediately following transformation. If
+that transformation matches, it activates the existing call; otherwise it inserts
+before that transformation. It never skips a different transformation to find
+a matching one farther ahead. With no following transformation, it appends. In a multi-constraint array,
+they target independent transformations after the jointly solved constraints.
+The search stops at the next constraint segment. App inserts the corresponding
+Core import when needed. It preserves existing aliases and avoids local name
+collisions.
+
+The toolbar starts with no active tool when selecting a model, self, or a blank
+array position. Choose a tool explicitly, or place the caret in an existing
+offset or rotation call to activate its tool. When focus moves into the viewport,
+the editor keeps a static caret and word marker at the current source position.
+The active tool's existing call is underlined; if the tool needs to insert a call,
+the underline appears on that new code after the edit. Marked code scrolls into
+view, including horizontally, without taking focus from the viewport or an input.
+Parameter and topology tools use the same source markers and navigation.
+Clicking a tool with an existing call moves the caret to the complete expression
+end, such as `offset()|` or `axisEdge(1).rotate(25)|`, and shows that step immediately. If a new call is needed, the viewport shows the state just
+before the actual insertion position. The chosen tool stays active, and clicking
+alone does not change the source. New array calls put the caret in the insertion
+gap: before the closing bracket at the end, or before the next item in the middle.
+From an array gap, the same rule checks only the immediately following item;
+a mismatch keeps the insertion position.
+
+The start of a self expression, such as `|self.axis.align(...)`, also counts as
+self context. Plain rotate and pivot selectors match point rotation; axis selectors match
+axis rotation. Choosing one does not activate a call of the other type.
+
+When an `offset` or `rotate` is selected, the matching tool edits that call.
+Choosing another tool checks the next transformation first. A match activates it;
+a mismatch inserts immediately after the selected call, before later operations. For independent transformations this inserts a new array
+item; a single return value becomes an array. It never chains one completed
+transformation into another. Handles and previews use the frame of that exact
+edit, excluding later operations. A spread argument is replaced
+with the current three values when editing that call.
+
+A safe shared parameter can update multiple instances of the same call. If it
+also controls a different operation, dragging adjusts the selected expression
+instead. A shared expression changes all of its runtime occurrences; it is not
+an override for only the clicked part.
+
+Release to commit the preview, or press `Esc` while dragging to cancel without
+closing the panel. Use Undo after an edit has been committed. Numeric panel
+input has a different meaning when an expression appears as a placeholder:
+it [replaces the whole argument](../../web/src/content/docs/docs/guides/model-tools.mdx#what-a-panel-can-edit).
+
+Use the position toolbar above the panel to choose translation or a rotation
+variant. In either rotation tool, hold Alt to move its reference instead of
+rotating the part. Point or axis candidates appear while the corresponding
+rotation tool is active; click one directly to choose the reference. Point selection
+retains a vertex ID; axis selection uses a straight edge or a named axis of self.
+Replacing a reference within the same rotation type retains its offset and angles;
+choosing a reference for the other rotation type adds a new zero-angle operation.
+
+To change the standalone geometry and its origin, see
+[origins and rotation](origins-and-rotation.mdx).
+
+See [code and geometry](../../web/src/content/docs/docs/concepts/code-and-geometry.md) for the distinction
+between a model value and its runtime context.
+
+## Measure before building a part
+
+Use `distance(a, b, axis?)` when another part's dimensions depend on existing
+geometry. The query resolves the inputs' current relations and returns an
+ordinary number; a group is not required before measuring.
+
+<ModelExample id="distance" />
+
+In this example, change `gap` to resize the opening and its beam. The beam reads
+the X gap between the two facing bounds and the support's Z depth, then builds
+with those dimensions. Its height remains fixed. The Arguments presets show
+two sizes of the same assembly.
+
+Omit the axis for the shortest spatial distance, or provide `x`, `y`, `z`, a
+direction vector, or a straight edge/axis reference for the gap between projected
+intervals. Use topology faces when their actual trimmed shape matters; a
+directional bound measures its rectangular extent. See the
+[measurement reference](api.md#measurements) for supported inputs
+and coordinate rules.
+
+Measurements follow source order. Adding a later relation does not retroactively
+change a computed length. For a repeated part already in a group, expose the
+intended occurrence and measure that reference.
+
+Place the cursor anywhere inside a `distance(...)` call to inspect the measurement
+in the viewport. Both measured objects are emphasized against dimmed related
+models, with a distance line and numeric label. Whole solids and groups retain
+their model appearance instead of receiving a face-selection overlay. The preview uses the solved
+positions at that call, even before a `group` exists. A projected measurement is
+marked with its axis: the line spans the projection intervals, so its endpoints
+need not lie on the selected geometry. The line is placed within the shared
+transverse bounds when possible: for a point inside a face’s projection, it starts
+at the point and reaches the face along the measurement axis. Overlapping
+intervals on the measurement axis show zero.
+
+Inside the call, selecting a model variable emphasizes that model and dims the
+other whole-model operand. Selecting an
+element reference emphasizes that element while the other measured element stays
+visible at secondary emphasis. An explicitly selected bound also shows its normal
+direction; other measured bounds keep only their face and corner markers. The
+measurement line stays visible as you move between arguments.
+
+Measurements use a gray dashed line with short ticks at both ends and a neutral
+numeric label. The X, Y, or Z letter uses the matching viewport axis color; custom
+directions keep a neutral `axis` label. Dash spacing, endpoint ticks, and text
+keep their screen size as you zoom and are included in annotated image exports. This preview is passive; measurement
+parameter controls and element-picking tools are not yet available.