← Commit history
README.md+207−12@@ -74,6 +74,7 @@ window.Adom3DViewerBabylon9 = { version: "0.11.0", // this build, injected from package.json BABYLON: <common @babylonjs/core classes>, // also window.BABYLON loadBabylon(), // Promise of the whole @babylonjs/core; fills BABYLON in+ babylonVersion: "9.5.0", // the Babylon.js release BABYLON and loadBabylon() come from }; ``` @@ -100,6 +101,20 @@ window.Adom3DViewerBabylon9 = { - `setGroundVisible(visible)` / `goHome()` / `setHomeView({ alpha, beta, radiusScale?, target? } | null)`: Home (the view cube and `goHome()`) goes to the host's view when one is set, else the top-front-right corner (0.9.2, adom/adom-3d-viewer#9). `target: [x, y, z]` is the point that view orbits, in the model's own frame (a GLB's coordinates, Z up, as the viewer shows them); without it the view aims at the model's bounding-box center (0.12.3, adom/wiki#237) - `setBottomLight(on)` / `getBottomLightState()`: underside fill light, default off - `setProjectionMode(ortho)` / `getProjectionMode()`+- `getCameraState()`: `{ alpha, beta, radius, target: [x, y, z] }`, angles in radians+- `moveCamera(to, { ms? })`: `to` is a view (`"home"`, `"fit"`, or a view+ cube face: `"front"`, `"back"`, `"left"`, `"right"`, `"top"`, `"bottom"`)+ or any part of a camera state. With `ms` it eases there the short way+ round. A face view lands where clicking that cube face does. Resolves with+ the final state; a new move cancels the one in flight, and a move ends+ where it was asked to even when the browser throttles animation frames+- `orbit({ degrees?, ms? })`: turn around the target, 360 degrees over+ 4000 ms by default+- `openGate()` / `isGated()`: start a viewer created with `gate`, as its+ Load button does; resolves with the ready report+- `on(event, listener)`, `findNodes(query)`, `highlight(target, options?)`,+ `clearHighlight()`, `isolate(target, options?)`, `clearIsolate()`,+ `focus(target, { ms? })`: see "Events, highlight and isolate" below - `toggleAxes("world" | "mesh-local", force?)` / `getAxesState()` - `getLayers()` / `setLayerVisible(name, visible)`: layers, either declared by the content via `extras.adomLayer` or matched against the built-in board@@ -112,12 +127,138 @@ window.Adom3DViewerBabylon9 = { - `setShadowRefreshRate(rate | null)`: pin the shadow map refresh rate; `null` restores automatic behavior. Needed for content animated from outside the viewer, which `scene.animationGroups` cannot see-- `destroy()`+- `destroy()`: releases this viewer's engine, scene and listeners++Each `init()` returns an independent viewer with its own canvas, WebGL+context, engine, scene, camera, lights and view cube, so a page can hold+several. Each one costs a WebGL context and, unless `shadows` is false, a+shadow map: 8192 x 8192 (about 256 MB of GPU memory) while it is the only+viewer with shadows, 4096 with up to four, 2048 beyond that. Live viewers'+maps resize as viewers come and go. Browsers cap the live contexts per page,+so destroy viewers a page no longer shows. `init()` options: `zUp`, `modelUrl`, `showViewCube`, `showGround`, `environmentUrl`, `environmentBytes`, `environment` (`"studio"` | `"none"`),-`initialViewMode`, `onReady(report)`, `onMeshHover(mesh, tip)`, and-`onGroundCreated(ground)`. The hover+`initialViewMode`, `onReady(report)`, `onMeshHover(mesh, tip)`,+`onGroundCreated(ground)`, `onContextLost()`, `onContextRestored()`,+`showHelp`, `lightBudget`, `intros`, `gate`, and these scene options:++| Option | Default | Effect |+|---|---|---|+| `animate` | `true` | `false` holds every animation group at its first frame after each load |+| `repeat` | `0` | an animation the model starts with plays this many times, then rests on its last frame; `0` loops |+| `tooltips` | `"all"` | `"authored"` shows only `extras.tooltip` labels; `"off"` shows none. `onMeshHover` still runs |+| `axes` | `true` | world axes at startup |+| `bottomLight` | `false` | bottom fill light at startup |+| `shadows` | `true` | `false` turns shadows off and skips the shadow map; `getShadowGenerator()` then returns null |+| `homeView` | none | `{ alpha, beta, radiusScale?, target? }`, the view Home goes to (as `setHomeView`) |+| `homeOnLoad` | `false` | the first model load opens at Home instead of the starting top-down view |+| `loadTimeoutMs` | `0` | a URL load that has not finished in this time rejects and the ready report says `MODEL_LOAD_TIMEOUT`; a model that arrives later is discarded. `0` waits forever |+| `background` | `"studio"` | `"transparent"` clears to alpha 0 so the page shows through (screenshots keep the alpha); `"#rrggbb"` is a flat color. Anything else throws |++`replayAnimations()` plays the model's animations again from their first+frame, `repeat` times (looping when `repeat` is 0 and `animate` is on), and+returns false when there are none. Layer intros replay with `replayIntros()`.++### Events, highlight and isolate++`on(event, listener)` adds a listener and returns a function that removes it.+An unknown event name throws. A listener that throws is logged and does not+stop the others.++| Event | Fires | Carries |+|---|---|---|+| `"pick"` | a click that did not drag | `{ mesh, path, point, x, y, button, shiftKey, ctrlKey, altKey, metaKey }` |+| `"hover"` | the content mesh under the pointer changes | `{ mesh, path, point, x, y }` |+| `"load"` | a model was added or replaced, by any load call or `modelUrl` | `{ url, root, meshes }`; `url` is null for bytes |+| `"error"` | a model load failed or timed out | `{ url, message, code }`, `code` `"MODEL_LOAD_FAILED"` or `"MODEL_LOAD_TIMEOUT"` |+| `"camera"` | the view changed; at most once per rendered frame | the camera state, as `getCameraState()` |+| `"layer"` | a layer was shown or hidden, from the panel or `setLayerVisible` | `{ name, visible }` |+| `"contextlost"`, `"contextrestored"` | as `onContextLost` and `onContextRestored` | `{}` |++Pick and hover in detail:++- `"pick"` fires on a click that did not drag (an orbit or pan is not a+ pick). `mesh` is the content mesh under the pointer, or `null` on empty+ space. A double-click is two picks and then the viewer's own focus move;+ Shift+Alt+click places the orbit pivot and is not a pick.+- `"hover"` fires when the content mesh under the pointer changes, and once+ with `mesh: null` when the pointer leaves content.++Both carry `{ mesh, path, point, x, y }`: `path` is the node names from the+model root down to the mesh, `point` the world position hit, `x` and `y`+the pointer in CSS pixels from the canvas's top left. A pick adds `button` and the modifier keys.+Only loaded models and content roots are reported, never the ground, axes+or view cube, and the view cube's corner fires no pick.++`findNodes(query)` returns the content nodes, meshes and transform nodes,+whose name equals a string, matches a RegExp, or passes a function.++`highlight(target, { color?, alpha?, mode? })` lights a node, an array of+nodes, or whatever a `findNodes` query matches; a node lights every mesh+under it. `color` is `"#rrggbb"` or `[r, g, b]` from 0 to 1 (default blue),+`alpha` the overlay strength (default 0.75), and `mode` is `"overlay"` (the+default: a tint that stays readable on gold and metal) or `"outline"` (a+glow around the mesh). It returns `{ meshes, clear() }`. Highlights stack:+where two share a mesh the later one shows, and clearing it brings back the+one beneath. `clearHighlight()` removes them all.++```js+let selected = null;+viewer.on("pick", (e) => {+ selected?.clear();+ selected = e.mesh ? viewer.highlight(e.mesh) : null;+});+viewer.highlight(/^(lead|pin|pad)_?0*7$/i, { color: "#ffaa00" });+```++`isolate(target, { mode?, alpha? })` shows only the target. Every other content+mesh is hidden (`mode: "hide"`, the default) or drawn at `alpha` (`"ghost"`,+default 0.15), and stops taking picks. One isolation holds at a time: a new+`isolate()` replaces the last, and `clearIsolate()` or the returned `clear()`+ends it. When the target matches no mesh nothing changes and `meshes` is+empty. Layers and state groups keep working underneath, and models loaded+afterwards are not affected.++`focus(target, { ms? })` turns the camera to the target so it fills about 80%+of the view, keeping the current angles (the move double-click makes), and+eases over `ms` like `moveCamera`. It resolves with the camera state, or null+when nothing matches.++```js+const part = viewer.isolate("U3", { mode: "ghost" });+await viewer.focus("U3", { ms: 600 });+// later+part.clear();+```++### Large models and lost WebGL contexts++`gate: { bytes?, vertices?, downloadUrl? }` makes the viewer click to load.+`downloadUrl` must be an http(s) or relative URL; `init()` throws on any other,+such as `javascript:`.+It shows a card with the model's size (from `bytes` and `vertices`), a Load+button and, with `downloadUrl`, a Download link, and creates no engine, scene+or WebGL context until the reader presses Load or the host calls+`openGate()`. Model loads asked for before then wait for it, and+`whenReady()` resolves after it. Where to draw the line is the host's call:+pass `gate` only for models it judges too large to open unasked.++The browser can take a viewer's WebGL context away, when a page holds more+live contexts than it allows or the GPU resets. Nothing paints until the+context is back; the engine then rebuilds its GPU state by itself.+`onContextLost` and `onContextRestored` report both moments. A host that+would rather start over keeps the view and rebuilds:++```js+const view = viewer.getCameraState();+viewer.destroy();+viewer = Adom3DViewerBabylon9.init(host, options);+await viewer.loadModel(url);+await viewer.moveCamera(view);+```++The hover hook is called on the pick the viewer already performs: return a string to override the tooltip, `null` to suppress it, or nothing to leave the viewer's own text alone. It is called with `(null, null)` when the pointer leaves@@ -152,7 +293,8 @@ Shift+Alt+click a point on the model to set the center of rotation (a glowing dot marks it; orbit and zoom then work around that spot). The rest of the controls follow: drag to orbit, right-drag or Ctrl+drag to pan, scroll to zoom toward the cursor, the cube faces with Home and Fit, hold Space to spin. The-`?` key and Escape toggle the card. The first time a model is ready in a+`?` key and Escape toggle the card; with several viewers on a page, only the+one the pointer or focus was in last answers. The first time a model is ready in a browser, a tip bubble says the Shift+Alt line once and is then remembered (ephemeral storage in sandboxed frames). `init(host, { showHelp: false })` hides all of it for hosts that draw their own help (0.7.4: a host container that is already positioned, such as `position: absolute; inset: 0`, keeps its positioning; 0.7.3 forced it to relative, and the canvas collapsed to 150 px after the host hid and re-showed the viewer); `viewer.showHelp()` and@@ -182,7 +324,7 @@ not snap). ```js const viewer = Adom3DViewerBabylon9.init(host, { modelUrl: "/adom/part/render/part.glb" }); const report = await viewer.whenReady();-// { ok, engine: { webglVersion, contextLost }, environment: { source, ready, error },+// { ok, destroyed, engine: { webglVersion, contextLost }, environment: { source, ready, error }, // camera: { ready, mode }, storage: "persistent" | "ephemeral", // loadingOverlay: "hidden" | "visible", model: { requested, loaded, meshes, vertices, error }, // cspViolations: [{ directive, blocked }], hints: [{ code, level, message, action }], version }@@ -193,7 +335,10 @@ environment is ready (or deliberately absent), no CSP violation was recorded and any requested model loaded with geometry. Otherwise the hints name the fix: `CSP_BLOCKED`, `MODEL_LOAD_FAILED`, `MODEL_EMPTY`, `ENVIRONMENT_FAILED`, `ENVIRONMENT_PENDING`, `STORAGE_EPHEMERAL` (info), `LOADING_OVERLAY_STUCK`,-`WEBGL_CONTEXT_LOST`.+`WEBGL_CONTEXT_LOST`, `VIEWER_DESTROYED` (info). A viewer destroyed before its+scene was ready, gated and never opened or still starting, resolves+`whenReady()` with `destroyed: true` and `ok: false`; `onReady` is not called+for it. One thing the frame's host must do: an opaque origin fetches module scripts in CORS mode, so the bundle must be served with `Access-Control-Allow-Origin`@@ -212,6 +357,15 @@ recomputed per frame, and light height, intensity, panning speed and radius limits are all derived from model size, so a 5 mm part and a 500 mm assembly both frame and light correctly without a unit setting. +### Babylon classes and loadBabylon()++`getScene()`, `getEngine()`, `getCamera()` and `getShadowGenerator()` return the+viewer's live Babylon objects, and `addContentRoot(node)` brings host-built+meshes into framing, shadows, hover and picks. To build those meshes a host+needs Babylon's classes, and it must use the viewer's copy, not one of its own:+two copies of Babylon on a page do not share `instanceof`, scene components or+the engine store.+ `Adom3DViewerBabylon9.BABYLON` (also `window.BABYLON`) holds the Babylon classes host pages commonly use, bundled with the viewer: Vector2/3/4, Quaternion, Matrix, Color3/4, Axis, Space, Scalar, Mesh, AbstractMesh,@@ -233,6 +387,48 @@ a one-time warning naming the fix. Until 0.11.0 the bundle imported the whole engine for this namespace: a page downloaded 12.4 MB of script to show one model; it is about 4 MB now (1.4 MB compressed). +What a host can rely on:++- `loadBabylon()` resolves with the same module the viewer runs on, so a class+ from it is the class of the viewer's own objects (`viewer.getScene()+ instanceof (await loadBabylon()).Scene`). Calling it again returns the same+ object.+- `babylonVersion` names that Babylon.js release. A host written against+ Babylon's API checks it, not the viewer's own `version`.+- The classes listed above stay in `BABYLON` without `loadBabylon()`. Taking+ one out breaks pages that use it, as 0.11.0 did, so it is a breaking change+ and the release notes say so.+- Pass the viewer's scene (`viewer.getScene()`) when creating Babylon objects.+ Babylon puts an object created without one in the last scene created, which+ on a page with several viewers is whichever viewer started last. Each+ viewer's internal view cube scene never becomes that default.++### Board layers and pin finish++Shipped on the release line in 0.12.8 to 0.12.10; here since 0.13.0.++- Board layers. A GLB whose `Adom.Board.Top` and `Adom.Board.Bottom`+ materials carry the optional `ADOM_board_layers` glTF extension (dense or+ sparse layout) is drawn with the Round 3 shader: signed-distance copper,+ mask-opening and silk edges stay sharp close up, with a smooth handover to+ the base colour and metallic-roughness textures at normal viewing+ distances. Models without the extension, WebGPU and WebGL 1 engines, and+ failed data or shader loads keep those textures.+- Pin finish. Materials named `AdomMachineGold` get the approved machine-pin+ grain and a reflection map of their own, embedded in the bundle so no URL+ reaches the frame's CSP. `environment: 'none'` keeps the grain and drops the+ reflections.+- Lighting. Every scene uses environment intensity 0.5 and KHR PBR Neutral+ tone mapping (Board Look 0.6).++Both hook only this viewer's own glTF loads, so several viewers on one page+keep their materials apart. A model load resolves, and `load` fires, once the+board-layer and pin textures are ready, including a load called right after+`init()` or behind a closed gate. `loadTimeoutMs` covers the import, not that+wait: each of those textures gives up on its own after 10 s and leaves the+model's own textures, so a slow one never fails or discards a model that+loaded. `destroy()` releases them with the viewer.+ ## Build from source ```bash@@ -253,6 +449,11 @@ set `PUPPETEER_EXECUTABLE_PATH`, or install one into `~/.cache/puppeteer` with library instead; `dist-standalone/` is the self-contained browser bundle the wiki and release assets ship. +`VIEWER_DIST=<dir>` moves the standalone build's output, and the directory+the tests read, away from `dist-standalone/`. On a Windows/WSL live mirror,+set `VIEWER_DIST=dist/standalone` for both `build:standalone` and the tests so+the generated output stays in the mirror's excluded `dist/` folder.+ ## Consumers - wiki.adom.inc component pages: git-wiki vendors `dist-standalone/` into@@ -266,9 +467,3 @@ Source of record is GitHub `adom-inc/adom-3d-viewer-babylon9`: commits and pull requests go there, and CI builds and tests every pull request. A `vX.Y.Z` tag publishes that version here (package, source push, bundle release asset) through `scripts/release.sh`; see `publish-skills/release/SKILL.md`.--### Board layers (0.12.8)--GLBs with the optional `ADOM_board_layers` material extension use the selected Round 3 shader: signed-distance copper, mask-opening and silk edges close up, with a smooth handover to the existing base and metallic-roughness textures at normal viewing distances. Models without the extension, unsupported engines and failed data or shader loads retain those textures. The loader waits for board-layer textures, isolates each scene and releases them with their material.--For Windows/WSL live mirrors, set `VIEWER_DIST=dist/standalone` for both `build:standalone` and the tests so generated output stays in the mirror’s excluded `dist/` folder.
VERSION+1−1@@ -1 +1 @@-0.12.10+0.13.0
package.json+6−56@@ -1,63 +1,9 @@ { "name": "adom-3d-viewer-babylon9",- "version": "0.12.10",+ "version": "0.13.0", "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.", "type": "app",- "main": "./dist/index.js",- "module": "./dist/index.js",- "types": "./dist/index.d.ts",- "exports": {- ".": {- "import": "./dist/index.js",- "types": "./dist/index.d.ts"- }- },- "files": [- "dist",- "dist-standalone",- "src",- "standalone.ts"- ],- "scripts": {- "build": "vite build",- "build:standalone": "vite build --config vite.standalone.config.mts",- "dev": "vite build --watch",- "prepare": "npm run build",- "test:sandbox": "node test/wiki-sandbox.test.mjs",- "test:orbit": "node test/orbit.test.mjs",- "test": "node test/run-all.mjs",- "test:viewcube": "node test/viewcube.test.mjs",- "test:help": "node test/help.test.mjs",- "test:lights": "node test/lights.test.mjs",- "test:replace": "node test/replace.test.mjs",- "test:layers": "node test/layers.test.mjs",- "test:bundle": "node test/bundle.test.mjs",- "test:home": "node test/home-target.test.mjs",- "test:intro": "node test/intro.test.mjs",- "test:visibility": "node test/visibility.test.mjs"- }, "dependencies": {},- "devDependencies": {- "@babylonjs/addons": "9.5.0",- "@babylonjs/core": "9.5.0",- "@babylonjs/gui": "9.5.0",- "@babylonjs/gui-editor": "9.5.0",- "@babylonjs/inspector": "9.5.0",- "@babylonjs/loaders": "9.5.0",- "@babylonjs/materials": "9.5.0",- "@babylonjs/serializers": "9.5.0",- "@sveltejs/vite-plugin-svelte": "^3.1.2",- "babylonjs-gltf2interface": "9.5.0",- "puppeteer-core": "25.15.0",- "svelte": "4.2.20",- "svelte-check": "^3.8.6",- "terser": "^5.46.2",- "typescript": "^5.5.4",- "vite": "^5.4.1"- },- "peerDependencies": {- "svelte": "^4.0.0 || ^5.0.0"- }, "slug": "adom-3d-viewer", "license": "MIT", "tags": [@@ -91,5 +37,9 @@ "prompt": "Download the 0.4.3 viewer bundle so my tool vendors a fixed build" } ],- "title": "Adom 3D Viewer"+ "title": "Adom 3D Viewer",+ "scripts": {+ "install": "./install.sh",+ "uninstall": "./uninstall.sh"+ } }
page.json+1−1@@ -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.12.10",+ "version": "0.13.0", "tags": [ "3d", "viewer",