forgecad 0.1.0

package/examples/api/folded-service-panel-cover.js

@@ -0,0 +1,117 @@
+import {
+  circle2d,
+  rect,
+  roundedRect,
+  sheetMetal,
+} from 'forgecad';
+
+export const FOLDED_SERVICE_PANEL_COVER_SPEC = {
+  panel: { width: 180, height: 110 },
+  thickness: 1.5,
+  bendRadius: 2.0,
+  bendAllowance: { kFactor: 0.42 },
+  cornerRelief: { size: 4.0 },
+};
+
+const FOLDED_SERVICE_PANEL_REGION_NAMES = [
+  'panel',
+  'bend-top',
+  'flange-top',
+  'bend-right',
+  'flange-right',
+  'bend-bottom',
+  'flange-bottom',
+  'bend-left',
+  'flange-left',
+];
+
+function mountingHole(radius, u, v) {
+  return {
+    sketch: circle2d(radius),
+    u,
+    v,
+  };
+}
+
+function assertIncludesAll(actual, expected, label) {
+  for (const name of expected) {
+    if (!actual.includes(name)) {
+      throw new Error(`${label} is missing "${name}". Got: ${actual.join(', ')}`);
+    }
+  }
+}
+
+export function buildFoldedServicePanelCoverPart() {
+  let part = sheetMetal(FOLDED_SERVICE_PANEL_COVER_SPEC)
+    .flange('top', { length: 18, angleDeg: 90 })
+    .flange('right', { length: 18, angleDeg: 90 })
+    .flange('bottom', { length: 18, angleDeg: 90 })
+    .flange('left', { length: 18, angleDeg: 90 })
+    .cutout('panel', rect(72, 36, true), { selfAnchor: 'center' })
+    .cutout('flange-right', roundedRect(26, 10, 5, true), { selfAnchor: 'center' });
+
+  const holes = [
+    mountingHole(2.2, -68, -37),
+    mountingHole(2.2, 68, -37),
+    mountingHole(2.2, -68, 37),
+    mountingHole(2.2, 68, 37),
+  ];
+
+  for (const hole of holes) {
+    part = part.cutout('panel', hole.sketch, {
+      u: hole.u,
+      v: hole.v,
+      selfAnchor: 'center',
+    });
+  }
+
+  return part;
+}
+
+function assertDescendant(face, label, semantic, minMembers = 1) {
+  if (!face.descendant) {
+    throw new Error(`${label} did not expose descendant metadata.`);
+  }
+  if (face.descendant.semantic !== semantic) {
+    throw new Error(`${label} expected descendant semantic "${semantic}", got "${face.descendant.semantic}".`);
+  }
+  if (face.descendant.memberCount < minMembers) {
+    throw new Error(`${label} expected at least ${minMembers} member(s), got ${face.descendant.memberCount}.`);
+  }
+}
+
+export function buildFoldedServicePanelCoverOutputs() {
+  const part = buildFoldedServicePanelCoverPart();
+  const regionNames = part.regionNames();
+  assertIncludesAll(regionNames, FOLDED_SERVICE_PANEL_REGION_NAMES, 'Sheet-metal regionNames()');
+  if (regionNames.length !== FOLDED_SERVICE_PANEL_REGION_NAMES.length) {
+    throw new Error(`Sheet-metal regionNames() should expose ${FOLDED_SERVICE_PANEL_REGION_NAMES.length} entries, got ${regionNames.length}.`);
+  }
+
+  const folded = part.folded();
+  const flat = part.flatPattern();
+
+  assertIncludesAll(folded.faceNames(), FOLDED_SERVICE_PANEL_REGION_NAMES, 'Folded faceNames()');
+  assertIncludesAll(flat.faceNames(), FOLDED_SERVICE_PANEL_REGION_NAMES, 'Flat faceNames()');
+
+  assertDescendant(folded.face('panel'), 'Folded panel', 'region');
+  assertDescendant(folded.face('flange-right'), 'Folded flange-right', 'region');
+  assertDescendant(folded.face('bend-right'), 'Folded bend-right', 'set', 2);
+  assertDescendant(flat.face('panel'), 'Flat panel', 'region');
+  assertDescendant(flat.face('flange-right'), 'Flat flange-right', 'region');
+  assertDescendant(flat.face('bend-right'), 'Flat bend-right', 'face');
+
+  return { part, folded, flat };
+}
+
+export function buildFoldedServicePanelCoverScene(options = {}) {
+  const { folded, flat } = buildFoldedServicePanelCoverOutputs();
+  const flatOffsetX = options.flatOffsetX ?? 280;
+  const foldedColor = options.foldedColor ?? '#a2b0b7';
+  const flatColor = options.flatColor ?? '#d7bf95';
+
+  return [
+    { name: 'Folded Service Panel Cover', shape: folded, color: foldedColor },
+    { name: 'Flat Service Panel Cover', shape: flat.translate(flatOffsetX, 0, 0), color: flatColor },
+  ];
+}

package/examples/api/gears-bevel-face-joints.forge.js

@@ -0,0 +1,157 @@
+// Bevel + face gear demo with runtime joint couplings.
+// Use the "Joints" section in the View Panel to drive both stages.
+
+const moduleSize = param("Module", 1.4, { min: 0.8, max: 3.0, step: 0.05 });
+const bevelInput = param("Bevel Driver", 30, { min: -360, max: 360, step: 1, unit: "°" });
+const faceInput = param("Face Driver", 20, { min: -360, max: 360, step: 1, unit: "°" });
+const shaftAngle = param("Bevel Shaft", 90, { min: 60, max: 120, step: 1, unit: "°" });
+const stageBacklash = moduleSize * 0.05;
+
+const bevelStage = lib.bevelGearPair({
+  pinion: {
+    module: moduleSize,
+    teeth: 16,
+    faceWidth: 10,
+    boreDiameter: 5,
+  },
+  gear: {
+    module: moduleSize,
+    teeth: 32,
+    faceWidth: 9,
+    boreDiameter: 8,
+  },
+  shaftAngleDeg: shaftAngle,
+  backlash: stageBacklash,
+  place: true,
+});
+
+const faceStage = lib.faceGearPair({
+  face: {
+    module: moduleSize,
+    teeth: 44,
+    faceWidth: 7,
+    toothHeight: moduleSize * 0.9,
+    side: "top",
+    boreDiameter: 10,
+  },
+  vertical: {
+    module: moduleSize,
+    teeth: 14,
+    faceWidth: 8,
+    boreDiameter: 5,
+  },
+  backlash: stageBacklash,
+  place: true,
+});
+
+for (const d of [...bevelStage.diagnostics, ...faceStage.diagnostics]) {
+  const tag = `[${d.level}] ${d.code}`;
+  if (d.level === "error") console.error(tag, d.message);
+  else if (d.level === "warn") console.warn(tag, d.message);
+  else console.info(tag, d.message);
+}
+
+const addOffset = (point, offset) => [
+  point[0] + offset[0],
+  point[1] + offset[1],
+  point[2] + offset[2],
+];
+
+const bevelOffset = [-110, 0, 0];
+const faceOffset = [110, 0, 0];
+
+const bevelPinionPivot = addOffset(bevelStage.pinionCenter, bevelOffset);
+const bevelGearPivot = addOffset(bevelStage.gearCenter, bevelOffset);
+const faceGearPivot = addOffset([0, 0, 0], faceOffset);
+const faceVerticalPivot = addOffset([faceStage.centerDistance, 0, faceStage.meshPlaneZ], faceOffset);
+
+jointsView({
+  joints: [
+    {
+      name: "Bevel Driver",
+      child: "Bevel Pinion",
+      type: "revolute",
+      axis: bevelStage.pinionAxis,
+      pivot: bevelPinionPivot,
+      min: -1080,
+      max: 1080,
+      default: bevelInput,
+      unit: "°",
+    },
+    {
+      name: "Bevel Driven",
+      child: "Bevel Gear",
+      type: "revolute",
+      axis: bevelStage.gearAxis,
+      pivot: bevelGearPivot,
+      min: -1080,
+      max: 1080,
+      default: 0,
+      unit: "°",
+    },
+    {
+      name: "Face Driver",
+      child: "Face Gear",
+      type: "revolute",
+      axis: [0, 0, 1],
+      pivot: faceGearPivot,
+      min: -1080,
+      max: 1080,
+      default: faceInput,
+      unit: "°",
+    },
+    {
+      name: "Face Driven",
+      child: "Face Vertical",
+      type: "revolute",
+      axis: [0, 1, 0],
+      pivot: faceVerticalPivot,
+      min: -1080,
+      max: 1080,
+      default: 0,
+      unit: "°",
+    },
+  ],
+  couplings: [
+    {
+      joint: "Bevel Driven",
+      terms: [{ joint: "Bevel Driver", ratio: bevelStage.jointRatio }],
+    },
+    {
+      joint: "Face Driven",
+      terms: [{ joint: "Face Driver", ratio: faceStage.jointRatio }],
+    },
+  ],
+  animations: [
+    {
+      name: "Dual Spin",
+      duration: 2.4,
+      loop: true,
+      keyframes: [
+        { at: 0.0, values: { "Bevel Driver": 0, "Face Driver": 0 } },
+        { at: 0.5, values: { "Bevel Driver": 180, "Face Driver": 120 } },
+        { at: 1.0, values: { "Bevel Driver": 360, "Face Driver": 240 } },
+      ],
+    },
+  ],
+  defaultAnimation: "Dual Spin",
+});
+
+return [
+  {
+    name: "Bevel Pinion",
+    shape: bevelStage.pinion.translate(bevelOffset[0], bevelOffset[1], bevelOffset[2]).color("#d7a25e"),
+  },
+  {
+    name: "Bevel Gear",
+    shape: bevelStage.gear.translate(bevelOffset[0], bevelOffset[1], bevelOffset[2]).color("#8ea8be"),
+  },
+  {
+    name: "Face Gear",
+    shape: faceStage.face.translate(faceOffset[0], faceOffset[1], faceOffset[2]).color("#6f8795"),
+  },
+  {
+    name: "Face Vertical",
+    shape: faceStage.vertical.translate(faceOffset[0], faceOffset[1], faceOffset[2]).color("#c98f5a"),
+  },
+];

package/examples/api/gears-tier1.forge.js

@@ -0,0 +1,57 @@
+// Tier 1 gears demo: spur pair + ring gear + rack gear
+
+const moduleSize = param("Module", 1.25, { min: 0.6, max: 3.0, step: 0.05 });
+const pinionTeeth = param("Pinion Teeth", 14, { min: 8, max: 28, integer: true });
+const drivenTeeth = param("Driven Teeth", 42, { min: 16, max: 90, integer: true });
+const backlash = param("Backlash", 0.05, { min: 0, max: 0.2, step: 0.01, unit: "mm" });
+const faceWidth = param("Face Width", 10, { min: 4, max: 18, unit: "mm" });
+
+const pair = lib.gearPair({
+  pinion: {
+    module: moduleSize,
+    teeth: pinionTeeth,
+    pressureAngleDeg: 20,
+    faceWidth,
+    boreDiameter: 5,
+  },
+  gear: {
+    module: moduleSize,
+    teeth: drivenTeeth,
+    pressureAngleDeg: 20,
+    faceWidth,
+    boreDiameter: 8,
+  },
+  backlash,
+});
+
+for (const d of pair.diagnostics) {
+  const tag = `[${d.level}] ${d.code}`;
+  if (d.level === "error") console.error(tag, d.message);
+  else if (d.level === "warn") console.warn(tag, d.message);
+  else console.info(tag, d.message);
+}
+
+const ring = lib.ringGear({
+  module: moduleSize,
+  teeth: Math.max(30, drivenTeeth + pinionTeeth + 4),
+  pressureAngleDeg: 20,
+  faceWidth,
+  backlash,
+  rimWidth: moduleSize * 3,
+}).translate(0, 95, 0);
+
+const rack = lib.rackGear({
+  module: moduleSize,
+  teeth: 22,
+  pressureAngleDeg: 20,
+  faceWidth,
+  backlash,
+  baseHeight: moduleSize * 2,
+}).translate(0, -95, 0);
+
+return [
+  { name: "Spur Pinion", shape: pair.pinion.color("#d5a15f") },
+  { name: "Spur Gear", shape: pair.gear.color("#9ab3ca") },
+  { name: "Ring Gear", shape: ring.color("#71808d") },
+  { name: "Rack Gear", shape: rack.color("#6f9272") },
+];

package/examples/api/geometry-info.forge.js

@@ -0,0 +1,49 @@
+// Geometry provenance inspection.
+// Run with: forgecad run examples/api/geometry-info.forge.js
+// The CLI now prints backend/representation/fidelity/topology for each object.
+
+const base = rectangle(-35, -20, 70, 40).extrude(18).color('#5f7c8a');
+
+const cutter = circle2d(11, 36).extrude(26).translate(0, 0, -4);
+const machined = base
+  .toShape()
+  .subtract(cutter)
+  .color('#9eb4bf')
+  .translate(0, 72, 0);
+
+const station = (w, d) => spline2d([
+  [w * 0.5, 0],
+  [w * 0.32, d * 0.46],
+  [0, d * 0.55],
+  [-w * 0.32, d * 0.46],
+  [-w * 0.5, 0],
+  [-w * 0.32, -d * 0.46],
+  [0, -d * 0.55],
+  [w * 0.32, -d * 0.46],
+], {
+  closed: true,
+  samplesPerSegment: 9,
+  tension: 0.35,
+});
+
+const lofted = loft(
+  [
+    station(26, 18),
+    station(48, 28),
+    station(34, 22),
+  ],
+  [0, 20, 46],
+  { edgeLength: 0.85 },
+)
+  .translate(110, 18, 0)
+  .color('#d8b36a');
+
+console.info('Tracked extrude', base.geometryInfo());
+console.info('Boolean cut', machined.geometryInfo());
+console.info('Lofted body', lofted.geometryInfo());
+
+return [
+  { name: 'Tracked Extrude', shape: base },
+  { name: 'Boolean Cut', shape: machined },
+  { name: 'Lofted Body', shape: lofted },
+];

package/examples/api/group-test.forge.js

@@ -0,0 +1,34 @@
+// Test assembly grouping — nested group format
+const baseW = param("Base Width", 100, { min: 60, max: 200, unit: "mm" });
+const baseD = param("Base Depth", 80, { min: 40, max: 150, unit: "mm" });
+
+// Bed assembly
+const bedPlate = box(baseW, baseD, 5).color('#666666');
+const glass = box(baseW - 10, baseD - 10, 3).translate(5, 5, 5).color('#aaddff');
+const heater = box(baseW - 20, baseD - 20, 1).translate(10, 10, -1).color('#cc4444');
+
+// Gantry
+const leftRail = box(5, baseD, 60).translate(-10, 0, 8).color('#888888');
+const rightRail = box(5, baseD, 60).translate(baseW + 5, 0, 8).color('#888888');
+const crossBar = box(baseW + 20, 5, 5).translate(-10, baseD / 2, 63).color('#aaaaaa');
+
+// Extruder (intentionally overlaps crossbar — intra-group collision)
+const nozzle = cylinder(15, 4).translate(baseW / 2, baseD / 2, 48).color('#ff8800');
+const heatsink = box(20, 20, 10, true).translate(baseW / 2, baseD / 2, 60).color('#cccccc');
+
+return [
+  { name: "Bed Assembly", group: [
+    { name: "Bed Plate", shape: bedPlate },
+    { name: "Glass Bed", shape: glass },
+    { name: "Heater", shape: heater },
+  ]},
+  { name: "Gantry", group: [
+    { name: "Left Rail", shape: leftRail },
+    { name: "Right Rail", shape: rightRail },
+    { name: "Cross Bar", shape: crossBar },
+  ]},
+  { name: "Extruder", group: [
+    { name: "Nozzle", shape: nozzle },
+    { name: "Heatsink", shape: heatsink },
+  ]},
+];

package/examples/api/group-vs-union.forge.js

@@ -0,0 +1,25 @@
+// group() vs union() — when to use which.
+//
+// union(a, b)  → merges into ONE mesh. Colors lost. Good for boolean operand.
+// group(a, b)  → keeps separate. Colors preserved. Transforms together.
+//
+// Use union when you need a single solid (e.g., to subtract from something).
+// Use group when you want parts to move together but stay visually distinct.
+
+const base = box(60, 60, 5, true).color('#888888');
+const col = cylinder(30, 5).color('#cc4444')
+  .attachTo(base, 'top', 'bottom');
+
+// --- group: colors preserved, transforms together (with named children) ---
+const grouped = group(
+  { name: "Base", shape: base },
+  { name: "Column", shape: col }
+).translate(-50, 0, 0);
+
+// --- union: one solid, one color ---
+const unioned = union(base, col).translate(50, 0, 0).color('#4488cc');
+
+return [
+  grouped,  // each child becomes a separate viewport object with names
+  { name: "Union (single solid)", shape: unioned },
+];

package/examples/api/import-args-unit.forge.js

@@ -0,0 +1,5 @@
+const w = param("Width", 30, { min: 10, max: 80, unit: "mm" });
+const h = param("Height", 20, { min: 10, max: 80, unit: "mm" });
+const d = param("Depth", 10, { min: 4, max: 40, unit: "mm" });
+
+return box(w, d, h, true);

package/examples/api/import-args.forge.js

@@ -0,0 +1,16 @@
+const left = importPart("api/import-args-unit.forge.js", {
+  "Width": 24,
+  "Height": 24,
+  "Depth": 8,
+}).translate(-20, 0, 0);
+
+const right = importPart("api/import-args-unit.forge.js", {
+  "Width": 52,
+  "Height": 16,
+  "Depth": 12,
+}).translate(20, 0, 0);
+
+return [
+  { name: "Left", shape: left, color: "#5c88da" },
+  { name: "Right", shape: right, color: "#d97c45" },
+];

package/examples/api/import-dimensions-follow.forge.js

@@ -0,0 +1,18 @@
+const left = importPart("api/dimensioned-bracket.forge.js", {
+  "Width": 55,
+  "Height": 45,
+  "Depth": 28,
+  "Thickness": 4,
+}).translate(-80, 0, 0);
+
+const right = importPart("api/dimensioned-bracket.forge.js", {
+  "Width": 55,
+  "Height": 45,
+  "Depth": 28,
+  "Thickness": 4,
+}).translate(80, 0, 0).rotate(0, 0, 180);
+
+return [
+  { name: "Left Bracket", shape: left, color: "#6a7bd1" },
+  { name: "Right Bracket", shape: right, color: "#d18a5a" },
+];

package/examples/api/import-placement-references.forge.js

@@ -0,0 +1,18 @@
+// Placement references let imported parts define semantic attachment points.
+
+const left = importPart("api/import-placement-widget-source.forge.js")
+  .placeReference("mount", [-90, 0, 0]);
+
+const right = importPart("api/import-placement-widget-source.forge.js", {
+  "Post Height": 40,
+}).attachTo(left, "objects.post.top", "mount", [90, 0, 0]);
+
+const cap = box(18, 18, 8, true)
+  .attachTo(right, "objects.post.top", "bottom")
+  .color("#384b5f");
+
+return [
+  { name: "Left", shape: left, color: "#5b7c8d" },
+  { name: "Right", shape: right, color: "#d38b4d" },
+  { name: "Cap", shape: cap },
+];

package/examples/api/import-placement-widget-source.forge.js

@@ -0,0 +1,30 @@
+const postHeight = param("Post Height", 26, { min: 12, max: 60, unit: "mm" });
+
+const base = box(48, 32, 8, true);
+const post = cylinder(postHeight, 5, undefined, undefined, true)
+  .translate(12, 0, 4 + postHeight / 2);
+
+return union(base, post)
+  .withReferences({
+    points: {
+      mount: [0, -16, -4],
+      postCenter: [12, 0, 4 + postHeight / 2],
+    },
+    edges: {
+      postAxis: {
+        start: [12, 0, 4],
+        end: [12, 0, 4 + postHeight],
+      },
+    },
+    surfaces: {
+      mountingFace: {
+        center: [0, -16, 0],
+        normal: [0, -1, 0],
+      },
+    },
+    objects: {
+      base,
+      post,
+    },
+  })
+  .color("#5b7c8d");

package/examples/api/import-relative-paths.forge.js

@@ -0,0 +1,18 @@
+// Relative import paths: ./ resolves from this file's folder.
+
+const left = importPart("./import-args-unit.forge.js", {
+  "Width": 26,
+  "Height": 22,
+  "Depth": 9,
+}).translate(-24, 0, 0);
+
+const right = importPart("./import-args-unit.forge.js", {
+  "Width": 46,
+  "Height": 18,
+  "Depth": 12,
+}).translate(24, 0, 0);
+
+return [
+  { name: "Left (./)", shape: left, color: "#5f87c6" },
+  { name: "Right (./)", shape: right, color: "#d18a5a" },
+];

package/examples/api/import-svg-sketch-shape.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 80">
+  <path
+    fill="#111111"
+    fill-rule="evenodd"
+    d="M 8 8 H 72 V 72 H 8 Z M 28 28 H 52 V 52 H 28 Z"
+  />
+  <circle cx="100" cy="16" r="7" fill="#111111" />
+  <polyline
+    points="88,46 100,60 112,46"
+    fill="none"
+    stroke="#111111"
+    stroke-width="5"
+    stroke-linejoin="round"
+  />
+</svg>

package/examples/api/import-svg-sketch.forge.js

@@ -0,0 +1,28 @@
+// SVG import demo:
+// - Filled regions (all vs largest only)
+// - Stroke-only import
+// - importSketch(...) overload for .svg
+
+const allFill = importSvgSketch("api/import-svg-sketch-shape.svg", {
+  include: "fill",
+  regionSelection: "all",
+});
+
+const largestFill = importSketch("api/import-svg-sketch-shape.svg", {
+  include: "fill",
+  regionSelection: "largest",
+  maxWidth: 35,
+  maxHeight: 35,
+  centerOnOrigin: true,
+});
+
+const strokeOnly = importSvgSketch("api/import-svg-sketch-shape.svg", {
+  include: "stroke",
+  flattenTolerance: 0.2,
+});
+
+return [
+  { name: "Fill (all regions)", shape: allFill.extrude(4).translate(-55, 0, 0).color("#5f87c6") },
+  { name: "Fill (largest region)", shape: largestFill.extrude(4).color("#d08f5b") },
+  { name: "Stroke geometry", shape: strokeOnly.extrude(4).translate(55, 0, 0).color("#66b38d") },
+];

package/examples/api/js-module-imports.forge.js

@@ -0,0 +1,9 @@
+import { buildAssembly } from "./js-module-scene.js";
+
+const { loadCount } = require("./js-module-pillars.js");
+
+if (loadCount() !== 1) {
+  throw new Error(`Expected shared JS module cache, got ${loadCount()}`);
+}
+
+export default buildAssembly();

package/examples/api/js-module-pillars.js

@@ -0,0 +1,25 @@
+import { box, union } from "forgecad";
+
+let moduleLoadCount = 0;
+moduleLoadCount += 1;
+
+export const capHeight = 6;
+
+export function loadCount() {
+  return moduleLoadCount;
+}
+
+export default class PillarPair {
+  constructor(spacing, height) {
+    this.spacing = spacing;
+    this.height = height;
+  }
+
+  build() {
+    const pillar = box(6, 6, this.height, true);
+    return union(
+      pillar.translate(-this.spacing / 2, 0, this.height / 2),
+      pillar.translate(this.spacing / 2, 0, this.height / 2),
+    );
+  }
+}

package/examples/api/js-module-scene.js

@@ -0,0 +1,9 @@
+import { box, union } from "forgecad";
+import PillarPair, { capHeight } from "./js-module-pillars.js";
+
+export function buildAssembly() {
+  const base = box(40, 18, 4, true);
+  const pillars = new PillarPair(24, 12).build().translate(0, 0, 2);
+  const cap = box(14, 18, capHeight, true).translate(0, 0, 17);
+  return union(base, pillars, cap).color("#d6a86a");
+}