@splnlss/3d-story-viewer 0.8.3 → 0.8.5

package/README.md

@@ -82,7 +82,7 @@ ellipsoidal height in meters. Caller-supplied positions are accepted from
 -12,000 through 100,000 meters. Internal conversions do not clamp or range-limit
 derived heights, so orbiting above 100 km and changing view mode remain valid.
 ECEF positions and local east-north-up (ENU) translations are meters;
-camera pitch, yaw, and roll and Gaussian XYZ rotations are degrees. Gaussian
+camera pitch, yaw, and roll and local-model XYZ rotations are degrees. Local
 scale is positive and dimensionless. 3D Tiles and mesh longitude/latitude
 offsets are degrees, and their altitude offsets are ellipsoidal meters. Missing
 offset members default independently to zero, while an explicit zero is
@@ -95,6 +95,15 @@ the existing geometry; it does not georeference a local model. A missing or
 invalid origin emits `CONTENT_LAYER_ERROR` and leaves the loaded mesh attached
 without the offset.
 
+Ungeoreferenced GLB models can instead use `options.transform`. Its `anchor`
+is WGS84 longitude/latitude in decimal degrees and ellipsoidal altitude in
+meters. `translationENU` is east/north/up in meters, `rotationDegrees` is a
+model-local XYZ Euler rotation in degrees, and `scale` is positive and
+dimensionless. The default `[90, 0, 0]` rotation maps glTF +Y Up to ENU +Up;
+set an explicit rotation when the model's authored axes differ. A local
+transform cannot be combined with legacy `offset` or `offsetOrigin`. Existing
+ECEF GLBs without a transform keep their coordinates.
+
 All accepted geospatial and camera values must be finite. Labels require
 longitude, latitude, and altitude on every update. At an exact pole, ECEF to
 geodetic conversion returns longitude 0 degrees because longitude is
@@ -150,6 +159,41 @@ RAD hosts must support HTTP byte ranges and cross-origin `GET`/`HEAD` requests.
 Expose `Content-Length`, `Content-Range`, and `Accept-Ranges`; relative RAD
 sidecar files must use the same policy.
 
+## Local GLB Placement and Targeted Updates
+
+```js
+const localBarn = {
+    id: 'barn', name: 'Barn', type: 'mesh', labels: ['barn'],
+    data: { url: 'https://assets.example.com/barn.glb' },
+    options: {
+        transform: {
+            anchor: { longitude: -105.2, latitude: 39.96, altitude: 1700 },
+            translationENU: [0, 0, 0], rotationDegrees: [90, 0, 0], scale: 1,
+        },
+    },
+};
+viewer.replaceContentLayer(localBarn.id, localBarn); // add or replace one layer
+viewer.replaceContentLayer(localBarn.id, null); // remove one layer
+```
+
+`replaceContentLayer` preserves unrelated layer objects and resources. It
+reports an invalid layer definition through `CONTENT_LAYER_ERROR`; an invalid
+ID or a mismatched replacement ID throws synchronously. A failed replacement
+leaves the previous layer in place. Existing `defineContentLayers` calls still
+replace the full set while retaining the current enabled-label selection.
+
+### Migrating From 0.8.4
+
+Version 0.8.5 adds optional local GLB placement and targeted content
+replacement. Existing mesh and 3D Tiles definitions keep their 0.8.4
+coordinates and offsets. Callers adding local GLBs should supply a WGS84
+anchor and review the glTF Y-up default in the scene.
+Transformed local GLBs render in the terrain depth pass with their authored
+glTF materials and the viewer's shared Draco/KTX2 decoders. Their render order
+is fixed to 0 so a catalog overlay order cannot make them show through terrain.
+GLBs without a transform retain the legacy layer-6 patch rendering and
+coordinate behavior.
+
 ## Environment Variables
 
 Viewer tokens can be passed directly in the constructor or provided through Vite environment variables: