+```
Asynchronously hashes data in batches.
diff --git a/docs/modules/csv/api-reference/csv-writer.md b/docs/modules/csv/api-reference/csv-writer.md
index a5683c7669..15fb69ece3 100644
--- a/docs/modules/csv/api-reference/csv-writer.md
+++ b/docs/modules/csv/api-reference/csv-writer.md
@@ -1,5 +1,9 @@
# CSVWriter
+
+ 
+
+
Writes tabular data into comma-separated value and [delimiter-separated value](https://en.wikipedia.org/wiki/Delimiter-separated_values) encoding.
| Loader | Characteristic |
diff --git a/docs/modules/draco/README.md b/docs/modules/draco/README.md
index 7f809c57b6..76d77881d4 100644
--- a/docs/modules/draco/README.md
+++ b/docs/modules/draco/README.md
@@ -28,7 +28,7 @@ Draco support requires the Draco libraries, which are quite big (see table below
Bundling the entire `draco3d` library:
-```js
+```typescript
import draco from 'draco3d';
import {setLoaderOptions} from '@loaders.gl/core';
setLoaderOptions({
@@ -40,7 +40,7 @@ setLoaderOptions({
Bundling only the WebAssembly decoder
-```js
+```typescript
import {setLoaderOptions} from '@loaders.gl/core';
setLoaderOptions({
modules: {
diff --git a/docs/modules/draco/api-reference/draco-loader.md b/docs/modules/draco/api-reference/draco-loader.md
index 359f26679a..b8ed5bdf3a 100644
--- a/docs/modules/draco/api-reference/draco-loader.md
+++ b/docs/modules/draco/api-reference/draco-loader.md
@@ -23,7 +23,7 @@ Features:
## Usage
-```js
+```typescript
import {DracoLoader} from '@loaders.gl/draco';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/draco/api-reference/draco-writer.md b/docs/modules/draco/api-reference/draco-writer.md
index 05a3ccf07a..0b595e5273 100644
--- a/docs/modules/draco/api-reference/draco-writer.md
+++ b/docs/modules/draco/api-reference/draco-writer.md
@@ -14,7 +14,7 @@ The `DracoWriter` encodes a mesh or point cloud using [Draco](https://google.git
## Usage
-```js
+```typescript
import {DracoWriter} from '@loaders.gl/draco';
import {encode} from '@loaders.gl/core';
diff --git a/docs/modules/draco/images/draco-writer.md b/docs/modules/draco/images/draco-writer.md
index 7b3c03de5c..1ff8737576 100644
--- a/docs/modules/draco/images/draco-writer.md
+++ b/docs/modules/draco/images/draco-writer.md
@@ -14,7 +14,7 @@ The `DracoWriter` encodes a mesh or point cloud (maps of attributes) using [Drac
## Usage
-```js
+```typescript
import {DracoWriter} from '@loaders.gl/draco';
import {encode} from '@loaders.gl/core';
diff --git a/docs/modules/excel/api-reference/excel-loader.md b/docs/modules/excel/api-reference/excel-loader.md
index 48b297b5b0..96f5d3f6a3 100644
--- a/docs/modules/excel/api-reference/excel-loader.md
+++ b/docs/modules/excel/api-reference/excel-loader.md
@@ -12,7 +12,7 @@
## Usage
-```js
+```typescript
import {ExcelLoader} from '@loaders.gl/excel';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/flatgeobuf/api-reference/flatgeobuf-loader.md b/docs/modules/flatgeobuf/api-reference/flatgeobuf-loader.md
index a446a4e2ed..571f9633fe 100644
--- a/docs/modules/flatgeobuf/api-reference/flatgeobuf-loader.md
+++ b/docs/modules/flatgeobuf/api-reference/flatgeobuf-loader.md
@@ -1,4 +1,4 @@
-# FlatGeobufLoader
+# FlatGeobufLoader 🚧
@@ -18,7 +18,7 @@ Loader for the [FlatGeobuf](http://flatgeobuf.org/) format, a binary FlatBuffers
## Usage
-```js
+```typescript
import {FlatGeobufLoader} from '@loaders.gl/flatgeobuf';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/geopackage/README.md b/docs/modules/geopackage/README.md
index ddf31b3af7..18598c78d7 100644
--- a/docs/modules/geopackage/README.md
+++ b/docs/modules/geopackage/README.md
@@ -1,4 +1,4 @@
-# Overview
+# Overview 🚧
diff --git a/docs/modules/geopackage/api-reference/geopackage-loader.md b/docs/modules/geopackage/api-reference/geopackage-loader.md
index a8b54f02d0..dff6dae211 100644
--- a/docs/modules/geopackage/api-reference/geopackage-loader.md
+++ b/docs/modules/geopackage/api-reference/geopackage-loader.md
@@ -1,4 +1,6 @@
-# GeoPackageLoader
+# GeoPackageLoader 🚧
+
+
@@ -18,40 +20,45 @@ GeoPackage loader
## Usage
-```js
+To load all tables in a geopackage file as GeoJSON:
+
+```typescript
import {GeoPackageLoader, GeoPackageLoaderOptions} from '@loaders.gl/geopackage';
import {load} from '@loaders.gl/core';
import {Tables, ObjectRowTable, Feature} from '@loaders.gl/schema';
const optionsAsTable: GeoPackageLoaderOptions = {
geopackage: {
+ shape: 'tables',
sqlJsCDN: 'https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.5.0/'
- },
- gis: {
- format: 'tables'
}
};
-const tablesData: Tables = await load(url, GeoPackageLoader, optionsAsTable);
+const tablesData: Tables = await load(url, GeoPackageLoader, optionsAsTable);
+```
+To load a specific table named `feature_table` in a geopackage file as GeoJSON:
+
+```typescript
const optionsAsGeoJson: GeoPackageLoaderOptions = {
geopackage: {
- sqlJsCDN: 'https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.5.0/'
- },
- gis: {
- format: 'geojson'
+ shape: 'geojson',
+ table: 'feature_table',
+ sqlJsCDN: 'https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.5.0/',
}
};
-const geoJsonData: Record = await load(url, GeoPackageLoader, optionsAsGeoJson);
+
+const geoJsonData: GeoJSONTable = await load(url, GeoPackageLoader, optionsAsGeoJson);
+
```
## Options
| Option | Type | Default | Description |
| --------------------- | ------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `options.shape` | String | `'tables'` \| '`geojson-table'` | Output format. |
+| `options.table` | String | N/A | name of table to load | Output format. |
| `geopackage.sqlJsCDN` | String | `'https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.5.0/'` | CDN from which to load the SQL.js bundle. This is loaded asynchronously when the GeoPackageLoader is called on a file. |
-| `options.gis.format` | String | `'tables'` | Output format for data. If set to `geojson` |
-- `geopackage.sqlJsCDN`: As of March 2022, SQL.js versions 1.6.0, 1.6.1, and 1.6.2 were tested as not working. Therefore this library pins to use of SQL.js version 1.5.0, and requires the WASM bundle from the same version.
## Output
@@ -65,7 +72,11 @@ The `GeoPackageLoader` currently loads all features from all vector tables.
Returns `Record`, an object mapping from table name to an array of GeoJSON features. The `Feature` type is defined in `@loaders.gl/schema`.
+## Remarks
+
+- `options.geopackage.sqlJsCDN`: As of March 2022, SQL.js versions 1.6.0, 1.6.1, and 1.6.2 were tested as not working.
+
## Future Work
-- Select a single vector layer/table to load. Right now all vector tables are loaded. This would fit well in the two-stage loader process, where the first stage reads metadata from the file (i.e. the list of available layers) and the second stage loads one or more
+- Select a single vector layer/table to load. This could would fit well in the two-stage loader process, where the first stage reads metadata from the file (i.e. the list of available layers) and the second stage loads one or more tables.
- Binary and GeoJSON output. Right now the output is GeoJSON-only, and is contained within an object mapping table names to geometry data. This is the same problem as we discussed previously for MVT, where with GeoPackage especially it's decently likely to only desire a portion of the layers contained in the file.
diff --git a/docs/modules/geopackage/formats/geopackage.md b/docs/modules/geopackage/formats/geopackage.md
new file mode 100644
index 0000000000..533c736675
--- /dev/null
+++ b/docs/modules/geopackage/formats/geopackage.md
@@ -0,0 +1,5 @@
+# Geopackage
+
+
+
+The `@loaders.gl/geopackage` module handles the OGC [GeoPackage](https://www.geopackage.org/) format.
diff --git a/docs/modules/gis/api-reference/binary-to-geojson.md b/docs/modules/gis/api-reference/binary-to-geojson.md
index 6fdb321387..f190c8a97b 100644
--- a/docs/modules/gis/api-reference/binary-to-geojson.md
+++ b/docs/modules/gis/api-reference/binary-to-geojson.md
@@ -5,7 +5,7 @@ a valid GeoJSON Geometry, Feature or array of Features.
## Usage
-```js
+```typescript
import {load} from '@loaders.gl/core';
import {JSONLoader} from '@loaders.gl/json';
import {geojsonToBinary, binaryToGeojson} from '@loaders.gl/gis';
diff --git a/docs/modules/gis/api-reference/geojson-to-binary.md b/docs/modules/gis/api-reference/geojson-to-binary.md
index a9a409db77..1c3303525c 100644
--- a/docs/modules/gis/api-reference/geojson-to-binary.md
+++ b/docs/modules/gis/api-reference/geojson-to-binary.md
@@ -7,22 +7,14 @@ main process.
## Usage
-```js
+```typescript
import {load} from '@loaders.gl/core';
import {JSONLoader} from '@loaders.gl/json';
import {geojsonToBinary} from '@loaders.gl/gis';
const geoJSONfeatures = await load('data.geojson', JSONLoader);
-/*
- * Default options are:
- *
- * {
- * fixRingWinding: true
- * numericPropKeys: derived from data
- * PositionDataType: Float32Array
- * }
- */
+// See table below for full list of options
const options = {PositionDataType: Float32Array};
const binaryFeatures = geojsonToBinary(geoJSONfeatures, options);
```
@@ -38,13 +30,13 @@ non-numeric property objects of the given geometry type.
Each `TypedArray` is wrapped inside an _accessor object_, where `.value` contains the raw numeric data, and `.size` gives the number of values per vertex. For example,
-```js
+```typescript
positions: {value: Float32Array, size: 3}
```
corresponds to 3D coordinates, where each vertex is defined by three numbers.
-```js
+```typescript
{
points: {
// Array of x, y or x, y, z positions
@@ -95,8 +87,8 @@ corresponds to 3D coordinates, where each vertex is defined by three numbers.
polygonIndices: {value: Uint16Array | Uint32Array, size: 1},
// Indices within positions of the start of each primitive Polygon/ring
primitivePolygonIndices: {value: Uint16Array | Uint32Array, size: 1},
- // Triangle indices. Allows deck.gl to skip performing costly triangulation on main thread
- triangles: {value: Uint32Array, size: 1},
+ // Triangle indices. Allows deck.gl to skip performing costly triangulation on main thread. Not present if `options.triangulate` is `false`
+ triangles?: {value: Uint32Array, size: 1},
// Array of original feature indexes by vertex
globalFeatureIds: {value: Uint16Array | Uint32Array, size: 1},
// Array of Polygon feature indexes by vertex
@@ -121,10 +113,13 @@ corresponds to 3D coordinates, where each vertex is defined by three numbers.
| Option | Type | Default | Description |
| ---------------- | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| fixRingWinding | `Boolean` | `true` | Whether the fix incorrect ring winding for polygons. Valid `GeoJSON` polygons have the outer ring coordinates in CCW order and with holes in CW order |
+| fixRingWinding | `Boolean` | `true` | Whether to fix incorrect ring winding for polygons. Valid `GeoJSON` polygons have the outer ring coordinates in CCW order and with holes in CW order |
| numericPropKeys | `Array` | Derived from data | Names of feature properties that should be converted to numeric `TypedArray`s. Passing `[]` will force all properties to be returned as normal objects. |
| PositionDataType | `class` | `Float32Array` | Data type used for positions arrays. |
+| triangulate | `Boolean` | `true` | Whether polygons are broken into triangles as part of the conversion (generally required for GPU rendering) |
## Notes
In the case of the source geoJson features having an object as a property, it would not be deep cloned, so it would be linked from the output object (be careful on further mutations).
+
+Triangulation of polygons can be time consuming. If not needed, set the `triangulate` option to `false`.
diff --git a/docs/modules/gltf/README.md b/docs/modules/gltf/README.md
index d362629a91..1a58f94a07 100644
--- a/docs/modules/gltf/README.md
+++ b/docs/modules/gltf/README.md
@@ -23,7 +23,7 @@ To simplify traversing and building glTF data objects, the [`GLTFScenegraph`](/d
A glTF data object can also be built programmatically using the GLTFScenegraph's "fluent API":
-```js
+```typescript
import {encode} from '@loaders.gl/gltf';
import {GLTFScenegraph, GLTFWriter} from '@loaders.gl/gltf';
const gltfScenegraph = new GLTFScenegraph()
@@ -55,7 +55,7 @@ Certain glTF extensions are fully or partially supported by the glTF classes. Fo
Draco encoding and decoding is supported by the `GLTFBuilder` and `GLTFParser` classes but requires the DracoWriter and DracoLoader dependencies to be "injected" by the application.
-```js
+```typescript
import {GLTFBuilder} from '@loaders.gl/gltf';
import {DracoWriter, DracoLoader} from '@loaders.gl/draco';
diff --git a/docs/modules/gltf/api-reference/glb-loader.md b/docs/modules/gltf/api-reference/glb-loader.md
index d97879a11d..de892e88d7 100644
--- a/docs/modules/gltf/api-reference/glb-loader.md
+++ b/docs/modules/gltf/api-reference/glb-loader.md
@@ -17,7 +17,7 @@ Note: applications that want to parse GLB-formatted glTF files would normally us
## Usage
-```js
+```typescript
import {load} from '@loaders.gl/core';
import {GLBLoader} from '@loaders.gl/gltf';
const gltf = await load(url, GLBLoader);
@@ -39,7 +39,7 @@ Remarks:
Returns
-```json
+```typescripton
{
"header": {
"byteLength": number,
diff --git a/docs/modules/gltf/api-reference/glb-writer.md b/docs/modules/gltf/api-reference/glb-writer.md
index 46327baadc..0f8a2f3379 100644
--- a/docs/modules/gltf/api-reference/glb-writer.md
+++ b/docs/modules/gltf/api-reference/glb-writer.md
@@ -14,7 +14,7 @@ Note: applications that want to encode GLB-formatted glTF files should normally
## Usage
-```js
+```typescript
import {GLBWriter} from '@loaders.gl/gltf';
import {encodeSync} from '@loaders.gl/core';
diff --git a/docs/modules/gltf/api-reference/gltf-loader.md b/docs/modules/gltf/api-reference/gltf-loader.md
index c93ed7c9b2..d22a87633e 100644
--- a/docs/modules/gltf/api-reference/gltf-loader.md
+++ b/docs/modules/gltf/api-reference/gltf-loader.md
@@ -40,7 +40,7 @@ The GLTF Loader returns an object with a `json` field containing the glTF Sceneg
Optionally, the loaded gltf can be "post processed", which lightly annotates and transforms the loaded JSON structure to make it easier to use. Refer to [postProcessGLTF](post-process-gltf) for details.
-In addition, certain glTF extensions, in particular Draco mesh encoding, can be fully or partially processed during loading. When possible (and extension processing is enabled), such extensions will be resolved/decompressed and replaced with standards conformant representations. See [glTF Extensions](gltf-extensions) for more information.
+In addition, certain glTF extensions, in particular Draco mesh encoding, can be fully or partially processed during loading. When possible (and extension processing is enabled), such extensions will be resolved/decompressed and replaced with standards conformant representations.
Note: while supported, synchronous parsing of glTF (e.g. using `parseSync()`) has significant limitations. When parsed asynchronously (using `await parse()` or `await load()`), the following additional capabilities are enabled:
@@ -78,7 +78,7 @@ The data format returned by the `GLTFLoader` is the unmodified glTF JSON extract
The standard glTF JSON structure will be available in the `json` field.
-```json
+```typescripton
{
json: {
scenes: [...],
@@ -92,7 +92,7 @@ The standard glTF JSON structure will be available in the `json` field.
However, the objects inside these arrays will have been pre-processed to simplify usage. For details on changes and extra fields added to the various glTF objects, see [post processing](post-process-gltf).
-```json
+```typescripton
{
// The base URI used to load this glTF, if any. For resolving relative uris to linked resources.
baseUri: String,
diff --git a/docs/modules/gltf/api-reference/gltf-scenegraph.md b/docs/modules/gltf/api-reference/gltf-scenegraph.md
index e68d2dba94..6bea6d5562 100644
--- a/docs/modules/gltf/api-reference/gltf-scenegraph.md
+++ b/docs/modules/gltf/api-reference/gltf-scenegraph.md
@@ -8,7 +8,7 @@ The `GLTFScenegraph` class provides an API for accessing and modifying glTF data
### Accessing
-```js
+```typescript
import {GLTFLoader, GLTFScenegraph} from '@loaders.gl/gltf';
import {load} from '@loaders.gl/core';
@@ -42,7 +42,7 @@ const scenegraph = gltf.getScene(2);
### Modifying
-```js
+```typescript
import {load, encode} from '@loaders.gl/core';
import {ImageWriter} from '@loaders.gl/images';
import {GLTFLoader, GLTFWriter, GLTFScenegraph} from '@loaders.gl/gltf';
diff --git a/docs/modules/gltf/api-reference/gltf-writer.md b/docs/modules/gltf/api-reference/gltf-writer.md
index 147e1106ad..c2217f96a2 100644
--- a/docs/modules/gltf/api-reference/gltf-writer.md
+++ b/docs/modules/gltf/api-reference/gltf-writer.md
@@ -12,7 +12,7 @@ The `GLTFWriter` is a writer for glTF scenegraphs.
## Usage
-```js
+```typescript
import {GLTFWriter} from '@loaders.gl/gltf';
import {encodeSync} from '@loaders.gl/core';
diff --git a/docs/modules/gltf/api-reference/post-process-gltf.md b/docs/modules/gltf/api-reference/post-process-gltf.md
index 240cb0b954..8541f2a2a6 100644
--- a/docs/modules/gltf/api-reference/post-process-gltf.md
+++ b/docs/modules/gltf/api-reference/post-process-gltf.md
@@ -7,7 +7,7 @@ For details see below.
## Usage
-```js
+```typescript
import {load} from '@loaders.gl.core';
import {GLTFLoader, postProcessGLTF} from '@loaders.gl/gltf';
diff --git a/docs/modules/gltf/formats/gltf.md b/docs/modules/gltf/formats/gltf.md
index 30f87e1f85..ad42436a0a 100644
--- a/docs/modules/gltf/formats/gltf.md
+++ b/docs/modules/gltf/formats/gltf.md
@@ -24,7 +24,7 @@ A glTF file uses one of two possible file extensions: .gltf (JSON/ASCII) or .glb
## glTF Extensions
-glTF extensions can be present in glTF files, and will be present in the parsed JSON. glTF extensions can supported by applications by inspecting the `extensions` fields inside glTF objects, and it is up to each application to handle or ignore them.
+glTF extensions can be present in glTF files, and will be present in the parsed JSON. glTF extensions can be supported by applications by inspecting the `extensions` fields inside glTF objects, and it is up to each application to handle or ignore them.
loaders.gl aims to provide support for glTF extensions that can be handled completely or partially during loading, and article describes glTF extensions that are fully or partially processed by the `@loaders.gl/gltf` classes.
@@ -37,7 +37,8 @@ Note that many glTF extensions affect aspects that are firmly outside of the sco
| [KHR_texture_basisu](#khr_texture_basisu) | Y | Adds the ability to specify textures using KTX v2 |
| [KHR_texture_transform](#khr_texture_transform) | Y | Adds transformation properties (translation, rotation, scale) for TEXCOORD\_ mesh attribute |
| KHR_texture_webp | Y |
-| [EXT_mesh_features](#ext_mesh_features) | N | (In progress) 3D tiles extension |
+| [EXT_mesh_features](#ext_mesh_features) | Y | 3D tiles extension |
+| [EXT_structural_metadata](#ext_structural_metadata) | Y | 3D tiles extension |
| [KHR_lights_punctual](#khr_lights_punctual) | Y\* | Deprecated |
| [KHR_materials_unlit](#khr_materials_unlit) | Y\* | Deprecated |
| [EXT_feature_metadata](#ext_feature_metadata) | Y\* | Deprecated. 3D tiles extension |
@@ -120,3 +121,9 @@ The `GLTFLoader` by default fully decompresses meshopt compressed geometries, re
3D tiles extension by Cesium. This extension defines a means of assigning identifiers to geometry and subcomponents of geometry within a glTF 2.0 asset.
[EXT_mesh_features](https://github.com/CesiumGS/glTF/tree/c38f7f37e894004353c15cd0481bc5b7381ce841/extensions/2.0/Vendor/EXT_mesh_features)
+
+### EXT_structural_metadata
+
+3D tiles extension by Cesium. This extension defines a means of storing structured metadata within a glTF 2.0 asset.
+
+[EXT_structural_metadata](https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata)
diff --git a/docs/modules/i3s/README.md b/docs/modules/i3s/README.md
index 3ab18eeeb4..27195649b5 100644
--- a/docs/modules/i3s/README.md
+++ b/docs/modules/i3s/README.md
@@ -27,8 +27,6 @@ To handle the complex dynamic tile selection and loading required to performantl
- [`Tileset3D`](/docs/modules/tiles/api-reference/tileset-3d) to work with the loaded tileset.
- [`Tile3D`](/docs/modules/tiles/api-reference/tile-3d) to access data for a specific tile.
-## Remarks
-
-`@loaders.gl/3s` is still under experimental, and mainly support decoding `MeshPyramids` (3D Object and Integrated Mesh) profiles.
-
## Attribution
+
+MIT license, code is written for loaders.gl.
\ No newline at end of file
diff --git a/docs/modules/i3s/api-reference/i3s-loader.md b/docs/modules/i3s/api-reference/i3s-loader.md
index 82ac58cd12..7d68d30c3c 100644
--- a/docs/modules/i3s/api-reference/i3s-loader.md
+++ b/docs/modules/i3s/api-reference/i3s-loader.md
@@ -17,36 +17,36 @@ A loader for loading an [Indexed 3d Scene (I3S) layer](https://github.com/Esri/i
## I3S Layer type support
-| Layer Type | Supported | I3S Spec Link |
-| -------------------- | ------------ | ------------------------------------------------------------------------------ |
-| 3DObject | yes | https://github.com/Esri/i3s-spec/blob/master/docs/1.7/3Dobject_ReadMe.md |
-| Integrated Mesh | yes | https://github.com/Esri/i3s-spec/blob/master/docs/1.7/IntegratedMesh_ReadMe.md |
-| Points | no | https://github.com/Esri/i3s-spec/blob/master/docs/1.7/Point_ReadMe.md |
-| PointClouds | no | https://github.com/Esri/i3s-spec/blob/master/docs/2.0/pcsl_ReadMe.md |
-| Building Scene Layer | experimental | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/BSL_ReadMe.md |
+| Layer Type | Supported | I3S Spec Link |
+| -------------------- | -------------- | ------------------------------------------------------------------------------ |
+| 3DObject | ✅ | https://github.com/Esri/i3s-spec/blob/master/docs/1.7/3Dobject_ReadMe.md |
+| Integrated Mesh | ✅ | https://github.com/Esri/i3s-spec/blob/master/docs/1.7/IntegratedMesh_ReadMe.md |
+| Points | ❌ | https://github.com/Esri/i3s-spec/blob/master/docs/1.7/Point_ReadMe.md |
+| PointClouds | ❌ | https://github.com/Esri/i3s-spec/blob/master/docs/2.0/pcsl_ReadMe.md |
+| Building Scene Layer | 🚧 experimental | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/BSL_ReadMe.md |
## I3S Aspects support
| Aspect | Supported | I3S Spec Link |
| --------------------- | --------- | -------------------------------------------------------------------------------------------- |
-| Node pages | yes | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/nodePage.cmn.md |
-| Compressed attributes | yes | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/compressedAttributes.cmn.md |
-| PBR materials | yes | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/pbrMetallicRoughness.cmn.md |
-| Feature attributes | yes | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/attributeStorageInfo.cmn.md |
-| Texture Atlas | yes | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/texture.cmn.md#atlas-usage-and-regions |
+| Node pages | ✅ | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/nodePage.cmn.md |
+| Compressed attributes | ✅ | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/compressedAttributes.cmn.md |
+| PBR materials | ✅ | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/pbrMetallicRoughness.cmn.md |
+| Feature attributes | ✅ | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/attributeStorageInfo.cmn.md |
+| Texture Atlas | ✅ | https://github.com/Esri/i3s-spec/blob/master/docs/1.8/texture.cmn.md#atlas-usage-and-regions |
## Texture formats
I3S textures specification - https://github.com/Esri/i3s-spec/blob/master/docs/1.8/texture.cmn.md
-| Texture | Supported |
-| ---------------------------------------------- | ---------- |
-| JPEG | yes |
-| PNG | yes |
-| .dds with DXT1 (no alpha) | yes |
-| .dds with DXT5 (alpha channel) | yes |
-| ktx-etc2 | not tested |
-| Basis Universal Texture format in Khronos KTX2 | yes |
+| Texture | Supported |
+| ---------------------------------------------- | ------------ |
+| JPEG | ✅ |
+| PNG | ✅ |
+| .dds with DXT1 (no alpha) | ✅ |
+| .dds with DXT5 (alpha channel) | ✅ |
+| ktx-etc2 | 🚧 not tested |
+| Basis Universal Texture format in Khronos KTX2 | ✅ |
## Terms
@@ -72,7 +72,7 @@ A simple react app uses [`I3SLoader`](https://github.com/visgl/loaders.gl/blob/m
[Example Codepen](https://codepen.io/belom88/pen/JjamLvx)
-```js
+```typescript
import React, {Component} from 'react';
import {StaticMap} from 'react-map-gl';
@@ -157,7 +157,7 @@ A more complex example can be found [here](https://github.com/visgl/loaders.gl/t
Basic API usage is illustrated in the following snippet. Create a `Tileset3D` instance, point it a valid tileset URL, set up callbacks, and keep feeding in new camera positions:
-```js
+```typescript
import {load} from '@loaders.gl/core';
import {I3SLoader} from '@loaders.gl/i3s';
import {Tileset3D} from '@loaders.gl/tiles';
@@ -178,7 +178,7 @@ const viewport = new WebMercatorViewport({latitude, longitude, zoom, ...})
tileset3d.update(viewport);
// Viewport changes (pan zoom etc)
-tileset3d.update(viewport);
+tileset3d.selectTiles(viewport);
// Visible tiles
const visibleTiles = tileset3d.tiles.filter(tile => tile.selected);
@@ -237,15 +237,15 @@ The following fields are guaranteed. Additionally, the loaded tile object will c
After content is loaded, the following fields are guaranteed. But different tiles may have different extra content fields.
-| Field | Type | Contents |
-| -------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `cartesianOrigin` | `Number[3]` | "Center" of tile geometry in WGS84 fixed frame coordinates |
-| `cartographicOrigin` | `Number[3]` | "Origin" in lng/lat (center of tile's bounding volume) |
-| `modelMatrix` | `Number[16]` | Transforms tile geometry positions to fixed frame coordinates |
-| `vertexCount` | `Number` | Transforms tile geometry positions to fixed frame coordinates |
+| Field | Type | Contents |
+| -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `cartesianOrigin` | `Number[3]` | "Center" of tile geometry in WGS84 fixed frame coordinates |
+| `cartographicOrigin` | `Number[3]` | "Origin" in lng/lat (center of tile's bounding volume) |
+| `modelMatrix` | `Number[16]` | Transforms tile geometry positions to fixed frame coordinates |
+| `vertexCount` | `Number` | Transforms tile geometry positions to fixed frame coordinates |
| `attributes` | `Object` | Each attribute follows luma.gl [accessor](https://github.com/visgl/luma.gl/blob/master/docs/api-reference/webgl/README.md) properties |
-| `texture` | `Object` | Loaded texture by [`loaders.gl/image`](https://loaders.gl/modules/images/docs/api-reference/image-loader) |
-| `featureData` | `Object` | Loaded feature data for parsing the geometies (Will be deprecated in 2.x) |
+| `texture` | `Object` | Loaded texture by [`loaders.gl/image`](https://loaders.gl/modules/images/docs/api-reference/image-loader) |
+| `featureData` | `Object` | Loaded feature data for parsing the geometies (Will be deprecated in 2.x) |
`attributes` contains following fields
diff --git a/docs/modules/i3s/recipes/attribute-driven-colorization.md b/docs/modules/i3s/recipes/attribute-driven-colorization.md
new file mode 100644
index 0000000000..8de999e8a1
--- /dev/null
+++ b/docs/modules/i3s/recipes/attribute-driven-colorization.md
@@ -0,0 +1,118 @@
+# Attribute-driven colorization
+
+
+ 
+
+
+In I3S, a feature represents a real-world object within a node. For example, a building within a 3D object scene layer. Node resources such as geometry buffer and attributes can belong to a feature and can be accessed by an object-ID.
+
+In terms of geometry, every vertex of a mesh is associated with some feature. At the same time, every feature is associated with feature attribute values. For example, there might be `HEIGHT` attribute that stores roof height information about every building.
+
+All that means that it is possible to make some visual effects related to attribute value. It might be text labels, colors, opacity etc.
+
+From 3.4 version loaders.gl provides attributes colorization capability that allows colorization of node mesh by some attribute value.
+
+The complete case of attributes colorization is done in [I3S Explorer](https://i3s.loaders.gl/viewer?tileset=new-york). It is an open source ReactJS application. See source code on [GitHub](https://github.com/visgl/loaders.gl-showcases).
+
+
+
+## Find out layer's attributes
+
+It is necessary to pick some attribute to colorize a layer by. So it is necessary to load the layer JSON:
+
+```javascript
+import {load} from '@loaders.gl/core';
+import {I3SLoader} from '@loaders.gl/i3s';
+
+const i3sLayer = await load(url, I3SBuildingSceneLayerLoader);
+```
+
+List and types of attributes might be taken from [`i3sLayer.fields`](https://github.com/Esri/i3s-spec/blob/master/docs/1.9/field.cmn.md) and [`i3sLayer.attributeStorageInfo`](https://github.com/Esri/i3s-spec/blob/master/docs/1.8/attributeStorageInfo.cmn.md) properties.
+
+## Setup colorization scale
+
+Attributes colorization capability applies linear color gradient. To create this gradient attribute values range is required.
+
+To get minimum and maximum attribute values [statistics](https://github.com/Esri/i3s-spec/blob/master/docs/1.9/statisticsInfo.cmn.md) can be used. The [statistics info JSON](https://github.com/Esri/i3s-spec/blob/master/docs/1.9/statsInfo.cmn.md) has min and max values. Usage of those values allows setting true attribute values range not clamping extremum values.
+
+As soon as statistics info is stored in separate resources, it has to be loaded in a separate request. Statistics is just a JSON data and can be loaded with JSONLoader:
+
+```javascript
+import {load} from '@loaders.gl/core';
+import {JSONLoader} from '@loaders.gl/loader-utils';
+
+const attributeStats = await load(`${url}/statistics/f_5/0`, JSONLoader);
+```
+
+## Use I3SLoader with `colorsByAttribute` option
+
+To colorize a dataset I3SLoader has to be used with `colorsByAttribute` option:
+
+```
+ import { StaticMap } from "react-map-gl";
+ import DeckGL from "@deck.gl/react";
+ import { Tile3DLayer } from "@deck.gl/geo-layers";
+ import { I3SLoader } from "@loaders.gl/i3s";
+
+ function renderLayer() {
+ const loadOptions = {
+ i3s: {
+ colorsByAttribute: {
+ attributeName,
+ minValue: statistics.min,
+ maxValue: statistics.max,
+ minColor: [146, 146, 252, 255], // #9292FC
+ maxColor: [44, 44, 175, 255], // #2C2CAF
+ },
+ },
+ };
+ return new Tile3DLayer({
+ id: `tile3d-layer-${layer.id}`,
+ data: url,
+ loader: I3SLoader,
+ loadOptions,
+ });
+ }
+
+
+
+
+```
+
+## Colorization mode
+
+Attributes colorization capability can work in 2 modes: 'replace' and 'multiply'.
+
+`replace` mode. Attribute-based colors replace geometry vertex colors. This is the default mode.
+
+`multiply` mode. Attribute-based colors multiply with geometry vertex colors.
+
+Usage example:
+
+```javascript
+function renderLayer() {
+ const loadOptions = {
+ i3s: {
+ colorsByAttribute: {
+ attributeName,
+ minValue: statistics.min,
+ maxValue: statistics.max,
+ minColor: [146, 146, 252, 255], // #9292FC
+ maxColor: [44, 44, 175, 255], // #2C2CAF
+ mode: 'multiply' // or 'replace'
+ }
+ }
+ };
+ return new Tile3DLayer({
+ id: `tile3d-layer-${layer.id}`,
+ data: url,
+ loader: I3SLoader,
+ loadOptions
+ });
+}
+```
diff --git a/docs/modules/i3s/recipes/bsl-explorer.png b/docs/modules/i3s/recipes/bsl-explorer.png
new file mode 100644
index 0000000000..9e3487ca9b
Binary files /dev/null and b/docs/modules/i3s/recipes/bsl-explorer.png differ
diff --git a/docs/modules/i3s/recipes/building-scene-layer.md b/docs/modules/i3s/recipes/building-scene-layer.md
new file mode 100644
index 0000000000..b2bcb43fa7
--- /dev/null
+++ b/docs/modules/i3s/recipes/building-scene-layer.md
@@ -0,0 +1,96 @@
+# I3S Building Scene Layer (BSL)
+
+
+ 
+
+
+A building scene layer can represent 3D model content based on BIM structuring disciplines such as architectural or structural, and categories such as windows or walls. In I3S [specification](https://github.com/Esri/i3s-spec) BSL is a layer type.
+
+BSL doesn't have content resources. It is a composite layer that consists of multiple sublayers. Every sublayer can be: `group`, `3DObject` or `Point`.
+
+`group` sublayer is also just a composite layer. It contains further levels of sublayers and provides a nested structure for BSL. As a result, BSL has a tree-like sublayers structure with `3DObject` and `Point` layers;
+
+`3DObject` and `Point` sublayers are content layers. Those layer types are separated types of layers in I3S spec and can be used independently. Loaders.gl supports `3DObject` layer types and doesn't support `Point`.
+
+## BSL visualization with deck.gl
+
+I3S `3DObject` layer is shown in deck.gl with [Tile3DLayer](https://deck.gl/docs/api-reference/geo-layers/tile-3d-layer). The complete case of BSL visualization is done in [I3S Explorer](https://i3s.loaders.gl/viewer?tileset=turanga-library). It is an open source ReactJS application. See source code on [GitHub](https://github.com/visgl/loaders.gl-showcases).
+
+
+
+### Load BSL
+
+For BSL it is necessary to do preparation steps to obtain data for `Tile3DLayer`.
+
+Loaders.gl has `I3SBuildingSceneLayerLoader` that is used to load BSL JSON metadata and pick `3DObject` sublayers.
+
+```javascript
+import {load} from '@loaders.gl/core';
+import {I3SBuildingSceneLayerLoader} from '@loaders.gl/i3s';
+
+const {header, sublayers} = await load(tilesetData.url, I3SBuildingSceneLayerLoader);
+```
+
+The loader returns a flattened array called `sublayers` that contains only `3DObject` layers from the BSL sublayers tree.
+
+### Show sublayers in deck.gl
+
+```jsx
+import {StaticMap} from 'react-map-gl';
+import DeckGL from '@deck.gl/react';
+import {Tile3DLayer} from '@deck.gl/geo-layers';
+import {COORDINATE_SYSTEM} from '@deck.gl/core';
+import {I3SLoader} from '@loaders.gl/i3s';
+
+function renderLayer() {
+ const tile3dLayers = sublayers.map((layer) => {
+ if (!layer.visibility) {
+ return null;
+ }
+ const loadOptions = {
+ i3s: {coordinateSystem: COORDINATE_SYSTEM.LNGLAT_OFFSETS}
+ };
+ if (token) {
+ loadOptions.i3s.token = token;
+ }
+ return new Tile3DLayer({
+ id: `tile3d-layer-${layer.id}`,
+ data: layer.url,
+ loader: I3SLoader,
+ loadOptions
+ });
+ });
+}
+
+
+
+;
+```
+
+Take a look at sublayer properties:
+
+- `id` - unique identifier required to set deck.gl layer id;
+- `url` - `3DObject` layer url;
+- `visibility` - BSL has an initial visibility state for all sublayers. Use this property to control sublayers' visibility.
+
+### Control sublayers' visibility
+
+`I3SBuildingSceneLayerLoader` returns also a `header` object. `header.sublayers` is a JSON nested tree that can be used to visualize BSL explorer panel.
+
+
+
+With such a panel it is possible to change a sublayer visibility property:
+
+```javascript
+ function onChangeHandler(treeItem) => {
+ const sublayer = sublayers.find((sublayer) => sublayer.id === treeItem.id);
+ if (sublayer) {
+ sublayer.visibility = !sublayer.visibility;
+ }
+ }
+```
diff --git a/docs/modules/i3s/recipes/i3s-explorer-building.png b/docs/modules/i3s/recipes/i3s-explorer-building.png
new file mode 100644
index 0000000000..ad335e8ea0
Binary files /dev/null and b/docs/modules/i3s/recipes/i3s-explorer-building.png differ
diff --git a/docs/modules/i3s/recipes/i3s-new-york-colorize-by-heightroof.png b/docs/modules/i3s/recipes/i3s-new-york-colorize-by-heightroof.png
new file mode 100644
index 0000000000..c6165587a6
Binary files /dev/null and b/docs/modules/i3s/recipes/i3s-new-york-colorize-by-heightroof.png differ
diff --git a/docs/modules/images/api-reference/binary-image-api.md b/docs/modules/images/api-reference/binary-image-api.md
index 31984dc3df..04077849db 100644
--- a/docs/modules/images/api-reference/binary-image-api.md
+++ b/docs/modules/images/api-reference/binary-image-api.md
@@ -13,7 +13,7 @@ The format is reported using MIME types strings. Supported binary formats and th
## Usage
-```js
+```typescript
const response = await fetchFile(imageUrl);
const arrayBuffer = await response.arrayBuffer();
@@ -33,7 +33,7 @@ Parameters:
Returns a metadata object describing the image. Returns `null` if the binary data does not represent a known binary image format.
-```js
+```typescript
{
mimeType: string;
width: number;
diff --git a/docs/modules/images/api-reference/image-loader.md b/docs/modules/images/api-reference/image-loader.md
index 63a98e590e..76be5a104e 100644
--- a/docs/modules/images/api-reference/image-loader.md
+++ b/docs/modules/images/api-reference/image-loader.md
@@ -14,7 +14,7 @@ An image loader that works under both Node.js (requires `@loaders.gl/polyfills`)
## Usage
-```js
+```typescript
import '@loaders.gl/polyfills'; // only needed if using under Node
import {ImageLoader} from '@loaders.gl/images';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/images/api-reference/image-writer.md b/docs/modules/images/api-reference/image-writer.md
index 36e7334b56..c6e0adadc0 100644
--- a/docs/modules/images/api-reference/image-writer.md
+++ b/docs/modules/images/api-reference/image-writer.md
@@ -14,7 +14,7 @@ The `ImageWriter` class can encode an image into `ArrayBuffer` both under browse
## Usage
-```js
+```typescript
import '@loaders.gl/polyfill'; // only if using under Node
import {ImageWriter} from '@loaders.gl/images';
import {encode} from '@loaders.gl/core';
diff --git a/docs/modules/images/api-reference/parsed-image-api.md b/docs/modules/images/api-reference/parsed-image-api.md
index 5c5faee0a7..79eab94a10 100644
--- a/docs/modules/images/api-reference/parsed-image-api.md
+++ b/docs/modules/images/api-reference/parsed-image-api.md
@@ -8,7 +8,7 @@ Background: The image returned by the [`ImageLoader`](/docs/modules/images/api-r
E.g., the `getImageData` method enables the application to get width, height and pixel data from an image returned by the `ImageLoader` in a platform independent way:
-```js
+```typescript
import {ImageLoader, getImageSize, getImageData} from `@loaders.gl/images`;
import {load} from `@loaders.gl/core`;
diff --git a/docs/modules/json/README.md b/docs/modules/json/README.md
index 48ff165310..ba81ca9b2b 100644
--- a/docs/modules/json/README.md
+++ b/docs/modules/json/README.md
@@ -24,9 +24,7 @@ npm install @loaders.gl/core @loaders.gl/json
| [`GeoJSONLoader`](/docs/modules/json/api-reference/geojson-loader) |
| [`NDGeoJSONLoader`](/docs/modules/json/api-reference/ndgeojson-loader) |
| [`JSONWriter`](/docs/modules/json/api-reference/json-writer) |
-| [`NDJSONWriter`](/docs/modules/json/api-reference/ndjson-writer) |
| [`GeoJSONWriter`](/docs/modules/json/api-reference/geojson-writer) |
-| [`NDGeoJSONWriter`](/docs/modules/json/api-reference/ndgeojson-writer) |
## Additional APIs
diff --git a/docs/modules/json/api-reference/geojson-loader.md b/docs/modules/json/api-reference/geojson-loader.md
index 1eb61d4e1d..5cfcafb862 100644
--- a/docs/modules/json/api-reference/geojson-loader.md
+++ b/docs/modules/json/api-reference/geojson-loader.md
@@ -17,7 +17,7 @@ Streaming loader for GeoJSON encoded files.
For simple usage, you can load and parse a JSON file atomically:
-```js
+```typescript
import {GeoJSONLoader} from '@loaders.gl/json';
import {load} from '@loaders.gl/core';
@@ -27,7 +27,7 @@ const data = await load(url, GeoJSONLoader, {json: options});
For larger files, GeoJSONLoader supports streaming JSON parsing, in which case it will yield "batches" of rows from one array.
To parse a stream of GeoJSON, the user can specify the `options.json.jsonpaths` to stream the `features` array.
-```js
+```typescript
import {GeoJSONLoader} from '@loaders.gl/json';
import {loadInBatches} from '@loaders.gl/core';
@@ -50,7 +50,7 @@ When batch parsing an embedded JSON array as a table, it is possible to get acce
The loader will yield an initial and a final batch with `batch.container` providing the container object and `batch.batchType` set to `partial-result` and `final-result` respectively.
-```js
+```typescript
import {GeoJSONLoader} from '@loaders.gl/json';
import {loadInBatches} from '@loaders.gl/core';
diff --git a/docs/modules/json/api-reference/geojson-writer.md b/docs/modules/json/api-reference/geojson-writer.md
index c23c699109..9c76f05087 100644
--- a/docs/modules/json/api-reference/geojson-writer.md
+++ b/docs/modules/json/api-reference/geojson-writer.md
@@ -1,6 +1,10 @@
# GeoJSONWriter
-Streaming loader for GeoJSON encoded files.
+
+
+
+
+Streaming writer for GeoJSON encoded files.
| Loader | Characteristic |
| -------------- | ---------------------------------------------------- |
@@ -17,22 +21,22 @@ Streaming loader for GeoJSON encoded files.
For simple usage, you can encode a table into a JSON "file" atomically:
-```js
-import {GeoJSONLoader} from '@loaders.gl/json';
+```typescript
+import {GeoJSONWriter} from '@loaders.gl/json';
import {encode} from '@loaders.gl/core';
-const data = await encode(url, GeoJSONLoader, {json: options});
+const data = await encode(url, GeoJSONWriter, {json: options});
```
### Streaming and JSON paths
-For larger files, GeoJSONLoader supports streaming JSON parsing, in which case it will yield "batches" of rows from one array.
+For larger files, GeoJSONWriter supports streaming JSON parsing, in which case it will yield "batches" of rows from one array.
-```js
-import {GeoJSONLoader} from '@loaders.gl/json';
+```typescript
+import {GeoJSONWriter} from '@loaders.gl/json';
import {encodeInBatches} from '@loaders.gl/core';
-const batches = await encodeInBatches('geojson.json', GeoJSONLoader, {json: {jsonpaths: ['$.features']}});
+const batches = await encodeInBatches('geojson.json', GeoJSONWriter, {json: {jsonpaths: ['$.features']}});
for await (const batch of batches) {
// batch.data will contain a number of rows
diff --git a/docs/modules/json/api-reference/json-loader.md b/docs/modules/json/api-reference/json-loader.md
index 423dc310ec..daa7ec8eb1 100644
--- a/docs/modules/json/api-reference/json-loader.md
+++ b/docs/modules/json/api-reference/json-loader.md
@@ -15,7 +15,7 @@ Streaming loader for JSON encoded files.
For simple usage, you can load and parse a JSON file atomically:
-```js
+```typescript
import {JSONLoader} from '@loaders.gl/json';
import {load} from '@loaders.gl/core';
@@ -25,7 +25,7 @@ const data = await load(url, JSONLoader, {json: options});
For larger files, JSONLoader supports streaming JSON parsing, in which case it will yield "batches" of rows from one array.
To parse a stream of GeoJSON, the user can specify the `options.json.jsonpaths` to stream the `features` array.
-```js
+```typescript
import {JSONLoader} from '@loaders.gl/json';
import {loadInBatches} from '@loaders.gl/core';
@@ -48,7 +48,7 @@ When batch parsing an embedded JSON array as a table, it is possible to get acce
The loader will yield an initial and a final batch with `batch.container` providing the container object and `batch.batchType` set to `partial-result` and `final-result` respectively.
-```js
+```typescript
import {JSONLoader} from '@loaders.gl/json';
import {loadInBatches} from '@loaders.gl/core';
diff --git a/docs/modules/json/api-reference/json-writer.md b/docs/modules/json/api-reference/json-writer.md
new file mode 100644
index 0000000000..92a68e03f6
--- /dev/null
+++ b/docs/modules/json/api-reference/json-writer.md
@@ -0,0 +1,79 @@
+# JSONWriter
+
+
+
+
+
+Streaming writer for GeoJSON encoded files.
+
+| Loader | Characteristic |
+| -------------- | ---------------------------------------------------- |
+| File Extension | `.geojson` |
+| Media Type | `application/geo+json` |
+| File Type | Text |
+| File Format | JSON |
+| Data Format | [Classic Table](/docs/specifications/category-table) |
+| Supported APIs | `encode`, `encodeSync`, `encodeÓInBatches` |
+
+## Usage
+
+For simple usage, you can encode a table into a JSON "file" atomically:
+
+```typescript
+import {JSONWriter} from '@loaders.gl/json';
+import {encode} from '@loaders.gl/core';
+
+const data = await encode(url, JSONWriter, {json: options});
+```
+
+### Streaming and JSON paths
+
+For larger files, JSONWriter supports streaming JSON parsing, in which case it will yield "batches" of rows from one array.
+
+```typescript
+import {JSONWriter} from '@loaders.gl/json';
+import {encodeInBatches} from '@loaders.gl/core';
+
+const batches = await encodeInBatches('geojson.json', JSONWriter, {json: {jsonpaths: ['$.features']}});
+
+for await (const batch of batches) {
+ // batch.data will contain a number of rows
+ for (const feature of batch.data) {
+ switch (feature.geometry.type) {
+ case 'Polygon':
+ ...
+ }
+ }
+}
+```
+
+To parse a stream of GeoJSON, the user can specify the `options.json.jsonpaths` to stream the `features` array.
+
+If no JSONPath is specified the loader will stream the first array it encounters in the JSON payload.
+
+
+## Data Format
+
+Encoded batches are array buffers or strings
+
+## Options
+
+Supports table category options such as `batchType` and `batchSize`.
+
+| Option | From | Type | Default | Description |
+| ---------------- | ------------------------------------------------------------------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `json.table` | [] | `boolean` | `false` | Parses non-streaming JSON as table, i.e. return the first embedded array in the JSON. Always `true` during batched/streaming parsing. |
+| `json.jsonpaths` | [] | `string[]` | `[]` | A list of JSON paths (see below) indicating the array that can be streamed. |
+
+## JSONPaths
+
+A minimal subset of the JSONPath syntax is supported, to specify which array in a JSON object should be streamed as batchs.
+
+`$.component1.component2.component3`
+
+- No support for wildcards, brackets etc. Only paths starting with `$` (JSON root) are supported.
+- Regardless of the paths provided, only arrays will be streamed.
+
+## Attribution
+
+This loader is based on a fork of dscape's [`clarinet`](https://github.com/dscape/clarinet) under BSD 2-clause license.
diff --git a/docs/modules/json/api-reference/ndjson-loader.md b/docs/modules/json/api-reference/ndjson-loader.md
index 484f9be12a..7bae462964 100644
--- a/docs/modules/json/api-reference/ndjson-loader.md
+++ b/docs/modules/json/api-reference/ndjson-loader.md
@@ -18,7 +18,7 @@ Streaming loader for NDJSON encoded files and related formats (LDJSON and JSONL)
## Usage
-```js
+```typescript
import {NDJSONLoader} from '@loaders.gl/json';
import {load} from '@loaders.gl/core';
@@ -27,7 +27,7 @@ const data = await load(url, NDJSONLoader, {ndjson: options});
The NDJSONLoader supports streaming NDJSON parsing, in which case it will yield "batches" of rows, where each row is a parsed line from the NDJSON stream.
-```js
+```typescript
import {NDJSONLoader} from '@loaders.gl/json';
import {loadInBatches} from '@loaders.gl/core';
diff --git a/docs/modules/json/formats/geojson-geometry.md b/docs/modules/json/formats/geojson-geometry.md
new file mode 100644
index 0000000000..fc2bc2db90
--- /dev/null
+++ b/docs/modules/json/formats/geojson-geometry.md
@@ -0,0 +1,47 @@
+# GeoJSON Geometry
+
+GeoJSON geometries can sometimes be useful independently of GeoJSON.
+
+## Examples
+
+```json
+ {
+ "type": "Point",
+ "coordinates": [102.0, 0.5]
+ },
+```
+
+```json
+ {
+ "type": "LineString",
+ "coordinates": [
+ [102.0, 0.0],
+ [103.0, 1.0],
+ [104.0, 0.0],
+ [105.0, 1.0]
+ ]
+ },
+```
+
+```json
+ {
+ "type": "Polygon",
+ "coordinates": [
+ [
+ [100.0, 0.0],
+ [101.0, 0.0],
+ [101.0, 1.0],
+ [100.0, 1.0],
+ [100.0, 0.0]
+ ]
+ ]
+ }
+```
+
+## Alternatives
+
+| Format | Notes |
+| ------------ | ------------------------------------------------------------------- |
+| WKB | Binary, more compact |
+| WKT | Text based, slightly more compact, a bit harder to parse (not JSON) |
+| GML Geometry | XML based, even more verbose, more complex to parse |
diff --git a/docs/modules/json/formats/geojson.md b/docs/modules/json/formats/geojson.md
new file mode 100644
index 0000000000..4311851ad9
--- /dev/null
+++ b/docs/modules/json/formats/geojson.md
@@ -0,0 +1,16 @@
+# GeoJSON
+
+- [IETF standard](https://datatracker.ietf.org/doc/html/rfc7946)
+- [geojson.org](https://geojson.org/)
+
+GeoJSON is a format for encoding a variety of geographic data structures together with properties.
+
+## Geometries
+
+Since GeoJSON geometries can be independently useful they are described on a [separate page](./geojson-geometry).
+
+## Alternatives
+
+| Format | Support | Description |
+| -------- | ------- | --------------------------------------------- |
+| TopoJSON | ❌ | A more compact version that encodes topology. |
diff --git a/docs/modules/kml/api-reference/gpx-loader.md b/docs/modules/kml/api-reference/gpx-loader.md
index 647cb1eee8..9c491b49d5 100644
--- a/docs/modules/kml/api-reference/gpx-loader.md
+++ b/docs/modules/kml/api-reference/gpx-loader.md
@@ -6,11 +6,6 @@
The `GPXLoader` parses [GPX files][gpx_wikipedia] into GeoJSON. From Wikipedia:
-> GPX, or GPS Exchange Format, is an XML schema designed as a common GPS data
-> format for software applications. It can be used to describe waypoints,
-> tracks, and routes. ... Location data (and optionally elevation, time, and
-> other information) is stored in tags and can be interchanged between GPS
-> devices and software.
| Loader | Characteristic |
| --------------------- | ------------------------------------------ |
@@ -26,7 +21,7 @@ The `GPXLoader` parses [GPX files][gpx_wikipedia] into GeoJSON. From Wikipedia:
## Usage
-```js
+```typescript
import {GPXLoader} from '@loaders.gl/kml';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/kml/api-reference/kml-loader.md b/docs/modules/kml/api-reference/kml-loader.md
index af6a040fe3..8ad5def182 100644
--- a/docs/modules/kml/api-reference/kml-loader.md
+++ b/docs/modules/kml/api-reference/kml-loader.md
@@ -1,14 +1,8 @@
# KMLLoader
-The `KMLLoader` parses [KML files][kml_wikipedia] into GeoJSON. From Wikipedia:
-
-> Keyhole Markup Language (KML) is an XML notation for expressing geographic
-> annotation and visualization within two-dimensional maps and three-dimensional
-> Earth browsers.
+
-KML is now an [Open Geospatial Consortium standard][kml_ogc_standard].
-
-[kml_ogc_standard]: https://www.ogc.org/standards/kml
+The `KMLLoader` parses [KML files][kml_wikipedia] into GeoJSON. From Wikipedia:
| Loader | Characteristic |
| --------------------- | ------------------------------------------ |
@@ -24,7 +18,7 @@ KML is now an [Open Geospatial Consortium standard][kml_ogc_standard].
## Usage
-```js
+```typescript
import {KMLLoader} from '@loaders.gl/kml';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/kml/api-reference/tcx-loader.md b/docs/modules/kml/api-reference/tcx-loader.md
index ba70b171f6..6e634f3496 100644
--- a/docs/modules/kml/api-reference/tcx-loader.md
+++ b/docs/modules/kml/api-reference/tcx-loader.md
@@ -6,13 +6,6 @@
The `TCXLoader` parses [TCX files][tcx_wikipedia] into GeoJSON. From Wikipedia:
-> Training Center XML (TCX) is a data exchange format introduced in 2007 as part
-> of Garmin's Training Center product. The XML is similar to GPX since it
-> exchanges GPS tracks, but treats a track as an Activity rather than simply a
-> series of GPS points. TCX provides standards for transferring heart rate,
-> running cadence, bicycle cadence, calories in the detailed track. It also
-> provides summary data in the form of laps.
-
| Loader | Characteristic |
| --------------------- | ------------------------------------------ |
| File Extension | `.tcx` |
@@ -27,7 +20,7 @@ The `TCXLoader` parses [TCX files][tcx_wikipedia] into GeoJSON. From Wikipedia:
## Usage
-```js
+```typescript
import {TCXLoader} from '@loaders.gl/kml';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/kml/formats/gpx.md b/docs/modules/kml/formats/gpx.md
new file mode 100644
index 0000000000..934e4a9550
--- /dev/null
+++ b/docs/modules/kml/formats/gpx.md
@@ -0,0 +1,9 @@
+# GPX
+
+- [GPX - Wikipedia](https://en.wikipedia.org/wiki/GPS_Exchange_Format)
+
+GPX, or GPS Exchange Format, is an XML schema designed as a common GPS data
+format for software applications. It can be used to describe waypoints,
+tracks, and routes. ... Location data (and optionally elevation, time, and
+other information) is stored in tags and can be interchanged between GPS
+devices and software.
\ No newline at end of file
diff --git a/docs/modules/kml/formats/kml.md b/docs/modules/kml/formats/kml.md
new file mode 100644
index 0000000000..185f2ab520
--- /dev/null
+++ b/docs/modules/kml/formats/kml.md
@@ -0,0 +1,13 @@
+# KML
+
+
+
+- [KML Tutorial - Google](https://developers.google.com/kml/documentation/kml_tut)
+
+Keyhole Markup Language (KML) is an XML notation for expressing geographic
+annotation and visualization within two-dimensional maps and three-dimensional
+Earth browsers.
+
+KML is now an [Open Geospatial Consortium standard][kml_ogc_standard].
+
+[kml_ogc_standard]: https://www.ogc.org/standards/kml
diff --git a/docs/modules/kml/formats/tcx.md b/docs/modules/kml/formats/tcx.md
new file mode 100644
index 0000000000..f0ed60149a
--- /dev/null
+++ b/docs/modules/kml/formats/tcx.md
@@ -0,0 +1,10 @@
+# TCX
+
+- [TCX - Wikipedia](https://en.wikipedia.org/wiki/Training_Center_XML)
+
+Training Center XML (TCX) is a data exchange format introduced in 2007 as part
+of Garmin's Training Center product. The XML is similar to GPX since it
+exchanges GPS tracks, but treats a track as an Activity rather than simply a
+series of GPS points. TCX provides standards for transferring heart rate,
+running cadence, bicycle cadence, calories in the detailed track. It also
+provides summary data in the form of laps.
diff --git a/docs/modules/las/api-reference/las-loader.md b/docs/modules/las/api-reference/las-loader.md
index 9012c366fc..59ed17ee78 100644
--- a/docs/modules/las/api-reference/las-loader.md
+++ b/docs/modules/las/api-reference/las-loader.md
@@ -14,7 +14,7 @@ The `LASLoader` parses a point cloud in the LASER file format.
## Usage
-```js
+```typescript
import {LASLoader} from '@loaders.gl/las';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/las/formats/las.md b/docs/modules/las/formats/las.md
new file mode 100644
index 0000000000..1347004b3c
--- /dev/null
+++ b/docs/modules/las/formats/las.md
@@ -0,0 +1,3 @@
+# LAS / LAZ
+
+The `@loaders.gl/las` module handles the [LASER file format](https://www.asprs.org/divisions-committees/lidar-division/laser-las-file-format-exchange-activities) (LAS) or its compressed version (LAZ), a public format for the interchange of 3-dimensional point cloud data data, developed for LIDAR mapping purposes.
diff --git a/docs/modules/lerc/README.md b/docs/modules/lerc/README.md
new file mode 100644
index 0000000000..4804ca0a72
--- /dev/null
+++ b/docs/modules/lerc/README.md
@@ -0,0 +1,5 @@
+# Overview
+
+
+
+
diff --git a/docs/modules/wms/api-reference/lerc-loader.md b/docs/modules/lerc/api-reference/lerc-loader.md
similarity index 99%
rename from docs/modules/wms/api-reference/lerc-loader.md
rename to docs/modules/lerc/api-reference/lerc-loader.md
index 54faf49145..1325cb609a 100644
--- a/docs/modules/wms/api-reference/lerc-loader.md
+++ b/docs/modules/lerc/api-reference/lerc-loader.md
@@ -24,7 +24,7 @@ There are two major versions, known as "Lerc1" and "Lerc2".
## Usage
-```js
+```typescript
import {LERCLoader} from '@loaders.gl/wms';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/wms/formats/lerc.md b/docs/modules/lerc/formats/lerc.md
similarity index 100%
rename from docs/modules/wms/formats/lerc.md
rename to docs/modules/lerc/formats/lerc.md
diff --git a/docs/modules/loader-utils/README.md b/docs/modules/loader-utils/README.md
new file mode 100644
index 0000000000..9e008035f2
--- /dev/null
+++ b/docs/modules/loader-utils/README.md
@@ -0,0 +1,3 @@
+# Overview
+
+The `@loaders.gl/loader-utils` contains utilities for creating loaders.
diff --git a/docs/modules/loader-utils/api-reference/parse-with-context.md b/docs/modules/loader-utils/api-reference/parse-with-context.md
new file mode 100644
index 0000000000..2d51da7515
--- /dev/null
+++ b/docs/modules/loader-utils/api-reference/parse-with-context.md
@@ -0,0 +1,25 @@
+# parseWithContext
+
+Use when invoking a sub-loader from a loader, to parse embedded data or perhaps an associated resource.
+
+## Usage
+
+```typescript
+import {parseWithContext} from '@loaders.gl/loader-utils';
+import {OBJLoader} from '@loaders.gl/obj';
+
+parse(data: ArrayBuffer, options: LoaderOptions, context?: LoaderContext) {
+ const subData = data.slice(100, 200);
+ data = await parseWithContext(subData, OBJLoader, options, context);
+}
+...
+```
+
+## Functions
+
+### parse
+
+### parseSyncWithContext
+
+### parseInBatchesWithContext
+
diff --git a/docs/modules/loader-utils/api-reference/request-scheduler.md b/docs/modules/loader-utils/api-reference/request-scheduler.md
index dd682cd5cc..06f9340c38 100644
--- a/docs/modules/loader-utils/api-reference/request-scheduler.md
+++ b/docs/modules/loader-utils/api-reference/request-scheduler.md
@@ -18,7 +18,7 @@ A primary use case is to let the app reprioritize or cancel requests if circumst
To schedule a request so that it can be issued at a time when it can be immediately processed.
-```js
+```typescript
const URL = '...';
const requestToken = await requestScheduler.scheduleRequest(URL);
if (requestToken) {
diff --git a/docs/modules/math/api-reference/gl-type.md b/docs/modules/math/api-reference/gl-type.md
index 89caaa3b25..14616f92e6 100644
--- a/docs/modules/math/api-reference/gl-type.md
+++ b/docs/modules/math/api-reference/gl-type.md
@@ -16,7 +16,7 @@ Helper functions to work with WebGL data type constants.
## Usage
-```js
+```typescript
import {GL, GLType} from '@loaders.gl/math';
// Returns Int8Array.BYTES_PER_ELEMENT
var size = GLType.getSizeInBytes(GL.BYTE);
diff --git a/docs/modules/mvt/README.md b/docs/modules/mvt/README.md
index bd1fdaae64..940695052c 100644
--- a/docs/modules/mvt/README.md
+++ b/docs/modules/mvt/README.md
@@ -1,6 +1,6 @@
# Overview
-The `@loaders.gl/mvt` module handles the [Mapbox Vector Tile](https://github.com/mapbox/vector-tile-spec) format, a protobuf-encoded format that defines geospatial geometries.
+The `@loaders.gl/mvt` module handles the [Mapbox Vector Tile](/docs/modules/mvt/formats/mvt) format, a protobuf-encoded format that defines geospatial geometries.
The modules also provides a `GeoJSONTiler` class that can serve up equivalent parsed
tiles from an in-memory `GeoJSON` file.
diff --git a/docs/modules/mvt/api-reference/mvt-loader.md b/docs/modules/mvt/api-reference/mvt-loader.md
index e4c625d36b..43e4018efe 100644
--- a/docs/modules/mvt/api-reference/mvt-loader.md
+++ b/docs/modules/mvt/api-reference/mvt-loader.md
@@ -12,7 +12,7 @@ Loader for the [Mapbox Vector Tile](https://docs.mapbox.com/vector-tiles/specifi
## Usage
-```js
+```typescript
import {MVTLoader} from '@loaders.gl/mvt';
import {load} from '@loaders.gl/core';
@@ -40,7 +40,7 @@ const geoJSONfeatures = await load(url, MVTLoader, loaderOptions);
The parser will return an array of [GeoJSON objects](https://tools.ietf.org/html/rfc7946) with WGS84 coordinates and feature properties from MVT if `coordinates` property is set to `wgs84` and `tileIndex` properties are present.
-```js
+```typescript
import {MVTLoader} from '@loaders.gl/mvt';
import {load} from '@loaders.gl/core';
@@ -66,7 +66,7 @@ Even though tile coordinates go from 0 to 1, there can be some negative (or grea
Note that local coordinates are relative to tile origin, which is in the top left.
-```js
+```typescript
import {MVTLoader} from '@loaders.gl/mvt';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/mvt/api-reference/tilejson-loader.md b/docs/modules/mvt/api-reference/tilejson-loader.md
new file mode 100644
index 0000000000..a1c584a7ec
--- /dev/null
+++ b/docs/modules/mvt/api-reference/tilejson-loader.md
@@ -0,0 +1,27 @@
+# PMTilesLoader
+
+The `PMTilesLoader` parses header/metadata from a pmtiles archive
+
+| Loader | Characteristic |
+| --------------------- | -------------------------------------------------- |
+| File Extension | `.json` |
+| File Type | Text |
+| File Format | [TileJSON](/docs/modules/mvt/formats/tilejson) |
+| Data Format | TileJSON |
+| Decoder Type | Synchronous |
+| Worker Thread Support | No |
+| Streaming Support | No |
+
+## Usage
+
+```typescript
+import {TileJSONLoader} from '@loaders.gl/pmtiles';
+import {load} from '@loaders.gl/core';
+
+const tileJSON = await load(url, TileJSONLoader, options);
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
diff --git a/docs/modules/mvt/formats/mvt.md b/docs/modules/mvt/formats/mvt.md
new file mode 100644
index 0000000000..665589668b
--- /dev/null
+++ b/docs/modules/mvt/formats/mvt.md
@@ -0,0 +1,15 @@
+# Mapbox Vector Tile
+
+- *[Mapbox Vector Tile Specification](https://github.com/mapbox/vector-tile-spec)*
+
+
+A specification for encoding tiled vector data.
+
+MVT is a protobuf-encoded format that defines geospatial geometries.
+
+## Metadata
+
+It is often useful to have global metadata about a tileset. A common complementary format for encoding tileset metadata is [TileJSON](./tilejson).
+
+
+
diff --git a/docs/modules/mvt/formats/tilejson.md b/docs/modules/mvt/formats/tilejson.md
new file mode 100644
index 0000000000..5c29814728
--- /dev/null
+++ b/docs/modules/mvt/formats/tilejson.md
@@ -0,0 +1,30 @@
+# TileJSON / Tilestats
+
+- *[TileJSON specification](https://github.com/mapbox/tilejson-spec/blob/master/3.0.0/README.md)*
+- *[Tilestats information](https://github.com/mapbox/mapbox-geostats)
+- *[Tilestats generation](https://github.com/mapbox/mapbox-geostats#output-the-stats)
+
+## TileJSON
+
+Metadata about a tileset.
+
+for representing metadata about multiple types of web-based map layers, to aid clients in configuration and browsing.
+
+As the name suggests, TileJSON is JSON encoded.
+
+## Tilestats
+
+Tilestats is a valuable inofficial "extension" to TileJSON. It provides column statistics, notably:
+- the data type of each column
+- min/max values for numeric columns (enabling e.g. global color scale calculations).
+- a sample of values for each column
+
+Tilestats are not always available so applications must be prepared to work in their absence.
+However, tilestats is output by major tilers such as [tippecanoe](https://github.com/mapbox/mapbox-geostats#output-the-stats).
+
+
+## Fields
+
+| Data | TileJSON | tilestats | Description |
+| --- | --- | --- | --- |
+|
\ No newline at end of file
diff --git a/docs/modules/obj/README.md b/docs/modules/obj/README.md
index c665495bb3..88cbcf6147 100644
--- a/docs/modules/obj/README.md
+++ b/docs/modules/obj/README.md
@@ -9,6 +9,12 @@ npm install @loaders.gl/obj
npm install @loaders.gl/core
```
+## Loaders and Writers
+
+| Loader |
+| -------------------------------------------------------- |
+| [`OBJLoader`](/docs/modules/obj/api-reference/obj-loader) |
+
## Attribution
OBJLoader is a port of [three.js](https://github.com/mrdoob/three.js)'s OBJLoader under MIT License.
diff --git a/docs/modules/obj/api-reference/obj-loader.md b/docs/modules/obj/api-reference/obj-loader.md
index 80d4178d03..9f97232553 100644
--- a/docs/modules/obj/api-reference/obj-loader.md
+++ b/docs/modules/obj/api-reference/obj-loader.md
@@ -14,7 +14,7 @@ The `OBJLoader` parses the OBJ half of the classic Wavefront OBJ/MTL format.
## Usage
-```js
+```typescript
import {OBJLoader} from '@loaders.gl/obj';
import {load} from '@loaders.gl/core';
@@ -25,3 +25,11 @@ const data = await load(url, OBJLoader, options);
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
+
+Remarks:
+
+- vertex colors are parsed as a `COLOR_0` attribute when red, green and blue values are included after x y and z (this precludes specifying w). The color values range from 0 to 1.
+
+## Attribution
+
+OBJLoader is a port of [three.js](https://github.com/mrdoob/three.js)'s OBJLoader under MIT License.
\ No newline at end of file
diff --git a/docs/modules/parquet/README.md b/docs/modules/parquet/README.md
index e14c3e7b80..2397958f32 100644
--- a/docs/modules/parquet/README.md
+++ b/docs/modules/parquet/README.md
@@ -1,4 +1,4 @@
-# @loaders.gl/parquet
+# @loaders.gl/parquet 🚧
diff --git a/docs/modules/parquet/api-reference/parquet-loader.md b/docs/modules/parquet/api-reference/parquet-loader.md
index be37e07927..e44b611cce 100644
--- a/docs/modules/parquet/api-reference/parquet-loader.md
+++ b/docs/modules/parquet/api-reference/parquet-loader.md
@@ -1,4 +1,4 @@
-# ParquetLoader
+# ParquetLoader 🆕 🚧
diff --git a/docs/modules/parquet/api-reference/parquet-writer.md b/docs/modules/parquet/api-reference/parquet-writer.md
index ac4d488106..da8d9f81ec 100644
--- a/docs/modules/parquet/api-reference/parquet-writer.md
+++ b/docs/modules/parquet/api-reference/parquet-writer.md
@@ -1,4 +1,4 @@
-# ParquetWriter
+# ParquetWriter 🆕 🚧
@@ -10,4 +10,4 @@
The Parquet format supports a large set of features (data types, encodings, compressions, encryptions etc) it require time and contributions for the loaders.gl implementation to provide support for all variations.
-Please refer to the detailed information about which [Parquet format features](/docs/modules/parquet/format/parquet) are supported.
+Please refer to the detailed information about which [Parquet format features](/docs/modules/parquet/formats/parquet) are supported.
diff --git a/docs/modules/parquet/formats/geoparquet.md b/docs/modules/parquet/formats/geoparquet.md
index 851957ef3a..6665b0584f 100644
--- a/docs/modules/parquet/formats/geoparquet.md
+++ b/docs/modules/parquet/formats/geoparquet.md
@@ -7,9 +7,11 @@ Geoparquet is a set of conventions for storing geospatial data in Parquet files.
Standardization is happening at [geoparquet.org](https://geoparquet.org).
-GeoParquet is similar to GeoArrow, as both a binary columnar formats with a high degree of similarity.
+GeoParquet file is a Parquet file that additionally follows these conventions:
-Essentially a GeoParquet file is a Parquet file that follows these conventions:
+- Geospatial metadata describing any geospatial columns is stored in the Parquet file's schema metadata (as stringified JSON).
+- Geometry columns are [WKB](/docs/modules/wkt/formats/wkb) encoded (additional encodings will likely be added)/
-- JSON encoded metadata stored in the Parquet file's schema metadata.
-- WKB encoded geometry columns
+## Alternatives
+
+GeoParquet can be compared to GeoArrow, as both are binary columnar formats with a high degree of similarity.
diff --git a/docs/modules/parquet/formats/parquet.md b/docs/modules/parquet/formats/parquet.md
index e70d8c8e08..2154dc93eb 100644
--- a/docs/modules/parquet/formats/parquet.md
+++ b/docs/modules/parquet/formats/parquet.md
@@ -7,15 +7,14 @@ Parquet is a binary columnar format optimized for compact storage on disk.
The GitHUB specification of [Apache Parquet](https://github.com/apache/parquet-format/blob/master/README.md).
-## Column encodings
+## Pages
-Some encodings are intended to improve successive column compression by organizing data so that it is less random.
+columns can be divided into pages (similar to Apache Arrow record batches) so that partial columns covering a range of rows can be read without reading the entire file.
-## Compared to similar formats
+## Alternatives
In contrast to Arrow which is designed to minimize serialization and deserialization, Parquet is optimized for storage on disk.
-
## Compression
Since Parquet is designed for read-write access, compression is applied per column chunk.
@@ -24,28 +23,30 @@ A wide range of compression codecs are supported. Internal parquet compression f
| Type | Read | Write |
| -------------- | ---- | ----- |
-| `UNCOMPRESSED` | YES | YES |
-| `GZIP` | YES | YES |
-| `SNAPPY` | YES | YES | |
-| `BROTLI` | YES | No | |
-| `LZO` | NO | NO | There is currently no readily available browser-based LZO module for JS |
-| `LZ4` | YES | YES |
-| `LZ4_RAW` | YES | YES |
-| `ZSTD` | YES | YES | |
+| `UNCOMPRESSED` | ✅ | ✅ |
+| `GZIP` | ✅ | ✅ |
+| `SNAPPY` | ✅ | ✅ | |
+| `BROTLI` | ✅ | No | |
+| `LZO` | ❌ | ❌ | There is currently no readily available browser-based LZO module for JS |
+| `LZ4` | ✅ | ✅ |
+| `LZ4_RAW` | ✅ | ✅ |
+| `ZSTD` | ✅ | ✅ | |
## Encoding
+Some encodings are intended to improve successive column compression by organizing data so that it is less random.
+
The following Parquet encodings are supported:
| Encoding | Read | Write | Types |
| ------------------------- | ---- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `PLAIN` | YES | YES | All |
-| `PLAIN_DICTIONARY` | YES | YES | All |
-| `RLE_DICTIONARY` | YES | NO | All |
-| `DELTA_BINARY_PACKED` | NO | NO | `INT32`, `INT64`, `INT_8`, `INT_16`, `INT_32`, `INT_64`, `UINT_8`, `UINT_16`, `UINT_32`, `UINT_64`, `TIME_MILLIS`, `TIME_MICROS`, `TIMESTAMP_MILLIS`, `TIMESTAMP_MICROS` |
-| `DELTA_BYTE_ARRAY` | NO | NO | `BYTE_ARRAY`, `UTF8` |
-| `DELTA_LENGTH_BYTE_ARRAY` | NO | NO | `BYTE_ARRAY`, `UTF8` |
+| `PLAIN` | ✅ | ✅ | All |
+| `PLAIN_DICTIONARY` | ✅ | ✅ | All |
+| `RLE_DICTIONARY` | ✅ | ❌ | All |
+| `DELTA_BINARY_PACKED` | ❌ | ❌ | `INT32`, `INT64`, `INT_8`, `INT_16`, `INT_32`, `INT_64`, `UINT_8`, `UINT_16`, `UINT_32`, `UINT_64`, `TIME_MILLIS`, `TIME_MICROS`, `TIMESTAMP_MILLIS`, `TIMESTAMP_MICROS` |
+| `DELTA_BYTE_ARRAY` | ❌ | ❌ | `BYTE_ARRAY`, `UTF8` |
+| `DELTA_LENGTH_BYTE_ARRAY` | ❌ | ❌ | `BYTE_ARRAY`, `UTF8` |
## Repetition
@@ -53,9 +54,9 @@ There are three repetition types in Parquet:
| Repetition | Supported |
| ---------- | --------- |
-| `REQUIRED` | YES |
-| `OPTIONAL` | YES |
-| `REPEATED` | YES |
+| `REQUIRED` | ✅ |
+| `OPTIONAL` | ✅ |
+| `REPEATED` | ✅ |
### Record Shredding
diff --git a/docs/modules/pcd/api-reference/pcd-loader.md b/docs/modules/pcd/api-reference/pcd-loader.md
index d9716cb23e..b63885c919 100644
--- a/docs/modules/pcd/api-reference/pcd-loader.md
+++ b/docs/modules/pcd/api-reference/pcd-loader.md
@@ -16,7 +16,7 @@ Note: Currently supports `ascii`, `binary` and compressed binary files.
## Usage
-```js
+```typescript
import {PCDLoader} from '@loaders.gl/pcd';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/ply/api-reference/ply-loader.md b/docs/modules/ply/api-reference/ply-loader.md
index b6d2d5707a..2e84ef6e10 100644
--- a/docs/modules/ply/api-reference/ply-loader.md
+++ b/docs/modules/ply/api-reference/ply-loader.md
@@ -14,7 +14,7 @@ The `PLYLoader` parses simple meshes in the Polygon File Format or the Stanford
## Usage
-```js
+```typescript
import {PLYLoader} from '@loaders.gl/ply';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/pmtiles/README.md b/docs/modules/pmtiles/README.md
new file mode 100644
index 0000000000..bcce3fdf12
--- /dev/null
+++ b/docs/modules/pmtiles/README.md
@@ -0,0 +1,3 @@
+# @loaders.gl/pmtiles
+
+Support for loading [pmtiles](/docs/modules/pmtiles/formats/pmtiles) format tiles.
diff --git a/docs/modules/pmtiles/api-reference/pmtiles-source.md b/docs/modules/pmtiles/api-reference/pmtiles-source.md
new file mode 100644
index 0000000000..ec1d342cae
--- /dev/null
+++ b/docs/modules/pmtiles/api-reference/pmtiles-source.md
@@ -0,0 +1,28 @@
+# PMTilesSource 🆕
+
+The `PMTilesSource` reads individual tiles from a PMTiles archive file.
+
+| Loader | Characteristic |
+| --------------------- | ----------------------------------------------- |
+| File Extension | `.pmtiles` |
+| File Type | Binary Archive |
+| File Format | [PMTiles](/docs/modules/pmtiles/formats/pmtiles) |
+| Data Format | Metadata |
+| Decoder Type | Asynchronous |
+| Worker Thread Support | No |
+| Streaming Support | No |
+
+## Usage
+
+```typescript
+import {PMTilesSource} from '@loaders.gl/pmtiles';
+import {load} from '@loaders.gl/core';
+
+const source = new PMTilesSource({url});
+const tile = await source.getTile(...);
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
diff --git a/docs/modules/pmtiles/formats/pmtiles.md b/docs/modules/pmtiles/formats/pmtiles.md
new file mode 100644
index 0000000000..a71c97e939
--- /dev/null
+++ b/docs/modules/pmtiles/formats/pmtiles.md
@@ -0,0 +1,164 @@
+# PMTiles
+
+PMTiles is a single-file archive format for tiled data designed to enable individual tiles to be loaded via HTTP range request access. A PMTiles archive can be hosted on a commodity storage platform such as Amazon S3.
+
+- *[PMTiles](https://github.com/protomaps/PMTiles)*
+
+## Overview
+
+TBA
+
+## Versions
+
+## Version 3
+
+- File Structure
+97% smaller overhead - Spec version 2 would always issue a 512 kilobyte initial request; version 3 reduces this to 16 kilobytes. What remains the same is that nearly any map tile can be retrieved in at most two additional requests.
+- Unlimited metadata - version 2 had a hard cap on the amount of JSON metadata of about 300 kilobytes; version 3 removes this limit. This is essential for tools like tippecanoe to store detailed column statistics. Essential archive information, such as tile type and compression methods, are stored in a binary header separate from application metadata.
+- Hilbert tile IDs - tiles internally are addressed by a single 64-bit Hilbert tile ID instead of Z/X/Y. See the blog post on Tile IDs for details.
+- Archive ordering - An optional clustered mode enforces that tile contents are laid out in Tile ID order.
+- Compressed directories and metadata - Directories used to fetch offsets of tile data consume about 10% the space of those in version 2. See the blog post on compressed directories for details.
+- JavaScript
+Compression - The TypeScript pmtiles library now includes a decompressor - fflate - to allow reading compressed vector tile archives directly in the browser. This reduces the size and latency of vector tiles by as much as 70%.
+- Tile Cancellation - All JavaScript plugins now support tile cancellation, meaning quick zooming across many levels will interrupt the loading of tiles that are never shown. This has a significant effect on the perceived user experience, as tiles at the end of a animation will appear earlier.
+- ETag support - clients can detect when files change on static storage by reading the ETag HTTP header. This means that PMTiles-based map applications can update datasets in place at low frequency without running into caching problems.
+
+## Version 3 Specification
+
+### File structure
+
+A PMTiles archive is a single-file archive of square tiles with five main sections:
+
+1. A fixed-size, 127-byte **Header** starting with `PMTiles` and then the spec version - currently `3` - that contains offsets to the next sections.
+2. A root **Directory**, described below. The Header and Root combined must be less than 16,384 bytes.
+3. JSON metadata.
+4. Optionally, a section of **Leaf Directories**, encoded the same way as the root.
+5. The tile data.
+
+### Entries
+
+A Directory is a list of `Entries`, in ascending order by `TileId`:
+
+ Entry = (TileId uint64, Offset uint64, Length uint32, RunLength uint32)
+
+* `TileId` starts at 0 and corresponds to a cumulative position on the series of square Hilbert curves starting at z=0.
+* `Offset` is the position of the tile in the file relative to the start of the data section.
+* `Length` is the size of the tile in bytes.
+* `RunLength` is how many times this tile is repeated: the `TileId=5,RunLength=2` means that tile is present at IDs 5 and 6.
+* If `RunLength=0`, the offset/length points to a Leaf Directory where `TileId` is the first entry.
+
+### Directory Serialization
+
+Entries are stored in memory as integers, but serialized to disk using these compression steps:
+
+1. A little-endian varint indicating the # of entries
+2. Delta encoding of `TileId`
+3. Zeroing of `Offset`:
+ * `0` if it is equal to the `Offset` + `Length` of the previous entry
+ * `Offset+1` otherwise
+4. Varint encoding of all numbers
+5. Columnar ordering: all `TileId`s, all `RunLength`s, all `Length`s, then all `Offset`s
+6. Finally, general purpose compression as described by the `Header`'s `InternalCompression` field
+
+##3 Directory Hierarchy
+
+* The number of entries in the root directory and leaf directories is up to the implementation.
+* However, the compressed size of the header plus root directory is required in v3 to be under **16,384 bytes**. This is to allow latency-optimized clients to prefetch the root directory and guarantee it is complete. A sophisticated writer might need several attempts to optimize this.
+* Root size, leaf sizes and depth should be configurable by the user to optimize for different trade-offs: cost, bandwidth, latency.
+
+### Header Design
+
+*Certain fields belonging to metadata in v2 are promoted to fixed-size header fields. This allows a map container to be initialized to the desired extent or center without blocking on the JSON metadata, and allows proxies to return well-defined HTTP headers.*
+
+The `Header` is 127 bytes, with little-endian integer values:
+
+| offset | description | width |
+| ------ | ----------------------------------------------------------------------------------------- | ----- |
+| 0 | magic number `PMTiles` | 7 |
+| 7 | spec version, currently `3` | 1 |
+| 8 | offset of root directory | 8 |
+| 16 | length of root directory | 8 |
+| 24 | offset of JSON metadata, possibly compressed by `InternalCompression` | 8 |
+| 32 | length of JSON metadata | 8 |
+| 40 | offset of leaf directories | 8 |
+| 48 | length of leaf directories | 8 |
+| 56 | offset of tile data | 8 |
+| 64 | length of tile data | 8 |
+| 72 | # of addressed tiles, 0 if unknown | 8 |
+| 80 | # of tile entries, 0 if unknown | 8 |
+| 88 | # of tile contents, 0 if unknown | 8 |
+| 96 | boolean clustered flag, `0x1` if true | 1 |
+| 97 | `InternalCompression` enum (0 = Unknown, 1 = None, 2 = Gzip, 3 = Brotli, 4 = Zstd) | 1 |
+| 98 | `TileCompression` enum | 1 |
+| 99 | tile type enum (0 = Unknown/Other, 1 = MVT (PBF Vector Tile), 2 = PNG, 3 = JPEG, 4 = WEBP | 1 |
+| 100 | min zoom | 1 |
+| 101 | max zoom | 1 |
+| 102 | min longitude (signed 32-bit integer: longitude * 10,000,000) | 4 |
+| 106 | min latitude | 4 |
+| 110 | max longitude | 4 |
+| 114 | max latitude | 4 |
+| 118 | center zoom | 1 |
+| 119 | center longitude | 4 |
+| 123 | center latitude | 4 |
+
+### Notes
+
+* **# of addressed tiles**: the total number of tiles before run-length encoding, i.e. `Sum(RunLength)` over all entries.
+* **# of tile entries**: the total number of entries across all directories where `RunLength > 0`.
+* **# # of tile contents**: the number of referenced blobs in the tile section, or the unique # of offsets. If the archive is completely deduplicated, this is equal to the # of unique tile contents. If there is no deduplication, this is equal to the number of tile entries above.
+* **boolean clustered flag**: if true, blobs in the data section are ordered by Hilbert `TileId`. When writing with deduplication, this means that offsets are either contiguous with the previous offset+length, or refer to a lesser offset.
+* **compression enum**: Mandatory, tells the client how to decompress contents as well as provide correct `Content-Encoding` headers to browsers.
+* **tile type**: A hint as to the tile contents. Clients and proxies may use this to:
+ * Automatically determine a visualization method
+ * provide a conventional MIME type `Content-Type` HTTP header
+ * Enforce a canonical extension e.g. `.mvt`, `png`, `jpeg`, `.webp` to prevent duplication in caches
+
+### Organization
+
+In most cases, the archive should be in the order `Header`, Root Directory, JSON Metadata, Leaf Directories, Tile Data. It is possible to relocate sections other than `Header` arbitrarily, but no current writers/readers take advantage of this. A future design may allow for reverse-ordered archives to enable single-pass writing.
+
+
+## Version 2
+
+*Note: this is deprecated in favor of spec version 3.*
+
+PMTiles is a binary serialization format designed for two main access patterns: over the network, via HTTP 1.1 Byte Serving (`Range:` requests), or via memory-mapped files on disk. **All integer values are little-endian.**
+
+A PMTiles archive is composed of:
+* a fixed-size 512,000 byte header section
+* Followed by any number of tiles in arbitrary format
+* Optionally followed by any number of *leaf directories*
+
+### Header
+* The header begins with a 2-byte magic number, "PM"
+* Followed by 2 bytes, the PMTiles specification version (currently 2).
+* Followed by 4 bytes, the length of metadata (M bytes)
+* Followed by 2 bytes, the number of entries in the *root directory* (N entries)
+* Followed by M bytes of metadata, which **must be a JSON string with bounds, minzoom and maxzoom properties (new in v2)**
+* Followed by N * 17 bytes, the root directory.
+
+### Directory structure
+
+A directory is a contiguous sequence of 17 byte entries. A directory can have at most 21,845 entries. **A directory must be sorted by Z, X and then Y order (new in v2).**
+
+An entry consists of:
+* 1 byte: the zoom level (Z) of the entry, with the top bit set to 1 instead of 0 to indicate the offset/length points to a leaf directory and not a tile.
+* 3 bytes: the X (column) of the entry.
+* 3 bytes: the Y (row) of the entry.
+* 6 bytes: the offset of where the tile begins in the archive.
+* 4 bytes: the length of the tile, in bytes.
+
+**All leaf directory entries follow non-leaf entries. All leaf directories in a single directory must have the same Z value. (new in v2).**
+
+### Notes
+* A full directory of 21,845 entries holds exactly a complete pyramid with 8 levels, or 1+4+16+64+256+1024+4096+16384.
+* A PMTiles archive with less than 21,845 tiles should have a root directory and no leaf directories.
+* Multiple tile entries can point to the same offset; this is useful for de-duplicating certain tiles, such as an empty "ocean" tile.
+* Analogously, multiple leaf directory entries can point to the same offset; this can avoid inefficiently-packed small leaf directories.
+* The tentative media type for PMTiles archives is `application/vnd.pmtiles`.
+
+### Implementation suggestions
+
+* PMTiles is designed to make implementing a writer simple. Reserve 512KB, then write all tiles, recording their entry information; then write all leaf directories; finally, rewind to 0 and write the header.
+* The order of tile data in the archive is unspecified; an optimized implementation should arrange tiles on a 2D space-filling curve.
+* PMTiles readers should cache directory entries by byte offset, not by Z/X/Y. This means that deduplicated leaf directories result in cache hits.
\ No newline at end of file
diff --git a/docs/modules/polyfills/api-reference/README.md b/docs/modules/polyfills/api-reference/README.md
index 2e096116e0..0dfc331766 100644
--- a/docs/modules/polyfills/api-reference/README.md
+++ b/docs/modules/polyfills/api-reference/README.md
@@ -1,10 +1,8 @@
# Overview
-The optional `@loaders.gl/polyfills` module installs support for Node.js and older browsers.
+The `@loaders.gl/polyfills` module installs support for Node.js. This module should be imported before you call any loaders.gl functionality under Node.js
-loaders.gl is based on the HTML5 API provided by modern, evergreen browsers. Older browsers (mainly Edge and IE11) as well as versions of Node.js prior to v12 do not provide certain classes that loaders.gl depends on.
-
-Note that while `@loaders.gl/polyfills` is designed to work seamlessly with other loaders.gl modules, using it is not a requirement. There are other good polyfill modules available on `npm` that can be used in its place.
+loaders.gl is based on the HTML5 API provided by modern, evergreen browsers.
## Installation
@@ -16,33 +14,28 @@ npm install @loaders.gl/polyfills
Just import `@loaders.gl/polyfills` before you start using other loaders.gl modules.
-```js
+```typescript
import '@loaders.gl/polyfills';
import '@loaders.gl/core';
```
-To use the experimental `Blob` and `File` polyfills
+## Features
-```js
-import {installFilePolyfills} from '@loaders.gl/polyfills';
-installFilePolyfills();
-```
+The polyfills module installs the following capabilities.
-## Included Polyfills
+- fetching files from Node file system
+- Node Filesystem implementation
+- Node ReadableFile and WritableFile implementations
+- Node Crypto class
+- Node Stream support
+- Node library loading
+- Image parsing and encoding under Node.js
+ |
+## Deprecated polyfills
-| Polyfill | Node | Browser | Comments |
-| ------------------------------- | ------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TextEncoder`/`TextDecoder` | Node.js < 11 | Yes (Older browsers) | Only UTF8 is guaranteed to be supported |
-| `atob`/`btoa` | All versions | No | Note: these functions are [not unicode safe](https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding#The_Unicode_Problem), but OK to use for test cases. |
-| `fetch` | All versions | No | A subset of the fetch API is supported, see below. |
-| `Response` | All versions | No | A subset of the `Response` API is supported, see below. |
-| `Headers` | All versions | No | A subset of the fetch API is supported, see below. |
-| `Blob` (Experimental) | All versions | No | A subset of the fetch API is supported, see below. |
-| `File` (Experimental) | All versions | No | A subset of the fetch API is supported, see below. |
-| `FileReader` (Experimental) | All versions | No | A subset of the fetch API is supported, see below. |
-| `ReadableStream` (Experimental) | All versions | No | A subset of the ReadableStream API is supported. |
+Before Node v18, `fetch` needed to be polyfilled. The `@loaders.gl/polyfills` module still conditionally installs a fetch polyfill on Node 16, but this is expected to be removed in next major release.
-## fetch Polyfill
+### fetch Polyfill
The Node.js `fetch`, `Response` and `Headers` polyfills supports a large subset of the browser fetch API, including:
@@ -55,18 +48,9 @@ The Node.js `fetch`, `Response` and `Headers` polyfills supports a large subset
The Node.js `fetch` is able to follow 30X redirect: if `Response` has status 300-399 and `location` header is set, the `fetch` polyfill re-requests data from `location`.
-# TextEncoder and TextDecoder Polyfills
-
-`TextEncoder` and `TextDecoder` polyfills are provided to ensure these APIs are always available. In modern browsers these will evaluate to the built-in objects of the same name, however under Node.js polyfills are transparently installed.
-
-Note: The provided polyfills only guarantee UTF8 support.
-
## Remarks
-- Applications should only install this module if they need to run under older environments. While the polyfills are only installed at runtime if the platform does not already support them, importing this module will increase the application's bundle size.
-- Refer to browser documentation for the usage of these classes, e.g. MDN.
-- In the browser, overhead of using these imports is not as high, as most polyfills are only bundled under Node.js.
-- If working under older browsers, e.g. IE11, you may need to install your own TextEncoder/TextDecoder polyfills before loading this library
+- The polyfills module can safely be imported in the browser. It is designed to be a no-op in this case, though if you are using new cutting-edge bundlers, they may not respect this configuration.
## Attribution
diff --git a/docs/modules/schema/README.md b/docs/modules/schema/README.md
index 9dc2df7e0d..baf6c9744e 100644
--- a/docs/modules/schema/README.md
+++ b/docs/modules/schema/README.md
@@ -11,11 +11,11 @@
The table API is modelled after a subset of the Apache Arrow API:
-| Class | Arrow Counterpart | Description |
-| ------------------------------------------------------------------ | ----------------- | ------------ |
-| [`Table`](/docs/modules/schema/api-reference/table) | Table | Table |
-| [`TableSchema`](/docs/modules/schema/api-reference/table-schema) | `Schema` | Table schema |
-| [`TableBatch`](/docs/modules/schema/api-reference/table-batch) | `RecordBatch` | Table batch |
+| Class | Arrow Counterpart | Description |
+| --------------------------------------------------------- | ----------------- | ----------- |
+| [`Table`](/docs/modules/schema/api-reference/table) | `Table` | Table |
+| [`Schema`](/docs/modules/schema/api-reference/schema) | `Schema` | Schema |
+| [`Batch`](/docs/modules/schema/api-reference/table-batch) | `RecordBatch` | Batch |
## Determining shape of loaded data
@@ -44,12 +44,12 @@ processTile(tile.data);
### Table Category
-| Shape | Category | Types / Description |
-| --- | --- | --- |
-| `table` | `Table` |
-| `array-row-table` | `ArrayRowTable` |
+| Shape | Category | Types / Description |
+| ------------------ | ---------------- | ------------------- |
+| `table` | `Table` |
+| `array-row-table` | `ArrayRowTable` |
| `object-row-table` | `ObjectRowTable` |
-| `columnar-table` | `ColumnarTable` |
+| `columnar-table` | `ColumnarTable` |
- Tables can be
- row-oriented, i.e. organized as an array of rows
@@ -59,7 +59,7 @@ Rows can contain either
- an array of values, where the column name is found in the schema.
- object with key-value pairs, where the key is the column name
-```json
+```typescripton
{
"shape": ,
"data":
@@ -69,10 +69,10 @@ Rows can contain either
## GIS Category
-| Shape | Category | Types / Description |
-| --- | --- | --- |
-| `geojson` | `GeoJSON` | GeoJSON is a `features` array wrapped at the top level |
-| `array-row-table` | `ArrayRowTable` |
+| Shape | Category | Types / Description |
+| ------------------ | ---------------- | ---------------------------------------------------------------- |
+| `geojson` | `GeoJSON` | GeoJSON is a `features` array wrapped at the top level |
+| `array-row-table` | `ArrayRowTable` |
| `object-row-table` | `ObjectRowTable` |
-| `geojson-table` | `GeojsonTable` | GeoJSON table essentially contains the `features` array from the
+| `geojson-table` | `GeojsonTable` | GeoJSON table essentially contains the `features` array from the |
diff --git a/docs/modules/schema/api-reference/apache-arrow.md b/docs/modules/schema/api-reference/apache-arrow.md
new file mode 100644
index 0000000000..ff37b1100c
--- /dev/null
+++ b/docs/modules/schema/api-reference/apache-arrow.md
@@ -0,0 +1,4 @@
+# Apache Arrow
+
+loaders.gl aims to provide strong support for and interoperability with Apache Arrow.
+
diff --git a/docs/modules/schema/api-reference/geometries.md b/docs/modules/schema/api-reference/geometries.md
new file mode 100644
index 0000000000..ed7514f50b
--- /dev/null
+++ b/docs/modules/schema/api-reference/geometries.md
@@ -0,0 +1,27 @@
+# Geometries
+
+
+## GeoJSONTable
+
+The `GeoJSONTable` is one of the standard data return formats from loaders.gl loaders.
+It is a GeoJSON FeatureCollection with two extra fields (`shape` and `schema`)
+
+
+## Binary Geometries
+
+loaders.gl defines a Binary Geometry Format.
+
+The format is designed to work directly with the binary support in deck.gl layers.
+
+This format is currently described in more detail in the `@loaders.gl/gis` module documentation.
+
+##
+
+## Tesselation
+
+Some loaders can perform tesselation.
+
+This is typically done with earcut, which is a very fast polygon tesselator. The drawback with
+
+There can also be problems if polygons have very large numbers of holes.
+
diff --git a/docs/modules/schema/api-reference/schema.md b/docs/modules/schema/api-reference/schema.md
new file mode 100644
index 0000000000..35e39c9d5f
--- /dev/null
+++ b/docs/modules/schema/api-reference/schema.md
@@ -0,0 +1,19 @@
+# Schema
+
+loaders.gl provides a simple serializable schema class to help describe tables and table like data.
+The Schema is modelled after Arrow.
+
+
+## Schema Deduction
+
+Schemas can be deduced, but unless the data format is binary, this can lead to mistakes.
+
+For instance, should a column with zip codes in a CSV be treated as strings or numbers? (Most auto detection systems would classify the type as numbers, but most users would prefer for that column to be classified as string, to avoid potential dropping of leading zeroes among other things.)
+
+## Schema Serialization
+
+..
+
+## Apache Arrow Schemas
+
+...
diff --git a/docs/modules/schema/api-reference/table-schema.md b/docs/modules/schema/api-reference/table-schema.md
deleted file mode 100644
index ab2b1b22ec..0000000000
--- a/docs/modules/schema/api-reference/table-schema.md
+++ /dev/null
@@ -1 +0,0 @@
-# TableSchema
diff --git a/docs/modules/schema/api-reference/table.md b/docs/modules/schema/api-reference/table.md
index f91505acf6..55b81ecc8f 100644
--- a/docs/modules/schema/api-reference/table.md
+++ b/docs/modules/schema/api-reference/table.md
@@ -1 +1,30 @@
# Table
+
+loaders.gl defines a number of table types.
+
+- `ObjectRowTable`
+- `ArrayRowTable`
+- `GeoJSONTable`
+- `ColumnarTable`
+- `ArrowTable`
+
+These all have a `shape` field on the top level.
+
+(If you are an advanced TypeScript programmer, you will appreciate that this lets typescript treat table types as a "discriminated union", meaning that once the type has been checked in an if or switch statement, the typing of the table is implied).
+
+
+## Table Schemas
+
+Each table has an optional `schema` field. If it is present, it contains a list of fields (name, type and metadata for each field), as well as metadata for the table itself.
+
+There are also utilities for deducing schemas.
+
+## Table Utilities
+
+A set of utilities are provided to work with tables independently of which of the supported representations they are in.
+
+- `tableLength``
+- ...
+
+
+
diff --git a/docs/modules/shapefile/api-reference/dbf-loader.md b/docs/modules/shapefile/api-reference/dbf-loader.md
index 0eb6a21180..1ad7075ae3 100644
--- a/docs/modules/shapefile/api-reference/dbf-loader.md
+++ b/docs/modules/shapefile/api-reference/dbf-loader.md
@@ -22,7 +22,7 @@ Note: Most applications will want to use the `ShapefileLoader` instead of this l
The `DBFLoader` parses feature attributes from the Shapefile format.
-```js
+```typescript
import {DBFLoader} from '@loaders.gl/shapefile';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/shapefile/api-reference/shapefile-loader.md b/docs/modules/shapefile/api-reference/shapefile-loader.md
index 71fd86ff5d..ab8dceb65a 100644
--- a/docs/modules/shapefile/api-reference/shapefile-loader.md
+++ b/docs/modules/shapefile/api-reference/shapefile-loader.md
@@ -19,7 +19,7 @@ Shapefile loader
## Usage
-```js
+```typescript
import {ShapefileLoader} from '@loaders.gl/shapefile';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/shapefile/api-reference/shp-loader.md b/docs/modules/shapefile/api-reference/shp-loader.md
index 9ed16ea946..97b72faf9f 100644
--- a/docs/modules/shapefile/api-reference/shp-loader.md
+++ b/docs/modules/shapefile/api-reference/shp-loader.md
@@ -21,7 +21,7 @@ Note: Most applications will want to use the `ShapefileLoader` instead of this l
## Usage
-```js
+```typescript
import {SHPLoader} from '@loaders.gl/shapefile';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/shapefile/formats/shapefile.md b/docs/modules/shapefile/formats/shapefile.md
index f1b793d757..c50c288111 100644
--- a/docs/modules/shapefile/formats/shapefile.md
+++ b/docs/modules/shapefile/formats/shapefile.md
@@ -1,23 +1,24 @@
# Shapefile
-- *[`@loaders.gl/shapefile`](/docs/modules/shapefile/formats/shapefile)*
-- *https://www.clicketyclick.dk/databases/xbase/format/data_types.html*
-- *http://www.dbase.com/Knowledgebase/INT/db7_file_fmt.htm*
-- *http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=Geoprocessing_considerations_for_shapefile_output*
-- *https://www.loc.gov/preservation/digital/formats/fdd/fdd000326.shtml*
-- *https://support.esri.com/en/technical-article/000013192*
+ESRI Shapefiles is a file format for storing geospatial vector data.
-ESRI Shapefiles are a popular file format for storing geospatial vector data.
+- *[`@loaders.gl/shapefile`](/docs/modules/shapefile)*
+- *[Wikipedia](https://en.wikipedia.org/wiki/Shapefile)* - *[ESRI Shapefile Whitepaper](https://www.esri.com/content/dam/esrisites/sitecore-archive/Files/Pdfs/library/whitepapers/pdfs/shapefile.pdf)* - *[Notes on Shapefile usage](http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=Geoprocessing_considerations_for_shapefile_output)*
+- *[DBF header](http://www.dbase.com/Knowledgebase/INT/db7_file_fmt.htm)* - *[data types](https://www.clicketyclick.dk/databases/xbase/format/data_types.html_)* - *[code pages](https://support.esri.com/en/technical-article/000013192)* - *[implementation notes](https://www.loc.gov/preservation/digital/formats/fdd/fdd000326.shtml)*
-## Multi-file Summary
+*Note that Shapefiles are falling out of favor in modern usage (likely due to the significant inconvenience of having to deal with multiple files). However, a lot of valuable geospatial data available is still provided in Shapefile format, and sometimes only in this format.
+Additional information and some strong opinions can be found at [switchfromshapefile.org](http://switchfromshapefile.org/).*
-The format consists of a number of files that must be stored together
-(in the same directory, and with the same file name but different extensions).
-Files with extensions `.shp`, `.shx`, `.dbf` must exist;
-additional files with other extensions such as `.prj` and `.cpg` may exist.
+## A multi-file format
-A common problem with shapefiles is that the user only opens the shp file but not the dbf.
+A Shapefile consists of a number of files that must be read and written together.
+Because of this, they are typically stored together with the same file name but different extensions.
+These related files are usually stored in the same directory or inside a common zip archive.
+While it is possible to just load the geometries from a `.shp` file, files with extensions `.shp`, `.shx`, `.dbf` are often expected to exist,
+and additional files with other extensions such as `.prj` and `.cpg` may also exist, if needed.
+
+A common problem with shapefiles is that the user only opens the `.shp` file but not the accompanying files such as `.dbf`.
| File | Type | Contents |
| ------ | ------ | -------------------------------------------------------------------------------------------------------------- |
@@ -26,3 +27,48 @@ A common problem with shapefiles is that the user only opens the shp file but no
| `.shx` | Binary | The index (technically required, however it is sometimes possible to open shapefiles without the index) |
| `.prj` | Text | A small usually single line text file containing a WKT-CRS style projection. WGS84 is assumed if not present. |
| `.cpg` | Text | A small text file containing a text encoding name for the DBF text fields. `latin1` is assumed if not present. |
+
+### Coordinate Systems
+
+Arbitrary coordinate reference systems are supported for Shapefiles.
+
+Such coordinate systems are reprojected to WGS84 on import.
+
+### Encodings
+
+The optional "code page" file (`.cpg`) specifies the encoding of any text data in the Shapefile (or more precisely, in the sidecar `.dbf` file). If no `.cpg` file is provided, `latin1` encoding is assumed.
+
+### Geometries
+
+A Shapefile always encodes a single type of geometries. The following geometries are supported:
+
+| Shape type | GeoJSON | loaders.gl | Value | Fields |
+| ------------- | ------------ | ---------- | ----- | --------------------------------------------------------------------------------------------------------------- |
+| `Null` shape | `null` | ✅ | 0 | None |
+| `Point` | `Point` | ✅ | 1 | X, Y |
+| `Polyline` | `LineString` | ✅ | 3 | MBR, Number of parts, Number of points, Parts, Points |
+| `Polygon` | `Polygon` | ✅ | 5 | MBR, Number of parts, Number of points, Parts, Points |
+| `MultiPoint` | `MultiPoint` | ✅ | 8 | MBR, Number of points, Points |
+| `PointZ` | `Point` | ✅ | 11 | X, Y, Z Optional: M |
+| `PolylineZ` | `LineString` | ✅ | 13 | MBR, Number of parts, Number of points, Parts, Points, Z range, Z array Optional: M range, M array |
+| `PolygonZ` | `Polygon` | ✅ | 15 | MBR, Number of parts, Number of points, Parts, Points, Z range, Z array Optional: M range, M array |
+| `MultiPointZ` | `MultiPoint` | ✅ | 18 | MBR, Number of points, Points, Z range, Z array Optional: M range, M array |
+| `PointM` | `Point` | ✅ | 21 | X, Y, M |
+| `PolylineM` | `LineString` | ✅ | 23 | MBR, Number of parts, Number of points, Parts, Points Optional: M range, M array |
+| `PolygonM` | `Polygon` | ✅ | 25 | MBR, Number of parts, Number of points, Parts, Points Optional: M range, M array |
+| `MultiPointM` | `MultiPoint` | ✅ | 28 | MBR, Number of points, Points Optional Fields: M range, M array |
+| `MultiPatch` | | ❌ | 31 | MBR , Number of parts, Number of points, Parts, Part types, Points, Z range, Z array Optional: M range, M array |
+
+- `value` is the internal shapefile encoding
+
+### Version History
+
+- The shapefile format was introduced with ArcView GIS version 2 in the early 1990s.
+
+### Troubleshooting
+
+- No data columns: The most common problem with shapefile is probably that they user only opens the main `.shp` file. In this case only the geometry is included, but no data columns are present.
+- Geometry projection issues: geometry may fail to load or be visualized incorrectly without the associated `.prj` file.
+- Incorrect strings: Encodings may not be correct without the `.cpg` file.
+
+Also note that there is a very large number of possible projections and it is hard to test that every possible projection is supported. If your data is old or known to be problematic, it may be worth double checking that things look correct after importing.
diff --git a/docs/modules/terrain/api-reference/quantized-mesh-loader.md b/docs/modules/terrain/api-reference/quantized-mesh-loader.md
index 6220ff99f5..d1f9367942 100644
--- a/docs/modules/terrain/api-reference/quantized-mesh-loader.md
+++ b/docs/modules/terrain/api-reference/quantized-mesh-loader.md
@@ -22,7 +22,7 @@ mesh][quantized_mesh] format.
## Usage
-```js
+```typescript
import {QuantizedMeshLoader} from '@loaders.gl/terrain';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/terrain/api-reference/terrain-loader.md b/docs/modules/terrain/api-reference/terrain-loader.md
index dbf7eae558..6a683c2d24 100644
--- a/docs/modules/terrain/api-reference/terrain-loader.md
+++ b/docs/modules/terrain/api-reference/terrain-loader.md
@@ -15,7 +15,7 @@ The `TerrainLoader` reconstructs mesh surfaces from height map images, e.g. [Map
## Usage
-```js
+```typescript
import {ImageLoader} from '@loaders.gl/images';
import {TerrainLoader} from '@loaders.gl/terrain';
import {load, registerLoaders} from '@loaders.gl/core';
diff --git a/docs/modules/textures/api-reference/basis-loader.md b/docs/modules/textures/api-reference/basis-loader.md
index 70053cddeb..69b91a5f39 100644
--- a/docs/modules/textures/api-reference/basis-loader.md
+++ b/docs/modules/textures/api-reference/basis-loader.md
@@ -16,7 +16,7 @@ A loader for Basis Universal "supercompressed" GPU textures. Extracts supercompr
## Usage
-```js
+```typescript
import {BasisLoader} from '@loaders.gl/textures';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/textures/api-reference/compressed-texture-loader.md b/docs/modules/textures/api-reference/compressed-texture-loader.md
index 0d52effbf1..25613aa9ee 100644
--- a/docs/modules/textures/api-reference/compressed-texture-loader.md
+++ b/docs/modules/textures/api-reference/compressed-texture-loader.md
@@ -16,7 +16,7 @@ Loader for compressed textures in the PVR file format
## Usage
-```js
+```typescript
import {CompressedTextureLoader} from '@loaders.gl/textures';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/textures/api-reference/compressed-texture-writer.md b/docs/modules/textures/api-reference/compressed-texture-writer.md
index 5a03450839..56d26d7e44 100644
--- a/docs/modules/textures/api-reference/compressed-texture-writer.md
+++ b/docs/modules/textures/api-reference/compressed-texture-writer.md
@@ -1,4 +1,4 @@
-# CompressedTextureWriter
+# CompressedTextureWriter 🚧
@@ -19,7 +19,7 @@
## Usage
-```js
+```typescript
import '@loaders.gl/polyfill'; // only if using under Node
import {encodeURLtoURL} from '@loaders.gl/core';
import {CompressedTextureWriter} from '@loaders.gl/textures';
diff --git a/docs/modules/textures/api-reference/crunch-loader.md b/docs/modules/textures/api-reference/crunch-loader.md
index 905920b394..0ffe64c5d1 100644
--- a/docs/modules/textures/api-reference/crunch-loader.md
+++ b/docs/modules/textures/api-reference/crunch-loader.md
@@ -16,7 +16,7 @@ Loader for compressed textures in the Crunch file format
## Usage
-```js
+```typescript
import {CrunchWorkerLoader} from '@loaders.gl/textures';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/textures/api-reference/ktx2-basis-texture-writer.md b/docs/modules/textures/api-reference/ktx2-basis-texture-writer.md
index 231809d150..09f8413742 100644
--- a/docs/modules/textures/api-reference/ktx2-basis-texture-writer.md
+++ b/docs/modules/textures/api-reference/ktx2-basis-texture-writer.md
@@ -1,4 +1,4 @@
-# KTX2BasisWriter
+# KTX2BasisWriter 🚧
@@ -19,7 +19,7 @@
## Usage
-```js
+```typescript
import '@loaders.gl/polyfill'; // only if using under Node
import {load, encode} from '@loaders.gl/core';
import {KTX2BasisUniversalTextureWriter} from '@loaders.gl/textures';
diff --git a/docs/modules/textures/api-reference/load-image-array.md b/docs/modules/textures/api-reference/load-image-array.md
index 6f05e44f07..41c8c439b8 100644
--- a/docs/modules/textures/api-reference/load-image-array.md
+++ b/docs/modules/textures/api-reference/load-image-array.md
@@ -9,7 +9,7 @@ A function that loads an array of images. Primarily intended for loading:
Loading an array of images
-```js
+```typescript
import '@loaders.gl/polyfills'; // only needed for Node.js support
import {loadImageArray} from `@loaders.gl/images`;
@@ -20,7 +20,7 @@ for (const image of images) {
}
```
-```js
+```typescript
import '@loaders.gl/polyfills'; // only needed for Node.js support
import {loadImageArray} from `@loaders.gl/images`;
diff --git a/docs/modules/textures/api-reference/load-image-cube.md b/docs/modules/textures/api-reference/load-image-cube.md
index b99b4610d6..8f54b736f3 100644
--- a/docs/modules/textures/api-reference/load-image-cube.md
+++ b/docs/modules/textures/api-reference/load-image-cube.md
@@ -6,7 +6,7 @@ A function that loads 6 images representing the faces of a cube. Primarily inten
Load images for a cubemap with one image per face
-```js
+```typescript
import '@loaders.gl/polyfills'; // only needed for Node.js support
import {loadImageCube} from `@loaders.gl/images`;
@@ -19,7 +19,7 @@ for (const face in imageCube) {
Load images for a cubemap with an array of mip images per face
-```js
+```typescript
import '@loaders.gl/polyfills'; // only needed for Node.js support
import {loadImageCube} from `@loaders.gl/images`;
diff --git a/docs/modules/textures/api-reference/load-image.md b/docs/modules/textures/api-reference/load-image.md
index 679cc1e13b..88d3975771 100644
--- a/docs/modules/textures/api-reference/load-image.md
+++ b/docs/modules/textures/api-reference/load-image.md
@@ -2,14 +2,14 @@
## Usage
-```js
+```typescript
import '@loaders.gl/polyfills'; // only needed if using under Node
import {loadImage} from `@loaders.gl/images`;
const image = await loadImage(url);
```
-```js
+```typescript
import '@loaders.gl/polyfills'; // only needed if using under Node
import {loadImage} from `@loaders.gl/images`;
diff --git a/docs/modules/textures/api-reference/npy-loader.md b/docs/modules/textures/api-reference/npy-loader.md
index cc6365cc1c..481090dd8e 100644
--- a/docs/modules/textures/api-reference/npy-loader.md
+++ b/docs/modules/textures/api-reference/npy-loader.md
@@ -21,7 +21,7 @@ The `NPYLoader` parses an array from the [NPY format][npy-spec], a lightweight e
## Usage
-```js
+```typescript
import {_NPYLoader} from '@loaders.gl/textures';
import {load} from '@loaders.gl/core';
diff --git a/docs/modules/textures/formats/compressed-textures.md b/docs/modules/textures/formats/compressed-textures.md
index a1a245161f..a222639fc7 100644
--- a/docs/modules/textures/formats/compressed-textures.md
+++ b/docs/modules/textures/formats/compressed-textures.md
@@ -100,7 +100,7 @@ Data returned by any loaders.gl "image" category loader (including texture loade
To use compressed textures in WebGL
-```js
+```typescript
const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, texture);
@@ -143,7 +143,7 @@ Support for compressed textures is a work in progress in the [WebGPU standard](h
At the time of writing, only S3 texture compression has been specified:
-```js
+```typescript
// BC compressed formats usable if "texture-compression-bc" is both
// supported by the device/user agent and enabled in requestDevice.
"bc1-rgba-unorm",
diff --git a/docs/modules/tile-converter/api-reference/3d-tiles-converter.md b/docs/modules/tile-converter/api-reference/3d-tiles-converter.md
index f63287cd02..b8e5cd2d61 100644
--- a/docs/modules/tile-converter/api-reference/3d-tiles-converter.md
+++ b/docs/modules/tile-converter/api-reference/3d-tiles-converter.md
@@ -8,7 +8,7 @@ The `Tiles3DConverter` class converts an I3S layer. It converts between the OGC
## Usage
-```js
+```typescript
import {Tiles3DConverter} from '@loaders.gl/tile-converter';
const TILESET_URL =
diff --git a/docs/modules/tile-converter/api-reference/i3s-converter.md b/docs/modules/tile-converter/api-reference/i3s-converter.md
index b4ff40a300..da8b68b954 100644
--- a/docs/modules/tile-converter/api-reference/i3s-converter.md
+++ b/docs/modules/tile-converter/api-reference/i3s-converter.md
@@ -8,7 +8,7 @@ The `I3SConverter` class converts a 3D Tiles tileset to I3S layer.
## Usage
-```js
+```typescript
import {I3SConverter} from '@loaders.gl/tile-converter';
const converter = new I3SConverter();
@@ -45,7 +45,9 @@ Converts a tileset to I3S format
- `options.generateTextures: boolean` Whether the converter should generate additional texture of another format. For non-compressed source texture format (JPG, PNG) the converter creates additional KTX2 texture. For compressed source texture (KTX2) the converter creates additional JPG texture. To encode and decode KTX2 [Basis Universal Supercompressed GPU Texture Codec](https://github.com/BinomialLLC/basis_universal) is used.
- `options.generateBoundingVolumes: boolean` Whether the converter generate new bounding volumes from the mesh vertices. The default behavior is convertion bounding volumes (box, sphere or region) from 3DTiles tileset data. If this option is set `true` the converter will ignore source bounding volume and generate new bounding volume (oriented bounding box and minimal bounding sphere) from the geometry POSITION attribute.
- `options.instantNodeWriting: boolean` Whether the converter should keep JSON resources ([3DNodeIndexDocuments](https://github.com/Esri/i3s-spec/blob/master/docs/1.8/3DNodeIndexDocument.cmn) and [nodePages](https://github.com/Esri/i3s-spec/blob/master/docs/1.8/nodePage.cmn)) on disk during conversion. The default behavior is the converter keeps JSON resources in memory till the end of conversion. Those resources need to be updated during conversion (adding child nodes and neighbor nodes). If this option is set `true` the converter will keep JSON resources on disk all the time. Use this option for large datasets when the nodes tree is large and "memory overflow" error occurs. Instant node writing saves memory usage in cost of conversion speed (>2 times slower).
-- `options.validate` Enable Validation
+- `options.metadataClass: string` One of the list of feature metadata classes, detected by converter on "analyze" stage
+- `options.analyze: boolean` Analyze the input tileset content without conversion.
+- `options.validate: boolean` Enable Validation.
### Validation
diff --git a/docs/modules/tile-converter/cli-reference/i3s-server.md b/docs/modules/tile-converter/cli-reference/i3s-server.md
new file mode 100644
index 0000000000..790c783501
--- /dev/null
+++ b/docs/modules/tile-converter/cli-reference/i3s-server.md
@@ -0,0 +1,81 @@
+# I3S Server
+
+
+
+
+ 
+
+
+
+I3S Server is a NodeJS HTTP service built on top of [Express](https://expressjs.com). It can serve I3S data from output path of tile-converter or from SLPK file container.
+
+## Installation
+
+The i3s-server is published as a part of `@loaders.gl/tile-converter` library.
+
+Create a new folder:
+
+```bash
+mkdir tmp
+cd tmp
+```
+
+Install `@loaders.gl/tile-converter` package:
+
+```bash
+npm i @loaders.gl/tile-converter
+```
+
+## Serve the output data of `tile-converter`
+
+Convert 3DTiles tileset to I3S without `--slpk` option:
+
+```bash
+npx tile-converter --install-dependencies
+npx tile-converter --input-type 3DTILES --tileset /path/to/tileset.json --name NewTileset
+```
+
+### Start HTTP server
+```bash
+PORT=8080 HTTPS_PORT=4443 I3sLayerPath="./data" DEBUG=i3s-server:* npx i3s-server
+```
+
+#### The layer should be available on URLs
+- `http://localhost:8080/NewTileset/SceneServer/layers/0`
+- `https://localhost:4443/NewTileset/SceneServer/layers/0`
+
+#### Open in ArcGIS
+
+`https://www.arcgis.com/home/webscene/viewer.html?url=http://localhost:8080/NewTileset/SceneServer`
+
+#### Open in I3S Explorer
+
+`https://i3s.loaders.gl/viewer?tileset=http://localhost:8080/NewTileset/SceneServer/layers/0`
+
+## Serve SLPK
+
+Example for path `../datasets/Rancho_Mesh_mesh_v17_1.slpk`:
+
+### Start the server
+
+```bash
+PORT=8080 HTTPS_PORT=4443 I3sLayerPath="../datasets/Rancho_Mesh_mesh_v17_1.slpk" DEBUG=i3s-server:* npx i3s-server
+```
+#### The layer should be available on URLs
+
+- `http://localhost:8080/SceneServer/layers/0/...`
+- `https://localhost:4443/SceneServer/layers/0/...`
+
+#### Open in ArcGIS
+
+`https://www.arcgis.com/home/webscene/viewer.html?url=http://localhost:8080/SceneServer`
+
+#### Open in I3S Explorer
+
+`https://i3s.loaders.gl/viewer?tileset=http://localhost:8080/SceneServer/layers/0`
+
+## ENV variables
+
+- `I3sLayerPath` - path to converted data or SLPK file.
+- `PORT` - HTTP port. Eg for `PORT = 8080 npx i3s-server` the server will work on host `http://localhost:8080/...`. Default value is `80`;
+- `HTTPS_PORT` - HTTPS port. Eg for `PORT = 4443 npx i3s-server` the server will work on host `https://localhost:4443/...`. Default value is `443`
\ No newline at end of file
diff --git a/docs/modules/tile-converter/cli-reference/metadata-class-selection-promt.png b/docs/modules/tile-converter/cli-reference/metadata-class-selection-promt.png
new file mode 100644
index 0000000000..4093e32156
Binary files /dev/null and b/docs/modules/tile-converter/cli-reference/metadata-class-selection-promt.png differ
diff --git a/docs/modules/tile-converter/cli-reference/slpk-extractor.md b/docs/modules/tile-converter/cli-reference/slpk-extractor.md
new file mode 100644
index 0000000000..374359a0e3
--- /dev/null
+++ b/docs/modules/tile-converter/cli-reference/slpk-extractor.md
@@ -0,0 +1,53 @@
+# SLPK extractor
+
+
+
+
+
+
+
+
+SLPK extractor is utility that helps to extract slpk to a dataset that can be served via i3s-server
+
+## Installation
+
+The slpk-extractor is published as a part of `@loaders.gl/tile-converter`
+
+Create a new folder:
+
+```bash
+mkdir tmp
+cd tmp
+```
+
+Install `@loaders.gl/tile-converter` package:
+
+```bash
+npm i @loaders.gl/tile-converter
+```
+
+## Extraction
+
+Extract .slpk to the `./data` folder:
+
+```bash
+npx slpk-extractor --tileset="./path/to/the/file.slpk" --output="./data//SceneServer/layers/0"
+```
+Then you can start serving dataset
+
+### Start HTTP server
+```bash
+PORT=8080 HTTPS_PORT=4443 I3sLayerPath="./data" DEBUG=i3s-server:* npx i3s-server
+```
+
+#### The layer should be available on URLs
+- `http://localhost:8080/SceneServer/layers/0`
+- `https://localhost:4443/SceneServer/layers/0`
+
+#### Open in ArcGIS
+
+`https://www.arcgis.com/home/webscene/viewer.html?url=http://localhost:8080//SceneServer`
+
+#### Open in I3S Explorer
+
+`https://i3s.loaders.gl/viewer?tileset=http://localhost:8080/SceneServer/layers/0`
diff --git a/docs/modules/tile-converter/cli-reference/supported-features.md b/docs/modules/tile-converter/cli-reference/supported-features.md
index 37e127f594..b58976f1c9 100644
--- a/docs/modules/tile-converter/cli-reference/supported-features.md
+++ b/docs/modules/tile-converter/cli-reference/supported-features.md
@@ -18,12 +18,12 @@ The tile-converter is capable to convert 3D tiles data of formats [3DTiles](http
## Input data source types
-| Specification | Data source type | Status |
-| ------------- | ------------------------ | ------------- |
-| `I3S` | SLPK | Not supported |
-| `I3S` | HTTP REST service | Supported |
-| `3DTiles` | Local file system folder | Supported |
-| `3DTiles` | Cesium ION URL | Supported |
+| Specification | Data source type | Status |
+| ------------- | ------------------------ | ------------------------------- |
+| `I3S` | SLPK | Supported as local HTTP service |
+| `I3S` | HTTP REST service | Supported |
+| `3DTiles` | Local file system folder | Supported |
+| `3DTiles` | Cesium ION URL | Supported |
## Versions
@@ -46,9 +46,9 @@ Some 3DTiles vNext extensions are supported as input data.
| `3DTiles` | `3DTILES_implicit_tiling` | Supported |
| `3DTiles` | `3DTILES_bounding_volume_S2` | Supported |
| `3DTIles` | `3DTILES_metadata` | Not applicable for `I3S` |
-| `glTF` | `EXT_mesh_features` | In progress |
-| `glTF` | `EXT_feature_metadata` | In progress |
-| `glTF` | `EXT_structural_metadata` | In progress |
+| `glTF` | `EXT_mesh_features` | Supported |
+| `glTF` | `EXT_feature_metadata` | Supported |
+| `glTF` | `EXT_structural_metadata` | Supported |
## Internal data types
diff --git a/docs/modules/tile-converter/cli-reference/tile-converter.md b/docs/modules/tile-converter/cli-reference/tile-converter.md
index 062fbefd68..c2262ecd60 100644
--- a/docs/modules/tile-converter/cli-reference/tile-converter.md
+++ b/docs/modules/tile-converter/cli-reference/tile-converter.md
@@ -1,4 +1,4 @@
-# Tile converter
+# Tile Converter
@@ -10,110 +10,159 @@