3dtiles-inspector 0.2.7 → 0.2.8

package/CHANGELOG.md

@@ -6,6 +6,13 @@ The format is based on Keep a Changelog and this project follows Semantic Versio
 
 ## [Unreleased]
 
+## [0.2.8] - 2026-05-13
+
+### Fixed
+
+- Fixed save-time crop memory spikes on large tilesets by limiting concurrent Gaussian Splat resource processing based on CPU parallelism, capped at 8 workers.
+- Fixed viewer stalls when many tiles are loaded by avoiding repeated tileset-wide leaf geometric-error scans during tile preprocessing.
+
 ## [0.2.7] - 2026-05-10
 
 ### Changed

package/dist/inspector-assets/viewer/app.js

@@ -45288,6 +45288,9 @@ function createGeometricErrorController({
   getTiles
 }) {
   const originalTileGeometricErrors = /* @__PURE__ */ new WeakMap();
+  let knownTileChildCounts = /* @__PURE__ */ new WeakMap();
+  let cachedGlobalLeafGeometricError = null;
+  let cachedGlobalLeafGeometricErrorRoot = null;
   let geometricErrorScaleExponent = 0;
   let geometricErrorScale = 1;
   let lastSavedGeometricErrorScale = 1;
@@ -45300,6 +45303,39 @@ function createGeometricErrorController({
   function getEffectiveGeometricErrorLayerScale() {
     return lastSavedGeometricErrorLayerScale * geometricErrorLayerScale;
   }
+  function getTilesRoot() {
+    return getTiles()?.root || null;
+  }
+  function getCachedGlobalLeafGeometricError() {
+    const root = getTilesRoot();
+    if (cachedGlobalLeafGeometricErrorRoot !== root) {
+      cachedGlobalLeafGeometricErrorRoot = root;
+      cachedGlobalLeafGeometricError = null;
+      knownTileChildCounts = /* @__PURE__ */ new WeakMap();
+    }
+    return cachedGlobalLeafGeometricError;
+  }
+  function setCachedGlobalLeafGeometricError(leafGeometricError) {
+    cachedGlobalLeafGeometricErrorRoot = getTilesRoot();
+    cachedGlobalLeafGeometricError = leafGeometricError;
+  }
+  function clearCachedGlobalLeafGeometricError() {
+    cachedGlobalLeafGeometricError = null;
+  }
+  function trackTileChildCount(tile, children) {
+    knownTileChildCounts.set(tile, children.length);
+  }
+  function invalidateLeafCacheIfParentChildrenChanged(parentTile) {
+    if (!parentTile || typeof parentTile !== "object") {
+      return;
+    }
+    const children = Array.isArray(parentTile.children) ? parentTile.children : [];
+    const knownChildCount = knownTileChildCounts.get(parentTile);
+    if (cachedGlobalLeafGeometricError !== null && knownChildCount !== children.length) {
+      clearCachedGlobalLeafGeometricError();
+    }
+    trackTileChildCount(parentTile, children);
+  }
   function updateTilesetErrorTarget() {
     const tiles = getTiles();
     if (!tiles) {
@@ -45338,6 +45374,7 @@ function createGeometricErrorController({
     visited.add(tile);
     let leafGeometricError = null;
     const children = Array.isArray(tile.children) ? tile.children : [];
+    trackTileChildCount(tile, children);
     for (const child of children) {
       const childLeafGeometricError = getKnownTileLeafGeometricError(
         child,
@@ -45350,31 +45387,58 @@ function createGeometricErrorController({
     visited.delete(tile);
     return leafGeometricError === null ? originalGeometricError : leafGeometricError;
   }
-  function getGlobalTileLeafGeometricError(tile) {
+  function getGlobalTileLeafGeometricError(tile, { forceRefresh = false } = {}) {
+    if (!forceRefresh) {
+      const cachedLeafGeometricError = getCachedGlobalLeafGeometricError();
+      if (cachedLeafGeometricError !== null) {
+        return cachedLeafGeometricError;
+      }
+    }
     const tiles = getTiles();
     const rootLeafGeometricError = tiles?.root ? getKnownTileLeafGeometricError(tiles.root) : null;
+    if (tiles?.root && tile === tiles.root) {
+      setCachedGlobalLeafGeometricError(rootLeafGeometricError);
+      return rootLeafGeometricError;
+    }
     const tileLeafGeometricError = getKnownTileLeafGeometricError(tile);
+    let leafGeometricError = null;
     if (rootLeafGeometricError === null) {
-      return tileLeafGeometricError;
-    }
-    if (tileLeafGeometricError === null) {
-      return rootLeafGeometricError;
+      leafGeometricError = tileLeafGeometricError;
+    } else if (tileLeafGeometricError === null) {
+      leafGeometricError = rootLeafGeometricError;
+    } else {
+      leafGeometricError = Math.min(
+        rootLeafGeometricError,
+        tileLeafGeometricError
+      );
     }
-    return Math.min(rootLeafGeometricError, tileLeafGeometricError);
+    setCachedGlobalLeafGeometricError(leafGeometricError);
+    return leafGeometricError;
   }
-  function applyLayerScaleToTile(tile, leafGeometricError = getGlobalTileLeafGeometricError(tile)) {
+  function applyLayerScaleToTile(tile, leafGeometricError = null, parentTile = null) {
+    invalidateLeafCacheIfParentChildrenChanged(parentTile);
     const originalGeometricError = getOriginalTileGeometricError(tile);
-    if (originalGeometricError === null || leafGeometricError === null) {
+    if (originalGeometricError === null) {
+      return;
+    }
+    const layerScale = getEffectiveGeometricErrorLayerScale();
+    if (layerScale === 1) {
+      tile.geometricError = originalGeometricError;
+      return;
+    }
+    const effectiveLeafGeometricError = leafGeometricError ?? getGlobalTileLeafGeometricError(tile);
+    if (effectiveLeafGeometricError === null) {
       return;
     }
-    tile.geometricError = leafGeometricError + (originalGeometricError - leafGeometricError) * getEffectiveGeometricErrorLayerScale();
+    tile.geometricError = effectiveLeafGeometricError + (originalGeometricError - effectiveLeafGeometricError) * layerScale;
   }
   function applyLayerScaleToTileset() {
     const tiles = getTiles();
     if (!tiles) {
       return;
     }
-    const leafGeometricError = getGlobalTileLeafGeometricError(tiles.root);
+    const layerScale = getEffectiveGeometricErrorLayerScale();
+    const leafGeometricError = layerScale === 1 ? null : getGlobalTileLeafGeometricError(tiles.root, { forceRefresh: true });
     tiles.traverse(
       (tile) => {
         applyLayerScaleToTile(tile, leafGeometricError);
@@ -63249,8 +63313,8 @@ function createTerrainGlobeTiles(options) {
 function createGeometricErrorLayerScalePlugin(preprocessNode) {
   return {
     name: "GeometricErrorLayerScalePlugin",
-    preprocessNode(tile) {
-      preprocessNode(tile);
+    preprocessNode(tile, tilesetDir, parentTile) {
+      preprocessNode(tile, null, parentTile);
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3dtiles-inspector",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Inspect, align, and save local 3D Tiles root transforms in an interactive browser session.",
   "author": "William Liu <lyz15972107087@gmail.com>",
   "license": "Apache-2.0",

package/src/server/splatCrop/gltfResource.js

@@ -70,7 +70,7 @@ function parseGlb(filePath) {
     if (chunkType === GLB_JSON_CHUNK_TYPE) {
       json = JSON.parse(chunk.toString('utf8').replace(/\0+$/g, '').trimEnd());
     } else if (chunkType === GLB_BIN_CHUNK_TYPE && !bin) {
-      bin = Buffer.from(chunk);
+      bin = chunk;
     }
 
     offset = chunkEnd;
@@ -190,7 +190,7 @@ function loadResourceBuffer(resource, bufferIndex) {
         `${resource.filePath}.buffers[${bufferIndex}].uri`,
       );
       resource.dataUriMetadata.set(bufferIndex, metadata);
-      record = { bytes: Buffer.from(bytes), dataUri: true };
+      record = { bytes, dataUri: true };
     } else {
       const bufferPath = resolveLocalUri(
         path.dirname(resource.filePath),
@@ -205,7 +205,7 @@ function loadResourceBuffer(resource, bufferIndex) {
     }
   } else if (resource.type === 'glb' && bufferIndex === 0) {
     record = {
-      bytes: Buffer.from(resource.embeddedBin || Buffer.alloc(0)),
+      bytes: resource.embeddedBin || Buffer.alloc(0),
       embedded: true,
     };
   } else {
@@ -322,7 +322,7 @@ function applyBufferReplacements(resource, bufferIndex, replacements) {
 
   replacements.forEach((replacement) => {
     parts.push(record.bytes.subarray(cursor, replacement.start));
-    parts.push(Buffer.from(replacement.bytes));
+    parts.push(replacement.bytes);
     cursor = replacement.end;
   });
 

package/src/server/splatCrop/traversal.js

@@ -22,6 +22,71 @@ const {
   removeMeshPrimitives,
   updateGaussianPrimitiveAccessorCounts,
 } = require('./gaussianPrimitives');
+const { SPLAT_CROP_WORKER_COUNT } = require('./workerPool');
+
+class AsyncLimiter {
+  constructor(limit) {
+    this.active = 0;
+    this.limit = normalizeConcurrency(limit);
+    this.queue = [];
+  }
+
+  run(task) {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ reject, resolve, task });
+      this.dispatch();
+    });
+  }
+
+  dispatch() {
+    while (this.active < this.limit && this.queue.length > 0) {
+      const job = this.queue.shift();
+      this.active += 1;
+      Promise.resolve()
+        .then(job.task)
+        .then(job.resolve, job.reject)
+        .finally(() => {
+          this.active -= 1;
+          this.dispatch();
+        });
+    }
+  }
+}
+
+function normalizeConcurrency(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0
+    ? Math.max(1, Math.floor(number))
+    : 1;
+}
+
+function createAsyncLimiter(limit = SPLAT_CROP_WORKER_COUNT) {
+  return new AsyncLimiter(limit);
+}
+
+async function mapWithConcurrency(items, concurrency, mapper) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return [];
+  }
+
+  const limit = normalizeConcurrency(concurrency);
+  const results = new Array(items.length);
+  let nextIndex = 0;
+
+  async function worker() {
+    while (nextIndex < items.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await mapper(items[index], index);
+    }
+  }
+
+  const workerCount = Math.min(limit, items.length);
+  await Promise.all(
+    Array.from({ length: workerCount }, () => worker()),
+  );
+  return results;
+}
 
 function getContentSlots(tile) {
   const slots = [];
@@ -594,36 +659,16 @@ async function processGltfResource({
   let hasResourceBounds = false;
   let deletedSplats = 0;
   let modified = false;
-  const rewriteTasks = [];
 
   for (const [bufferViewIndex, viewDescriptors] of byBufferView) {
     const slice = getBufferViewSlice(resource, bufferViewIndex);
-    rewriteTasks.push({
-      bufferViewIndex,
-      slice,
-      viewDescriptors,
-      promise: rewriteSpzBytesInWorker({
-        bytes: slice.bytes,
-        descriptors: viewDescriptors,
-        screenSelections,
-        workerPool,
-      }),
+    const rewrite = await rewriteSpzBytesInWorker({
+      bytes: slice.bytes,
+      descriptors: viewDescriptors,
+      screenSelections,
+      workerPool,
     });
-  }
-
-  const rewriteResults = await Promise.all(
-    rewriteTasks.map(async (task) => ({
-      ...task,
-      rewrite: await task.promise,
-    })),
-  );
 
-  for (const {
-    bufferViewIndex,
-    rewrite,
-    slice,
-    viewDescriptors,
-  } of rewriteResults) {
     deletedSplats += rewrite.deleted;
     if (rewrite.bounds) {
       hasResourceBounds =
@@ -766,11 +811,13 @@ async function processGltfContentSlot(
     context.resourceLocks,
     resourcePath,
     () =>
-      processLockedSplatResource(
-        context,
-        resourcePath,
-        tileSceneMatrix,
-        tileProjectionMatrix,
+      context.resourceLimiter.run(() =>
+        processLockedSplatResource(
+          context,
+          resourcePath,
+          tileSceneMatrix,
+          tileProjectionMatrix,
+        ),
       ),
   );
 
@@ -809,6 +856,8 @@ async function processNestedTilesetContentSlot(
     emptySplatResources: context.emptySplatResources,
     progress: context.progress,
     resourceLocks: context.resourceLocks,
+    resourceLimiter: context.resourceLimiter,
+    traversalConcurrency: context.traversalConcurrency,
     workerPool: context.workerPool,
   });
 
@@ -862,6 +911,14 @@ async function processContentSlot(context, slot, tileTransform, tileProjection)
   return createContentSlotResult(slot, { boundsKnown: false });
 }
 
+async function processContentSlots(context, tile, tileTransform, tileProjection) {
+  return mapWithConcurrency(
+    getContentSlots(tile),
+    context.traversalConcurrency,
+    (slot) => processContentSlot(context, slot, tileTransform, tileProjection),
+  );
+}
+
 function applyContentResultsToTile(context, tile, contentResults) {
   const contentBounds = [];
   let boundsKnown = true;
@@ -893,16 +950,18 @@ async function pruneEmptyChildren(context, tile, tileTransform, tileProjection)
     };
   }
 
-  const children = tile.children.slice();
-  const childResults = await Promise.all(
-    children.map(async (child) => ({
-      child,
-      result: await visitTilesetTile(context, child, tileTransform, false),
-    })),
-  );
   const childBounds = [];
   let boundsKnown = true;
   const keptChildren = [];
+  const childResults = await mapWithConcurrency(
+    tile.children,
+    context.traversalConcurrency,
+    async (child) => ({
+      child,
+      result: await visitTilesetTile(context, child, tileTransform, false),
+    }),
+  );
+
   childResults.forEach(({ child, result }) => {
     if (result.empty) {
       context.tilesetModified = true;
@@ -960,10 +1019,11 @@ async function visitTilesetTile(context, tile, inheritedTransform, isRootTile) {
     isRootTile,
   );
   const tileProjection = getTileProjection(context.THREE, tile);
-  const contentResults = await Promise.all(
-    getContentSlots(tile).map((slot) =>
-      processContentSlot(context, slot, worldTransform, tileProjection),
-    ),
+  const contentResults = await processContentSlots(
+    context,
+    tile,
+    worldTransform,
+    tileProjection,
   );
 
   const contentSummary = applyContentResultsToTile(context, tile, contentResults);
@@ -1016,6 +1076,8 @@ async function traverseTileset({
   emptySplatResources,
   progress,
   resourceLocks,
+  resourceLimiter = null,
+  traversalConcurrency = SPLAT_CROP_WORKER_COUNT,
   workerPool,
 }) {
   const resolvedTilesetPath = assertPathInsideRoot(
@@ -1039,6 +1101,8 @@ async function traverseTileset({
     throw new InspectorError(`${resolvedTilesetPath} must contain a root object.`);
   }
 
+  const normalizedTraversalConcurrency =
+    normalizeConcurrency(traversalConcurrency);
   const context = {
     THREE,
     deletedSplats: 0,
@@ -1047,11 +1111,14 @@ async function traverseTileset({
     processedResources,
     processedSplatResources: 0,
     resourceLocks,
+    resourceLimiter:
+      resourceLimiter || createAsyncLimiter(normalizedTraversalConcurrency),
     rootDir,
     rootTransform,
     screenSelections,
     tilesetDir: path.dirname(resolvedTilesetPath),
     tilesetModified: false,
+    traversalConcurrency: normalizedTraversalConcurrency,
     upRotationMatrix,
     visitedTilesets,
     workerPool,

package/src/server/splatCrop/workerPool.js

@@ -1,11 +1,37 @@
 const path = require('path');
+const os = require('os');
 const { Worker } = require('worker_threads');
 
 const { InspectorError } = require('../../errors');
 
-const SPLAT_CROP_WORKER_COUNT = 4;
+const MAX_SPLAT_CROP_WORKER_COUNT = 8;
 const SPLAT_CROP_WORKER_PATH = path.join(__dirname, 'worker.js');
 
+function getAvailableParallelism() {
+  if (typeof os.availableParallelism === 'function') {
+    try {
+      const parallelism = os.availableParallelism();
+      if (Number.isFinite(parallelism) && parallelism > 0) {
+        return parallelism;
+      }
+    } catch (err) {
+      // Fall back to os.cpus() below.
+    }
+  }
+
+  const cpus = os.cpus();
+  return Array.isArray(cpus) && cpus.length > 0 ? cpus.length : 1;
+}
+
+function getDefaultSplatCropWorkerCount() {
+  return Math.min(
+    MAX_SPLAT_CROP_WORKER_COUNT,
+    Math.max(1, getAvailableParallelism() - 1),
+  );
+}
+
+const SPLAT_CROP_WORKER_COUNT = getDefaultSplatCropWorkerCount();
+
 function deserializeWorkerError(error) {
   const message =
     error && typeof error.message === 'string'
@@ -74,7 +100,13 @@ class SplatCropWorkerPool {
       const result = message.result || {};
       job.resolve({
         bounds: result.bounds || null,
-        bytes: result.bytes ? Buffer.from(result.bytes) : null,
+        bytes: result.bytes
+          ? Buffer.from(
+              result.bytes.buffer,
+              result.bytes.byteOffset,
+              result.bytes.byteLength,
+            )
+          : null,
         deleted: Number(result.deleted || 0),
         empty: !!result.empty,
         splatCount: Number(result.splatCount || 0),
@@ -179,6 +211,7 @@ class SplatCropWorkerPool {
 }
 
 module.exports = {
+  getDefaultSplatCropWorkerCount,
   SPLAT_CROP_WORKER_COUNT,
   SplatCropWorkerPool,
 };

package/src/viewer/scene/tiles.js

@@ -100,8 +100,8 @@ export function createTerrainGlobeTiles(options) {
 function createGeometricErrorLayerScalePlugin(preprocessNode) {
   return {
     name: 'GeometricErrorLayerScalePlugin',
-    preprocessNode(tile) {
-      preprocessNode(tile);
+    preprocessNode(tile, tilesetDir, parentTile) {
+      preprocessNode(tile, null, parentTile);
     },
   };
 }

package/src/viewer/transform/geometricError.js

@@ -21,6 +21,9 @@ export function createGeometricErrorController({
   getTiles,
 }) {
   const originalTileGeometricErrors = new WeakMap();
+  let knownTileChildCounts = new WeakMap();
+  let cachedGlobalLeafGeometricError = null;
+  let cachedGlobalLeafGeometricErrorRoot = null;
   let geometricErrorScaleExponent = 0;
   let geometricErrorScale = 1;
   let lastSavedGeometricErrorScale = 1;
@@ -36,6 +39,51 @@ export function createGeometricErrorController({
     return lastSavedGeometricErrorLayerScale * geometricErrorLayerScale;
   }
 
+  function getTilesRoot() {
+    return getTiles()?.root || null;
+  }
+
+  function getCachedGlobalLeafGeometricError() {
+    const root = getTilesRoot();
+    if (cachedGlobalLeafGeometricErrorRoot !== root) {
+      cachedGlobalLeafGeometricErrorRoot = root;
+      cachedGlobalLeafGeometricError = null;
+      knownTileChildCounts = new WeakMap();
+    }
+    return cachedGlobalLeafGeometricError;
+  }
+
+  function setCachedGlobalLeafGeometricError(leafGeometricError) {
+    cachedGlobalLeafGeometricErrorRoot = getTilesRoot();
+    cachedGlobalLeafGeometricError = leafGeometricError;
+  }
+
+  function clearCachedGlobalLeafGeometricError() {
+    cachedGlobalLeafGeometricError = null;
+  }
+
+  function trackTileChildCount(tile, children) {
+    knownTileChildCounts.set(tile, children.length);
+  }
+
+  function invalidateLeafCacheIfParentChildrenChanged(parentTile) {
+    if (!parentTile || typeof parentTile !== 'object') {
+      return;
+    }
+
+    const children = Array.isArray(parentTile.children)
+      ? parentTile.children
+      : [];
+    const knownChildCount = knownTileChildCounts.get(parentTile);
+    if (
+      cachedGlobalLeafGeometricError !== null &&
+      knownChildCount !== children.length
+    ) {
+      clearCachedGlobalLeafGeometricError();
+    }
+    trackTileChildCount(parentTile, children);
+  }
+
   function updateTilesetErrorTarget() {
     const tiles = getTiles();
     if (!tiles) {
@@ -87,6 +135,7 @@ export function createGeometricErrorController({
     visited.add(tile);
     let leafGeometricError = null;
     const children = Array.isArray(tile.children) ? tile.children : [];
+    trackTileChildCount(tile, children);
     for (const child of children) {
       const childLeafGeometricError = getKnownTileLeafGeometricError(
         child,
@@ -105,37 +154,69 @@ export function createGeometricErrorController({
       : leafGeometricError;
   }
 
-  function getGlobalTileLeafGeometricError(tile) {
+  function getGlobalTileLeafGeometricError(tile, { forceRefresh = false } = {}) {
+    if (!forceRefresh) {
+      const cachedLeafGeometricError = getCachedGlobalLeafGeometricError();
+      if (cachedLeafGeometricError !== null) {
+        return cachedLeafGeometricError;
+      }
+    }
+
     const tiles = getTiles();
     const rootLeafGeometricError = tiles?.root
       ? getKnownTileLeafGeometricError(tiles.root)
       : null;
-    const tileLeafGeometricError = getKnownTileLeafGeometricError(tile);
 
-    if (rootLeafGeometricError === null) {
-      return tileLeafGeometricError;
+    if (tiles?.root && tile === tiles.root) {
+      setCachedGlobalLeafGeometricError(rootLeafGeometricError);
+      return rootLeafGeometricError;
     }
 
-    if (tileLeafGeometricError === null) {
-      return rootLeafGeometricError;
+    const tileLeafGeometricError = getKnownTileLeafGeometricError(tile);
+    let leafGeometricError = null;
+
+    if (rootLeafGeometricError === null) {
+      leafGeometricError = tileLeafGeometricError;
+    } else if (tileLeafGeometricError === null) {
+      leafGeometricError = rootLeafGeometricError;
+    } else {
+      leafGeometricError = Math.min(
+        rootLeafGeometricError,
+        tileLeafGeometricError,
+      );
     }
 
-    return Math.min(rootLeafGeometricError, tileLeafGeometricError);
+    setCachedGlobalLeafGeometricError(leafGeometricError);
+    return leafGeometricError;
   }
 
   function applyLayerScaleToTile(
     tile,
-    leafGeometricError = getGlobalTileLeafGeometricError(tile),
+    leafGeometricError = null,
+    parentTile = null,
   ) {
+    invalidateLeafCacheIfParentChildrenChanged(parentTile);
+
     const originalGeometricError = getOriginalTileGeometricError(tile);
-    if (originalGeometricError === null || leafGeometricError === null) {
+    if (originalGeometricError === null) {
+      return;
+    }
+
+    const layerScale = getEffectiveGeometricErrorLayerScale();
+    if (layerScale === 1) {
+      tile.geometricError = originalGeometricError;
+      return;
+    }
+
+    const effectiveLeafGeometricError =
+      leafGeometricError ?? getGlobalTileLeafGeometricError(tile);
+    if (effectiveLeafGeometricError === null) {
       return;
     }
 
     tile.geometricError =
-      leafGeometricError +
-      (originalGeometricError - leafGeometricError) *
-        getEffectiveGeometricErrorLayerScale();
+      effectiveLeafGeometricError +
+      (originalGeometricError - effectiveLeafGeometricError) * layerScale;
   }
 
   function applyLayerScaleToTileset() {
@@ -144,7 +225,11 @@ export function createGeometricErrorController({
       return;
     }
 
-    const leafGeometricError = getGlobalTileLeafGeometricError(tiles.root);
+    const layerScale = getEffectiveGeometricErrorLayerScale();
+    const leafGeometricError =
+      layerScale === 1
+        ? null
+        : getGlobalTileLeafGeometricError(tiles.root, { forceRefresh: true });
     tiles.traverse(
       (tile) => {
         applyLayerScaleToTile(tile, leafGeometricError);