@thatopen/services 0.1.3 → 0.3.0

package/src/cli/templates/app/src/setups/reality-capture/lib/hidden-tiles-plugin.ts

@@ -0,0 +1,88 @@
+// 3DTilesRendererJS plugin: serve a STANDARD loose 3D Tiles dataset whose tiles
+// are stored as platform HIDDEN files, streamed one-file-per-tile.
+//
+// Seam: the renderer's `fetchData(url, options)` hook (intercepts BOTH the root
+// tileset and every tile content fetch). Point the TilesRenderer at
+// `<baseUrl>/tileset.json`; relative content URIs then resolve to
+// `<baseUrl>/<relUri>` (e.g. "mem://t/tiles/n12_d3.spz"), which we strip back to
+// the dataset-relative path (`relUri`) and look up in the `hiddenFiles` map to
+// find the platform hidden-file id to download.
+//
+// SHARED CONTRACT (matches the converters): the main visible file is a standard
+// `tileset.json`; each tile `content.uri` is a relative path under "tiles/".
+// tileset.json carries a top-level `hiddenFiles: { "<content.uri>": "<id>" }`
+// map. We fetch a tile blob with `client.downloadHiddenFile(id)` -> Response.
+//
+// Per-tile streaming = one `downloadHiddenFile` per visible tile; the controller's
+// Q1 LRU/count-budget governor bounds how many are resident/loading at once.
+
+// Structural type for the platform client: download a normal file by id (the
+// tileset main file) and a hidden file by id (each tile). PlatformClient /
+// EngineServicesClient satisfy this.
+export interface HiddenTilesClient {
+  downloadFile(fileId: string, params?: any): Promise<Response>;
+  downloadHiddenFile(hiddenId: string): Promise<Response>;
+}
+
+export interface HiddenTilesOptions {
+  baseUrl: string; // synthetic base the TilesRenderer is pointed at, e.g. "mem://t"
+  tilesetBytes: Uint8Array; // the already-downloaded tileset.json bytes
+  hiddenFiles: Record<string, string>; // content.uri -> hidden file id
+  client: HiddenTilesClient;
+}
+
+export class HiddenTilesPlugin {
+  name = "HIDDEN_TILES_PLUGIN";
+  private baseUrl: string;
+  private tilesetBytes: Uint8Array;
+  private hiddenFiles: Record<string, string>;
+  private client: HiddenTilesClient;
+
+  constructor({ baseUrl, tilesetBytes, hiddenFiles, client }: HiddenTilesOptions) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.tilesetBytes = tilesetBytes;
+    this.hiddenFiles = hiddenFiles;
+    this.client = client;
+  }
+
+  // dataset-relative path for URLs under our synthetic base, else null.
+  private rel(url: string): string | null {
+    const prefix = this.baseUrl + "/";
+    return url.startsWith(prefix) ? url.slice(prefix.length) : null;
+  }
+
+  // The renderer fetch hook. Return a Response, or null to let the default fetch
+  // run (URLs that aren't under our base).
+  async fetchData(url: string, _options: any): Promise<Response | null> {
+    const rel = this.rel(url);
+    if (rel === null) return null;
+
+    // Root tileset request: serve the bytes we already downloaded.
+    if (rel === "tileset.json") {
+      // copy out into a standalone ArrayBuffer for the Response
+      const b = this.tilesetBytes;
+      const ab = (b.byteOffset === 0 && b.byteLength === b.buffer.byteLength
+        ? b.buffer
+        : b.slice().buffer) as ArrayBuffer;
+      return new Response(ab, {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    // Content (tile) request: strip query/fragment, look up the hidden id.
+    const relUri = decodeURIComponent(rel.split("?")[0].split("#")[0]);
+    const hiddenId = this.hiddenFiles[relUri];
+    if (!hiddenId) {
+      // not a known tile -> 404 so the renderer treats it as a failed fetch.
+      return new Response(null, { status: 404, statusText: "Not Found" });
+    }
+
+    const res = await this.client.downloadHiddenFile(hiddenId);
+    const buf = await res.arrayBuffer();
+    return new Response(buf, {
+      status: 200,
+      headers: { "Content-Type": "application/octet-stream" },
+    });
+  }
+}

package/src/cli/templates/app/src/setups/reality-capture/lib/point-tile-plugin.ts

@@ -0,0 +1,166 @@
+import * as THREE from "three";
+import { frame, placeAtAnchor } from "./render-frame";
+
+// ---- decode worker pool -----------------------------------------------------
+// Dequantizes node blobs off the main thread (grimoire: worker-zero-copy decode).
+//
+// INLINE worker: the decode logic is bundled as a source STRING -> Blob -> object
+// URL classic worker. NO `new URL("./worker.ts", import.meta.url)` — that breaks
+// under esbuild bundling + the platform's sandboxed iframe (Invalid URL). This
+// blob-URL form works in every bundler/sandbox (same approach Spark uses).
+// Blob: f64 anchor[3] | f32 scale[3] | u32 count | (u16 x,y,z + u8 r,g,b)*count.
+const WORKER_SRC = `
+self.onmessage = function (e) {
+  var id = e.data.id, buffer = e.data.buffer;
+  var dv = new DataView(buffer);
+  var ax = dv.getFloat64(0, true), ay = dv.getFloat64(8, true), az = dv.getFloat64(16, true);
+  var sx = dv.getFloat32(24, true), sy = dv.getFloat32(28, true), sz = dv.getFloat32(32, true);
+  var count = dv.getUint32(36, true);
+  var positions = new Float32Array(count * 3);
+  var colors = new Uint8Array(count * 3);
+  var o = 40;
+  for (var k = 0; k < count; k++) {
+    positions[k * 3] = dv.getUint16(o, true) * sx;
+    positions[k * 3 + 1] = dv.getUint16(o + 2, true) * sy;
+    positions[k * 3 + 2] = dv.getUint16(o + 4, true) * sz;
+    colors[k * 3] = dv.getUint8(o + 6);
+    colors[k * 3 + 1] = dv.getUint8(o + 7);
+    colors[k * 3 + 2] = dv.getUint8(o + 8);
+    o += 9;
+  }
+  self.postMessage({ id: id, positions: positions, colors: colors, count: count, anchor: [ax, ay, az] }, [positions.buffer, colors.buffer]);
+};
+`;
+let _blobURL: string | null = null;
+function workerURL(): string {
+  return (_blobURL ??= URL.createObjectURL(new Blob([WORKER_SRC], { type: "text/javascript" })));
+}
+
+type Decoded = { positions: Float32Array; colors: Uint8Array; count: number; anchor: [number, number, number] };
+class DecodePool {
+  private workers: Worker[] = [];
+  private idle: Worker[] = [];
+  private queue: { id: number; buffer: ArrayBuffer; resolve: (d: Decoded) => void }[] = [];
+  private pending = new Map<number, (d: Decoded) => void>();
+  private nextId = 0;
+  constructor(n: number) {
+    for (let i = 0; i < n; i++) {
+      const w = new Worker(workerURL()); // classic blob worker (no import.meta.url, no module type)
+      w.onmessage = (e: MessageEvent<Decoded & { id: number }>) => {
+        const r = this.pending.get(e.data.id);
+        this.pending.delete(e.data.id);
+        this.idle.push(w);
+        r?.(e.data);
+        this.drain();
+      };
+      this.workers.push(w); this.idle.push(w);
+    }
+  }
+  decode(buffer: ArrayBuffer): Promise<Decoded> {
+    return new Promise((resolve) => { this.queue.push({ id: this.nextId++, buffer, resolve }); this.drain(); });
+  }
+  private drain() {
+    while (this.idle.length && this.queue.length) {
+      const w = this.idle.pop()!; const job = this.queue.shift()!;
+      this.pending.set(job.id, job.resolve);
+      w.postMessage({ id: job.id, buffer: job.buffer }, [job.buffer]); // transfer in (zero-copy)
+    }
+  }
+}
+// LAZY: workers are created on the FIRST decode (a points tile), never at module
+// load — so merely importing this module (e.g. for the splat path) spins up nothing.
+let _pool: DecodePool | null = null;
+function getPool(): DecodePool {
+  return (_pool ??= new DecodePool(Math.min(16, Math.max(3, (navigator.hardwareConcurrency || 4) - 1))));
+}
+export function decodeStats() {
+  const p = _pool as any;
+  return p ? { workers: p.workers.length, idle: p.idle.length, queued: p.queue.length, pending: p.pending.size }
+           : { workers: 0, idle: 0, queued: 0, pending: 0 };
+}
+
+// 3DTilesRendererJS plugin: decodes our quantized point-node format into a
+// node-local THREE.Points, tagged with its float64 world anchor for RTC.
+//
+// Node blob (sliced out of cloud.bin by byte range):
+//   header: f64 anchor[3] | f32 scale[3] | u32 count   (40 B)
+//   body:   per point u16 x,y,z + u8 r,g,b              (9 B)
+// Decoded position = stored * scale  (node-local, small, float32-safe).
+//
+// Same `parseToMesh` seam the experiment proved with Spark: return a
+// THREE.Object3D and the renderer owns transform/cull/cache/eviction. We must
+// NOT be async at the top level (invokeOnePlugin treats a Promise as truthy and
+// stops iterating), so non-matching content returns null synchronously.
+
+// Shared material for all point nodes. Writes rgb + view-space log-depth (alpha)
+// so the EDL post pass gets its depth field for free (no second target).
+const pointUniforms = { uPointSize: { value: frame.pointSize } };
+
+const pointMaterial = new THREE.ShaderMaterial({
+  uniforms: pointUniforms,
+  vertexShader: /* glsl */ `
+    attribute vec3 color;
+    uniform float uPointSize;
+    varying vec3 vColor;
+    varying float vLogZ;
+    void main() {
+      vColor = color;
+      vec4 mv = modelViewMatrix * vec4(position, 1.0);
+      vLogZ = log2(max(1e-6, -mv.z));
+      gl_Position = projectionMatrix * mv;
+      gl_PointSize = uPointSize;
+    }
+  `,
+  fragmentShader: /* glsl */ `
+    varying vec3 vColor;
+    varying float vLogZ;
+    void main() {
+      gl_FragColor = vec4(vColor, vLogZ);
+    }
+  `,
+});
+
+export function setPointSize(px: number) {
+  pointUniforms.uPointSize.value = px;
+}
+
+export class PointTilePlugin {
+  name = "POINT_TILE_PLUGIN";
+  tiles: any = null;
+
+  init(tiles: any) {
+    this.tiles = tiles;
+  }
+
+  // parseToMesh: hand the blob to the decode WORKER POOL (off-thread dequant +
+  // zero-copy transfer back) so tile loads never hitch the main thread. Must
+  // return null synchronously for non-matching content (a Promise is truthy and
+  // would stop plugin iteration); matching content returns a Promise<Points>.
+  parseToMesh(
+    buffer: ArrayBuffer,
+    _tile: any,
+    _extension: string,
+    uri: string,
+    signal: AbortSignal
+  ) {
+    if (!uri.includes(".pnt")) return null;
+    if (signal.aborted) return null;
+    return getPool().decode(buffer).then((d) => {
+      if (signal.aborted) return null;
+      const geom = new THREE.BufferGeometry();
+      geom.setAttribute("position", new THREE.BufferAttribute(d.positions, 3));
+      geom.setAttribute("color", new THREE.BufferAttribute(d.colors, 3, true));
+      const points = new THREE.Points(geom, pointMaterial);
+      points.matrixAutoUpdate = false;
+      points.frustumCulled = false; // renderer culls per tile already
+      points.userData.worldAnchor = d.anchor; // float64 world anchor for RTC
+      placeAtAnchor(points, d.anchor);
+      return points;
+    });
+  }
+
+  disposeTile(tile: any) {
+    const scene = tile.engineData?.scene;
+    if (scene && scene.geometry) scene.geometry.dispose();
+  }
+}

package/src/cli/templates/app/src/setups/reality-capture/lib/render-frame.ts

@@ -0,0 +1,31 @@
+import * as THREE from "three";
+
+// Shared floating-origin (RTC) state for the whole viewer.
+//
+// The precision stack: authoritative coordinates live in float64 (plain JS
+// numbers). `origin` is a float64 world point near the camera. Every renderable
+// (point node, splat) is placed at  worldAnchor - origin  computed in float64,
+// then assigned to a float32 Object3D.position — which is small and safe. When
+// the camera travels far, we rebase `origin` and shift everything, so GPU
+// coordinates never grow large no matter the absolute world position.
+
+export const POINT_LAYER = 1;
+export const SPLAT_LAYER = 2;
+
+export const frame = {
+  // float64 render origin in world space
+  origin: [0, 0, 0] as [number, number, number],
+  pointSize: 3.0,
+  edlStrength: 0.35,
+  edlRadius: 1.4,
+  edlOn: true,
+};
+
+// Place a point node at its FULL float64 world anchor. The recentering (origin
+// subtraction) is done ONCE by pointContainer.position = -origin each frame — so
+// world = -origin + anchor + localOffset = (worldPoint - origin), small + precise.
+// (Do NOT subtract origin here too, or it gets subtracted twice.)
+export function placeAtAnchor(obj: THREE.Object3D, anchor: [number, number, number]) {
+  obj.position.set(anchor[0], anchor[1], anchor[2]);
+  obj.updateMatrix();
+}

package/src/cli/templates/app/src/setups/reality-capture/lib/splat-tile-plugin.ts

@@ -0,0 +1,51 @@
+import * as THREE from "three";
+import { SplatMesh } from "@sparkjsdev/spark";
+
+// 3DTilesRendererJS plugin that renders .ply Gaussian-splat tiles via Spark —
+// the proven seam from Antonio's 3d-tiles experiment, kept intact. The point of
+// the slice: the SAME streaming foundation (3DTilesRendererJS) drives this splat
+// branch and the point-cloud branch as peers, differing only at parseToMesh.
+//
+// parseToMesh must not be async at the top level (a returned Promise is treated
+// as truthy and stops plugin iteration) — return null synchronously for non-ply.
+export class SplatTilePlugin {
+  name = "SPLAT_TILE_PLUGIN";
+  tiles: any = null;
+
+  init(tiles: any) {
+    this.tiles = tiles;
+  }
+
+  parseToMesh(
+    buffer: ArrayBuffer,
+    _tile: any,
+    extension: string,
+    _uri: string,
+    signal: AbortSignal
+  ) {
+    if (extension !== "ply" && extension !== "spz") return null;
+    // Spark's SplatMesh sniffs the actual file type (PLY/SPZ/SPLAT/…) from the
+    // bytes, so both load the same way.
+    return (async () => {
+      if (signal.aborted) return null;
+      const splatMesh = new SplatMesh({ fileBytes: new Uint8Array(buffer) });
+      await splatMesh.initialized;
+      if (signal.aborted) {
+        splatMesh.dispose();
+        return null;
+      }
+      // Real splat count from the LOADED data — format-agnostic. (A byte probe of
+      // the header is fragile: SPZ is gzipped, so reading bytes off the top gives
+      // garbage ~2.6e9, which poisons the motion-budget governor's count and makes
+      // the Motion-detail slider a no-op.) packedSplats.numSplats is correct for
+      // every format.
+      splatMesh.userData.splatCount = (splatMesh as any).packedSplats?.numSplats ?? 0;
+      return splatMesh as unknown as THREE.Object3D;
+    })();
+  }
+
+  disposeTile(tile: any) {
+    const scene = tile.engineData?.scene;
+    if (scene && typeof scene.dispose === "function") scene.dispose();
+  }
+}