← Commit history

Publish 0.13.0

AdityaAngajala ·f6ae17a158 · ·parent ccce900
4 files changed +215−70
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",