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

package/docs/custom-primitives.mdx

@@ -0,0 +1,58 @@
+---
+title: Building custom primitives
+description: Bring a Replicad solid into Code3D with normal model capabilities and parameter tools.
+sidebar:
+  order: 10
+---
+
+import ModelExample from '../../web/src/components/ModelExample.astro';
+
+Start with the built-in [modeling operations](api.md) when they
+fit the part. For other solid geometry, `definePrimitive` wraps a synchronous
+Replicad builder as a normal Code3D model.
+
+Import both `definePrimitive` and `replicad` from `@code3d/core/replicad`.
+The builder returns one solid; the result supports the usual `material`,
+`relate`, `expose`, fillet, and chamfer operations.
+
+## A twisted knob with a shaft bore
+
+This example extrudes a hexagonal profile with a twist, cuts a D-shaped bore,
+and places two instances on a base. Its `@code3d.param` annotations make the
+dimensions and twist angle available in call-site panels.
+
+<ModelExample id="custom-primitives" />
+
+Open the example and place the cursor in either `twistKnob(...)` call to
+adjust its inputs. The short knob supplies a twist of 30°; the tall one uses
+the builder's default of 60°. The twist annotation also declares `default: 60`,
+so the tall knob's panel shows that value as a placeholder. Typing a number
+adds an explicit twist argument; simply opening the panel leaves it omitted.
+
+## Return a model, own the intermediate geometry
+
+Returning the solid transfers it to Code3D. Do not delete, mutate, or return
+that same shape again. Intermediate Replicad resources remain the builder's
+responsibility; the example uses `localGC()` and `finally` to release them.
+Some Replicad operations consume their inputs, so resource handling follows
+the operations used.
+
+Validate dimensions inside the builder. A single-solid aggregate from a
+Replicad boolean can be normalized, but multiple solids, shells, or aggregates
+with stray lower-dimensional geometry are rejected.
+
+`definePrimitive()` caches deterministic construction by definition and arguments,
+including validation, normalization, topology and bounds. A hit skips the builder
+and creates a fresh model with its own shape handles and source tracing. Pass all
+changing captured state as explicit arguments. The App fingerprints static
+builders and their dependencies for persistent reuse; dynamic closures and
+ordinary Node calls use function object identity for memory reuse.
+
+Primitives share the same memory and disk budgets as Core computations and
+Screws. Use [`cache()`](api.md#cached-computations) for ordinary
+data computations; geometry needs `definePrimitive()` so Core manages its native
+resources.
+
+Your function stays ordinary TypeScript and can be exported for other modules.
+See [adding tools to model functions](../../web/src/content/docs/docs/guides/model-tools.mdx) for annotation rules and
+[reusable models](../../web/src/content/docs/docs/guides/reusable-models.mdx) for naming attachment points.

package/docs/local-coordinates.md

@@ -0,0 +1,187 @@
+---
+title: Local coordinates and placement
+description: Understand positions, origin offsets, model axes, and where a part sits in a composition.
+sidebar:
+  order: 3
+---
+
+Every model has its own local coordinates. Its origin is `[0, 0, 0]`.
+The geometry can be away from that origin: a point at `[10, 0, 0]` still
+belongs to a model whose origin is zero.
+
+## Positions, dimensions, and displacements
+
+Use coordinate arrays for positions and separate numbers for dimensions,
+displacements, and angles:
+
+| Expression                     | Meaning                                              |
+| ------------------------------ | ---------------------------------------------------- |
+| `box(10, 20, 30)`              | Dimensions along local X, Y, and Z; centered at zero |
+| `point()`                      | A point at local zero                                |
+| `point([10, 2, -3])`           | A point at the supplied local coordinates            |
+| `line([10, 0, 0])`             | A line from zero to the supplied endpoint            |
+| `line([10, 0, 0], [20, 0, 0])` | A line between two local positions                   |
+| `originOffset(10, 0, 0)`       | Move the origin by a local displacement              |
+| `pivot([10, 0, 0])`            | Choose a rotation center in self's local coordinates |
+| `offset(10, 0, 0)`             | Move a relate result along fixed composition axes    |
+| `rotate(0, 90, 0)`             | Rotate geometry by 90° around local Y                |
+
+Curve control points use the returned model's local coordinates too. A common
+offset in their coordinates is retained; the curve does not automatically move
+its start or center to zero.
+
+## Default origin rules
+
+Constructors define a local coordinate frame. Derived operations inherit their
+main input's frame; they do not automatically recenter the resulting geometry.
+Only an explicit origin operation chooses a different local zero.
+
+| Constructor or operation                          | Origin and coordinate frame                                                                                                                |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `box`, `sphere`, `circle`, `ellipse`, `rectangle` | Geometry is constructed around local zero.                                                                                                 |
+| `cylinder`, `tube`, `frustum`, `regularPrism`     | The central axis passes through zero; height is centered on Y. This is not a center-of-mass rule.                                          |
+| `regularPolygon`                                  | The polygon's construction-circle center, which need not equal its bounding-box center.                                                    |
+| `coil`                                            | The helix axis passes through zero; the centerline's axial span is centered on Y.                                                          |
+| `point`, `line`, `arc`, `bezier`, `spline`        | Retain the supplied coordinates relative to zero; neither endpoints nor curve centers are automatically moved to zero.                     |
+| Faces made from a sketch                          | Retain the sketch's local frame.                                                                                                           |
+| `text`                                            | All returned faces share the text layout's baseline origin, including its glyph advances and offsets. Individual letters are not centered. |
+| `definePrimitive`                                 | Retain the frame used by the returned geometry; no automatic recentering.                                                                  |
+| `extrude`                                         | Inherit the input face's frame, without centering the extrusion.                                                                           |
+| `union`, `intersect`                              | Inherit the first operand's frame.                                                                                                         |
+| `cut`                                             | Inherit the stock's frame.                                                                                                                 |
+| `loft`                                            | Inherit the first section's frame.                                                                                                         |
+| `group`                                           | Inherit the first member's frame after solving placement; an empty group uses the default frame.                                           |
+| `rotate`, `scaled`, `fillet`, `chamfer`, `shell`  | Retain the input model's frame, even when its geometric bounds change.                                                                     |
+| `relate`, `material`, `expose`                    | Retain the model's local frame; relations describe its placement within a composition.                                                     |
+
+For example, `point([10, 0, 0])` has geometry at X = 10 and an origin at zero.
+Similarly, `rectangle(10, 10).extrude(20)` keeps its origin on the starting
+plane, while `box(10, 20, 10)` is centered on its origin.
+
+Explicit choices are `originOffset(dx, dy, dz)` for a displacement,
+`originPoint(pointRef)` for a referenced point, `originVertex(id)` for an own
+topology vertex, and `originCenter()` for the existing center anchor. The last
+two require geometry and are not available on groups. A carried center anchor
+is not necessarily the center of the current axis-aligned bounding box.
+
+## Coordinate references
+
+Every model, including a group, provides `model.frame`, a reference to its local
+coordinate system. `model.frame.origin` references that frame's zero point;
+`model.origin` is the same reference. Neither is a geometric model.
+For `point([10, 0, 0])`, the geometry is at X = 10 while its frame origin is zero.
+Changing local geometry with `rotate()` does not rotate the model's coordinate
+axes. Placement through `relate()` determines the frame's pose in a composition.
+
+Use `self.origin.align(other.origin)` to coincide just the origins, or
+`self.frame.align(other.frame)` to coincide both origins and all three axes.
+Coordinate references can be named with `expose`; an exposed frame and its
+`.origin` follow the selected occurrence through nested groups and transforms.
+A newly read `model.origin` always references the current local zero. Previously
+selected references retain their meaning through subsequent origin edits.
+
+## Changing the origin changes point coordinates
+
+`originOffset(dx, dy, dz)` chooses a new origin at that displacement in the
+input model. In the result, that origin is zero and each point has coordinates:
+
+```text
+p_new = p_old - [dx, dy, dz]
+```
+
+For example, the point in `point([10, 2, -3]).originOffset(4, 0, 0)` is at
+`[6, 2, -3]`. Conversely, `point().originOffset(-10, -2, 3)` creates the same
+local geometry as `point([10, 2, -3])`.
+
+The shape and distances between points stay the same. Geometry, `center`,
+named anchors, and topology positions use the new coordinates together.
+Directions and normals keep their direction. The operation returns a new
+model value and preserves topology IDs; earlier values and references retain
+their meaning. Successive origin offsets add and opposite offsets cancel.
+
+Use `originPoint(pointRef)` on any model to make a referenced point zero.
+For geometric models, `originVertex(id)` selects an own topology vertex and
+`originCenter()` selects the carried center anchor. The [origin and rotation guide](origins-and-rotation.mdx)
+shows how to select and drag these in the viewport.
+
+## The origin, center, and axes have different roles
+
+`line([10, 0, 0])` has its origin at zero and its midpoint at `[5, 0, 0]`.
+Rotating it with `.rotate(0, 90, 0)` gives a line from zero to `[0, 0, -10]`.
+Calling `.originCenter()` first puts the endpoints at `[-5, 0, 0]` and
+`[5, 0, 0]`, so the same rotation now turns the line around its midpoint.
+
+Geometric `rotate()` and `scaled()` act around the current local zero.
+The `center` anchor follows these transformations; rotation does not replace
+it with the center of the new axis-aligned bounding box.
+
+The model's XYZ axes remain its local coordinate axes. `up` means local +Y
+even after the geometry rotates. A line's tangent or a face's normal belongs
+to that geometric reference and can point in a different direction. Relation
+offsets use the target reference's axes; an explicit `pivot([x, y, z])` uses
+self's model coordinates. See [relations](relations.mdx) for those
+placement rules.
+
+## Placing a part in a composition
+
+`relate()` describes placement relative to other parts. Inspect a related
+part by itself to see its local geometry; inspect the relation or a consuming
+composition to see the solved placement. An `originOffset()` changes the
+part's local geometry coordinates, while a relation's `offset()` participates
+in its placement conditions.
+
+Several relations on one model are solved together. Their offsets belong to
+those conditions, and any remaining freedom uses the solver's default result.
+See [combining conditions](relations.mdx#combine-conditions) before
+using an offset in a system with multiple relations.
+
+New model values also have a coordinate frame:
+
+- A boolean result uses the main operand's local coordinates.
+- A loft uses its first section's local coordinates.
+- A group uses its first member's local coordinates, retaining relative placement.
+- `expose()` brings a reference into the outer model's local space. For a
+  repeated part, use the reference from its specific instance.
+
+Export uses these same coordinates: a standalone part has local geometry,
+and a composition includes its parts' resolved placement. The chosen output
+scale and up axis are applied afterward. See [exporting models](../../web/src/content/docs/docs/guides/exporting.md).
+
+## Group origins
+
+A group first solves the placement of its direct members, then expresses all
+members in the **first member's local coordinate frame**, including its origin
+and axes. This is the same reference rule used by `union`, `intersect`, and
+`loft`; `cut` uses the stock's frame. Reordering members can change the group's
+frame, while preserving their relative placement. A nested group is one member,
+with its own existing frame. An empty group uses the default origin and axes.
+A relation's rotation affects that solved member frame; rotating the member's
+geometry directly with `.rotate()` does not redefine its local axes.
+
+```ts
+import {box, group} from '@code3d/core';
+
+const base = box(20, 4, 10).originOffset(0, 2, 0);
+const lid = box(20, 2, 10).originOffset(0, -1, 0);
+const assembly = group([base, lid]);
+const mounted = assembly.originPoint(lid.center);
+```
+
+Here the unrestrained member origins coincide at the contact plane. That point
+becomes the group origin. `originPoint(lid.center)` chooses the lid's center in
+the assembled coordinates; `originOffset()` can then shift it further. Both
+operations re-express the whole group, preserving member spacing and internal
+relations. The default is chosen once and does not overwrite explicit edits.
+
+Changing the first member's origin before constructing a new group changes the
+reference frame, even if constraints keep its physical geometry in place.
+Changing a later member's origin does not select a different reference member;
+its placement still follows the assembly constraints.
+Within an existing model, origin edits also update its own stored relation
+references, so a constraint on a selected geometric point still follows that
+same point.
+
+For repeated geometry, select an instance's named reference, such as
+`assembly.originPoint(rightPart.body.center)`. A reference to the shared source
+alone is ambiguous and is rejected. The same instance resolution applies to
+`expose()`.

package/docs/origins-and-rotation.mdx

@@ -0,0 +1,105 @@
+---
+title: Choosing an origin and rotating a part
+description: Set a pivot, rotate geometry, and adjust both directly in the viewport.
+sidebar:
+  order: 5
+---
+
+import ModelExample from '../../web/src/components/ModelExample.astro';
+
+The origin defines local coordinates and is always zero in the resulting model.
+An origin offset `d` changes every point coordinate from `p` to `p - d`, preserving
+the shape. `rotate` turns the geometry around that local zero; a
+[relation](relations.mdx) places the resulting part in a composition. For
+positions, dimensions, and reference axes, start with
+[local coordinates and placement](local-coordinates.md).
+
+<ModelExample id="rotate" />
+
+The [rotation example](/examples/rotate/) focuses on `rotate` alone.
+The companion [origin source](https://github.com/vilicvane/code3d/blob/main/packages/app/examples/operations/origin.ts)
+lets you inspect the origin operations below independently.
+
+## Choose a pivot
+
+Place the cursor in `blank.originVertex(3)`. Pick a vertex in the viewport to
+use it as the origin. The ID belongs to the operation's input model, just like
+other [topology selections](topology.md).
+
+Use `.originPoint(pointRef)` to select a center, named point, or topology vertex
+on any model, including a group member. Use `.originOffset(dx, dy, dz)` to move the origin by a displacement or `.originCenter()` to make
+the body's center local zero. `originVertex()` similarly makes the chosen
+vertex zero. These operations return new model values; `blank` is unchanged.
+
+## Fine-tune the origin
+
+Move to `pivoted.originOffset(0, 2, 0)` and drag an axis arrow. The origin
+marker moves against the snapshot captured at drag start. On release, the
+geometry switches to the resulting coordinates and the marker returns to local
+zero. Offsets accumulate across calls.
+
+You can also drag the origin marker's arrows while inspecting `originPoint`, `originVertex`
+or `originCenter`. The App adds or updates an `originOffset(...)` call so the
+chosen vertex or center remains the starting point.
+
+## Rotate the part
+
+In the rotation example, move to `blank.rotate(15, 35, 0)` and drag a rotation ring, or enter an angle
+in the panel. Angles are in degrees, applied around fixed local X, then Y,
+then Z axes. Each ring follows the effective axis of its angle parameter;
+the rings need not line up with the world axes when other angles are nonzero.
+
+Repeated `rotate` calls compose in source order. Named references
+rotate with the shape, and topology IDs are preserved. Changing the origin
+afterward does not undo an earlier rotation.
+
+## Recenter without undoing the rotation
+
+After a rotation, `.originCenter()` recenters the result. The `center` anchor follows the body's
+transforms; it is not recalculated from the rotated shape's axis-aligned
+bounding box. A subsequent `originOffset(0, 2, 0)` moves the pivot beyond that center.
+
+Applying `originOffset(0, -2, 0)` cancels that last offset. The center is again
+local zero, and the shape retains its rotation.
+
+## Compose with other parts
+
+Origin operations, `rotate()` and `scaled()` preview their own returned value.
+Their ordinary preview does not add downstream consumers. Select the inputs of
+`group`, `union`, `cut`, `intersect` or `loft` to inspect the context declared by
+that operation's public inspector. A standalone model uses its local frame;
+an ordinary collection retains its members' shared composition positions.
+
+Inspectors can retain the pose at the selected operation, so later transformations
+do not replace its geometry or stage. See [source inspection](runtime.md#source-inspection)
+for the common rules and custom JSDoc callbacks.
+
+A relation such as `companion.relate(part => part.on(rotated.up))` can place
+a companion against a rotated part before grouping them. Inspecting the companion by itself uses its local
+frame, without its assembly placement.
+
+Origin edits update the local coordinates of geometry, bounds and named
+references together. The model's `up` direction remains local +Y even after
+geometry rotates. For a rotation that only affects composition, use a
+[constraint pivot or axis](relations.mdx#choose-a-rotation-pivot-or-axis), with
+coordinates written as `pivot([x, y, z])`.
+
+## Finish or cancel a drag
+
+Dragging previews the change. Release to write it to source, or press `Esc`
+before releasing to cancel. Cancellation keeps the panel and editor position;
+move the cursor out of the call to leave its tool. Use Undo for an edit already
+written to source.
+
+When possible, a drag changes a unique safe upstream parameter. Otherwise it
+adjusts the current expression by a numeric increment. Entering a number in a
+panel can instead replace that expression: see
+[what a panel can edit](../../web/src/content/docs/docs/guides/model-tools.mdx#what-a-panel-can-edit).
+
+Solids, faces, curves, and points provide all these operations. Groups provide
+`originPoint()`, `originOffset()` and `rotate()`; their default origin comes from the first member's local coordinate frame. See [group origins](local-coordinates.md#group-origins)
+for direct assembly and instance selection. To rotate the whole assembly about
+a member point, use `assembly.originPoint(part.center).rotate(0, 0, 30)`. Its
+internal placements remain intact, including nested groups; angle inputs and
+rotation rings work the same way as on a single part. See the [API reference](api.md#origins-and-rotation)
+for the complete method list.