← Commit history
page.json+3−3@@ -4,7 +4,7 @@ "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.7.2",+ "version": "0.7.3", "tags": [ "3d", "viewer",@@ -28,7 +28,7 @@ "install_hint": "", "version_cmd": "" },- "readme": "# Adom 3D Viewer\n\nThe Babylon 9.5 viewer engine behind every component page's 3D tab on\nwiki.adom.inc. A fork of `adom-inc/3d-viewer` (Babylon 7.54) upgraded to\nBabylon 9.5 with the redesigned Inspector v9, built as a versioned ESM bundle\nthat downstream tools vendor (the wiki's native component viewer, chiplinter,\nand the next wave of Adom 3D apps).\n\nThis page is the canonical home: the source lives on the Files tab\n(`adom-wiki repo clone adom/adom-3d-viewer`), and each version's\nbuilt bundle is attached as a release asset you can pin.\n\n## What is in 0.4.x\n\n- Layers toolbar: slide-out per-layer visibility panel driven by the node\n naming convention (fr4_board, pad_top, silk, barrel, pin1_marker, ...).\n- Z-fighting fixes for PCB models: 10x depth precision, polygon-offset\n tie-breaking for nested shells, near plane at radius/50, XY-area container\n ordering.\n- Skybox mesh replaced by a screen-space background layer (tight far plane,\n faded ground rim): frameModel no longer fits a 5000-unit skybox.\n- Sandbox storage guard: localStorage/sessionStorage access is wrapped, so the\n viewer initializes fully (lights, IBL, shadows) inside sandboxed iframes.\n- Transparent radial-fade ground, hover tooltips, orbit-center UX,\n world-origin and mesh-local axis helpers, laser-etch text overlays.\n\n## Get the bundle (pin a version)\n\nEvery release attaches the built bundle as a tarball asset:\n\n```bash\nadom-wiki release download adom/adom-3d-viewer <version> adom-3d-viewer-babylon9-<version>.tar.gz\ntar -xzf adom-3d-viewer-babylon9-<version>.tar.gz -C ./vendor/3d-viewer/\n```\n\nThe extracted `VERSION` file records exactly which build you have. The bundle\ncode-splits into ~60 chunks; serve them all from the same directory as the\nentry (`adom-3d-viewer-babylon9.esm.js`) and browsers fetch chunks on demand.\n\n## Embed it\n\n```html\n<!-- Browser shim for Node-style globals that @babylonjs/inspector's React\n (Fluent UI) deps assume. Add BEFORE loading the bundle. -->\n<script>\n window.process = window.process || { env: { NODE_ENV: \"production\" } };\n window.global = window.global || window;\n</script>\n\n<script type=\"module\">\n await import(\"./vendor/3d-viewer/adom-3d-viewer-babylon9.esm.js\");\n const v = window.Adom3DViewerBabylon9;\n const viewer = v.init(host, { zUp: true, showViewCube: true });\n await viewer.loadModel(\"chip.glb\");\n viewer.frameModel();\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. The\nglobal is `window.Adom3DViewerBabylon9` (distinct from the legacy\n`window.Adom3DViewer`), so both bundles can coexist during a migration.\n\n## API\n\n```js\nwindow.Adom3DViewerBabylon9 = {\n init(host, options), // mounts the viewer, returns ViewerInstance\n rotateYUpToZUp(scene), // kicad-cli GLBs (Y-up) -> adom viewer (Z-up)\n addLaserEtch(scene, opts), // bake a laser-etched chip-marking text overlay\n version: \"0.5.0\", // this build, injected from package.json\n BABYLON: <full @babylonjs/core namespace>, // re-exported for consumers\n};\n```\n\n`ViewerInstance` exposes:\n\n- `loadModel(url)` / `loadModelBytes(bytes, { extension? })` / `clearScene()` / `frameModel(fillFraction?)`\n- `whenReady()` / `getReadyReport()`: the ready report (see \"Sandboxed\n frames\" below): resolves once the first scene is up and reflects the\n current state on every later call; never rejects\n- `getScene()` / `getEngine()` / `getCamera()` / `getShadowGenerator()`\n- `addContentRoot(node, opts?)` / `removeContentRoot(node)`\n- `toggleDebugLayer()` / `showDebugLayer()` / `hideDebugLayer()`\n- `setGroundVisible(visible)` / `goHome()`\n- `setBottomLight(on)` / `getBottomLightState()`: underside fill light, default off\n- `setProjectionMode(ortho)` / `getProjectionMode()`\n- `toggleAxes(\"world\" | \"mesh-local\", force?)` / `getAxesState()`\n- `getLayers()` / `setLayerVisible(name, visible)`: layers, either declared by\n the content via `extras.adomLayer` or matched against the built-in board\n vocabulary (`docs/CONTENT-CONVENTIONS.md`). Each entry carries `group` for\n sectioning and `declared` to say which source it came from. Empty for GLBs\n with fewer than two layers\n- `captureScreenshot({ width?, height? })`: resolves to a PNG data URL.\n Renders through an offscreen target, so the result does not depend on the\n on-screen canvas size\n- `setShadowRefreshRate(rate | null)`: pin the shadow map refresh rate;\n `null` restores automatic behaviour. Needed for content animated from\n outside the viewer, which `scene.animationGroups` cannot see\n- `destroy()`\n\n`init()` options: `zUp`, `modelUrl`, `showViewCube`, `showGround`,\n`environmentUrl`, `environmentBytes`, `environment` (`\"studio\"` | `\"none\"`),\n`initialViewMode`, `onReady(report)`, `onMeshHover(mesh, tip)`, and\n`onGroundCreated(ground)`. The hover\nhook is called on the pick the viewer already performs: return a string to\noverride the tooltip, `null` to suppress it, or nothing to leave the viewer's\nown text alone. It is called with `(null, null)` when the pointer leaves\ncontent, so a consumer-driven highlight can clear itself.\n\n`onGroundCreated` is called with the ground mesh after every rebuild. The\nground's geometry belongs to the viewer, because it is sized from content bounds\nand rebuilt whenever the model is reframed; its appearance does not, so this is\nwhere a consumer applies its own ground material. Setting the material once from\noutside will not survive the next reframe.\n\n### Sandboxed frames (wiki widgets and readmes)\n\nThe wiki's widget and readme frames are opaque origins under a strict CSP\n(`connect-src 'self' data:`, `img-src data: https:`, no `blob:`), and every\n`localStorage` access there throws. Since 0.7.0 the viewer is built for that\n(adom/adom-3d-viewer#5):\n\n### Orbit\n\nThe camera orbits freely through both poles (0.7.1). Dragging through a flat\ntop or bottom view keeps rotating in the same direction; there is no stop\nnear the underside and no beta limit. Presets (`front`, `back`, the view cube)\nstill land upright. `npm run test:orbit` drives real pointer drags across both\npoles in the Y-up and Z-up frames.\n\n### View cube: click on release, drag to orbit\n\nA view-cube face navigates on mouse RELEASE (0.7.2, adom/adom-3d-viewer#4),\nnot on press: pressing on the cube and dragging orbits the model exactly like\ndragging on the model, the way Fusion's cube behaves. A release within 4 px\nof the press, still over the same face, is the click that animates the camera\nto that face. `npm run test:viewcube` checks all three cases (drag on the cube\nmatches a drag on the model, a clean click snaps on release, a wander does\nnot snap).\n\n- The studio environment map loads from memory (Babylon's buffer option), and\n images (environment mip levels, GLB-embedded textures) decode as\n ImageBitmaps, so no `blob:` URL is ever fetched. `environmentBytes` injects\n your own `.env` bytes the same way; `environment: \"none\"` skips the map.\n- Preferences fall back to document-local memory when storage is denied; the\n report says `storage: \"ephemeral\"`.\n- `loadModelBytes(bytes)` takes a model the host already fetched or verified,\n so the frame's CSP never sees a model URL.\n- The loading overlay always comes down, model failure included, and\n `whenReady()` resolves with a report:\n\n```js\nconst viewer = Adom3DViewerBabylon9.init(host, { modelUrl: \"/adom/part/render/part.glb\" });\nconst report = await viewer.whenReady();\n// { ok, engine: { webglVersion, contextLost }, environment: { source, ready, error },\n// camera: { ready, mode }, storage: \"persistent\" | \"ephemeral\",\n// loadingOverlay: \"hidden\" | \"visible\", model: { requested, loaded, meshes, vertices, error },\n// cspViolations: [{ directive, blocked }], hints: [{ code, level, message, action }], version }\n```\n\n`ok` is true only when the scene rendered, the overlay is gone, the\nenvironment is ready (or deliberately absent), no CSP violation was recorded\nand any requested model loaded with geometry. Otherwise the hints name the fix:\n`CSP_BLOCKED`, `MODEL_LOAD_FAILED`, `MODEL_EMPTY`, `ENVIRONMENT_FAILED`,\n`ENVIRONMENT_PENDING`, `STORAGE_EPHEMERAL` (info), `LOADING_OVERLAY_STUCK`,\n`WEBGL_CONTEXT_LOST`.\n\nOne thing the frame's host must do: an opaque origin fetches module scripts in\nCORS mode, so the bundle must be served with `Access-Control-Allow-Origin`\n(the wiki's `/static/vendor/` route does).\n\n`npm run test:sandbox` proves all of it in headless Chrome: an https server\ncarrying the wiki's exact widget CSP, an `sandbox=\"allow-scripts\"` iframe, a\nready report that says ok, painted chip pixels, then three destroy/recreate\nrounds alternating URL and bytes transport. Reads `puppeteer-core` and a\nChrome from `~/.cache/puppeteer` (or `PUPPETEER_EXECUTABLE_PATH`).\n\n### Scale\n\nMillimetre-scale models are supported. The near plane is `radius/50`\nrecomputed per frame, and light height, intensity, panning speed and radius\nlimits are all derived from model size, so a 5 mm part and a 500 mm assembly\nboth frame and light correctly without a unit setting.\n\nThe full `@babylonjs/core` namespace is exposed at\n`Adom3DViewerBabylon9.BABYLON` so consumers do not need their own import side.\nchiplinter uses `V.BABYLON.MeshBuilder.CreateDisc`, `V.BABYLON.PBRMaterial`,\n`V.BABYLON.Tools.CreateScreenshotUsingRenderTarget`, and friends directly.\n\n## Build from source\n\n```bash\nadom-wiki repo clone adom/adom-3d-viewer\ncd adom-3d-viewer\nnpm install\nnpx vite build --config vite.standalone.config.ts # -> dist-standalone/\n```\n\n`npm run build` (plain `vite build`) produces the npm-consumable `dist/`\nlibrary instead; `dist-standalone/` is the self-contained browser bundle the\nwiki and release assets ship.\n\n## Consumers\n\n- wiki.adom.inc component pages: git-wiki vendors `dist-standalone/` into\n `static/vendor/adom-3d-viewer-babylon9` and pins it via `VIEWER_BUNDLE_VER`.\n- `adom-chiplinter`: vendors the release tarball into `vendor/3d-viewer/`.\n- Downstream viewer work is tracked on adom/wiki issues (#48, #53, #60).\n\n## Development\n\nSource of record is this page's repo. GitHub `adom-inc/adom-3d-viewer-babylon9`\nis the working mirror where CI and day-to-day commits happen; each released\nversion is ported here (source push + package publish + bundle release asset).\n",+ "readme": "# Adom 3D Viewer\n\nThe Babylon 9.5 viewer engine behind every component page's 3D tab on\nwiki.adom.inc. A fork of `adom-inc/3d-viewer` (Babylon 7.54) upgraded to\nBabylon 9.5 with the redesigned Inspector v9, built as a versioned ESM bundle\nthat downstream tools vendor (the wiki's native component viewer, chiplinter,\nand the next wave of Adom 3D apps).\n\nThis page is the canonical home: the source lives on the Files tab\n(`adom-wiki repo clone adom/adom-3d-viewer`), and each version's\nbuilt bundle is attached as a release asset you can pin.\n\n## What is in 0.4.x\n\n- Layers toolbar: slide-out per-layer visibility panel driven by the node\n naming convention (fr4_board, pad_top, silk, barrel, pin1_marker, ...).\n- Z-fighting fixes for PCB models: 10x depth precision, polygon-offset\n tie-breaking for nested shells, near plane at radius/50, XY-area container\n ordering.\n- Skybox mesh replaced by a screen-space background layer (tight far plane,\n faded ground rim): frameModel no longer fits a 5000-unit skybox.\n- Sandbox storage guard: localStorage/sessionStorage access is wrapped, so the\n viewer initializes fully (lights, IBL, shadows) inside sandboxed iframes.\n- Transparent radial-fade ground, hover tooltips, orbit-center UX,\n world-origin and mesh-local axis helpers, laser-etch text overlays.\n\n## Get the bundle (pin a version)\n\nEvery release attaches the built bundle as a tarball asset:\n\n```bash\nadom-wiki release download adom/adom-3d-viewer <version> adom-3d-viewer-babylon9-<version>.tar.gz\ntar -xzf adom-3d-viewer-babylon9-<version>.tar.gz -C ./vendor/3d-viewer/\n```\n\nThe extracted `VERSION` file records exactly which build you have. The bundle\ncode-splits into ~60 chunks; serve them all from the same directory as the\nentry (`adom-3d-viewer-babylon9.esm.js`) and browsers fetch chunks on demand.\n\n## Embed it\n\n```html\n<!-- Browser shim for Node-style globals that @babylonjs/inspector's React\n (Fluent UI) deps assume. Add BEFORE loading the bundle. -->\n<script>\n window.process = window.process || { env: { NODE_ENV: \"production\" } };\n window.global = window.global || window;\n</script>\n\n<script type=\"module\">\n await import(\"./vendor/3d-viewer/adom-3d-viewer-babylon9.esm.js\");\n const v = window.Adom3DViewerBabylon9;\n const viewer = v.init(host, { zUp: true, showViewCube: true });\n await viewer.loadModel(\"chip.glb\");\n viewer.frameModel();\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. The\nglobal is `window.Adom3DViewerBabylon9` (distinct from the legacy\n`window.Adom3DViewer`), so both bundles can coexist during a migration.\n\n## API\n\n```js\nwindow.Adom3DViewerBabylon9 = {\n init(host, options), // mounts the viewer, returns ViewerInstance\n rotateYUpToZUp(scene), // kicad-cli GLBs (Y-up) -> adom viewer (Z-up)\n addLaserEtch(scene, opts), // bake a laser-etched chip-marking text overlay\n version: \"0.5.0\", // this build, injected from package.json\n BABYLON: <full @babylonjs/core namespace>, // re-exported for consumers\n};\n```\n\n`ViewerInstance` exposes:\n\n- `loadModel(url)` / `loadModelBytes(bytes, { extension? })` / `clearScene()` / `frameModel(fillFraction?)`\n- `whenReady()` / `getReadyReport()`: the ready report (see \"Sandboxed\n frames\" below): resolves once the first scene is up and reflects the\n current state on every later call; never rejects\n- `getScene()` / `getEngine()` / `getCamera()` / `getShadowGenerator()`\n- `addContentRoot(node, opts?)` / `removeContentRoot(node)`\n- `toggleDebugLayer()` / `showDebugLayer()` / `hideDebugLayer()`\n- `setGroundVisible(visible)` / `goHome()`\n- `setBottomLight(on)` / `getBottomLightState()`: underside fill light, default off\n- `setProjectionMode(ortho)` / `getProjectionMode()`\n- `toggleAxes(\"world\" | \"mesh-local\", force?)` / `getAxesState()`\n- `getLayers()` / `setLayerVisible(name, visible)`: layers, either declared by\n the content via `extras.adomLayer` or matched against the built-in board\n vocabulary (`docs/CONTENT-CONVENTIONS.md`). Each entry carries `group` for\n sectioning and `declared` to say which source it came from. Empty for GLBs\n with fewer than two layers\n- `captureScreenshot({ width?, height? })`: resolves to a PNG data URL.\n Renders through an offscreen target, so the result does not depend on the\n on-screen canvas size\n- `setShadowRefreshRate(rate | null)`: pin the shadow map refresh rate;\n `null` restores automatic behaviour. Needed for content animated from\n outside the viewer, which `scene.animationGroups` cannot see\n- `destroy()`\n\n`init()` options: `zUp`, `modelUrl`, `showViewCube`, `showGround`,\n`environmentUrl`, `environmentBytes`, `environment` (`\"studio\"` | `\"none\"`),\n`initialViewMode`, `onReady(report)`, `onMeshHover(mesh, tip)`, and\n`onGroundCreated(ground)`. The hover\nhook is called on the pick the viewer already performs: return a string to\noverride the tooltip, `null` to suppress it, or nothing to leave the viewer's\nown text alone. It is called with `(null, null)` when the pointer leaves\ncontent, so a consumer-driven highlight can clear itself.\n\n`onGroundCreated` is called with the ground mesh after every rebuild. The\nground's geometry belongs to the viewer, because it is sized from content bounds\nand rebuilt whenever the model is reframed; its appearance does not, so this is\nwhere a consumer applies its own ground material. Setting the material once from\noutside will not survive the next reframe.\n\n### Sandboxed frames (wiki widgets and readmes)\n\nThe wiki's widget and readme frames are opaque origins under a strict CSP\n(`connect-src 'self' data:`, `img-src data: https:`, no `blob:`), and every\n`localStorage` access there throws. Since 0.7.0 the viewer is built for that\n(adom/adom-3d-viewer#5):\n\n### Orbit\n\nThe camera orbits freely through both poles (0.7.1). Dragging through a flat\ntop or bottom view keeps rotating in the same direction; there is no stop\nnear the underside and no beta limit. Presets (`front`, `back`, the view cube)\nstill land upright. `npm run test:orbit` drives real pointer drags across both\npoles in the Y-up and Z-up frames.\n\n### The ? button: controls card and the Shift+Alt tip\n\nEvery viewer draws a small `?` in its bottom-right corner (0.7.3). The card it\nopens leads with the move that makes large boards and scaffolds navigable:\nShift+Alt+click a point on the model to set the centre of rotation (a glowing\ndot marks it; orbit and zoom then work around that spot). The rest of the\ncontrols follow: drag to orbit, right-drag or Ctrl+drag to pan, scroll to zoom\ntoward the cursor, the cube faces with Home and Fit, hold Space to spin. The\n`?` key and Escape toggle the card. The first time a model is ready in a\nbrowser, a tip bubble says the Shift+Alt line once and is then remembered\n(ephemeral storage in sandboxed frames). `init(host, { showHelp: false })`\nhides all of it for hosts that draw their own help; `viewer.showHelp()` and\n`viewer.hideHelp()` drive the card. `npm run test:help` covers it.\n\n### View cube: click on release, drag to orbit\n\nA view-cube face navigates on mouse RELEASE (0.7.2, adom/adom-3d-viewer#4),\nnot on press: pressing on the cube and dragging orbits the model exactly like\ndragging on the model, the way Fusion's cube behaves. A release within 4 px\nof the press, still over the same face, is the click that animates the camera\nto that face. `npm run test:viewcube` checks all three cases (drag on the cube\nmatches a drag on the model, a clean click snaps on release, a wander does\nnot snap).\n\n- The studio environment map loads from memory (Babylon's buffer option), and\n images (environment mip levels, GLB-embedded textures) decode as\n ImageBitmaps, so no `blob:` URL is ever fetched. `environmentBytes` injects\n your own `.env` bytes the same way; `environment: \"none\"` skips the map.\n- Preferences fall back to document-local memory when storage is denied; the\n report says `storage: \"ephemeral\"`.\n- `loadModelBytes(bytes)` takes a model the host already fetched or verified,\n so the frame's CSP never sees a model URL.\n- The loading overlay always comes down, model failure included, and\n `whenReady()` resolves with a report:\n\n```js\nconst viewer = Adom3DViewerBabylon9.init(host, { modelUrl: \"/adom/part/render/part.glb\" });\nconst report = await viewer.whenReady();\n// { ok, engine: { webglVersion, contextLost }, environment: { source, ready, error },\n// camera: { ready, mode }, storage: \"persistent\" | \"ephemeral\",\n// loadingOverlay: \"hidden\" | \"visible\", model: { requested, loaded, meshes, vertices, error },\n// cspViolations: [{ directive, blocked }], hints: [{ code, level, message, action }], version }\n```\n\n`ok` is true only when the scene rendered, the overlay is gone, the\nenvironment is ready (or deliberately absent), no CSP violation was recorded\nand any requested model loaded with geometry. Otherwise the hints name the fix:\n`CSP_BLOCKED`, `MODEL_LOAD_FAILED`, `MODEL_EMPTY`, `ENVIRONMENT_FAILED`,\n`ENVIRONMENT_PENDING`, `STORAGE_EPHEMERAL` (info), `LOADING_OVERLAY_STUCK`,\n`WEBGL_CONTEXT_LOST`.\n\nOne thing the frame's host must do: an opaque origin fetches module scripts in\nCORS mode, so the bundle must be served with `Access-Control-Allow-Origin`\n(the wiki's `/static/vendor/` route does).\n\n`npm run test:sandbox` proves all of it in headless Chrome: an https server\ncarrying the wiki's exact widget CSP, an `sandbox=\"allow-scripts\"` iframe, a\nready report that says ok, painted chip pixels, then three destroy/recreate\nrounds alternating URL and bytes transport. Reads `puppeteer-core` and a\nChrome from `~/.cache/puppeteer` (or `PUPPETEER_EXECUTABLE_PATH`).\n\n### Scale\n\nMillimetre-scale models are supported. The near plane is `radius/50`\nrecomputed per frame, and light height, intensity, panning speed and radius\nlimits are all derived from model size, so a 5 mm part and a 500 mm assembly\nboth frame and light correctly without a unit setting.\n\nThe full `@babylonjs/core` namespace is exposed at\n`Adom3DViewerBabylon9.BABYLON` so consumers do not need their own import side.\nchiplinter uses `V.BABYLON.MeshBuilder.CreateDisc`, `V.BABYLON.PBRMaterial`,\n`V.BABYLON.Tools.CreateScreenshotUsingRenderTarget`, and friends directly.\n\n## Build from source\n\n```bash\nadom-wiki repo clone adom/adom-3d-viewer\ncd adom-3d-viewer\nnpm install\nnpx vite build --config vite.standalone.config.ts # -> dist-standalone/\n```\n\n`npm run build` (plain `vite build`) produces the npm-consumable `dist/`\nlibrary instead; `dist-standalone/` is the self-contained browser bundle the\nwiki and release assets ship.\n\n## Consumers\n\n- wiki.adom.inc component pages: git-wiki vendors `dist-standalone/` into\n `static/vendor/adom-3d-viewer-babylon9` and pins it via `VIEWER_BUNDLE_VER`.\n- `adom-chiplinter`: vendors the release tarball into `vendor/3d-viewer/`.\n- Downstream viewer work is tracked on adom/wiki issues (#48, #53, #60).\n\n## Development\n\nSource of record is this page's repo. GitHub `adom-inc/adom-3d-viewer-babylon9`\nis the working mirror where CI and day-to-day commits happen; each released\nversion is ported here (source push + package publish + bundle release asset).\n", "author": { "name": "Kyle Bergstedt", "email": "[email protected]"@@ -62,4 +62,4 @@ "uninstall": "./uninstall.sh" }, "org": "adom"-}+}