← Commit history
page.json+2−2@@ -2,7 +2,7 @@ "schema_version": 1, "type": "app", "slug": "adom-3d-viewer",- "title": "Adom 3D Viewer (Babylon 9.5)",+ "title": "Adom 3D Viewer", "brief": "The Babylon 9.5 engine behind every component page's 3D tab on wiki.adom.inc. Versioned ESM bundle with GLB loading, view cube, layers toolbar, ground shadows, and Z-up CAD framing.", "version": "0.4.3", "tags": [@@ -28,7 +28,7 @@ "install_hint": "", "version_cmd": "" },- "readme": "# adom-3d-viewer-babylon9\n\nA fork of Colby's `adom-3d-viewer` (Babylon 7.54) bumped to Babylon 9.5.0 with\nthe redesigned Inspector v9. Built as an ESM bundle for downstream Adom tools\nto vendor — chiplinter consumes it today, and we expect it to back the next\n~10 Adom 3D viewers.\n\n## Why fork\n\nColby's `adom-3d-viewer` is the canonical viewer for InstaPCB previews and\nchipfit, but it's pinned to Babylon 7.54 because chipfit-v2 + tscircuit ship\nthe same renderer. We needed Babylon 9's redesigned Inspector for chiplinter's\nscene-graph debugging and didn't want to disturb Colby's surface area, so this\nis a parallel fork.\n\n## What's in the bundle\n\nThe build produces a single ESM entry plus code-split chunks:\n\n```\nadom-3d-viewer-babylon9.esm.js ← entry, sets window.Adom3DViewerBabylon9\nchunk-*.js ← code-split chunks (Babylon core, inspector, etc.)\nVERSION\n```\n\nLoaded via:\n\n```html\n<script type=\"module\">\n await import('/path/to/adom-3d-viewer-babylon9.esm.js');\n const v = window.Adom3DViewerBabylon9;\n v.init(host, { zUp: true, modelUrl: 'asset/foo.glb' });\n</script>\n```\n\n## Why ESM (not IIFE)\n\nBabylon 9's `@babylonjs/inspector` has circular imports that resolve to TDZ\nwhen collapsed into a single IIFE scope (regardless of minifier). Vite's ESM\noutput preserves module boundaries so the inspector initializes cleanly.\nConsumers load via `<script type=\"module\">`, which all modern browsers\nsupport.\n\n## API\n\n```js\nwindow.Adom3DViewerBabylon9 = {\n init(host, options), // mounts the viewer in `host`, returns ViewerInstance\n rotateYUpToZUp(scene), // for kicad-cli GLBs (Y-up) → adom viewer (Z-up)\n addLaserEtch(scene, opts), // bake a laser-etched chip-marking text overlay\n BABYLON: <full @babylonjs/core namespace>, // re-exported for consumers\n};\n```\n\n`ViewerInstance` exposes:\n- `loadModel(url)` / `clearScene()` / `frameModel(fillFraction?)`\n- `getScene()` / `getEngine()` / `getCamera()` / `getShadowGenerator()`\n- `addContentRoot(node, opts?)` / `removeContentRoot(node)`\n- `toggleDebugLayer()` / `showDebugLayer()` / `hideDebugLayer()`\n- `setGroundVisible(visible)` / `goHome()`\n- `setProjectionMode(ortho)` / `getProjectionMode()`\n- `destroy()`\n\nThe full `@babylonjs/core` namespace is exposed at `Adom3DViewerBabylon9.BABYLON`\nso consumers don't need their own `import` side — chiplinter uses\n`V.BAB.MeshBuilder.CreateDisc`, `V.BAB.PBRMaterial`, `V.BAB.Quaternion`,\n`V.BAB.Tools.CreateScreenshotUsingRenderTarget`, etc. directly.\n\n## Install (drop into a tool's vendor/3d-viewer/)\n\nThe wiki ships the bundle as a tarball. Pull it into your tool's vendor\ndirectory at install time:\n\n```bash\n# Install everything to a known shared location\nsudo mkdir -p /usr/local/share/adom-3d-viewer-babylon9\ncurl -fsSL https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-3d-viewer-babylon9/adom-3d-viewer-babylon9.tar.gz \\\n | sudo tar -xz -C /usr/local/share/adom-3d-viewer-babylon9\n\n# Then symlink (or copy) into your tool's vendor/3d-viewer/\nln -sfn /usr/local/share/adom-3d-viewer-babylon9 /usr/local/bin/vendor/3d-viewer\n```\n\nOr just curl individual files if your tool only needs the entry (`adom-3d-viewer-babylon9.esm.js`):\n\n```bash\ncurl -fsSL https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-3d-viewer-babylon9/adom-3d-viewer-babylon9.tar.gz | tar -xz -C ./vendor/3d-viewer\n```\n\n## Browser shims required\n\nThe inspector's React deps (Fluent UI) assume a Node environment. Add this\nshim before loading the bundle:\n\n```html\n<script>\n window.process = window.process || { env: { NODE_ENV: 'production' } };\n window.global = window.global || window;\n</script>\n<script type=\"module\">\n await import('/path/to/adom-3d-viewer-babylon9.esm.js');\n</script>\n```\n\n## Defaults (3d-viewer-design skill compliance)\n\n| Rule | Status | Notes |\n|---|---|---|\n| §1 Babylon engine | ✅ | `@babylonjs/core` 9.5.0 |\n| §3b Background gradient `#5a6b7e → #2a3340` | ✅ | `SceneBuilder.ts` |\n| §4a HDRI environment | ✅ | bundled `.env` cube texture |\n| §4b Bottom-light toggle | ✅ | exposed via consumer toolbar (HemisphericLight ground-color boost) |\n| §4d Ground plane + ShadowGenerator(8192) | ✅ | medium-gray ground, blur PCF, optional via `showGround` prop |\n| §5a PBRMaterial default | ✅ | every internal material is PBR |\n| §6a `zoomToMouseLocation = true` | ✅ | `AdomCamera.ts` |\n| §6c Shift+Alt+Click recenter | ✅ | `AdomCamera.ts` |\n| §7 ViewCube + tween presets | ✅ | `ViewCubeBuilder.ts` |\n| **§8a World-origin axes (default ON)** | ✅ **v0.2.0** | R/G/B at scene origin, scaled to 15% of scene radius via `refreshAxisScale` after each `frameModel` |\n| **§8b Mesh-local axes (default OFF, toggleable)** | ✅ **v0.2.0** | parented to each loaded GLB root via `addMeshLocalAxes` |\n| **§8c Screen-space corner triad (always on)** | ⚠ **deferred to v0.3.0** | Second-camera-with-viewport approach didn't render — `engine.runRenderLoop(() => scene.render())` honors `scene.activeCamera` only, not the `activeCameras` array. v0.3.0 will use `UtilityLayerRenderer` with an explicit secondary `engine.render()` pass. §8a + §8b cover the bulk of \"where is origin\" debugging in the meantime. |\n| §6b.i Adaptive `wheelDeltaPercentage` (`100/R`) | ⚠ open | currently a constant `0.1`; pan + radius limits ARE adaptive |\n| §11 Y-up→Z-up | ✅ | `rotateYUpToZUp(scene)` exposed on the global |\n\n## §8 axis-helper API (v0.2.0)\n\n```js\n// World axes (default ON) — R/G/B at scene origin, sized to 15% of scene radius.\nviewer.toggleAxes('world'); // toggle\nviewer.toggleAxes('world', true); // explicit set\nviewer.getAxesState(); // → { world: bool, meshLocal: bool }\n\n// Mesh-local axes (default OFF) — auto-attaches to each loaded GLB root.\nviewer.toggleAxes('mesh-local'); // toggle\n```\n\nReach the helpers directly via `scene.metadata.__adomAxes` if you want to add\nor remove per-root helpers programmatically (e.g. while debugging a custom\nloader path that bypasses `loadModel`).\n\n## Consumers\n\n- `adom-chiplinter` — vendors `dist-standalone/` into `vendor/3d-viewer/`\n- (future) `adom-chipfit-v3` — when v2 lands its own Babylon 9 upgrade\n- (future) standalone scene-graph utility scripts\n\n## Source\n\nSource code lives at `adom-inc/adom-3d-viewer-babylon9` (private repo). The\ncanonical install artifact is the wiki tarball.\n",+ "readme": "# adom-3d-viewer-babylon9\n\nA fork of Colby's `adom-3d-viewer` (Babylon 7.54) bumped to Babylon 9.5.0 with\nthe redesigned Inspector v9. Built as an ESM bundle for downstream Adom tools\nto vendor \u2014 chiplinter consumes it today, and we expect it to back the next\n~10 Adom 3D viewers.\n\n## Why fork\n\nColby's `adom-3d-viewer` is the canonical viewer for InstaPCB previews and\nchipfit, but it's pinned to Babylon 7.54 because chipfit-v2 + tscircuit ship\nthe same renderer. We needed Babylon 9's redesigned Inspector for chiplinter's\nscene-graph debugging and didn't want to disturb Colby's surface area, so this\nis a parallel fork.\n\n## What's in the bundle\n\nThe build produces a single ESM entry plus code-split chunks:\n\n```\nadom-3d-viewer-babylon9.esm.js \u2190 entry, sets window.Adom3DViewerBabylon9\nchunk-*.js \u2190 code-split chunks (Babylon core, inspector, etc.)\nVERSION\n```\n\nLoaded via:\n\n```html\n<script type=\"module\">\n await import('/path/to/adom-3d-viewer-babylon9.esm.js');\n const v = window.Adom3DViewerBabylon9;\n v.init(host, { zUp: true, modelUrl: 'asset/foo.glb' });\n</script>\n```\n\n## Why ESM (not IIFE)\n\nBabylon 9's `@babylonjs/inspector` has circular imports that resolve to TDZ\nwhen collapsed into a single IIFE scope (regardless of minifier). Vite's ESM\noutput preserves module boundaries so the inspector initializes cleanly.\nConsumers load via `<script type=\"module\">`, which all modern browsers\nsupport.\n\n## API\n\n```js\nwindow.Adom3DViewerBabylon9 = {\n init(host, options), // mounts the viewer in `host`, returns ViewerInstance\n rotateYUpToZUp(scene), // for kicad-cli GLBs (Y-up) \u2192 adom viewer (Z-up)\n addLaserEtch(scene, opts), // bake a laser-etched chip-marking text overlay\n BABYLON: <full @babylonjs/core namespace>, // re-exported for consumers\n};\n```\n\n`ViewerInstance` exposes:\n- `loadModel(url)` / `clearScene()` / `frameModel(fillFraction?)`\n- `getScene()` / `getEngine()` / `getCamera()` / `getShadowGenerator()`\n- `addContentRoot(node, opts?)` / `removeContentRoot(node)`\n- `toggleDebugLayer()` / `showDebugLayer()` / `hideDebugLayer()`\n- `setGroundVisible(visible)` / `goHome()`\n- `setProjectionMode(ortho)` / `getProjectionMode()`\n- `destroy()`\n\nThe full `@babylonjs/core` namespace is exposed at `Adom3DViewerBabylon9.BABYLON`\nso consumers don't need their own `import` side \u2014 chiplinter uses\n`V.BAB.MeshBuilder.CreateDisc`, `V.BAB.PBRMaterial`, `V.BAB.Quaternion`,\n`V.BAB.Tools.CreateScreenshotUsingRenderTarget`, etc. directly.\n\n## Install (drop into a tool's vendor/3d-viewer/)\n\nThe wiki ships the bundle as a tarball. Pull it into your tool's vendor\ndirectory at install time:\n\n```bash\n# Install everything to a known shared location\nsudo mkdir -p /usr/local/share/adom-3d-viewer-babylon9\ncurl -fsSL https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-3d-viewer-babylon9/adom-3d-viewer-babylon9.tar.gz \\\n | sudo tar -xz -C /usr/local/share/adom-3d-viewer-babylon9\n\n# Then symlink (or copy) into your tool's vendor/3d-viewer/\nln -sfn /usr/local/share/adom-3d-viewer-babylon9 /usr/local/bin/vendor/3d-viewer\n```\n\nOr just curl individual files if your tool only needs the entry (`adom-3d-viewer-babylon9.esm.js`):\n\n```bash\ncurl -fsSL https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-3d-viewer-babylon9/adom-3d-viewer-babylon9.tar.gz | tar -xz -C ./vendor/3d-viewer\n```\n\n## Browser shims required\n\nThe inspector's React deps (Fluent UI) assume a Node environment. Add this\nshim before loading the bundle:\n\n```html\n<script>\n window.process = window.process || { env: { NODE_ENV: 'production' } };\n window.global = window.global || window;\n</script>\n<script type=\"module\">\n await import('/path/to/adom-3d-viewer-babylon9.esm.js');\n</script>\n```\n\n## Defaults (3d-viewer-design skill compliance)\n\n| Rule | Status | Notes |\n|---|---|---|\n| \u00a71 Babylon engine | \u2705 | `@babylonjs/core` 9.5.0 |\n| \u00a73b Background gradient `#5a6b7e \u2192 #2a3340` | \u2705 | `SceneBuilder.ts` |\n| \u00a74a HDRI environment | \u2705 | bundled `.env` cube texture |\n| \u00a74b Bottom-light toggle | \u2705 | exposed via consumer toolbar (HemisphericLight ground-color boost) |\n| \u00a74d Ground plane + ShadowGenerator(8192) | \u2705 | medium-gray ground, blur PCF, optional via `showGround` prop |\n| \u00a75a PBRMaterial default | \u2705 | every internal material is PBR |\n| \u00a76a `zoomToMouseLocation = true` | \u2705 | `AdomCamera.ts` |\n| \u00a76c Shift+Alt+Click recenter | \u2705 | `AdomCamera.ts` |\n| \u00a77 ViewCube + tween presets | \u2705 | `ViewCubeBuilder.ts` |\n| **\u00a78a World-origin axes (default ON)** | \u2705 **v0.2.0** | R/G/B at scene origin, scaled to 15% of scene radius via `refreshAxisScale` after each `frameModel` |\n| **\u00a78b Mesh-local axes (default OFF, toggleable)** | \u2705 **v0.2.0** | parented to each loaded GLB root via `addMeshLocalAxes` |\n| **\u00a78c Screen-space corner triad (always on)** | \u26a0 **deferred to v0.3.0** | Second-camera-with-viewport approach didn't render \u2014 `engine.runRenderLoop(() => scene.render())` honors `scene.activeCamera` only, not the `activeCameras` array. v0.3.0 will use `UtilityLayerRenderer` with an explicit secondary `engine.render()` pass. \u00a78a + \u00a78b cover the bulk of \"where is origin\" debugging in the meantime. |\n| \u00a76b.i Adaptive `wheelDeltaPercentage` (`100/R`) | \u26a0 open | currently a constant `0.1`; pan + radius limits ARE adaptive |\n| \u00a711 Y-up\u2192Z-up | \u2705 | `rotateYUpToZUp(scene)` exposed on the global |\n\n## \u00a78 axis-helper API (v0.2.0)\n\n```js\n// World axes (default ON) \u2014 R/G/B at scene origin, sized to 15% of scene radius.\nviewer.toggleAxes('world'); // toggle\nviewer.toggleAxes('world', true); // explicit set\nviewer.getAxesState(); // \u2192 { world: bool, meshLocal: bool }\n\n// Mesh-local axes (default OFF) \u2014 auto-attaches to each loaded GLB root.\nviewer.toggleAxes('mesh-local'); // toggle\n```\n\nReach the helpers directly via `scene.metadata.__adomAxes` if you want to add\nor remove per-root helpers programmatically (e.g. while debugging a custom\nloader path that bypasses `loadModel`).\n\n## Consumers\n\n- `adom-chiplinter` \u2014 vendors `dist-standalone/` into `vendor/3d-viewer/`\n- (future) `adom-chipfit-v3` \u2014 when v2 lands its own Babylon 9 upgrade\n- (future) standalone scene-graph utility scripts\n\n## Source\n\nSource code lives at `adom-inc/adom-3d-viewer-babylon9` (private repo). The\ncanonical install artifact is the wiki tarball.\n", "author": { "name": "Kyle Bergstedt", "email": "[email protected]"