@loaders.gl/tiles 4.5.3 → 5.0.0-alpha.10

package/LICENSE

@@ -24,8 +24,20 @@ THE SOFTWARE.
 
 Copyright (c) 2015 Uber Technologies, Inc.
 
-loaders.gl includes certain files from Cesium (https://github.com/AnalyticalGraphicsInc/cesium) 
-under the  Apache 2 License (found in the submodule: modules/3d-tiles):)
+Portions of modules/images/src/lib/category-api/binary-image-api.ts are based on
+binary-gltf-utils (https://github.com/Qantas94Heavy/binary-gltf-utils) under the
+MIT License reproduced above.
+
+Copyright (c) 2016-17 Karl Cheng
+
+Portions of modules/schema-utils/src/lib/utils/async-queue.ts are adapted from
+async-iter-demo (https://github.com/rauschma/async-iter-demo) under the MIT
+License reproduced above.
+
+Copyright (c) 2016 Axel Rauschmayer
+
+loaders.gl includes certain files from Cesium (https://github.com/CesiumGS/cesium)
+under the Apache 2.0 License, including files in modules/3d-tiles.
 
 Copyright 2011-2018 CesiumJS Contributors
 
@@ -38,4 +50,3 @@ Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and limitations under the License.
-

package/README.md

@@ -4,4 +4,139 @@ This module contains the common components for tiles loaders, i.e. [3D tiles](ht
 
 [loaders.gl](https://loaders.gl/docs) is a collection of loaders for big data visualizations.
 
-For documentation please visit the [website](https://loaders.gl).
+## Source-backed tilesets
+
+`Tileset3D` now supports source-backed construction for format-specific loading behavior while keeping traversal and culling logic in the shared runtime.
+
+```ts
+import {Tiles3DLoader} from '@loaders.gl/3d-tiles';
+import {Tiles3DSource, Tileset3D} from '@loaders.gl/tiles';
+
+const source = new Tiles3DSource({url, loader: Tiles3DLoader});
+const tileset = new Tileset3D(source, options);
+```
+
+Available source classes:
+
+- `Tiles3DSource` for 3D Tiles datasets
+- `I3SSource` for I3S datasets
+
+Archive-backed `.3tz` and `.slpk` datasets use the same source classes through archive-aware
+source construction helpers. Archive parsing stays in the `@loaders.gl/3d-tiles` and
+`@loaders.gl/i3s` packages rather than being duplicated in `@loaders.gl/tiles`.
+
+`Tileset3D` now requires an explicit source instance. Root metadata loading and normalization happen inside the source implementation.
+
+The shared `Tileset3DSource` contract owns:
+
+- root metadata loading and normalization
+- runtime tile-header creation
+- tile content URL resolution
+- tile content fetching
+- format-specific view-state metadata
+- format-specific post-load bookkeeping
+
+`Tileset3D` remains responsible for traversal, culling, request scheduling, selection, and cache management.
+
+### Camera-independent content traversal
+
+Conversion and inspection jobs can visit the complete dataset without creating a viewport:
+
+```ts
+import {traverseTilesetContents} from '@loaders.gl/tiles';
+
+for await (const {tile, contents} of traverseTilesetContents(tileset, {signal})) {
+  // `contents` preserves the tile's declared content order.
+  processTile(tile, contents);
+}
+```
+
+The traversal follows declared placements in depth-first order, resolves lazy 3D Tiles subtrees and
+I3S child headers through their source, and visits nested tilesets before descending into them.
+Repeated resource URLs remain separate visits when they appear at different placements, since each
+placement can have its own transform. By default, the caller owns loaded-content lifetime and
+should unload or destroy the tileset when processing completes.
+
+Pass `{signal, unloadContent: true}` with a runtime dedicated to traversal to unload newly read
+content when the iterator advances or closes, including on cancellation and errors. Preloaded
+content is retained. Finish processing each placement before requesting the next one; do not retain
+payloads or concurrently update the runtime. Tile placements and children remain available, and the
+caller still owns tileset destruction and source/archive lifetimes. This limits content retention,
+not decoder allocations, source caches, or the full dataset's metadata.
+
+For broader documentation please visit the [website](https://loaders.gl).
+
+## Tileset2D
+
+`Tileset2D` is the shared cache and loading engine for source-backed 2D tile rendering.
+
+API reference: [`Tileset2D`](../../docs/modules/tiles/api-reference/tileset-2d.md)
+
+Its purpose is to separate:
+
+- shared tile content, request scheduling, and cache eviction
+- per-view selection and visibility state
+
+That lets multiple layers and views reuse the same tile cache without duplicating requests or
+overwriting each other's traversal state.
+
+### Installation
+
+```ts
+import {
+  Tileset2D,
+  type Tileset2DProps,
+  type TileLoadProps
+} from '@loaders.gl/tiles';
+```
+
+### Construct from `getTileData`
+
+```ts
+const tileset = new Tileset2D({
+  getTileData: async ({id, bbox}: TileLoadProps) => fetchTile(id, bbox),
+  maxZoom: 14,
+  maxCacheSize: 256
+});
+```
+
+### Construct from a loaders.gl `TileSource`
+
+```ts
+import type {TileSource} from '@loaders.gl/loader-utils';
+import {Tileset2D} from '@loaders.gl/tiles';
+
+const tileSource: TileSource = createTileSourceSomehow();
+const tileset = Tileset2D.fromTileSource(tileSource, {
+  maxCacheByteSize: 32 * 1024 * 1024
+});
+```
+
+When backed by a `TileSource`, the tileset reads metadata once and adopts:
+
+- `minZoom`
+- `maxZoom`
+- `boundingBox` mapped to `extent`
+
+Explicit options still override source metadata.
+
+### Key API
+
+- `tiles`: current contents of the shared tile cache
+- `selectedTiles` / `visibleTiles`: union views across all attached consumers
+- `loadingTiles` / `unloadedTiles`: current loading and unloaded cache subsets
+- `stats`: live `@probe.gl/stats` counters for cache size, selection, visibility, and consumers
+- `subscribe(listener)`: tile lifecycle, metadata update, and stats callbacks
+- `setOptions(opts)`: update runtime configuration
+- `reloadAll()`: mark retained tiles stale for reload
+- `finalize()`: abort requests and clear the cache
+
+The shared stats currently populate:
+
+- `Tiles In Cache`
+- `Cache Size`
+- `Visible Tiles`
+- `Selected Tiles`
+- `Loading Tiles`
+- `Unloaded Tiles`
+- `Consumers`