forgecad 0.6.3 → 0.7.0

package/dist-skill/docs-dev/generated/lib.md

@@ -0,0 +1,50 @@
+---
+skill-group: toolbox
+skill-order: 100
+---
+
+# Part Library
+
+Pre-built fasteners, gears, pipes, structural profiles, and utility shapes. Access via `lib.*`.
+
+## Contents
+
+- [lib](#lib)
+
+---
+
+## Constants
+
+### `lib`
+
+Pre-built parametric parts available in user scripts as `lib.*`. **Details** Every key in this object becomes a method on the `lib` namespace exposed to `.forge.js` scripts. The catalog includes: **Fasteners:** `bolt`, `nut`, `washer`, `fastenerSet`, `fastenerHole`, `boltHole`, `counterbore`, `hexNut`, `holePattern` **Structure:** `tube`, `pipe`, `bracket`, `pipeRoute`, `elbow`, `tSlotProfile`, `tSlotExtrusion`, `profile2020BSlot6Profile`, `profile2020BSlot6` **Threads:** `thread` **Gears:** `spurGear`, `bevelGear`, `faceGear`, `sideGear`, `ringGear`, `rackGear`, `gearPair`, `bevelGearPair`, `faceGearPair`, `sideGearPair` **Utilities:** `explode` Extend this by adding new entries here and registering the corresponding runner binding in `runner.ts`. Sizes outside the supported ranges will throw at runtime with a descriptive error.
+
+- `boltHole(diameter: number, depth: number): Shape` — Simple cylindrical through-hole cutter centered on Z=0. Subtract the result from a part to produce a plain cylindrical clearance hole. For ISO metric sizes with fit classes and counterbore/countersink, use {
+- `fastenerHole(opts: FastenerHoleOptions): Shape` — ISO metric fastener hole cutter with optional counterbore or countersink. **Details** Returns a cutter shape (subtract from a solid to produce the hole). Sizes outside M2–M10 will throw. Extend `METRIC_HOLE_TABLE` in this file to add new sizes. **Example** ```ts const plate = box(60, 40, 8, true) .subtract(lib.fastenerHole({ size: 'M5', fit: 'normal', depth: 8 }) .translate(15, 10, 4)); ```
+- `counterbore(holeDia: number, boreDia: number, boreDepth: number, totalDepth: number): Shape` — Counterbore hole cutter — through-hole with a wider cylindrical recess at the top. Use for socket-head cap screws that must sit flush. Subtract from a solid. For ISO metric sizing and fit classes, prefer {
+- `tube(outerX: number, outerY: number, outerZ: number, wall: number): Shape` — Rectangular hollow tube (thin-wall box section). Both the outer and inner boxes are centered on the XY plane with their base at Z=0.
+- `pipe(height: number, outerRadius: number, wall: number, segments?: number): Shape` — Hollow cylindrical pipe. Centered on the XY plane, extending upward along +Z from z=0 to z=height. For complex routed pipe geometry, see `lib.pipeRoute`.
+- `hexNut(acrossFlats: number, height: number, holeDia: number): Shape` — Generic hex nut with a cylindrical bore. Constructed via intersection of three rotated rectangular slabs, then a bore is subtracted. Centered at origin, height along Z. For standard ISO metric nuts by thread size, use `lib.nut` instead.
+- `bracket(width: number, height: number, depth: number, thick: number, holeDia?: number): Shape` — L-shaped mounting bracket with optional through-holes. Produces a right-angle bracket: a horizontal base plate and a vertical wall. Both legs share `width`. Optional holes are drilled through the base (along Z) and the wall (along Y).
+- `holePattern(rows: number, cols: number, spacingX: number, spacingY: number, holeDia: number, depth: number): Shape` — Rectangular grid of cylindrical hole cutters. Returns the union of `rows × cols` cylinders laid out on a regular grid. Subtract from a solid to produce the full pattern. **Example** ```ts const pattern = lib.holePattern(3, 4, 20, 20, 4, 10); const panel = box(80, 70, 10, true).subtract(pattern.translate(-30, -30, 5)); ```
+- `thread(diameter: number, pitch: number, length: number, options?: { depth?: number; segments?: number; }): Shape` — External helical thread — clean mesh, no SDF grid artifacts. **Details** Builds a cross-section with a single trapezoidal tooth from the root radius out to the crest radius, then twist-extrudes it so the tooth traces a helix. Manifold's extrude+twist produces structured quad-based geometry that follows the thread profile cleanly. Returns a threaded cylinder along +Z from z=0 to z=length. **Example** ```ts const t = lib.thread(5, 0.8, 12); // M5 × 0.8 pitch, 12 mm long ```
+- `bolt(diameter: number, length: number, options?: { ... }): Shape` — ISO-style hex bolt with real helical threads. **Details** The hex head sits from z=0 up to z=headHeight. The shaft extends downward along −Z by `length` mm. An unthreaded shank section is included when `threadLength < length`. Default proportions follow ISO 4762 loosely: pitch ≈ 0.15×diameter, head height ≈ 0.65×diameter, across-flats ≈ 1.6×diameter. For standard M-size bolts pre-configured for a complete joint, use { **Example** ```ts const b = lib.bolt(5, 20); // M5 × 20 mm ```
+- `nut(diameter: number, options?: { pitch?: number; height?: number; acrossFlats?: number; segments?: number; }): Shape` — ISO-style hex nut with a threaded bore. **Details** Constructed from the intersection of three rotated slabs with a cylindrical bore subtracted. The nut is centered at the origin, height along Z. Default proportions follow ISO 4032 loosely: height ≈ 0.8×diameter, across-flats ≈ 1.6×diameter. The bore is a clearance bore (not modelled with helical threads) for rendering efficiency. For standard M-size nuts pre-configured for a complete joint, use { **Example** ```ts const n = lib.nut(5); // M5 nut ```
+- `washer(size: MetricSize, options?: { standard?: WasherStandard; segments?: number; }): Shape` — ISO metric flat washer (DIN 125-A). **Details** Returns a flat ring centered at the origin, thickness along Z. Dimensions are taken from { **Example** ```ts const w = lib.washer('M5'); // DIN 125-A M5 washer ```
+- `fastenerSet(size: MetricSize, boltLength: number, options?: FastenerSetOptions): FastenerSetResult` — Complete ISO metric fastener set — bolt, nut, optional washers, and matching hole cutters. **Details** Returns all geometry for one bolted joint: the bolt, nut, up to two washers, a clearance-hole cutter, and a tap-drill cutter. All shapes are returned **un-positioned** (each on the Z-axis). Place them with `.translate()`. Sizes outside M4–M10 are supported for the washer (M2–M10); unsupported combinations will throw. **Example** ```ts const hw = lib.fastenerSet('M5', 20); const topPlate = box(60, 40, 8, true) .subtract(hw.clearanceHole.translate(15, 10, 0)); const botPlate = box(60, 40, 8, true).translate(0, 0, -16) .subtract(hw.tappedHole.translate(15, 10, -8)); return [ { name: 'Top Plate', shape: topPlate }, { name: 'Bot Plate', shape: botPlate }, { name: 'Bolt', shape: hw.bolt.translate(15, 10, 4) }, { name: 'Nut', shape: hw.nut.translate(15, 10, -19) }, ]; ```
+- `pipeRoute(points: [ number` — Route a pipe (solid or hollow) through 3D waypoints with smooth bends. Each interior waypoint gets a torus-section bend. Straight segments connect them. Returns a single unioned Shape.
+- `elbow(pipeRadius: number, bendRadius: number, angle?: number | { ... }, options?: { ... }): Shape` — Pipe elbow — a curved pipe section (torus arc) for connecting two pipe directions. By default creates a bend in the XZ plane: incoming along +Z, outgoing rotated by `angle`. The bend starts at the origin, curving away from it.
+- `tSlotProfile(options?: TSlotProfileOptions): Sketch` — Build a 2D T-slot cross-section sketch. Default parameters describe a 20x20 B-type profile with slot 6. Use this when you want a drawing-ready profile sketch before extrusion.
+- `tSlotExtrusion(length: number, options?: TSlotExtrusionOptions): Shape` — Build a T-slot extrusion from the generated 2D profile. Extrudes along +Z by default.
+- `profile2020BSlot6Profile(options?: Profile2020BSlot6ProfileOptions): Sketch` — Accurate-ish 2D profile for 20x20 B-type slot 6. Returns a drawing-ready Sketch centered at origin.
+- `profile2020BSlot6(length: number, options?: Profile2020BSlot6Options): Shape` — 20x20 B-type slot 6 extrusion with profile-accurate defaults. Pass option overrides if your supplier's profile differs slightly.
+- `spurGear(options: SpurGearOptions): Shape` — Involute external spur gear with optional center bore. Specify module, teeth, faceWidth as required parameters. Optional tuning includes pressureAngleDeg (default 20), backlash, clearance, addendum, dedendum, boreDiameter, and segmentsPerTooth (default 10).
+- `bevelGear(options: BevelGearOptions): Shape` — Conical bevel gear generated from a tapered involute extrusion. Specify pitchAngleDeg directly or derive it from mateTeeth + shaftAngleDeg.
+- `faceGear(options: FaceGearOptions): Shape` — Face gear (crown style) where teeth are on one face (top or bottom) instead of the outer rim. Uses the same involute tooth sizing as spurGear, then projects the tooth band axially from one side. Alias for sideGear (which is kept for backward compatibility).
+- `sideGear(options: SideGearOptions): Shape` — Crown/face style gear where the teeth project from one side of the disk instead of the outer cylindrical rim.
+- `ringGear(options: RingGearOptions): Shape` — Internal ring gear with involute-derived tooth spaces. Specify rimWidth or outerDiameter for the annular body.
+- `rackGear(options: RackGearOptions): Shape` — Linear rack gear with pressure-angle flanks. Use with spurGear for rack-and-pinion mechanisms.
+- `gearPair(options: GearPairOptions): GearPairResult` — Build or validate a spur-gear pair and return ratio, backlash, and mesh diagnostics. Accepts either shapes from spurGear() or analytical specs for each member. When place is true (default), the gear is auto-positioned at the correct center distance.
+- `bevelGearPair(options: BevelGearPairOptions): BevelGearPairResult` — Build or validate a bevel-gear pair and return ratio diagnostics plus recommended joint placement vectors.
+- `faceGearPair(options: FaceGearPairOptions): FaceGearPairResult` — Build or validate a perpendicular pair between a face gear and a vertical spur gear.
+- `sideGearPair(options: SideGearPairOptions): SideGearPairResult` — Pair helper for side (crown/face) gear + perpendicular "vertical" spur gear. Auto-placement rotates the spur around +Y and positions it to mesh at the side tooth band.

package/dist-skill/docs-dev/generated/output.md

@@ -0,0 +1,234 @@
+---
+skill-group: output
+skill-order: 100
+---
+
+# Output & Annotations
+
+Dimensions, BOM entries, verification checks, and sketch export.
+
+## Contents
+
+- [Annotations & Output](#annotations-output) — `bom`, `robotExport`, `dim`, `dimLine`
+- [Sketch Export](#sketch-export) — `sketchToDxf`, `sketchToSvg`
+
+## Functions
+
+### Annotations & Output
+
+#### `bom()` — Register a Bill of Materials entry for report export.
+
+BOM entries are accumulated during script execution and exported alongside the model in report views. Rows are grouped by normalized `description + unit`. Pass an explicit `key` to force multiple descriptions to collapse into a single line item.
+
+- `quantity` must be a finite number `>= 0`. A quantity of `0` is silently ignored (useful for conditional scripting with [`param()`](/docs/core#param)-driven counts).
+- `unit` defaults to `"pieces"` when omitted or empty.
+- The assembly `solved.bom()` / `solved.bomCsv()` API is separate and covers per-part assembly metadata; this function is for free-form purchased-item annotation.
+
+```ts
+const tubeLen = param("Tube Length", 1200, { min: 300, max: 4000, unit: "mm" });
+const boltCount = param("Bolt Count", 16, { min: 0, max: 200, integer: true });
+
+bom(tubeLen, "iron tube 30 x 20", { unit: "mm" });
+bom(boltCount, "M4 bolt, 16 mm length");
+bom(4, "rubber foot", { key: "foot-rubber" }); // explicit aggregation key
+
+// Structured metadata for richer reports:
+bom(tubeLen, "rectangular steel tube", {
+  unit: "mm",
+  material: "steel",
+  section: [30, 20],
+  wall: 3,
+});
+```
+
+```ts
+bom(quantity: number, description: string, opts?: BomOpts): void
+```
+
+**`BomOpts`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `unit?` | `string` | Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces" |
+| `key?` | `string` | Optional explicit grouping key used during report aggregation. |
+| `material?` | `string` | Material name, e.g. "steel", "birch plywood", "nylon" |
+| `dimensions?` | `number[]` | Overall dimensions `[width, height]` or `[width, height, thickness]` in the entry's unit |
+| `section?` | `number[]` | Cross-section dimensions `[w, h]` for tubes and profiles |
+| `wall?` | `number` | Wall thickness for hollow sections (mm) |
+| `diameter?` | `number` | Diameter for round stock, bolts, dowels (mm) |
+| `length?` | `number` | Length for fasteners (mm) |
+| `process?` | `string` | Manufacturing process, e.g. "laser cut", "CNC", "welded" |
+| `notes?` | `string` | Free-form notes |
+| `grain?` | `string` | Wood grain direction, e.g. "long", "cross" |
+
+#### `robotExport()` — Declare that this script should export the assembly as a SDF/URDF robot package.
+
+Call `robotExport()` alongside your assembly definition. The CLI commands `forgecad export sdf` and `forgecad export urdf` pick up the declaration and produce a robot package with:
+
+- Mesh-based inertia tensors (full 6-component, not bounding-box approximations)
+- Separate collision meshes (convex hull by default — ~50–80% smaller)
+- Joint mimic elements derived from `addJointCoupling` / `addGearCoupling`
+
+**Collision mesh modes** (set per-link via `links["PartName"].collision`):
+
+| Mode | Description | Default | |------|-------------|---------| | `'convex'` | Convex hull (separate `_collision.stl`) | Yes | | `'box'` | AABB primitive — fastest physics | | | `'visual'` | Same mesh as visual — exact but slow | | | `'none'` | No collision geometry | |
+
+**Unit conventions:**
+
+- Revolute `velocity` is in degrees/second in Forge; exporters convert to rad/s.
+- Prismatic distances are in mm in Forge; exported in meters.
+- `massKg` is preferred; `densityKgM3` is used when mass is unknown.
+- Couplings with multiple terms: only the primary term (largest ratio) maps to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
+
+```ts
+const rover = assembly("Scout")
+  .addPart("Chassis", box(300, 220, 50, true))
+  .addPart("Left Wheel", cylinder(30, 60, undefined, 48, true))
+  .addRevolute("leftWheel", "Chassis", "Left Wheel", {
+    axis: [0, 1, 0],
+    frame: Transform.identity().translate(90, 140, 60),
+    effort: 20, velocity: 1080,
+  });
+
+robotExport({
+  assembly: rover,
+  modelName: "Scout",
+  links: {
+    Chassis: { massKg: 10 },
+    "Left Wheel": { massKg: 0.8 },
+  },
+  plugins: {
+    diffDrive: {
+      leftJoints: ["leftWheel"], rightJoints: ["rightWheel"],
+      wheelSeparationMm: 280, wheelRadiusMm: 60,
+    },
+  },
+  world: { generateDemoWorld: true },
+});
+```
+
+**CLI usage**
+
+```bash
+forgecad export sdf model.forge.js   # SDF package (Gazebo/Ignition)
+forgecad export urdf model.forge.js  # URDF package (ROS/PyBullet/MuJoCo)
+```
+
+```ts
+robotExport(options: RobotExportOptions): CollectedRobotExport
+```
+
+**`RobotExportOptions`**: `assembly: Assembly`, `modelName?: string`, `state?: JointState`, `static?: boolean`, `selfCollide?: boolean`, `allowAutoDisable?: boolean`, `links?: Record<string, RobotLinkExportOptions>`, `joints?: Record<string, RobotJointExportOptions>`, `diffDrive?: RobotDiffDrivePluginOptions`, `jointStatePublisher?: RobotJointStatePublisherOptions`, `world?: RobotWorldOptions`
+
+`RobotLinkExportOptions`: `{ massKg?: number, densityKgM3?: number, collision?: "visual" | "convex" | "box" | "none" }`
+
+`RobotJointExportOptions`: `{ effort?: number, velocity?: number, damping?: number, friction?: number }`
+
+**`RobotDiffDrivePluginOptions`**: `leftJoints: string[]`, `rightJoints: string[]`, `wheelSeparationMm: number`, `wheelRadiusMm: number`, `topic?: string`, `odomTopic?: string`, `tfTopic?: string`, `frameId?: string`, `odomFrameId?: string`, `maxLinearVelocity?: number`, `maxAngularVelocity?: number`, `linearAcceleration?: number`, `angularAcceleration?: number`
+
+`RobotJointStatePublisherOptions`: `{ enabled?: boolean, joints?: string[], topic?: string, updateRate?: number }`
+
+`RobotWorldOptions`: `{ name?: string, generateDemoWorld?: boolean, spawnPose?: RobotPose6, keyboardTeleop?: RobotWorldKeyboardTeleopOptions }`
+
+`RobotWorldKeyboardTeleopOptions`: `{ enabled?: boolean, linearStep?: number, angularStep?: number }`
+
+**`CollectedRobotExport`**: `modelName: string`, `assembly: AssemblyDefinition`, `state: JointState`, `static: boolean`, `selfCollide: boolean`, `allowAutoDisable: boolean`, `links: Record<string, RobotLinkExportOptions>`, `joints: Record<string, RobotJointExportOptions>`, `diffDrive?: RobotDiffDrivePluginOptions`, `jointStatePublisher?: RobotJointStatePublisherOptions`, `world: RobotWorldOptions | null`
+
+`AssemblyDefinition`: `{ name: string, parts: AssemblyPartDef[], joints: AssemblyJointDef[], jointCouplings: AssemblyJointCouplingDef[] }`
+
+`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
+
+**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
+
+**`AssemblyJointDef`**: `name: string`, `type: JointType`, `parent: string`, `child: string`, `frame: Transform`, `axis: Vec3`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`
+
+`AssemblyJointCouplingDef`: `{ joint: string, terms: JointCouplingTermRecord[], offset: number }`
+
+`JointCouplingTermRecord`: `{ joint: string, ratio: number }`
+
+#### `dim()` — Add a dimension annotation between two points.
+
+Dimension annotations are purely visual callouts rendered in the viewport and report export. They do not affect geometry or constrain the model.
+
+Point arguments accept 2D tuples `[x, y]`, 3D tuples `[x, y, z]`, or [`Point2D`](/docs/sketch#point2d) objects (Z is treated as 0 for 2D inputs).
+
+**Ownership Rules (Report Pages)**
+
+- `currentComponent: true` — deterministic ownership by the calling import instance. Use when authoring reusable imported parts.
+- `component: "Part Name"` — route dimension to another named returned object.
+- Multiple owners: dimension is shared and appears on the assembly overview page.
+- No ownership set: report export infers ownership via endpoint-in-bbox.
+
+```ts
+dim([-w / 2, 0, 0], [w / 2, 0, 0], { label: "Width" });
+dim([0, 0, -h / 2], [0, 0, h / 2], { label: "Height", offset: 14 });
+dim([0, 0, 0], [100, 0, 0], { component: "Base", color: "#00AAFF" });
+```
+
+`component` (string or string[] — report ownership), `currentComponent` (boolean)
+
+```ts
+dim(from: PointArg, to: PointArg, opts?: DimOpts): void
+```
+
+`DimOpts`: `{ offset?: number, label?: string, color?: string, component?: string | string[], currentComponent?: boolean }`
+
+#### `dimLine()` — Add a dimension annotation along a [`Line2D`](/docs/sketch#line2d).
+
+Convenience wrapper around { points from a constrained-sketch [`Line2D`](/docs/sketch#line2d) entity. All `opts` are forwarded unchanged.
+
+```ts
+const a = point(0, 0);
+const b = point(100, 0);
+dimLine(line(a, b), { label: "Span", offset: -8 });
+```
+
+```ts
+dimLine(l: Line2D, opts?: DimOpts): void
+```
+
+### Sketch Export
+
+#### `sketchToDxf()` — Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible).
+
+For regular sketches, each polygon loop becomes a closed `LWPOLYLINE`. For constrained sketches, exports raw `LINE`, `CIRCLE`, and `ARC` entities from the constraint edge geometry, which preserves internal/shared edges that `toPolygons()` would merge away.
+
+The R12 format is chosen for maximum compatibility with CAM tools, laser-cutter software, and older CAD readers.
+
+```ts
+const s = rect(100, 60);
+const dxf = sketchToDxf(s, { layer: 'cut' });
+```
+
+```ts
+sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
+```
+
+**`SketchDxfOptions`**
+- `layer?: string` — DXF layer name. Default: "0"
+- `colorIndex?: number` — DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black)
+
+#### `sketchToSvg()` — Export a 2D sketch as an SVG string.
+
+For regular sketches, exports filled polygon regions. For constrained sketches, exports raw edge geometry (LINE, ARC, CIRCLE) which preserves internal/shared edges that `toPolygons()` would merge away.
+
+The SVG uses the sketch's native coordinate system (Y-up) with a CSS transform that flips Y so the output renders correctly in SVG's Y-down space. Coordinates are in sketch units (typically mm).
+
+```ts
+const s = rect(100, 60);
+const svg = sketchToSvg(s, { stroke: '#333', strokeWidth: 0.8 });
+```
+
+```ts
+sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
+```
+
+**`SketchSvgOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `stroke?` | `string` | Stroke color. Default: "black" |
+| `strokeWidth?` | `number` | Stroke width in sketch units. Default: 0.5 |
+| `fill?` | `string` | Fill color. Default: "none" |
+| `padding?` | `number` | Padding around the sketch bounding box in sketch units. Default: 2 |
+| `pixelsPerUnit?` | `number` | If set, scale so 1 sketch-unit = this many px. Otherwise auto-fit. |