forgecad 0.10.3 → 0.10.5

package/dist/docs-raw/generated/core.md

@@ -18,13 +18,12 @@ skill-order: 100
 - [Grouping & Local Coordinates](#grouping-local-coordinates)
 - [Section & Projection](#section-projection)
 - [Verification](#verification)
-- [Shape](#shape) — Appearance, Face Topology, Edge Topology, Transforms, Booleans & Cutting, Features, Placement, Connectors, References, Measurement
+- [Shape](#shape) — Freeform Construction, Appearance, Face Topology, Edge Topology, Transforms, Booleans & Cutting, Features, Placement, Connectors, References, Measurement
 - [Transform](#transform)
 - [ShapeGroup](#shapegroup) — Children, Transforms, Placement, Connectors, References
 - [SurfacePattern](#surfacepattern)
 - [Pattern2D](#pattern2d)
 - [Pattern2DBuilder](#pattern2dbuilder)
-- [Sheet](#sheet)
 - [CurveNetBuilder](#curvenetbuilder)
 - [MatchEdgeBuilder](#matchedgebuilder)
 - [BridgeBuilder](#bridgebuilder)
@@ -34,6 +33,7 @@ skill-order: 100
 - [Points](#points)
 - [connector](#connector)
 - [Import](#import)
+- [Wrap](#wrap)
 
 ## Functions
 
@@ -704,6 +704,96 @@ Supports transforms (translate, rotate, scale, mirror, transform, rotateAround,
 |----------|------|-------------|
 | `materialProps` | `ShapeMaterialProps \| undefined` | — |
 
+**Freeform Construction**
+
+#### `slicePerpendicularToX(x: number, profile: Sketch, options?: FromSlicesAxisSliceOptions): FromSlicesSlice` — Create a slice descriptor perpendicular to the X axis.
+
+The profile is drawn in the YZ plane. `options.center` is `[y, z]`, so authors can place changing section centers without manually translating sketches in ForgeCAD's internal plane axes.
+
+```js
+Shape.fromSlices([
+  Shape.slicePerpendicularToX(-20, ellipse(10, 2), { center: [0, 3] }),
+  Shape.slicePerpendicularToX(20, ellipse(8, 1.5), { center: [0, 6] }),
+]);
+```
+
+**`FromSlicesAxisSliceOptions`**
+- `center?: FromSlicesVec2` — Plane-local profile center. XY uses [x, y], XZ uses [x, z], YZ uses [y, z].
+
+#### `slicePerpendicularToY(y: number, profile: Sketch, options?: FromSlicesAxisSliceOptions): FromSlicesSlice` — Create a slice descriptor perpendicular to the Y axis.
+
+The profile is drawn in the XZ plane. `options.center` is `[x, z]`.
+
+#### `slicePerpendicularToZ(z: number, profile: Sketch, options?: FromSlicesAxisSliceOptions): FromSlicesSlice` — Create a slice descriptor perpendicular to the Z axis.
+
+The profile is drawn in the XY plane. `options.center` is `[x, y]`.
+
+#### `sliceThrough(center: FromSlicesVec3, normal: FromSlicesVec3, profile: Sketch): FromSlicesSlice` — Create a slice descriptor through a world point with an arbitrary plane normal.
+
+The profile origin lands at `center`. Use this when the section plane is not one of the world XY/XZ/YZ planes.
+
+#### `sliceOnFrame(frame: FromSlicesFrameInput, profile: Sketch): FromSlicesSlice` — Create a slice descriptor on a full 3D work frame.
+
+Sheet frame helpers return the right shape for `frame`. Use `Sheet.frameAt()` for tangent construction planes, or `Sheet.framePerpendicularToU()` / `Sheet.framePerpendicularToV()` for cross-sections normal to a surface path. On the Manifold backend, framed slices are lofted in input order when every slice comes from a frame.
+
+**`FromSlicesFrameInput`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `point?` | `FromSlicesVec3` | World-space frame origin. Sheet frame helpers return this as `point`. |
+| `origin?` | `FromSlicesVec3` | Alias for `point` when using generic CAD frame terminology. |
+| `normal` | `FromSlicesVec3` | World-space frame normal. |
+| `tangentU?` | `FromSlicesVec3` | World-space direction for the profile's local X axis. Sheet frame helpers return this as `tangentU`. |
+| `tangentV?` | `FromSlicesVec3` | Optional world-space direction for the profile's local Y axis. Sheet frame helpers return this as `tangentV`. |
+| `xAxis?` | `FromSlicesVec3` | Alias for `tangentU`. |
+| `yAxis?` | `FromSlicesVec3` | Alias for `tangentV`. |
+
+#### `fromSlices(slices: FromSlicesSlice[], options?: FromSlicesOptions): Shape` — Construct a 3D shape from cross-section slices on one or more planes.
+
+On the Manifold backend, slices created with `Shape.sliceOnFrame()` are lofted in their input order while preserving each full 3D frame. Other slices with the same normal direction are lofted together. Slices with different normals are combined via smooth radial blending — each silhouette constrains the shape's extent, producing smooth ellipsoidal cross-sections.
+
+```js
+// Egg from two orthogonal silhouettes
+const eggProfile = ellipse(15, 25);
+return Shape.fromSlices([
+  { on: 'xz', at: 0, profile: eggProfile },
+  { on: 'yz', at: 0, profile: eggProfile },
+]);
+```
+
+```js
+// Vase with cross-section transitions
+return Shape.fromSlices([
+  Shape.slicePerpendicularToZ(0, circle2d(20)),
+  Shape.slicePerpendicularToZ(40, rect(25, 25)),
+  Shape.slicePerpendicularToZ(80, circle2d(8)),
+  Shape.slicePerpendicularToY(0, vaseOutline),
+]);
+```
+
+**`FromSlicesSlice`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `on` | `SlicePlane` | Plane normal: axis name or arbitrary unit vector. |
+| `at?` | `number` | Signed offset along the normal from the origin. Omit when `center` defines the plane. |
+| `center?` | `FromSlicesVec3` | World-space point where the 2D profile origin should land on the slice plane. |
+| `profile` | `Sketch` | 2D cross-section profile on that plane. |
+| `frame?` | `FromSlicesFramePlacement` | Full 3D section frame, preserved for ordered lofts through rotating planes. |
+
+**`FromSlicesFramePlacement`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `point` | `FromSlicesVec3` | World-space frame origin. |
+| `normal` | `FromSlicesVec3` | World-space section normal. |
+| `tangentU` | `FromSlicesVec3` | World-space direction for the profile's local X axis. |
+| `tangentV` | `FromSlicesVec3` | World-space direction for the profile's local Y axis. |
+
+**`FromSlicesOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing (Manifold only).
+- `boundsPadding?: number` — Extra bounding-box padding (Manifold only).
+
 **Appearance**
 
 #### `color(value: string | undefined): Shape` — Set the color of this shape (hex string, e.g. "#ff0000"). Returns a new Shape with the color applied.
@@ -741,6 +831,7 @@ box(100, 100, 10).color('#gold').material({ metalness: 0.95, roughness: 0.05 }).
 | `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
 | `specularColor?` | `string` | Specular highlight tint. |
 | `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
+| `texture?` | `{ image: string; projection: UvProjectionSpec; ...` | Projected bitmap texture set by `Shape.wrapTexture`. `image` is a self-contained `data:` URI; `projection` maps each vertex's final world position to (u,v) in the shader, so the texture survives transforms and boolean cuts. `imageWidth`/`imageHeight` are the intrinsic pixel dimensions. |
 
 **Face Topology**
 
@@ -1089,6 +1180,22 @@ Overloads:
 
 **Other**
 
+#### `wrapTexture(image: ImageHandle, projection: UvProjectionSpec): Shape` — Wrap an imported bitmap image around this shape using a projection.
+
+The `image` comes from `Import.image('path.png')`; the `projection` is one of the `Wrap.*` helpers — `Wrap.flat({ onto: 'top' })` lays it flat on a face, `Wrap.aroundCylinder({ axis: 'z' })` wraps it like a can label, `Wrap.onSphere()` maps it like a globe, and `Wrap.box()` cube-maps it onto the six sides.
+
+By default the image **auto-fits** the shape — one copy across the relevant extent, so no `width`/`height`/`size` is needed (pass them only to override). The (u,v) is derived from each vertex's final world position, so the image stays glued to the surface through transforms and boolean cuts with no UV layout to maintain — apply `wrapTexture` *after* positioning the shape. Returns a new Shape; the original is unchanged.
+
+```js
+const logo = Import.image('./logo.png');
+box(80, 80, 10).wrapTexture(logo, Wrap.flat({ onto: 'top' }));            // auto-fits the face
+
+const label = Import.image('./label.jpg');
+cylinder(60, 20).wrapTexture(label, Wrap.aroundCylinder({ axis: 'z' }));  // wraps the side
+```
+
+`ImageHandle`: `{ __forgeImage: true, dataUri: string, width: number, height: number, mimeType: string, byteLength: number }`
+
 #### `clone(): Shape` — Return a new Shape wrapper for explicit duplication in scripts.
 
 #### `geometryInfo(): GeometryInfo` — Inspect which backend/representation produced this solid.
@@ -1337,57 +1444,106 @@ const bracket = group(
 | `depth?` | `number` | Thread groove depth in millimeters. Default: 0.8. |
 | `underScale?` | `number` | Relative height of the under-crossing thread. Default: 0.15. |
 
-### `Sheet`
+### `CurveNetBuilder`
 
-A parametric open surface value (control grid + knots + analytic differential geometry).
+#### `alongRails(railA: CurveInput, railB: CurveInput): this` — Use two lengthwise boundary curves as guide rails.
 
-**Properties:**
+Chain `.sections(...)` to create a bi-rail surface: the rails define the sheet edges while each section curve shapes the cross-span at its station.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `surface` | `BSplineSurface` | — |
+#### `sections(...curves: CurveInput[]): this` — Add crosswise section curves.
 
-**Methods:**
+By itself this skins the sections into a surface. After `.alongRails(...)`, the sections are fitted between the two rails so the surface follows both the boundary guide curves and the section profiles.
+
+#### `resolution(samples: number): this` — Set the sampling resolution used to build curve-family surface grids.
+
+This affects `.lengthwise(...)`, `.crosswise(...)`, and `.alongRails(...).sections(...)` surfaces. It does not resample explicit `.cage(grid)` input because the cage already is the authored control net.
 
-#### `get frontEdge(): SheetEdge` — Edge naming follows parameter direction (documented): front=v0, rear=v1, left=u0, right=u1.
+#### `matchStartU(condition: BoundaryCondition): this` — Enforce a continuity condition on the `u = 0` (left) boundary.
 
-#### `thicken(wall: number, options?: { resolution?: number; }): Shape` — Offset the sheet along its analytic normals into a watertight solid shell of the given wall thickness. Throws if the wall would self-intersect on a concave region (no silent degenerate solid).
+Pass `{ edge }` to match an adjacent sheet's tangent (G1) or curvature (G2), or `{ tangent }` to impose an explicit cross-boundary direction. See `BoundaryCondition`.
 
-#### `matchEdge(edge: SheetEdge): MatchEdgeBuilder` — Per-edge continuity match against a neighbor (returns a NEW Sheet).
+**`BoundaryCondition`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `edge?` | `SheetEdge` | Match the tangent (G1) and curvature (G2) of an existing sheet edge across this boundary. |
+| `tangent?` | `Vec3` | Or impose an explicit cross-boundary tangent direction in world space (auto-normalized). |
+| `tangentScale?` | `number` | Scalar magnitude for the imposed `tangent` ramp, in model units. Ignored when `edge` is given. Default: the local cross-boundary control-span length (chord-scaled), so the imposed tangent has the same strength as the surface already carries — no magic number. |
+| `continuity?` | `0 \| 1 \| 2` | Continuity order to enforce on this side. Default inferred: 1 if a tangent or edge is given, else 0. G2 (curvature) requires an `edge` to copy the neighbor's second difference. |
 
 **`SheetEdge`**
 - `fixed: "u" | "v"` — Which parameter is held fixed along this edge.
 - `value: 0 | 1` — The fixed value (0 or 1).
 - Also: `sheet: Sheet`.
 
-- `get rearEdge(): SheetEdge`
-- `get leftEdge(): SheetEdge`
-- `get rightEdge(): SheetEdge`
-- `pointAt(u: number, v: number): Vec3`
-- `normalAt(u: number, v: number): Vec3`
-- `curvatureAt(u: number, v: number): SurfaceCurvature`
+#### `matchEndU(condition: BoundaryCondition): this` — Enforce a continuity condition on the `u = 1` (right) boundary. See `matchStartU`.
 
-### `CurveNetBuilder`
+#### `matchStartV(condition: BoundaryCondition): this` — Enforce a continuity condition on the `v = 0` (front) boundary. See `matchStartU`.
+
+#### `matchEndV(condition: BoundaryCondition): this` — Enforce a continuity condition on the `v = 1` (rear) boundary. See `matchStartU`.
+
+#### `closedU(): this` — Weld the two ends of the U direction into a tangent-continuous periodic loop, so the `u = 0` and `u = 1` boundaries coincide with NO G0 kink (a closed tube/ring in U — e.g. a bowl's around-rim seam). The cage's first and last U rows must already be coincident (the loop must close in position).
+
+#### `closedV(): this` — Weld the two ends of the V direction into a tangent-continuous periodic loop. See `closedU`.
 
 #### `toSheet(): Sheet` — Build (once) and return the Sheet.
 
 - `lengthwise(...curves: CurveInput[]): this`
 - `crosswise(...curves: CurveInput[]): this`
-- `alongRails(railA: CurveInput, railB: CurveInput): this`
-- `sections(...curves: CurveInput[]): this`
 - `cage(grid: Vec3[][]): this`
 - `degree(u: number, v: number): this`
 - `get frontEdge(): SheetEdge`
 - `get rearEdge(): SheetEdge`
 - `get leftEdge(): SheetEdge`
 - `get rightEdge(): SheetEdge`
+- `get frontCurve(): NurbsCurve3D`
+- `get rearCurve(): NurbsCurve3D`
+- `get leftCurve(): NurbsCurve3D`
+- `get rightCurve(): NurbsCurve3D`
 - `get surface(): BSplineSurface`
 - `pointAt(u: number, v: number): Vec3`
 - `normalAt(u: number, v: number): Vec3`
+- `frameAt(u: number, v: number, options?: SheetFrameOptions): SheetFrame`
+- `framePerpendicularToU(u: number, v: number, options?: SheetFrameOptions): SheetFrame`
+- `framePerpendicularToV(u: number, v: number, options?: SheetFrameOptions): SheetFrame`
 - `curvatureAt(u: number, v: number): SurfaceCurvature`
+- `curveAlong(edge: SheetEdge): NurbsCurve3D`
+- `curveAlongU(v: number): NurbsCurve3D`
+- `curveAlongV(u: number): NurbsCurve3D`
+- `pathAlong(edge: SheetEdge, options?: SheetPathAlongOptions): Vec3[]`
+- `pathAlongBoundary(spans: SheetBoundaryPathSpan[], options?: SheetBoundaryPathOptions): Vec3[]`
+- `pathAlongU(v: number, options?: SheetPathAlongOptions): Vec3[]`
+- `pathAlongV(u: number, options?: SheetPathAlongOptions): Vec3[]`
 - `thicken(wall: number, options?: { resolution?: number; }): Shape`
 - `matchEdge(edge: SheetEdge): MatchEdgeBuilder`
 
+**`SheetFrameOptions`**
+- `normalOffset?: number` — Offset the frame origin along the analytic surface normal. Default 0.
+
+**`SheetPathAlongOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Samples along the path span. Default 32. |
+| `start?` | `number` | Normalized start parameter along the path. Default 0. |
+| `end?` | `number` | Normalized end parameter along the path. Default 1. |
+| `reverse?` | `boolean` | Return points from end to start after sampling the span. Default false. |
+| `normalOffset?` | `number` | Offset each path point along the analytic surface normal. Default 0. |
+
+**`SheetBoundaryPathSpan`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `edge` | `SheetEdge` | Boundary edge to sample for this span. |
+| `start?` | `SheetPathParameter` | Normalized edge parameter or world point projected to the closest edge parameter. Default 0. |
+| `end?` | `SheetPathParameter` | Normalized edge parameter or world point projected to the closest edge parameter. Default 1. |
+| `samples?` | `number` | Samples along this edge span. Defaults to options.samplesPerEdge or 32. |
+
+**`SheetBoundaryPathOptions`**
+- `samplesPerEdge?: number` — Samples for spans that do not specify their own count. Default 32.
+- `normalOffset?: number` — Offset each path point along the analytic surface normal. Default 0.
+- `tolerance?: number` — Maximum allowed gap between adjacent sampled spans. Default 1e-6.
+
 ### `MatchEdgeBuilder`
 
 - `toG0(neighbor: SheetEdge): Sheet`
@@ -1494,3 +1650,11 @@ Namespaced file-format import helpers — the single vocabulary for bringing ext
   const yUpPart = Import.mesh("./part.obj", { sourceFrame: { up: "+Y" } });
   ```
 - `step(fileName: string, options?: StepImportOptions): Shape` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend. Use `sourceFrame: { up: "+Y" }` to rotate Y-up source files into ForgeCAD's Z-up world.
+- `image(fileName: string): ImageHandle` — Import a bitmap image (PNG, JPEG, or WebP) as an ImageHandle for projected texturing. Reads the pixel dimensions from the file header and embeds the bytes as a data URI. Pass the result to `Shape.wrapTexture(image, projection)` with a `Wrap.*` projection.
+
+### `Wrap`
+
+- `flat(opts: FlatWrapOptions): UvProjectionSpec` — Project the image flat onto an axis-aligned face — `onto` is one of top/bottom/front/back/left/right. Auto-fits the face (no width/height needed).
+- `aroundCylinder(opts: CylinderWrapOptions): UvProjectionSpec` — Wrap the image around a cylinder like a can label — `axis` is 'x' | 'y' | 'z'. Auto-fits one wrap around and the full height.
+- `onSphere(opts?: SphereWrapOptions): UvProjectionSpec` — Map the image over a sphere like a globe (longitude/latitude). Auto-centers on the sphere.
+- `box(opts?: BoxWrapOptions): UvProjectionSpec` — Cube-map the image onto a box — one copy per face. Auto-fits the box (no size needed).