@developmentseed/deck.gl-raster 0.7.0-beta.1 → 0.8.0-beta.1

package/dist/raster-tileset/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/raster-tileset/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC9E,YAAY,EACV,MAAM,EACN,YAAY,EACZ,OAAO,EACP,kBAAkB,GACnB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/raster-tileset/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,qCAAqC,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EACV,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,MAAM,EACN,YAAY,EACZ,OAAO,EACP,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/raster-tileset/index.js

@@ -1,5 +1,6 @@
 export { AffineTileset } from "./affine-tileset.js";
 export { AffineTilesetLevel } from "./affine-tileset-level.js";
 export { RasterTileset2D } from "./raster-tileset-2d.js";
+export { sortItemsByDistanceFromViewportCenter } from "./sort-by-distance.js";
 export { TileMatrixSetAdaptor } from "./tile-matrix-set.js";
 //# sourceMappingURL=index.js.map

package/dist/raster-tileset/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/raster-tileset/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/raster-tileset/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,qCAAqC,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/raster-tileset/raster-tile-traversal.d.ts

@@ -13,14 +13,13 @@
  * The result is a set of tiles at varying zoom levels that efficiently
  * cover the visible area with appropriate detail.
  *
- * The traversal is driven by a {@link TilesetDescriptor}, which abstracts over
+ * The traversal is driven by a {@link RasterTilesetDescriptor}, which abstracts over
  * both OGC TileMatrixSet grids and Zarr multiscale pyramids.
  */
 import type { Viewport } from "@deck.gl/core";
-import type { OrientedBoundingBox } from "@math.gl/culling";
-import { CullingVolume } from "@math.gl/culling";
+import { CullingVolume, OrientedBoundingBox } from "@math.gl/culling";
 import { BoundingVolumeCache } from "./bounding-volume-cache.js";
-import type { TilesetDescriptor, TilesetLevel } from "./tileset-interface.js";
+import type { RasterTilesetDescriptor, RasterTilesetLevel } from "./tileset-interface.js";
 import type { Bounds, TileIndex, ZRange } from "./types.js";
 /**
  * Raster Tile Node - represents a single tile in a tileset pyramid.
@@ -29,8 +28,8 @@ import type { Bounds, TileIndex, ZRange } from "./types.js";
  *
  * This node class uses the following coordinate system:
  *
- * - x: tile column (0 to TilesetLevel.matrixWidth, left to right)
- * - y: tile row (0 to TilesetLevel.matrixHeight, top to bottom)
+ * - x: tile column (0 to RasterTilesetLevel.matrixWidth, left to right)
+ * - y: tile row (0 to RasterTilesetLevel.matrixHeight, top to bottom)
  * - z: overview level. This assumes ordering where: 0 = coarsest, higher = finer
  */
 export declare class RasterTileNode {
@@ -57,17 +56,17 @@ export declare class RasterTileNode {
     /** A cache of the children of this node. */
     private _children?;
     constructor(x: number, y: number, z: number, { descriptor }: {
-        descriptor: TilesetDescriptor;
+        descriptor: RasterTilesetDescriptor;
     });
     /** Get the level info for this tile's z index. */
-    get level(): TilesetLevel;
+    get level(): RasterTilesetLevel;
     /** Get the children of this node.
      *
      * Find all tiles at level this.z + 1 whose spatial extent overlaps this tile.
      *
      * A tileset pyramid is not guaranteed to be a quadtree — it is a stack of
      * independent grids. We find children by mapping the parent tile's CRS bounds
-     * into the child grid using {@link TilesetLevel.crsBoundsToTileRange}.
+     * into the child grid using {@link RasterTilesetLevel.crsBoundsToTileRange}.
      */
     get children(): RasterTileNode[] | null;
     /**
@@ -106,6 +105,14 @@ export declare class RasterTileNode {
          * comparison would. See `dev-docs/lod-and-pixel-matching.md` § (A).
          */
         pixelRatio: number;
+        /**
+         * Number of world copies to shift this tile's bounding volume by along
+         * common-space X for frustum testing. Default `0` (primary world).
+         * Non-zero passes are additive — they may set `selected = true` but
+         * never override a previous `true` to `false`. See
+         * `dev-docs/world-copies.md`.
+         */
+        worldOffset?: number;
         /**
          * Bounding-volume cache shared by every node in this traversal. Populated
          * lazily as tiles are visited; reused across `getTileIndices` calls (so
@@ -138,8 +145,23 @@ export declare class RasterTileNode {
      * volume depends only on `(z, x, y, zRange)` for a given descriptor, so on a
      * cache hit it is returned without rerunning {@link computeBoundingVolume}'s
      * proj4 reprojections + oriented-bounding-box fit.
+     *
+     * For non-zero `worldOffset`, returns a translated copy (center shifted by
+     * `worldOffset * TILE_SIZE` along common-space X) without polluting the
+     * cache — the cache always stores the offset-0 volume. See
+     * `dev-docs/world-copies.md`.
+     *
+     * @param zRange               Elevation `[min, max]` in common-space units.
+     * @param project              Projection function for Globe view, or `null`
+     *                             for Web Mercator common space.
+     * @param boundingVolumeCache  Cache keyed by `z/x/y`. Stores the offset-0
+     *                             volume only.
+     * @param worldOffset          Number of world copies to translate the result
+     *                             by along common-space X. `0` returns the
+     *                             cached offset-0 volume directly. Non-zero
+     *                             values return a fresh translated copy.
      */
-    getBoundingVolume(zRange: ZRange, project: ((xyz: number[]) => number[]) | null, boundingVolumeCache: BoundingVolumeCache): {
+    getBoundingVolume(zRange: ZRange, project: ((xyz: number[]) => number[]) | null, boundingVolumeCache: BoundingVolumeCache, worldOffset?: number): {
         boundingVolume: OrientedBoundingBox;
         commonSpaceBounds: Bounds;
     };
@@ -157,7 +179,40 @@ export declare class RasterTileNode {
      *
      */
     private _getGenericBoundingVolume;
+    /**
+     * Globe-view bounding volume: reproject the tile's reference points to WGS84,
+     * project them onto the globe sphere (`project` = `viewport.projectPosition`)
+     * to build the oriented bounding box used for frustum culling, and separately
+     * compute a Web-Mercator-world AABB for the `bounds` pre-filter in
+     * {@link update} (which compares against `wgs84Bounds` in mercator world).
+     *
+     * NOTE: elevation is not modeled on globe yet — reference points are sampled
+     * at the surface (z = 0). Flat rasters only. See
+     * `dev-docs/specs/2026-05-21-globe-view-design.md`.
+     */
+    private _getGlobeBoundingVolume;
 }
+/**
+ * Rescale positions from EPSG:3857 into deck.gl's common space
+ *
+ * Similar to the upstream code here:
+ * https://github.com/visgl/deck.gl/blob/b0134f025148b52b91320d16768ab5d14a745328/modules/geo-layers/src/tileset-2d/tile-2d-traversal.ts#L172-L177
+ */
+export declare function rescaleEPSG3857ToCommonSpace([x, y]: [number, number]): [
+    number,
+    number
+];
+/**
+ * Inverse of {@link rescaleEPSG3857ToCommonSpace}: rescale a deck.gl
+ * common-space position back into EPSG:3857 meters.
+ *
+ * Common-space inputs are in-range by construction, so (unlike the forward
+ * direction) no latitude clamp is applied.
+ */
+export declare function rescaleCommonSpaceToEPSG3857([x, y]: [number, number]): [
+    number,
+    number
+];
 /**
  * Build the list of root (z=0) `RasterTileNode`s for the traversal.
  *
@@ -176,19 +231,19 @@ export declare class RasterTileNode {
  * Exported for unit testing.
  */
 export declare function createRootTiles(opts: {
-    descriptor: TilesetDescriptor;
+    descriptor: RasterTilesetDescriptor;
     viewport: Pick<Viewport, "getBounds">;
     datasetWgs84Bounds: Bounds;
 }): RasterTileNode[];
 /**
  * Get tile indices visible in viewport.
  *
- * Uses frustum culling driven by a {@link TilesetDescriptor}, which abstracts
+ * Uses frustum culling driven by a {@link RasterTilesetDescriptor}, which abstracts
  * over OGC TileMatrixSet grids and Zarr multiscale pyramids.
  *
  * Overview levels follow the descriptor ordering: index 0 = coarsest, higher = finer.
  */
-export declare function getTileIndices(descriptor: TilesetDescriptor, opts: {
+export declare function getTileIndices(descriptor: RasterTilesetDescriptor, opts: {
     viewport: Viewport;
     maxZ: number;
     zRange: ZRange | null;

package/dist/raster-tileset/raster-tile-traversal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"raster-tile-traversal.d.ts","sourceRoot":"","sources":["../../src/raster-tileset/raster-tile-traversal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EACL,aAAa,EAGd,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,KAAK,EACV,MAAM,EAIN,SAAS,EACT,MAAM,EACP,MAAM,YAAY,CAAC;AAiEpB;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACzB,yBAAyB;IACzB,CAAC,EAAE,MAAM,CAAC;IAEV,0BAA0B;IAC1B,CAAC,EAAE,MAAM,CAAC;IAEV,uDAAuD;IACvD,CAAC,EAAE,MAAM,CAAC;IAEV,OAAO,CAAC,UAAU,CAAoB;IAEtC;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAAC,CAAU;IAE/B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,CAAU;IAE3B,4CAA4C;IAC5C,OAAO,CAAC,SAAS,CAAC,CAA0B;gBAG1C,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,EAAE,UAAU,EAAE,EAAE;QAAE,UAAU,EAAE,iBAAiB,CAAA;KAAE;IAQnD,kDAAkD;IAClD,IAAI,KAAK,IAAI,YAAY,CAExB;IAED;;;;;;;OAOG;IACH,IAAI,QAAQ,IAAI,cAAc,EAAE,GAAG,IAAI,CA+BtC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,MAAM,EAAE;QACb,QAAQ,EAAE,QAAQ,CAAC;QAEnB,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;QAE9C,aAAa,EAAE,aAAa,CAAC;QAE7B,eAAe,EAAE,MAAM,CAAC;QACxB,wCAAwC;QACxC,IAAI,EAAE,MAAM,CAAC;QACb,sCAAsC;QACtC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,wCAAwC;QACxC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;;;;WAKG;QACH,UAAU,EAAE,MAAM,CAAC;QACnB;;;;;WAKG;QACH,mBAAmB,EAAE,mBAAmB,CAAC;KAC1C,GAAG,OAAO;IAyFX;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,GAAE,cAAc,EAAO,GAAG,cAAc,EAAE;IAY5D;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO;IAUhE;;;;;;;;OAQG;IACH,iBAAiB,CACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC,GAAG,IAAI,EAC7C,mBAAmB,EAAE,mBAAmB,GACvC;QAAE,cAAc,EAAE,mBAAmB,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE;IAUrE;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAwB7B;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;CAyDlC;AAsHD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,UAAU,EAAE,iBAAiB,CAAC;IAC9B,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACtC,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,cAAc,EAAE,CA4CnB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,iBAAiB,EAC7B,IAAI,EAAE;IACJ,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C,GACA,SAAS,EAAE,CAiGb"}
+{"version":3,"file":"raster-tile-traversal.d.ts","sourceRoot":"","sources":["../../src/raster-tileset/raster-tile-traversal.ts"],"names":[],"mappings":"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"}

package/dist/raster-tileset/raster-tile-traversal.js

@@ -13,12 +13,13 @@
  * The result is a set of tiles at varying zoom levels that efficiently
  * cover the visible area with appropriate detail.
  *
- * The traversal is driven by a {@link TilesetDescriptor}, which abstracts over
+ * The traversal is driven by a {@link RasterTilesetDescriptor}, which abstracts over
  * both OGC TileMatrixSet grids and Zarr multiscale pyramids.
  */
-import { _GlobeViewport, assert } from "@deck.gl/core";
+import { _GlobeViewport as GlobeViewport } from "@deck.gl/core";
 import { transformBounds } from "@developmentseed/proj";
-import { CullingVolume, makeOrientedBoundingBoxFromPoints, Plane, } from "@math.gl/culling";
+import { Vector3 } from "@math.gl/core";
+import { CullingVolume, makeOrientedBoundingBoxFromPoints, OrientedBoundingBox, Plane, } from "@math.gl/culling";
 import { lngLatToWorld, worldToLngLat } from "@math.gl/web-mercator";
 import { BoundingVolumeCache } from "./bounding-volume-cache.js";
 /**
@@ -33,6 +34,12 @@ import { BoundingVolumeCache } from "./bounding-volume-cache.js";
  * bottom-right.
  */
 const TILE_SIZE = 512;
+/**
+ * Maximum number of world copies to test on each side of the primary world
+ * during multi-world tile traversal. Matches upstream
+ * `@deck.gl/geo-layers/tile-2d-traversal.ts`.
+ */
+const MAX_MAPS = 3;
 // Reference points used to sample tile boundaries for bounding volume
 // calculation.
 //
@@ -64,6 +71,18 @@ const REF_POINTS_9 = REF_POINTS_5.concat([
     [1, 0.5], // right edge
     [0.5, 1], // bottom edge
 ]);
+// For the globe bounding volume: REF_POINTS_9 plus two more points on the
+// horizontal centerline (11 points total). The sphere surface bulges most
+// between samples along the widest span of a tile, so denser sampling there
+// keeps the oriented bounding box from under-enclosing the tile (which would
+// false-cull it). This matches upstream deck.gl's densest reference set, used
+// there only for the coarsest (whole-world) zoom. We use it for every globe
+// tile: a tile never spans more than the whole world, so 11 points always
+// suffice, and per-tile cost is paid once thanks to the bounding-volume cache.
+const REF_POINTS_11 = REF_POINTS_9.concat([
+    [0.25, 0.5],
+    [0.75, 0.5],
+]);
 /** semi-major axis of the WGS84 ellipsoid
  *
  * EPSG:3857 also uses the WGS84 datum, so this is used for conversions from
@@ -84,8 +103,8 @@ const MAX_WEB_MERCATOR_LAT = 85.05112877980659;
  *
  * This node class uses the following coordinate system:
  *
- * - x: tile column (0 to TilesetLevel.matrixWidth, left to right)
- * - y: tile row (0 to TilesetLevel.matrixHeight, top to bottom)
+ * - x: tile column (0 to RasterTilesetLevel.matrixWidth, left to right)
+ * - y: tile row (0 to RasterTilesetLevel.matrixHeight, top to bottom)
  * - z: overview level. This assumes ordering where: 0 = coarsest, higher = finer
  */
 export class RasterTileNode {
@@ -127,7 +146,7 @@ export class RasterTileNode {
      *
      * A tileset pyramid is not guaranteed to be a quadtree — it is a stack of
      * independent grids. We find children by mapping the parent tile's CRS bounds
-     * into the child grid using {@link TilesetLevel.crsBoundsToTileRange}.
+     * into the child grid using {@link RasterTilesetLevel.crsBoundsToTileRange}.
      */
     get children() {
         if (!this._children) {
@@ -174,16 +193,29 @@ export class RasterTileNode {
      * @returns true if this tile or any descendant is visible, false otherwise
      */
     update(params) {
-        // Reset state
-        this.childVisible = false;
-        this.selected = false;
-        const { viewport, cullingVolume, elevationBounds, minZ, maxZ = this.descriptor.levels.length - 1, project, bounds, pixelRatio, boundingVolumeCache, } = params;
-        // Get bounding volume for this tile
-        const { boundingVolume, commonSpaceBounds } = this.getBoundingVolume(elevationBounds, project, boundingVolumeCache);
+        const { viewport, cullingVolume, elevationBounds, minZ, maxZ = this.descriptor.levels.length - 1, project, bounds, pixelRatio, worldOffset = 0, boundingVolumeCache, } = params;
+        // Reset per-frame state on the primary pass only. Non-zero worldOffset
+        // passes are additive — they can flip selected/childVisible from
+        // false → true but never the reverse. See dev-docs/world-copies.md.
+        if (worldOffset === 0) {
+            this.childVisible = false;
+            this.selected = false;
+        }
+        // Get bounding volume for this tile (translated for frustum culling at
+        // non-zero worldOffset). `commonSpaceBounds` is the Web-Mercator-world AABB
+        // used for the LOD latitude (a worldOffset only shifts X, so latitude is
+        // unaffected).
+        const { boundingVolume, commonSpaceBounds } = this.getBoundingVolume(elevationBounds, project, boundingVolumeCache, worldOffset);
         // Step 1: Bounds checking
-        // If geographic bounds are specified, reject tiles outside those bounds
-        if (bounds && !this.insideBounds(bounds, commonSpaceBounds)) {
-            return false;
+        // If geographic bounds are specified, reject tiles outside those bounds.
+        // The dataset's `bounds` live in primary-world common space, and a tile
+        // at `(x, y, z)` represents the same data regardless of which world copy
+        // it's drawn in — so always compare against the offset-0 AABB.
+        if (bounds) {
+            const primaryWorldVolume = this.getBoundingVolume(elevationBounds, project, boundingVolumeCache, 0);
+            if (!this.insideBounds(bounds, primaryWorldVolume.commonSpaceBounds)) {
+                return false;
+            }
         }
         // Frustum culling
         // Test if tile's bounding volume intersects the camera frustum
@@ -197,7 +229,7 @@ export class RasterTileNode {
         // Only select this tile if no child is visible (prevents overlapping tiles)
         // "When pitch is low, force selection at maxZ."
         if (!this.childVisible && this.z >= minZ) {
-            const metersPerCSSPixel = getMetersPerPixelAtBoundingVolume(boundingVolume, viewport.zoom);
+            const metersPerCSSPixel = getMetersPerPixelAtCommonSpaceBounds(commonSpaceBounds, viewport.zoom);
             const tileMetersPerPixel = this.level.metersPerPixel;
             // On-screen size of one source pixel, measured in device pixels.
             // ≤ 1 means the source can fully resolve the rendered framebuffer.
@@ -215,14 +247,22 @@ export class RasterTileNode {
         // Note that if `this.children` is `null`, then there are no children
         // available because we're already at the finest tile resolution available
         if (children && children.length > 0) {
-            this.selected = false;
+            if (worldOffset === 0) {
+                this.selected = false;
+            }
             let anyChildVisible = false;
             for (const child of children) {
                 if (child.update(params)) {
                     anyChildVisible = true;
                 }
             }
-            this.childVisible = anyChildVisible;
+            // Only set childVisible to true; never override a previous true to
+            // false on a subsequent pass. Offset-0 already starts with
+            // childVisible=false (reset above), so this preserves the
+            // "any pass that finds a visible child wins" semantics.
+            if (anyChildVisible) {
+                this.childVisible = true;
+            }
             return anyChildVisible;
         }
         return true;
@@ -266,15 +306,41 @@ export class RasterTileNode {
      * volume depends only on `(z, x, y, zRange)` for a given descriptor, so on a
      * cache hit it is returned without rerunning {@link computeBoundingVolume}'s
      * proj4 reprojections + oriented-bounding-box fit.
+     *
+     * For non-zero `worldOffset`, returns a translated copy (center shifted by
+     * `worldOffset * TILE_SIZE` along common-space X) without polluting the
+     * cache — the cache always stores the offset-0 volume. See
+     * `dev-docs/world-copies.md`.
+     *
+     * @param zRange               Elevation `[min, max]` in common-space units.
+     * @param project              Projection function for Globe view, or `null`
+     *                             for Web Mercator common space.
+     * @param boundingVolumeCache  Cache keyed by `z/x/y`. Stores the offset-0
+     *                             volume only.
+     * @param worldOffset          Number of world copies to translate the result
+     *                             by along common-space X. `0` returns the
+     *                             cached offset-0 volume directly. Non-zero
+     *                             values return a fresh translated copy.
      */
-    getBoundingVolume(zRange, project, boundingVolumeCache) {
-        const hit = boundingVolumeCache.get(this.z, this.x, this.y);
-        if (hit && hit.zRange[0] === zRange[0] && hit.zRange[1] === zRange[1]) {
-            return hit;
+    getBoundingVolume(zRange, project, boundingVolumeCache, worldOffset = 0) {
+        const cacheHit = boundingVolumeCache.get(this.z, this.x, this.y);
+        // `base` is the tile's volume in the primary world (offset 0). The cache
+        // only ever stores the primary-world volume; it is returned as-is for
+        // worldOffset 0, or translated below for a non-zero offset.
+        let base;
+        if (cacheHit &&
+            cacheHit.zRange[0] === zRange[0] &&
+            cacheHit.zRange[1] === zRange[1]) {
+            base = cacheHit;
         }
-        const result = this.computeBoundingVolume(zRange, project);
-        boundingVolumeCache.set(this.z, this.x, this.y, { zRange, ...result });
-        return result;
+        else {
+            base = this.computeBoundingVolume(zRange, project);
+            boundingVolumeCache.set(this.z, this.x, this.y, { zRange, ...base });
+        }
+        if (worldOffset === 0) {
+            return base;
+        }
+        return translateBoundingVolume(base, worldOffset * TILE_SIZE);
     }
     /**
      * Compute (without caching) the 3D bounding volume for this tile in deck.gl's
@@ -284,12 +350,10 @@ export class RasterTileNode {
      * tiling is already in EPSG:3857.
      */
     computeBoundingVolume(zRange, project) {
-        // Case 1: Globe view - need to construct an oriented bounding box from
-        // reprojected sample points, but also using the `project` param
+        // Case 1: Globe view — reproject sample points to WGS84 and project them
+        // onto the globe sphere with the viewport's `project` function.
         if (project) {
-            assert(false, "TODO: implement getBoundingVolume in Globe view");
-            // Reproject positions to wgs84 instead, then pass them into `project`
-            // return makeOrientedBoundingBoxFromPoints(refPointPositions);
+            return this._getGlobeBoundingVolume(project);
         }
         // (Future) Case 2: Web Mercator input image, can directly compute AABB in
         // common space
@@ -344,6 +408,47 @@ export class RasterTileNode {
             commonSpaceBounds,
         };
     }
+    /**
+     * Globe-view bounding volume: reproject the tile's reference points to WGS84,
+     * project them onto the globe sphere (`project` = `viewport.projectPosition`)
+     * to build the oriented bounding box used for frustum culling, and separately
+     * compute a Web-Mercator-world AABB for the `bounds` pre-filter in
+     * {@link update} (which compares against `wgs84Bounds` in mercator world).
+     *
+     * NOTE: elevation is not modeled on globe yet — reference points are sampled
+     * at the surface (z = 0). Flat rasters only. See
+     * `dev-docs/specs/2026-05-21-globe-view-design.md`.
+     */
+    _getGlobeBoundingVolume(project) {
+        const tileCorners = this.level.projectedTileCorners(this.x, this.y);
+        const refPointsWgs84 = sampleReferencePointsInWGS84(REF_POINTS_11, tileCorners, this.descriptor.projectTo4326);
+        const refPointPositions = [];
+        let minX = Number.POSITIVE_INFINITY;
+        let minY = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        let maxY = Number.NEGATIVE_INFINITY;
+        for (const [lng, lat] of refPointsWgs84) {
+            const projected = project([lng, lat, 0]);
+            refPointPositions.push([projected[0], projected[1], projected[2]]);
+            const [worldX, worldY] = lngLatToWorld([lng, lat]);
+            if (worldX < minX) {
+                minX = worldX;
+            }
+            if (worldY < minY) {
+                minY = worldY;
+            }
+            if (worldX > maxX) {
+                maxX = worldX;
+            }
+            if (worldY > maxY) {
+                maxY = worldY;
+            }
+        }
+        return {
+            boundingVolume: makeOrientedBoundingBoxFromPoints(refPointPositions),
+            commonSpaceBounds: [minX, minY, maxX, maxY],
+        };
+    }
 }
 /**
  * Wrap a forward projection to EPSG:3857 so that it never returns NaN.
@@ -403,13 +508,31 @@ function sampleReferencePointsInEPSG3857(refPoints, tileCorners, projectTo3857,
     }
     return refPointPositions;
 }
+/**
+ * Sample the selected reference points in WGS84 lng/lat.
+ *
+ * Like {@link sampleReferencePointsInEPSG3857}, reference points are `[relX,
+ * relY]` fractions in `[0, 1]` bilinearly interpolated across the tile's four
+ * CRS corners, then reprojected to WGS84. Used by the GlobeView bounding-volume
+ * path, which projects lng/lat onto the sphere rather than rescaling 3857
+ * meters into common space.
+ */
+function sampleReferencePointsInWGS84(refPoints, tileCorners, projectTo4326) {
+    const { topLeft, topRight, bottomLeft, bottomRight } = tileCorners;
+    const refPointPositions = [];
+    for (const [relX, relY] of refPoints) {
+        const [geoX, geoY] = bilerpPoint(topLeft, topRight, bottomLeft, bottomRight, relX, relY);
+        refPointPositions.push(projectTo4326(geoX, geoY));
+    }
+    return refPointPositions;
+}
 /**
  * Rescale positions from EPSG:3857 into deck.gl's common space
  *
  * Similar to the upstream code here:
  * https://github.com/visgl/deck.gl/blob/b0134f025148b52b91320d16768ab5d14a745328/modules/geo-layers/src/tileset-2d/tile-2d-traversal.ts#L172-L177
  */
-function rescaleEPSG3857ToCommonSpace([x, y]) {
+export function rescaleEPSG3857ToCommonSpace([x, y]) {
     // Clamp Y to Web Mercator bounds
     const clampedY = Math.max(-EPSG_3857_HALF_CIRCUMFERENCE, Math.min(EPSG_3857_HALF_CIRCUMFERENCE, y));
     return [
@@ -417,6 +540,19 @@ function rescaleEPSG3857ToCommonSpace([x, y]) {
         (clampedY / EPSG_3857_CIRCUMFERENCE + 0.5) * TILE_SIZE,
     ];
 }
+/**
+ * Inverse of {@link rescaleEPSG3857ToCommonSpace}: rescale a deck.gl
+ * common-space position back into EPSG:3857 meters.
+ *
+ * Common-space inputs are in-range by construction, so (unlike the forward
+ * direction) no latitude clamp is applied.
+ */
+export function rescaleCommonSpaceToEPSG3857([x, y]) {
+    return [
+        (x / TILE_SIZE - 0.5) * EPSG_3857_CIRCUMFERENCE,
+        (y / TILE_SIZE - 0.5) * EPSG_3857_CIRCUMFERENCE,
+    ];
+}
 /**
  * Above this root-tile count, `createRootTiles` culls to the viewport
  * before instantiation. Below it, every root tile is created and downstream
@@ -482,7 +618,7 @@ export function createRootTiles(opts) {
 /**
  * Get tile indices visible in viewport.
  *
- * Uses frustum culling driven by a {@link TilesetDescriptor}, which abstracts
+ * Uses frustum culling driven by a {@link RasterTilesetDescriptor}, which abstracts
  * over OGC TileMatrixSet grids and Zarr multiscale pyramids.
  *
  * Overview levels follow the descriptor ordering: index 0 = coarsest, higher = finer.
@@ -497,7 +633,7 @@ export function getTileIndices(descriptor, opts) {
     // so this frame can never evict an entry it will need again this frame.
     boundingVolumeCache.sweep();
     // Only define `project` function for Globe viewports, same as upstream
-    const project = viewport instanceof _GlobeViewport && viewport.resolution
+    const project = viewport instanceof GlobeViewport && viewport.resolution
         ? viewport.projectPosition
         : null;
     // Get the culling volume of the current camera
@@ -562,6 +698,24 @@ export function getTileIndices(descriptor, opts) {
     for (const root of roots) {
         root.update(traversalParams);
     }
+    // World-copy passes: when the viewport spans multiple world copies (e.g.
+    // WebMercatorViewport with repeat: true panned across the antimeridian),
+    // re-run the traversal with the tile bounding volumes shifted by ±1, ±2…
+    // world copies along common-space X. A tile is selected if any pass selects
+    // it. See dev-docs/world-copies.md.
+    const subViewportCount = viewport.subViewports?.length ?? 0;
+    if (subViewportCount > 1) {
+        for (let offset = -1; offset >= -MAX_MAPS; offset--) {
+            if (!runOffsetPass(roots, traversalParams, offset)) {
+                break;
+            }
+        }
+        for (let offset = 1; offset <= MAX_MAPS; offset++) {
+            if (!runOffsetPass(roots, traversalParams, offset)) {
+                break;
+            }
+        }
+    }
     // Collect selected tiles
     const selectedNodes = [];
     for (const root of roots) {
@@ -569,6 +723,23 @@ export function getTileIndices(descriptor, opts) {
     }
     return selectedNodes;
 }
+/**
+ * Run a non-zero world-offset traversal pass over each root.
+ *
+ * Returns `true` if any root tile was visible at this offset, signaling the
+ * caller to walk further from the primary world. Returns `false` when no
+ * tiles were visible — the offset has gone past the visible range and the
+ * caller stops walking that side.
+ */
+function runOffsetPass(roots, baseParams, worldOffset) {
+    let anyVisible = false;
+    for (const root of roots) {
+        if (root.update({ ...baseParams, worldOffset })) {
+            anyVisible = true;
+        }
+    }
+    return anyVisible;
+}
 /**
  * Compute the meters per pixel at a given latitude and zoom level.
  *
@@ -583,10 +754,44 @@ function getMetersPerPixel(latitude, zoom) {
     return ((earthCircumference * Math.cos((latitude * Math.PI) / 180)) /
         2 ** (zoom + 8));
 }
-function getMetersPerPixelAtBoundingVolume(boundingVolume, zoom) {
-    const [_lng, lat] = worldToLngLat(boundingVolume.center);
+function getMetersPerPixelAtCommonSpaceBounds(commonSpaceBounds, zoom) {
+    const [minX, minY, maxX, maxY] = commonSpaceBounds;
+    // `commonSpaceBounds` is in Web Mercator world space ([0, 512]) in BOTH the
+    // mercator and globe paths (the globe path builds it via `lngLatToWorld`), so
+    // its center maps back to a real latitude. The 3D oriented-bounding-box
+    // center, by contrast, is in globe common space on a globe and would
+    // `worldToLngLat` to a garbage latitude (~-89°, near the Mercator
+    // singularity), making meters-per-pixel far too small so the LOD always
+    // recursed to the finest level.
+    const [, lat] = worldToLngLat([(minX + maxX) / 2, (minY + maxY) / 2]);
     return getMetersPerPixel(lat, zoom);
 }
+/**
+ * Translate a tile's bounding volume by `dx` units along common-space X.
+ *
+ * Returns a fresh OBB and AABB; does not mutate the input. Used by the
+ * world-copy traversal to test the same tile at multiple shifted positions
+ * without recomputing the underlying geometry.
+ */
+function translateBoundingVolume(base, dx) {
+    const { boundingVolume, commonSpaceBounds } = base;
+    const center = boundingVolume.center;
+    const translatedCenter = new Vector3((center[0] ?? 0) + dx, center[1] ?? 0, center[2] ?? 0);
+    const translated = new OrientedBoundingBox(translatedCenter, boundingVolume.halfAxes);
+    // `update()`'s bounds check always re-reads the offset-0 `commonSpaceBounds`,
+    // so this translated AABB isn't consumed in production — it's kept for API
+    // symmetry with `boundingVolume` and is asserted directly by unit tests.
+    const translatedBounds = [
+        commonSpaceBounds[0] + dx,
+        commonSpaceBounds[1],
+        commonSpaceBounds[2] + dx,
+        commonSpaceBounds[3],
+    ];
+    return {
+        boundingVolume: translated,
+        commonSpaceBounds: translatedBounds,
+    };
+}
 /**
  * Compute the axis-aligned bounding box of a rotated tile rectangle.
  */