3dtiles-inspector 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on Keep a Changelog and this project follows Semantic Versio
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-05-05
+
+### Added
+
+- Added realtime `camerapose` URL synchronization so shared viewer URLs can restore the current camera pose.
+
 ## [0.2.5] - 2026-05-05
 
 ### Fixed

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

@@ -68245,6 +68245,10 @@ function createFlyToController({
     }
     return true;
   }
+  function cancelCameraFlight() {
+    activeCameraFlight = null;
+    activeCameraFlightStatus = "";
+  }
   async function applyTilesSetPositionFromPointerEvent(event) {
     const coordinate = pickCoordinateFromPointerEvent(event);
     if (!coordinate) {
@@ -68309,6 +68313,7 @@ function createFlyToController({
   }
   return {
     applyTilesSetPositionFromPointerEvent,
+    cancelCameraFlight,
     frameTileset,
     getActiveEllipsoid,
     moveCameraToCoordinate,
@@ -68325,6 +68330,148 @@ var init_flyTo = __esm({
   }
 });
 
+// src/viewer/navigation/cameraUrlPose.js
+function formatPoseNumber(value) {
+  const fixed = value.toFixed(9);
+  const trimmed = fixed.replace(/(\.\d*?[1-9])0+$/, "$1").replace(/\.0+$/, "");
+  return trimmed === "-0" ? "0" : trimmed;
+}
+function serializeCameraPose(camera) {
+  camera.updateMatrixWorld(true);
+  const values = [
+    camera.position.x,
+    camera.position.y,
+    camera.position.z,
+    camera.quaternion.x,
+    camera.quaternion.y,
+    camera.quaternion.z,
+    camera.quaternion.w
+  ];
+  if (camera.isOrthographicCamera) {
+    values.push(camera.zoom);
+  }
+  if (!values.every(Number.isFinite)) {
+    return null;
+  }
+  return values.map(formatPoseNumber).join(CAMERA_POSE_VALUE_SEPARATOR);
+}
+function getCameraPoseParam(url) {
+  return url.searchParams.get(CAMERA_POSE_PARAM) ?? url.searchParams.get(CAMERA_POSE_ALIAS_PARAM);
+}
+function parseCameraPose(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return null;
+  }
+  const parts = value.trim().split(/[,_\s]+/).filter(Boolean);
+  if (parts.length !== CAMERA_POSE_COMPONENT_COUNT && parts.length !== CAMERA_POSE_COMPONENT_COUNT_WITH_ZOOM) {
+    return null;
+  }
+  const values = parts.map(Number);
+  if (!values.every(Number.isFinite)) {
+    return null;
+  }
+  const quaternionLength = Math.hypot(
+    values[3],
+    values[4],
+    values[5],
+    values[6]
+  );
+  if (quaternionLength <= 1e-12) {
+    return null;
+  }
+  const zoom = values.length === CAMERA_POSE_COMPONENT_COUNT_WITH_ZOOM ? values[7] : null;
+  if (zoom !== null && zoom <= 0) {
+    return null;
+  }
+  return {
+    position: values.slice(0, 3),
+    quaternion: values.slice(3, 7),
+    zoom
+  };
+}
+function replaceCameraPoseUrl(serializedPose) {
+  const url = new URL(window.location.href);
+  url.searchParams.delete(CAMERA_POSE_ALIAS_PARAM);
+  url.searchParams.set(CAMERA_POSE_PARAM, serializedPose);
+  window.history.replaceState(window.history.state, "", url.href);
+}
+function getInvalidCameraPoseMessage() {
+  return "Invalid camerapose URL parameter ignored. Expected x_y_z_qx_qy_qz_qw.";
+}
+function createCameraUrlPoseController({
+  camera,
+  cameraController,
+  setStatus
+}) {
+  let lastSerializedPose = null;
+  let lastUrlWriteTime = 0;
+  function applyPose(pose) {
+    camera.position.fromArray(pose.position);
+    camera.quaternion.fromArray(pose.quaternion).normalize();
+    if (pose.zoom !== null && camera.isOrthographicCamera) {
+      camera.zoom = Math.max(pose.zoom, 1e-6);
+      camera.updateProjectionMatrix();
+    }
+    camera.updateMatrixWorld(true);
+    cameraController.setCamera(camera);
+  }
+  function applyFromUrl({ showStatus = false } = {}) {
+    const url = new URL(window.location.href);
+    const value = getCameraPoseParam(url);
+    if (value === null) {
+      return false;
+    }
+    const pose = parseCameraPose(value);
+    if (!pose) {
+      if (showStatus && setStatus) {
+        setStatus(getInvalidCameraPoseMessage(), true);
+      }
+      return false;
+    }
+    applyPose(pose);
+    lastSerializedPose = serializeCameraPose(camera);
+    lastUrlWriteTime = performance.now();
+    if (lastSerializedPose) {
+      replaceCameraPoseUrl(lastSerializedPose);
+    }
+    if (showStatus && setStatus) {
+      setStatus("Applied camera pose from URL.");
+    }
+    return true;
+  }
+  function flush() {
+    const serializedPose = serializeCameraPose(camera);
+    if (!serializedPose || serializedPose === lastSerializedPose) {
+      return;
+    }
+    replaceCameraPoseUrl(serializedPose);
+    lastSerializedPose = serializedPose;
+    lastUrlWriteTime = performance.now();
+  }
+  function update(time = performance.now()) {
+    if (time - lastUrlWriteTime < CAMERA_POSE_UPDATE_INTERVAL_MS) {
+      return;
+    }
+    flush();
+  }
+  return {
+    applyFromUrl,
+    flush,
+    update
+  };
+}
+var CAMERA_POSE_PARAM, CAMERA_POSE_ALIAS_PARAM, CAMERA_POSE_COMPONENT_COUNT, CAMERA_POSE_COMPONENT_COUNT_WITH_ZOOM, CAMERA_POSE_UPDATE_INTERVAL_MS, CAMERA_POSE_VALUE_SEPARATOR;
+var init_cameraUrlPose = __esm({
+  "src/viewer/navigation/cameraUrlPose.js"() {
+    CAMERA_POSE_PARAM = "camerapose";
+    CAMERA_POSE_ALIAS_PARAM = "cameraPose";
+    CAMERA_POSE_COMPONENT_COUNT = 7;
+    CAMERA_POSE_COMPONENT_COUNT_WITH_ZOOM = 8;
+    CAMERA_POSE_UPDATE_INTERVAL_MS = 100;
+    CAMERA_POSE_VALUE_SEPARATOR = "_";
+  }
+});
+
 // src/viewer/screenSelection/state.js
 function clamp3(value, min, max) {
   return Math.min(max, Math.max(min, value));
@@ -71052,6 +71199,7 @@ var require_app = __commonJS({
     init_shutdown();
     init_setPositionController();
     init_flyTo();
+    init_cameraUrlPose();
     init_cropController();
     init_rootTransformController();
     init_transformModeController();
@@ -71256,6 +71404,14 @@ var require_app = __commonJS({
       getTiles: () => tiles,
       getTilesetBoundingSphere
     });
+    var cameraUrlPose = createCameraUrlPoseController({
+      camera,
+      cameraController,
+      setStatus
+    });
+    var appliedInitialCameraPose = cameraUrlPose.applyFromUrl({
+      showStatus: true
+    });
     setPositionController = createSetPositionController({
       cameraController,
       maxClickDistanceSq: SET_POSITION_CLICK_MAX_DISTANCE_SQ,
@@ -71559,10 +71715,19 @@ var require_app = __commonJS({
       renderer,
       setStatus
     });
-    loadTileset(TILESET_URL);
+    window.addEventListener("popstate", () => {
+      if (cameraUrlPose.applyFromUrl({ showStatus: true })) {
+        flyTo2.cancelCameraFlight();
+        cancelPositionPickModes();
+      }
+    });
+    window.addEventListener("pagehide", cameraUrlPose.flush);
+    cameraController.addEventListener("finish", cameraUrlPose.flush);
+    loadTileset(TILESET_URL, { frameOnLoad: !appliedInitialCameraPose });
     function frame() {
       cameraController.update();
       flyTo2.update();
+      cameraUrlPose.update();
       rootTransform.flush();
       globeController.update();
       tiles?.update();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3dtiles-inspector",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "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/viewer/app.js

@@ -17,6 +17,7 @@ import { bindViewerEvents } from './dom/events.js';
 import { createViewerShutdownRequester } from './io/shutdown.js';
 import { createSetPositionController } from './io/setPositionController.js';
 import { createFlyToController } from './navigation/flyTo.js';
+import { createCameraUrlPoseController } from './navigation/cameraUrlPose.js';
 import { createCropController } from './screenSelection/cropController.js';
 import { createRootTransformController } from './transform/rootTransformController.js';
 import { createTransformModeController } from './transform/transformModeController.js';
@@ -269,6 +270,15 @@ const flyTo = createFlyToController({
   getTilesetBoundingSphere,
 });
 
+const cameraUrlPose = createCameraUrlPoseController({
+  camera,
+  cameraController,
+  setStatus,
+});
+const appliedInitialCameraPose = cameraUrlPose.applyFromUrl({
+  showStatus: true,
+});
+
 setPositionController = createSetPositionController({
   cameraController,
   maxClickDistanceSq: SET_POSITION_CLICK_MAX_DISTANCE_SQ,
@@ -605,11 +615,21 @@ bindViewerEvents({
   setStatus,
 });
 
-loadTileset(TILESET_URL);
+window.addEventListener('popstate', () => {
+  if (cameraUrlPose.applyFromUrl({ showStatus: true })) {
+    flyTo.cancelCameraFlight();
+    cancelPositionPickModes();
+  }
+});
+window.addEventListener('pagehide', cameraUrlPose.flush);
+cameraController.addEventListener('finish', cameraUrlPose.flush);
+
+loadTileset(TILESET_URL, { frameOnLoad: !appliedInitialCameraPose });
 
 function frame() {
   cameraController.update();
   flyTo.update();
+  cameraUrlPose.update();
   rootTransform.flush();
   globeController.update();
   tiles?.update();

package/src/viewer/navigation/cameraUrlPose.js

@@ -0,0 +1,172 @@
+const CAMERA_POSE_PARAM = 'camerapose';
+const CAMERA_POSE_ALIAS_PARAM = 'cameraPose';
+const CAMERA_POSE_COMPONENT_COUNT = 7;
+const CAMERA_POSE_COMPONENT_COUNT_WITH_ZOOM = 8;
+const CAMERA_POSE_UPDATE_INTERVAL_MS = 100;
+const CAMERA_POSE_VALUE_SEPARATOR = '_';
+
+function formatPoseNumber(value) {
+  const fixed = value.toFixed(9);
+  const trimmed = fixed
+    .replace(/(\.\d*?[1-9])0+$/, '$1')
+    .replace(/\.0+$/, '');
+
+  return trimmed === '-0' ? '0' : trimmed;
+}
+
+function serializeCameraPose(camera) {
+  camera.updateMatrixWorld(true);
+
+  const values = [
+    camera.position.x,
+    camera.position.y,
+    camera.position.z,
+    camera.quaternion.x,
+    camera.quaternion.y,
+    camera.quaternion.z,
+    camera.quaternion.w,
+  ];
+
+  if (camera.isOrthographicCamera) {
+    values.push(camera.zoom);
+  }
+
+  if (!values.every(Number.isFinite)) {
+    return null;
+  }
+
+  return values.map(formatPoseNumber).join(CAMERA_POSE_VALUE_SEPARATOR);
+}
+
+function getCameraPoseParam(url) {
+  return (
+    url.searchParams.get(CAMERA_POSE_PARAM) ??
+    url.searchParams.get(CAMERA_POSE_ALIAS_PARAM)
+  );
+}
+
+function parseCameraPose(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return null;
+  }
+
+  const parts = value.trim().split(/[,_\s]+/).filter(Boolean);
+  if (
+    parts.length !== CAMERA_POSE_COMPONENT_COUNT &&
+    parts.length !== CAMERA_POSE_COMPONENT_COUNT_WITH_ZOOM
+  ) {
+    return null;
+  }
+
+  const values = parts.map(Number);
+  if (!values.every(Number.isFinite)) {
+    return null;
+  }
+
+  const quaternionLength = Math.hypot(
+    values[3],
+    values[4],
+    values[5],
+    values[6],
+  );
+  if (quaternionLength <= 1e-12) {
+    return null;
+  }
+
+  const zoom = values.length === CAMERA_POSE_COMPONENT_COUNT_WITH_ZOOM
+    ? values[7]
+    : null;
+  if (zoom !== null && zoom <= 0) {
+    return null;
+  }
+
+  return {
+    position: values.slice(0, 3),
+    quaternion: values.slice(3, 7),
+    zoom,
+  };
+}
+
+function replaceCameraPoseUrl(serializedPose) {
+  const url = new URL(window.location.href);
+  url.searchParams.delete(CAMERA_POSE_ALIAS_PARAM);
+  url.searchParams.set(CAMERA_POSE_PARAM, serializedPose);
+  window.history.replaceState(window.history.state, '', url.href);
+}
+
+function getInvalidCameraPoseMessage() {
+  return 'Invalid camerapose URL parameter ignored. Expected x_y_z_qx_qy_qz_qw.';
+}
+
+export function createCameraUrlPoseController({
+  camera,
+  cameraController,
+  setStatus,
+}) {
+  let lastSerializedPose = null;
+  let lastUrlWriteTime = 0;
+
+  function applyPose(pose) {
+    camera.position.fromArray(pose.position);
+    camera.quaternion.fromArray(pose.quaternion).normalize();
+
+    if (pose.zoom !== null && camera.isOrthographicCamera) {
+      camera.zoom = Math.max(pose.zoom, 1e-6);
+      camera.updateProjectionMatrix();
+    }
+
+    camera.updateMatrixWorld(true);
+    cameraController.setCamera(camera);
+  }
+
+  function applyFromUrl({ showStatus = false } = {}) {
+    const url = new URL(window.location.href);
+    const value = getCameraPoseParam(url);
+    if (value === null) {
+      return false;
+    }
+
+    const pose = parseCameraPose(value);
+    if (!pose) {
+      if (showStatus && setStatus) {
+        setStatus(getInvalidCameraPoseMessage(), true);
+      }
+      return false;
+    }
+
+    applyPose(pose);
+    lastSerializedPose = serializeCameraPose(camera);
+    lastUrlWriteTime = performance.now();
+    if (lastSerializedPose) {
+      replaceCameraPoseUrl(lastSerializedPose);
+    }
+    if (showStatus && setStatus) {
+      setStatus('Applied camera pose from URL.');
+    }
+    return true;
+  }
+
+  function flush() {
+    const serializedPose = serializeCameraPose(camera);
+    if (!serializedPose || serializedPose === lastSerializedPose) {
+      return;
+    }
+
+    replaceCameraPoseUrl(serializedPose);
+    lastSerializedPose = serializedPose;
+    lastUrlWriteTime = performance.now();
+  }
+
+  function update(time = performance.now()) {
+    if (time - lastUrlWriteTime < CAMERA_POSE_UPDATE_INTERVAL_MS) {
+      return;
+    }
+    flush();
+  }
+
+  return {
+    applyFromUrl,
+    flush,
+    update,
+  };
+}

package/src/viewer/navigation/flyTo.js

@@ -133,6 +133,11 @@ export function createFlyToController({
     return true;
   }
 
+  function cancelCameraFlight() {
+    activeCameraFlight = null;
+    activeCameraFlightStatus = '';
+  }
+
   async function applyTilesSetPositionFromPointerEvent(event) {
     const coordinate = pickCoordinateFromPointerEvent(event);
     if (!coordinate) {
@@ -204,6 +209,7 @@ export function createFlyToController({
 
   return {
     applyTilesSetPositionFromPointerEvent,
+    cancelCameraFlight,
     frameTileset,
     getActiveEllipsoid,
     moveCameraToCoordinate,