forgecad 0.6.3 → 0.8.0

package/dist-skill/docs/API/output/brep-export.md

@@ -1,87 +0,0 @@
----
-skill-group: output
-skill-order: 2
-skill-tiers: [standard]
----
-
-# BREP Export Parity
-
-This file tracks exact STEP/BREP export support. It is intentionally separated from the model-building docs because it describes output coverage, not the authoring surface itself.
-
-This table is the source of truth for ForgeCAD exact STEP/BREP export support.
-
-Update it whenever:
-- a Forge operation becomes exactly exportable
-- support becomes partial or regresses
-- a planned feature moves to implemented
-
-## Current Backend
-
-- Export executor: `uv run cli/forge-brep-export.py`
-- Compiler target: `cadquery-occt`
-- Exact kernel backend: CadQuery on OpenCascade
-- Default export policy: exact-subset only, never silent mesh-to-fake-BREP conversion
-- Optional CLI fallback: `--allow-faceted` exports closed mesh solids as explicit faceted OCCT solids for STEP/BREP; this is not exact replay
-
-## Parity Table
-
-| Forge Feature | Status | Exact Export | Notes |
-| --- | --- | --- | --- |
-| `box()` | Supported | Yes | Native OCCT solid replay |
-| `cylinder()` | Supported | Yes | Straight cylinder and cone-style `radiusTop` replay |
-| `sphere()` | Supported | Yes | Native OCCT solid replay |
-| `rect()` | Supported | Yes | As a profile for supported extrude/revolve flows |
-| `circle2d()` | Supported | Yes | As a profile for supported extrude/revolve flows |
-| `roundedRect()` | Supported | Yes | Replayed as an exact rounded wire/profile |
-| `rect(...).translate()` | Supported | Yes | Recorded as profile transforms |
-| `circle2d(...).translate()` | Supported | Yes | Recorded as profile transforms |
-| `roundedRect(...).translate()` | Supported | Yes | Recorded as profile transforms |
-| `rect(...).rotate()` | Supported | Yes | Recorded as profile transforms |
-| `circle2d(...).rotate()` | Supported | Yes | Recorded as profile transforms |
-| `roundedRect(...).rotate()` | Supported | Yes | Recorded as profile transforms |
-| `rect/circle/roundedRect.scale(...)` | Supported | Yes | Recorded as exact affine profile transforms |
-| `polygon()` / `ngon()` / polygon-backed `ellipse()` / `star()` | Supported | Yes | Replayed as exact line-segment profiles from recorded point loops |
-| `slot()` | Supported | Yes | Built from exact rect/circle booleans |
-| Sketch booleans (`union2d`, `difference2d`, `intersection2d`) | Supported | Yes | Only when every child profile is exact-exportable |
-| `rect/circle/roundedRect.extrude(height)` | Supported | Yes | `twist` / `divisions` must be absent |
-| `rect/circle/roundedRect.extrude(height, { scaleTop })` | Supported | Yes | Replayed as exact lofts; sketch booleans are decomposed into 3D booleans when needed |
-| `rect/circle/roundedRect.revolve(degrees)` | Supported | Yes | Replayed around Forge's revolve axis convention |
-| `Sketch.offset(delta, 'Round')` | Partial | Yes | Exact round-offset replay for exact-exportable profiles; `Square` / `Miter` still drop the plan |
-| `shape.translate()` | Supported | Yes | Recorded as exact solid transform |
-| `shape.rotate(x, y, z)` | Supported | Yes | Euler replay only |
-| `shape.scale(v)` | Supported | Yes | Recorded as an exact affine solid transform when every scale factor is finite and non-zero |
-| `rotateAround(...)` | Supported | Yes | Exact arbitrary-axis rotation is recorded with axis + pivot |
-| `pointAlong(...)` | Supported | Yes | Replayed via exact arbitrary-axis rotation from Forge's +Z axis |
-| `mirror(...)` | Supported | Yes | Replayed as an exact mirror transform across the origin plane normal |
-| `Shape.transform(matrix)` | Partial | Yes | Rigid affine subset only: orthonormal rotation + translation; scale/shear/perspective still unsupported |
-| `union()` | Supported | Yes | Only when every operand is exact-exportable |
-| `difference()` | Supported | Yes | Only when every operand is exact-exportable |
-| `intersection()` | Supported | Yes | Only when every operand is exact-exportable |
-| `split(cutter)` | Supported | Yes | Replayed as the exact pair `intersection(base, cutter)` and `difference(base, cutter)` when both operands are exact-exportable |
-| Returned multi-object scene | Supported | Yes | Exported as a STEP/BREP compound |
-| Returned mixed sketch + solid scene | Supported | Yes | Exact solids export; sketch-only objects are skipped with a warning |
-| Sketch `mirror()` | Supported | Yes | Recorded as an exact profile reflection across the origin line normal |
-| `loft()` | Partial | Yes | Forge now records loft intent in the compile graph and exports compatible section stacks through CadQuery/OCCT lofting, but runtime preview remains sampled/level-set and some mixed-topology stacks can still exceed OCCT loft compatibility |
-| `sweep()` | Partial | Yes | Forge now records sweep intent in the compile graph and exports compile-covered profiles along the canonical sampled polyline path; runtime preview remains sampled/level-set and `Curve3D` paths export through that sampled path representation |
-| `levelSet()` | Unsupported | No | Mesh/SDF output by design |
-| `smoothOut()` / `refine*()` / `simplify()` | Unsupported | No | Mesh post-processing, not exact BREP |
-| `warp()` | Unsupported | No | Deformation is mesh-domain today |
-| `trimByPlane()` / `splitByPlane()` | Supported | Yes | Replayed through an exact plane half-space trim in CadQuery/OCCT; `splitByPlane()` lowers to the pair of positive-side and opposite-side trims |
-| `Shape.hole()` | Partial | Yes | Circular through/blind holes plus counterbores, countersinks, and planar `upToFace` termination on supported face-query targets now replay exactly; patterned, drafted/two-sided, threaded, and combined counterbore+countersink workflows are still outside the defended subset |
-| `Shape.cutout()` | Partial | Yes | Sketch must already be placed with `onFace(...)`; blind/through and planar `upToFace` cut extents on defended face-query targets stay exact, but drafted, two-sided, and pattern-owned cut workflows are still unsupported |
-| `sheetMetal(...).folded()` / `sheetMetal(...).flatPattern()` | Supported | Yes | Compiler-owned v1 sheet-metal subset: base panel, up to four `90°` edge flanges, explicit thickness/radius/K-factor, rectangular corner reliefs, and planar panel/flange cutouts all replay exactly from one semantic model; arbitrary solid conversion, hems, jogs, lofted bends, bend cutouts, and nonuniform thickness remain unsupported |
-| `projectToPlane()`-driven downstream features | Partial | Yes | Exact replay is supported when the source reduces to one defended planar basis: straight placed extrusions, compatible shell/hole/cut descendants, and compatible boolean unions on matching parallel target planes; boolean difference/intersection, trim/fillet/chamfer silhouette changes, and non-parallel bases still reject with diagnostics |
-| `Shape.shell(thickness, { openFaces })` | Partial | Yes | Compiler-owned shell v1 rewrites compatible `box()`, `cylinder()`, and straight `extrude()` bases plus rigid transforms into exact boolean/extrude/cylinder plans; tapered extrudes, scale transforms, and general boolean/revolve/loft/sweep/trim bases are still unsupported |
-| `filletEdge()` / `chamferEdge()` | Partial | Yes | Compiler-owned tracked-edge subset: vertical edges from compile-covered `box()` bodies and `rectangle(...).extrude(...)` flows, plus preserved propagated sibling edges after earlier supported edge-finish rewrites when a later supported boolean union still records one defended lineage; shell, hole/cut, boolean difference/intersection, unsupported unions, and the already-finished merged edge itself are still outside the defended exact subset |
-| `TrackedShape` topology preservation | Partial | Synthetic only | Export succeeds for supported base solids, but named topology is not written to STEP/BREP |
-| Colors/materials in STEP/BREP | Partial | STEP only | Scene-object colors are written to STEP via CadQuery assembly export; `.brep` remains geometry-only |
-| STEP assembly structure/BOM metadata | Partial | Names only | STEP export writes a flat scene-object assembly to preserve names/colors; Forge assembly/BOM metadata is still not exported |
-
-The current defended exact subset is exercised by the ordinary-parts corpus in [`examples/compiler-corpus/README.md`](../../../../examples/compiler-corpus/README.md).
-
-## Planned Expansion Order
-
-1. Exact provenance-preserving replay for library helpers such as `lib.elbow()`, `lib.bolt()`, and related fastener/tube builders
-2. Safe exact affine scale replay where OCCT can preserve exact solids, especially scaled-sphere / pad workflows
-3. Broader exact OCCT-native feature coverage where BREP matters most: wider `shell()` coverage, broader fillet/chamfer coverage, richer face-driven feature ops
-4. Optional STEP product structure and metadata export

package/dist-skill/docs/API/output/dimensions.md

@@ -1,67 +0,0 @@
----
-skill-group: output
-skill-order: 4
----
-
-# Dimension Annotations
-
-Dimension annotations are visual callouts used in the viewport and report export.
-They are not constraints and do not change geometry, so they live outside the core model-building docs.
-
-## `dim(from, to, opts?)`
-
-Add a dimension between two points.
-
-**Parameters:**
-- `from` (`[number, number] | [number, number, number] | Point2D`)
-- `to` (`[number, number] | [number, number, number] | Point2D`)
-- `opts` (optional):
-  - `offset` (number, default `10`)
-  - `label` (string)
-  - `color` (string hex, for example `"#ffaa44"`)
-  - `component` (`string | string[]`) - explicit report ownership by returned object name
-  - `currentComponent` (boolean) - bind to the owning returned component instance
-
-```javascript
-const w = 120;
-const h = 60;
-const plate = box(w, 30, h, true);
-
-dim([-w / 2, 0, 0], [w / 2, 0, 0], { label: "Width" });
-dim([0, 0, -h / 2], [0, 0, h / 2], { label: "Height", offset: 14 });
-
-return plate;
-```
-
-Ownership examples:
-
-```javascript
-dim([0, 0, 0], [0, 80, 0], {
-  label: "Leg Width",
-  currentComponent: true,
-});
-
-dim([0, 0, 0], [0, 0, 18], {
-  label: "Top Gap",
-  component: "Tabletop",
-});
-```
-
-## `dimLine(line, opts?)`
-
-Add a dimension along a `Line2D`.
-
-```javascript
-const a = point(0, 0);
-const b = point(100, 0);
-dimLine(line(a, b), { label: "Span", offset: -8 });
-```
-
-## Ownership Rules (Report Pages)
-
-- Use `currentComponent: true` when authoring imported parts and you want deterministic ownership by the calling instance.
-- Use `component: "Part Name"` to route a dimension to another named returned object.
-- If multiple owners are bound, the dimension is shared and appears on the assembly overview page.
-- If no ownership is set, report export attempts automatic ownership via endpoint-in-bbox inference.
-
-See `examples/api/dimensioned-bracket.forge.js` for baseline usage.

package/dist-skill/docs/API/output/export.md

@@ -1,110 +0,0 @@
----
-skill-group: output
-skill-order: 1
----
-
-# Mesh Export
-
-ForgeCAD supports exporting 3D geometry to several mesh formats. Export is available both from the CLI and programmatically in the browser.
-
-## CLI Export
-
-The CLI provides the primary export workflow. See [`../../cli.md`](../../cli.md) for full details.
-
-```bash
-# STL export (binary)
-forgecad export stl model.forge.js -o output.stl
-
-# 3MF export (with colors and metadata)
-forgecad export 3mf model.forge.js -o output.3mf
-
-# STEP/BREP export (exact geometry via OCCT)
-forgecad export step model.forge.js -o output.step
-forgecad export brep model.forge.js -o output.brep
-```
-
-## Browser-Side Export Functions
-
-These functions are available in the browser runtime for programmatic export. They operate on mesh data and return binary buffers.
-
-### `buildBinaryStl(objects)`
-
-Generate a binary STL file from an array of shape objects.
-
-**Parameters:**
-- `objects` — Array of `{ name: string, shape: Shape, color?: string }`
-  - `color` is a hex string (`'#RRGGBB'`) for per-object coloring
-
-**Returns:** `ArrayBuffer` — Binary STL data
-
-> **Callout:** STL supports per-facet color via the legacy VisCAM/SolidView RGB555 convention (bit 15 flag). Not all slicers read this — for reliable color export, prefer 3MF.
-
-### `build3mfBuffer(objects, options?)`
-
-Generate a 3MF archive from an array of shape objects. 3MF is the recommended format for 3D printing — it preserves colors, metadata, and multiple objects in a single file.
-
-**Parameters:**
-- `objects` — Array of `{ name: string, shape: Shape, color?: string }`
-- `options` (optional):
-  - `title` (string) — Metadata title. Default: `'ForgeCAD model'`
-  - `application` (string) — Application name. Default: `'ForgeCAD'`
-  - `description` (string) — Metadata description. Default: same as title
-
-**Returns:** `Promise<Uint8Array>` — 3MF archive as binary data
-
-> **Callout:** This is a pure JavaScript implementation — no native dependencies needed. Colors are encoded as 3MF material resources with automatic grouping to minimize file size.
-
-## 2D Sketch Export
-
-Sketches can be exported to vector formats:
-
-### `sketchToSvg(sketch, options?)`
-
-Export a 2D sketch to an SVG string.
-
-### `sketchToDxf(sketch, options?)`
-
-Export a 2D sketch to a DXF string.
-
-See the auto-generated [API reference](../../generated/api-reference.md) for full signatures.
-
-## G-code Toolpath Export
-
-ForgeCAD also supports direct G-code authoring for FDM printing by returning a `GCodeBuilder` from a `.forge.js` script.
-
-This is a separate workflow from mesh export:
-- mesh export: model geometry, then slice elsewhere
-- G-code mode: script the toolpaths directly
-
-Use `forgecad export gcode script.forge.js -o output.gcode` for machine output.
-
-See [`gcode.md`](gcode.md) for the dedicated G-code mode guide, including:
-- the `gcode(profile?)` factory
-- the full `GCodeBuilder` API
-- viewport behavior
-- limitations and safety notes
-- recommended authoring patterns for continuous and non-planar prints
-
-## Robot Export (SDF / URDF)
-
-Assemblies with `robotExport({...})` can be exported as simulation-ready packages. See the [Assembly docs](../assembly/assembly.md#robot-export) for the full `robotExport()` API.
-
-```bash
-# SDF package (Gazebo/Ignition)
-forgecad export sdf model.forge.js [--output dir]
-
-# URDF package (ROS / PyBullet / MuJoCo)
-forgecad export urdf model.forge.js [--output dir]
-```
-
-Both formats produce:
-- Per-link STL meshes (visual + separate collision meshes)
-- Inertia tensors computed from actual mesh geometry
-- Joint limits, dynamics, and mimic (from joint couplings)
-- Manifest JSON with link/joint mappings
-
-SDF additionally supports: demo world generation, diff-drive plugin, joint state publisher, keyboard teleop.
-
-## Exact Geometry Export (STEP/BREP)
-
-For exact geometry (no tessellation), ForgeCAD uses the OCCT backend. See [`brep-export.md`](brep-export.md) for the parity matrix showing which operations produce exact vs. mesh geometry.

package/dist-skill/docs/API/output/gcode.md

@@ -1,195 +0,0 @@
-# G-code Toolpath Mode
-
-ForgeCAD can generate FDM G-code directly by returning a `GCodeBuilder` from a `.forge.js` script.
-
-This is a toolpath authoring surface, not a slicer.
-
-Use it when you want:
-- continuous spiral paths
-- non-planar or mathematically defined surfaces
-- lattice / string / ornamental structures that are really "paths in space"
-- direct control of speed, fan, travel, and extrusion sequencing
-
-Do not use it when you want automatic perimeters, infill, supports, or ordinary part slicing. Export STL or 3MF and use a slicer for that workflow.
-
-## Workflow
-
-1. Write a `.forge.js` script that creates a builder with `gcode(...)`.
-2. Emit moves with `travelTo(...)` and `extrudeTo(...)`.
-3. `export default g;`
-4. Validate with:
-
-```bash
-forgecad run script.forge.js
-```
-
-5. Export machine code with:
-
-```bash
-forgecad export gcode script.forge.js -o output.gcode
-```
-
-When a script returns a `GCodeBuilder`, ForgeCAD's interactive viewport renders the toolpath as colored line segments:
-- extrusion moves: green to red by speed
-- travel moves: translucent blue
-
-Current limitation:
-- `forgecad render ...` currently expects shape outputs and does not render `GCodeBuilder` scenes to PNG. Use the interactive viewport for visual inspection and `forgecad export gcode` for final output.
-
-## `gcode(profile?)`
-
-Factory function available as a global in `.forge.js` scripts.
-
-```js
-const g = gcode({ nozzle: 0.4, layerHeight: 0.2 });
-```
-
-### `PrinterProfile`
-
-| Field | Meaning | Default |
-| --- | --- | --- |
-| `bedX` | Bed width in mm | `220` |
-| `bedY` | Bed depth in mm | `220` |
-| `bedZ` | Max build height in mm | `250` |
-| `nozzle` | Nozzle diameter in mm | `0.4` |
-| `filament` | Filament diameter in mm | `1.75` |
-| `layerHeight` | Extrusion height used for bead-area math | `0.2` |
-| `printSpeed` | Default print speed in mm/min | `1800` |
-| `travelSpeed` | Travel speed in mm/min | `7200` |
-| `retractionDistance` | Retraction distance in mm | `1.0` |
-| `retractionSpeed` | Retraction speed in mm/min | `2700` |
-
-Important:
-- bed dimensions are currently profile metadata only; the builder does not clamp or reject out-of-bounds moves
-- temperatures passed to `preheat()` are emitted directly; there is no printer-specific safety layer
-
-## Builder API
-
-### Movement
-
-| Method | Meaning |
-| --- | --- |
-| `travelTo(x, y, z)` | Retract if needed, then move without extrusion |
-| `travelBy(dx, dy, dz)` | Relative travel |
-| `extrudeTo(x, y, z)` | Unretract if needed, then extrude to an absolute point |
-| `extrudeBy(dx, dy, dz)` | Relative extrusion |
-
-### Configuration
-
-| Method | Meaning |
-| --- | --- |
-| `setSpeed(mmPerSec)` | Set print speed in mm/s |
-| `setSpeedMmMin(mmPerMin)` | Set print speed in mm/min |
-| `setLayerHeight(mm)` | Change the layer height used for subsequent extrusion math |
-| `setFan(speed)` | Set part cooling fan, either `0..255` or `0.0..1.0` |
-| `fanOff()` | Turn fan off |
-
-### Start / End
-
-| Method | Meaning |
-| --- | --- |
-| `preheat({ hotend?, bed? })` | Emit units, absolute modes, heat, wait, home, and extruder reset |
-| `cooldown()` | Emit retract, cool-down, presentation move, and motor disable |
-
-### Raw / Query / Output
-
-| Method | Meaning |
-| --- | --- |
-| `comment(text)` | Insert a G-code comment |
-| `raw(line)` | Insert raw G-code text |
-| `getPosition()` | Return current `[x, y, z]` |
-| `build()` | Return `ToolpathData` with segments, bounds, estimates, and raw G-code |
-| `toGCode()` | Return the raw G-code string |
-
-## Behavioral Notes
-
-- `travelTo(...)` records a travel segment only after the first explicit move. The initial move from home to your start point is intentionally not rendered as a line from `[0, 0, 0]`.
-- `extrudeTo(...)` computes extrusion from traveled distance using a simple bead-area model:
-
-```text
-E increment = (layerHeight * nozzle * moveDistance) / filamentCrossSectionArea
-```
-
-- `setLayerHeight(...)` affects only future extrusion calculations. It does not retroactively change prior moves.
-- `raw(...)` and `comment(...)` modify the emitted G-code text, but they do not create viewport segments or contribute to the builder's time / bounds estimates.
-- The exported stats shown by `forgecad export gcode` are derived from tracked travel/extrude segments. They do not include heater wait time or arbitrary raw commands.
-
-## Recommended Authoring Patterns
-
-### 1. Start with an adhesion strategy
-
-Direct G-code mode does not generate first layers for you. If the piece needs a base disc, raft-like pad, or anchoring lines, script them explicitly.
-
-### 2. Prefer continuous paths
-
-The most compelling results usually come from one long extrusion path or a very small number of travels. This reduces seams and makes the piece feel intentionally "computed" instead of sliced.
-
-### 3. Keep Z changes smooth
-
-Non-planar toolpaths are the point of this mode, but abrupt Z jumps can become collisions or under-extrusion in the real machine. Bias toward gradual ramps and dense sampling.
-
-### 4. Treat speed and fan as part of the design
-
-These scripts control process behavior directly. Slow first layers, selective fan increases, and lower speeds on steep or delicate regions are part of the model, not post-processing.
-
-### 5. Stay inside your printer envelope yourself
-
-ForgeCAD stores bed dimensions in the profile, but the builder does not currently enforce bounds, acceleration limits, temperature caps, or nozzle-clearance safety.
-
-## Example
-
-```js
-const radius = 24;
-const height = 42;
-const layerHeight = 0.22;
-
-const g = gcode({ nozzle: 0.4, layerHeight, printSpeed: 1800 });
-const cx = 110;
-const cy = 110;
-
-g.preheat({ hotend: 205, bed: 55 });
-g.setFan(0);
-
-// Small spiral base
-g.travelTo(cx + 0.4, cy, layerHeight);
-g.setSpeed(16);
-for (let i = 0; i <= 1200; i += 1) {
-  const u = i / 1200;
-  const angle = u * Math.PI * 18;
-  const r = 0.4 + u * radius;
-  g.extrudeTo(cx + r * Math.cos(angle), cy + r * Math.sin(angle), layerHeight);
-}
-
-// Continuous sculpted wall
-g.setFan(1);
-g.setSpeed(30);
-const stepsPerTurn = 160;
-const totalSteps = Math.floor((height / layerHeight) * stepsPerTurn);
-for (let i = 0; i <= totalSteps; i += 1) {
-  const t = i / totalSteps;
-  const angle = (i / stepsPerTurn) * Math.PI * 2;
-  const r = radius * (1 - 0.15 * t) + 4 * Math.sin(5 * angle - 8 * t);
-  g.extrudeTo(
-    cx + r * Math.cos(angle),
-    cy + r * Math.sin(angle),
-    layerHeight + t * (height - layerHeight),
-  );
-}
-
-g.cooldown();
-
-export default g;
-```
-
-## Examples To Reuse
-
-- `examples/gcode/parametric-vase.forge.js`
-- `examples/gcode/spiral-tower.forge.js`
-- `examples/gcode/math-surface.forge.js`
-- `examples/gcode/lissajous-vase.forge.js`
-
-## Related Docs
-
-- [`../../CLI.md`](../../CLI.md) for the `forgecad export gcode` command
-- [`export.md`](export.md) for the broader export surface
-- [`brep-export.md`](brep-export.md) for exact STEP/BREP export, which is a separate workflow entirely