Adom 3D Viewer

{
  "schema_version": 1,
  "type": "app",
  "slug": "adom-3d-viewer",
  "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": [
    "3d",
    "viewer",
    "babylon",
    "glb",
    "pcb",
    "component-pages"
  ],
  "license": "MIT",
  "discovery_triggers": [
    "embed a 3d viewer for a glb model",
    "show a pcb or component in 3d",
    "babylon viewer for adom pages",
    "load the adom 3d viewer bundle",
    "layers toolbar for a 3d board view"
  ],
  "discovery_pitch": "The Babylon 9.5 ESM viewer engine that renders every component page's 3D tab on wiki.adom.inc: GLB loading, view cube, layers toolbar, shadows, laser-etch text, Z-up CAD framing.",
  "install": {
    "binary_name": "adom-3d-viewer-babylon9",
    "install_dir": "",
    "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 \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]"
  },
  "visibility": {
    "public": true
  },
  "hero": {
    "type": "billboard",
    "headline": "Adom 3D Viewer",
    "subhead": "The Babylon 9 engine behind every component page",
    "screenshot": "viewer-screenshot.png"
  },
  "sample_prompts": [
    {
      "label": "Embed the viewer",
      "prompt": "Load the adom 3d viewer bundle into my page and show model.glb"
    },
    {
      "label": "Pin a version",
      "prompt": "Download the 0.4.3 viewer bundle so my tool vendors a fixed build"
    }
  ],
  "metadata": {},
  "created_at": "2026-05-28T05:29:10.602Z",
  "updated_at": "2026-05-28T05:29:10.602Z",
  "skills": [],
  "name": "adom-3d-viewer-babylon9",
  "description": "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.",
  "dependencies": {},
  "scripts": {
    "install": "./install.sh",
    "uninstall": "./uninstall.sh"
  },
  "org": "adom"
}