forgecad 0.10.0 → 0.10.1

package/dist-skill/docs/generated/runtime-names.md

@@ -26,10 +26,10 @@ Point2D, Points, polygon, polygonVertices, port, Product, ProductPanelBuilder, P
 ProductSkin, ProductSkinBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask, rect
 Rectangle2D, robotExport, roundedRect, Route3D, scene, Sculpt, sdf, SdfShape
 selectEdge, selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shape
-ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sketch, sketchToDxf, sketchToSvg, slot
-SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody, SurfaceMembers
-sweep, text2d, textWidth, torus, toShape, Transform, union, union2d
-variableSweep, verify, Viewport, window, Wood
+ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg
+slot, SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody
+SurfaceMembers, sweep, text2d, textWidth, torus, toShape, Transform, union
+union2d, variableSweep, verify, Viewport, window, Wood
 ```
 
 `showLabels` is also a runtime global, but it is not part of the top-level collision check. Avoid reusing it unless you intentionally want a local value with that name.

package/examples/robotics/README.md

@@ -0,0 +1,46 @@
+# Robotics And SimReady Examples
+
+These examples show the current ForgeCAD simulation contract: physical parts use `Sim.body(...)`, joints carry drive intent, and the returned assembly finishes with `withSimulation(...)`.
+
+Run commands from the ForgeCAD repo root with the local CLI:
+
+```bash
+node dist-cli/forgecad.js check simready examples/robotics/simready-diff-drive-rover.forge.js
+node dist-cli/forgecad.js export mjcf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/forgecad-rover-mjcf
+```
+
+## Examples
+
+| Example | File | What It Proves |
+|---------|------|----------------|
+| Diff-drive rover | `simready-diff-drive-rover.forge.js` | Robot-body profile, wheel contact surfaces, velocity drives, and diff-drive controller metadata |
+| Parallel gripper | `simready-parallel-gripper.forge.js` | Prismatic joints, passive dynamics, and gripper contact-surface metadata |
+| Asset crate | `simready-asset-crate.forge.js` | One-part asset assembly with physical material, collider, and grasp-ready contact metadata |
+| Scout cam rover | `scout-cam-rover-simready/main.forge.js` | Larger copied robot with MJCF, SDF, URDF, MuJoCo smoke motion, starter Gym env, balance training, and push playback |
+
+## Minimum Workflow
+
+```bash
+node dist-cli/forgecad.js run examples/robotics/simready-diff-drive-rover.forge.js
+node dist-cli/forgecad.js check simready examples/robotics/simready-diff-drive-rover.forge.js
+node dist-cli/forgecad.js export mjcf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/forgecad-rover-mjcf
+```
+
+The MJCF export writes a runnable MuJoCo package with `scene.xml`, `manifest.json`, `simready-manifest.json`, and starter Python scripts.
+
+```bash
+cd /tmp/forgecad-rover-mjcf
+uv run --python 3.11 --with mujoco --with pillow python scripts/smoke_control.py --render-gif drive.gif
+```
+
+The smaller examples are meant to be readable API references. The Scout example is the end-to-end simulator workflow.
+
+## Picking The Right Example
+
+Use `simready-diff-drive-rover.forge.js` when you want the smallest robot that proves the full controller/export path.
+
+Use `simready-parallel-gripper.forge.js` when you care about manipulators, fingertips, or grasp-readiness metadata.
+
+Use `simready-asset-crate.forge.js` when the object is not a robot but still needs physical material, collision, and contact metadata.
+
+Use `scout-cam-rover-simready/` when you want MuJoCo scripts, generated package structure, GIF output, and a realistic source-authored robot example.

package/examples/robotics/scout-cam-rover-simready/README.md

@@ -0,0 +1,119 @@
+# Scout Cam Rover SimReady Example
+
+This is a copied, source-authored simulation version of the personal Scout Cam Rover model. The `.forge.js` file returns the normal assembly, and the same assembly carries the simulation contract through `withSimulation(...)`.
+
+## What Is Sim-Ready Here
+
+- Every assembly part has `Sim.body(...)` metadata with mass, physical material, and collision intent.
+- The TPU tires expose connector-based wheel contact surfaces through `Sim.contact.wheelSurface("tread")`.
+- The two wheel joints have velocity drive intent through `Sim.drive.velocity(...)`.
+- The root assembly uses `withSimulation(...)` with a `Sim.controller.diffDrive(...)` controller.
+- SDF export emits a Gazebo Sim DiffDrive plugin that listens on `/model/scout_cam_rover/cmd_vel`.
+
+## Local Checks
+
+Run from the ForgeCAD repo root:
+
+```bash
+node dist-cli/forgecad.js run examples/robotics/scout-cam-rover-simready/main.forge.js
+node dist-cli/forgecad.js check simready examples/robotics/scout-cam-rover-simready/main.forge.js
+node dist-cli/forgecad.js export mjcf examples/robotics/scout-cam-rover-simready/main.forge.js --output /tmp/scout-cam-rover-mjcf
+node dist-cli/forgecad.js export sdf examples/robotics/scout-cam-rover-simready/main.forge.js --output /tmp/scout-cam-rover-sdf
+node dist-cli/forgecad.js export urdf examples/robotics/scout-cam-rover-simready/main.forge.js --output /tmp/scout-cam-rover-urdf
+```
+
+The MJCF package is written to:
+
+```text
+/tmp/scout-cam-rover-mjcf/scout_cam_rover.xml
+/tmp/scout-cam-rover-mjcf/scene.xml
+/tmp/scout-cam-rover-mjcf/scripts/gym_env.py
+/tmp/scout-cam-rover-mjcf/scripts/smoke_control.py
+/tmp/scout-cam-rover-mjcf/scripts/train_balance.py
+/tmp/scout-cam-rover-mjcf/scripts/play_balance.py
+/tmp/scout-cam-rover-mjcf/simready-manifest.json
+```
+
+The SDF package is written to:
+
+```text
+/tmp/scout-cam-rover-sdf/models/scout_cam_rover/model.sdf
+/tmp/scout-cam-rover-sdf/simready-manifest.json
+```
+
+The URDF package is written to:
+
+```text
+/tmp/scout-cam-rover-urdf/scout_cam_rover.urdf
+/tmp/scout-cam-rover-urdf/simready-manifest.json
+```
+
+## Moving It In A Simulator
+
+The fastest local path is MuJoCo. The MJCF export includes a runnable scene and a package-local smoke controller that discovers the exported actuator names from `manifest.json`.
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with pillow python scripts/smoke_control.py --render-gif drive.gif
+```
+
+That command compiles the generated `scene.xml`, commands the wheel velocity actuators, prints a motion summary, and writes `/tmp/scout-cam-rover-mjcf/drive.gif`.
+The generated smoke controller calibrates the diff-drive motor signs inside MuJoCo before it commands semantic forward/turn/reverse motion, so mirrored wheel axes do not require hand-flipped script edits.
+
+The MJCF package also includes a small Gymnasium control lab and starter balance trainer:
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with numpy --with gymnasium --with pillow python scripts/train_balance.py --render-gif balance.gif --fps 10
+```
+
+That writes `policies/balance_linear.json` and `balance.gif`. The trainer is intentionally editable Python boilerplate: ForgeCAD wires the model, actuators, calibrated diff-drive semantics, and observation plumbing; the reward, policy class, curriculum, and RL library choice stay outside the CAD API.
+The GIF duration is controlled by both the simulated `--seconds` value and the rendered `--fps`; 10 FPS maps to a clean 100 ms GIF frame delay in common viewers.
+
+After training, push the policy with an external force pulse:
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with numpy --with gymnasium --with pillow python scripts/play_balance.py \
+  --policy policies/balance_linear.json \
+  --push-y 1 \
+  --push-at 2 \
+  --push-duration 0.15 \
+  --render-gif balance_push.gif \
+  --fps 10
+```
+
+`play_balance.py` applies the pulse through MuJoCo's root-body external force array and prints the final tilt, survival time, frame count, and approximate GIF duration.
+
+If your desktop supports MuJoCo's GLFW viewer, you can also open the generated scene:
+
+```bash
+uv run --python 3.11 --with mujoco python -m mujoco.viewer --mjcf=/tmp/scout-cam-rover-mjcf/scene.xml
+```
+
+Gazebo Sim is the SDF path, because ForgeCAD's SDF exporter already emits a DiffDrive plugin for the `Sim.controller.diffDrive(...)` metadata.
+
+```bash
+export GZ_SIM_RESOURCE_PATH=/tmp/scout-cam-rover-sdf/models:${GZ_SIM_RESOURCE_PATH}
+gz sim empty.sdf
+gz service -s /world/empty/create \
+  --reqtype gz.msgs.EntityFactory \
+  --reptype gz.msgs.Boolean \
+  --timeout 300 \
+  --req 'sdf_filename: "/tmp/scout-cam-rover-sdf/models/scout_cam_rover/model.sdf", name: "scout_cam_rover"'
+gz topic -t /model/scout_cam_rover/cmd_vel \
+  -m gz.msgs.Twist \
+  -p 'linear: {x: 0.15}, angular: {z: 0.0}'
+```
+
+Those commands require Gazebo Sim to be installed on the host. This repo check does not execute Gazebo, Isaac Sim, MuJoCo, or any physics engine.
+
+## Important Physics Caveat
+
+This robot is a two-wheel self-balancing rover. The exported DiffDrive controller can command the wheel joints, and the generated MuJoCo package includes a starter balance trainer, but the policy itself is simulator-side code. In a real physics project, the model usually needs one of these next:
+
+- A quick demo stabilizer: add a caster, skid, or temporary roll/pitch constraint so basic drive motion is inspectable.
+- A faithful robot controller: add IMU feedback and a balance PID/LQR loop that commands the wheel velocity or torque.
+- A simulator integration layer: connect the exported model to ROS 2 control, Gazebo systems, Isaac controllers, PufferLib, MJX, or another MuJoCo actuator/controller stack.
+
+Without that controller or stabilizer, the wheels can move but the body may fall over.

package/examples/robotics/scout-cam-rover-simready/lib/dims.js

@@ -0,0 +1,140 @@
+// Scout cam rover — shared dimension tree (pure data/math, no geometry).
+// World frame: Z up, ground z=0, axle along X at z=AXLE_Z, front of robot faces -Y.
+// All printed-part interfaces derive from these numbers; change here, not in parts.
+
+function compute(p) {
+  const wall = p.wall; // printed shell wall thickness
+
+  // ---- drive line / wheels --------------------------------------------------
+  const tireOD = p.wheelOD; // outer diameter incl. TPU tire
+  const tireThk = 5; // radial
+  const tireW = 14;
+  const rimOD = tireOD - 2 * tireThk;
+  const rimID = rimOD - 12; // rim band 6 thick radially
+  const rimW = 14;
+  const axleZ = tireOD / 2;
+
+  // N20 micro gearmotor (purchased): body 12 wide x 10 tall, 24 long incl gearbox,
+  // D-shaft d3 x 9.5 with 2.5 flat.
+  const motor = {
+    w: 12, h: 10, len: 24, // gearbox front face = mating plane
+    shaftD: 3, shaftFlat: 2.5, shaftLen: 9.5,
+    noseBossD: 4, noseBossL: 1.2, // small ring around shaft exit
+  };
+
+  // ---- chassis tub ----------------------------------------------------------
+  const tub = {
+    w: 70, d: 72, h: 52, z0: axleZ - 26, // base z (world) — axle centered in tub height
+    cornerR: 6,
+    wall: wall,
+    floorT: 2.8,
+    postSq: 12, postInset: 6, // corner posts receiving the shell plugs
+    sideScrewZ: 47, // tub-local height of the 4 horizontal shell screws
+  };
+  tub.axleZl = axleZ - tub.z0; // axle height in tub-local Z
+
+  // motor pod (printed, black): hides shaft exit, wheel hub runs inside its bore
+  const pod = {
+    od: 34, len: 14, boreD: 24,
+    screwR: 14.0, screwN: 3, // M2 from inside tub through the wall into pod bosses
+    pilotD: 1.7, wallClearD: 1.9, pilotDepth: 6,
+  };
+
+  // wheel hub geometry (wheel-local: z=0 bore mouth face, +Z outward)
+  const hub = {
+    bossD: 20,
+    bossL: 14, // reaches from inside pod bore out to the spoke web
+    boreD: 3.2, boreFlat: 2.65, boreDepth: 9,
+    faceHoleN: 5, faceHoleD: 2.6, faceHoleR: 6,
+  };
+  const web = { t: 6, z0: hub.bossL }; // spoke web axial band (wheel-local)
+  const rim = { z0: web.z0 - (rimW - web.t) / 2 }; // rim band centered on web
+  // wheel-local Z of bore mouth maps to world |x| = tub.w/2 + 1.5 (mouth sits 1.5 outside the wall,
+  // inside the pod bore). Pod outer face at tub.w/2 + pod.len.
+  const wheelMouthX = tub.w / 2 + 1.5;
+
+  // battery: 2x18650 holder (purchased) mounted vertically on the body shell rear
+  // inner wall — high mass is correct for an inverted-pendulum self-balancer.
+  const batt = { w: 70, h: 42, d: 21, mountHoleSpan: 50, zc: 38 }; // zc = shell-local center
+
+  // service door in the tub front wall (exposes driver / IMU / wiring bay)
+  const door = {
+    openW: 44, openH: 22, zc: 19, // tub-local opening, center height
+    panelW: 54, panelH: 34, panelT: 2.0,
+    plugT: 2.2, slop: 0.3, // plug per-side clearance into opening
+    recess: 1.0, recessSlop: 0.4,
+    screwDX: 23.5, screwDZ: 13.5, // screw offsets from door center
+    pilotD: 1.7, screwHeadD: 3.8, bossD: 6, bossLen: 7,
+  };
+
+  // electronics in the tub bay (purchased modules on printed floor posts)
+  const boards = {
+    standoffH: 4,
+    drv: { w: 16, d: 18, t: 1.6, x: -12, y: -22.5 },  // DRV8833 dual H-bridge
+    buck: { w: 22, d: 17, t: 1.6, x: 7.6, y: -22.5 }, // MP1584 5V buck
+    mpu: { w: 16.5, d: 21.5, t: 1.6, x: 0, y: 3 },    // MPU6050 IMU (mid-bay)
+  };
+  const sw = { w: 13, h: 9, t: 9, plateW: 15, plateH: 11, plateT: 1.8, zc: 14 }; // rocker, rear wall
+
+  // ---- body shell (upper cube) ---------------------------------------------
+  const body = {
+    w: 84, d: 92, h: 88, cornerR: 13,
+    yOff: -4, // shell center sits 4mm toward the front of the tub center
+    topT: 3.0,
+    plugSq: 8, plugL: 9.7, socketSq: 8.3, socketDepth: 10, // 4 corner plugs into tub posts
+    plugInsetX: 10, plugInsetY: 10, // plug centers from tub inner corners
+  };
+  // neck + ring on top of shell (printed as part of shell)
+  const neck = { od: 44, h: 14, boreD: 36, ringOD: 50, ringH: 4 };
+
+  // camera (front face of shell, shell-local: centered XY, base z=0)
+  const cam = {
+    zc: 52, // lens center height above shell base
+    recessD: 44, recessDepth: 1.0,
+    holeD: 26,
+    screwR: 18.5, screwN: 4, pilotD: 1.7, screwStartDeg: 0,
+    bezelOD: 43.4, bezelID: 28, bezelT: 3.4, // proud of face by bezelT - recessDepth
+    cowlD: 27.8, cowlT: 3.0, apertureD: 9.5,
+  };
+
+  // ESP32-CAM (purchased): PCB 27 x 40.5 x 1.6, lens barrel d8 x 6.5 on front
+  const esp = { pcbW: 27, pcbH: 40.5, pcbT: 1.6, barrelD: 8, barrelL: 6.5, compT: 3.0 };
+
+  // side vents: skewed recessed panel + 5 vertical through slots, both side faces
+  const vent = {
+    n: 5, slotW: 4.5, slotL: 36, pitch: 11,
+    recessDepth: 0.8, skewDZ: 14, // rear edge of band this much higher than front
+    yc: 3, zc: 56, bandW: 58, bandH: 52, // band center (shell-local y/z) and size
+  };
+
+  // SG90 servo (purchased) hung under a bridge bar across the neck-bore opening.
+  // Servo-local frame: z=0 at the tab TOP plane (mates upward against the bosses);
+  // spline axis at local x=0.
+  const servo = {
+    bodyW: 23, bodyD: 12.4, bodyDown: 19, bodyUp: 4.5, // body extent below/above tab plane
+    bodyXc: -5.6, // body center offset so the spline sits at x=0
+    tabSpan: 32.4, tabT: 2.5, tabHoleXa: -13.75, tabHoleXb: 13.75, // relative to body center
+    towerH: 4.6, towerD: 11.8, splineD: 4.8, splineH: 3.2,
+    hornD: 20.6, hornT: 1.8, hornHubD: 7.4, // round horn pressed on the spline
+    tabPlaneZ: 78.2, // shell-local height of the tab plane
+    bossSq: 8, // printed bosses hanging from the bridge bar
+  };
+  const bridge = { w: 10, holeD: 13 }; // bar left across the neck-bore wall opening
+
+  // turret (printed black) rides the servo horn through the neck bore
+  const turret = {
+    baseD: 40, baseH: 5, lugN: 4, lugW: 5, lugT: 2, lugH: 2.4,
+    barrelD: 34, barrelH: 15, capD: 37, capH: 3,
+    colD: 14, colHubD: 25, colHubH: 5, colLen: 12.5, // column reaches the horn through the neck
+    socketD: 21.2, socketDepth: 2.0,
+    gapAboveNeck: 1.2, // running gap between turret base underside and neck ring top
+  };
+
+  return {
+    wall, axleZ, tireOD, tireThk, tireW, rimOD, rimID, rimW,
+    motor, tub, pod, hub, web, rim, wheelMouthX,
+    batt, door, boards, sw, body, neck, cam, esp, vent, servo, bridge, turret,
+  };
+}
+
+module.exports = { compute };