← Commit history

Publish 0.7.2

Colby Knox ·1829d2b681 · ·parent 594c843
1 file changed +2−2
page.json+2−2
@@ -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.1",+  "version": "0.7.2",   "tags": [     "3d",     "viewer",@@ -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 \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.adom.inc/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.adom.inc/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",+  "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",   "author": {     "name": "Kyle Bergstedt",     "email": "[email protected]"