From bbe24a0827397ea7a74ccecb4b80e8dea39a07e1 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 20 May 2024 15:31:45 -0400 Subject: [PATCH] docs: Release notes for 4.3 (#3020) --- docs/developer-guide/using-sources.md | 22 ++-- docs/docs-sidebar.json | 2 +- docs/modules/mvt/README.md | 2 +- .../mvt/api-reference/geojson-tile-source.md | 113 ------------------ docs/whats-new.mdx | 20 +++- modules/mvt/test/index.ts | 6 +- 6 files changed, 39 insertions(+), 126 deletions(-) delete mode 100644 docs/modules/mvt/api-reference/geojson-tile-source.md diff --git a/docs/developer-guide/using-sources.md b/docs/developer-guide/using-sources.md index c1248c38b3..51b834b616 100644 --- a/docs/developer-guide/using-sources.md +++ b/docs/developer-guide/using-sources.md @@ -4,19 +4,22 @@ loaders.gl provides a number of `Source` exports that support multi-step data lo **Sources** are designed encapsulates the following data access models: -| Encapsulated Data | Description | +| Data Access Model | Description | | --------------------------- | ------------------------------------------------------------------------------- | -| ***web service** | interact with a web service that returns data assets for different regions etc. | -| **cloud storage** | -| **archive files** | read individual assets from a (very large) multi-asset archive files. | -| **dynamic data generation** | +| ***web service** | Interact with a web service that returns data assets for different regions etc. | +| **cloud storage** | Read static assets as-needed from large cloud-native file formats | +| **archive files** | Read individual assets from a (very large) multi-asset archive files. | +| **dynamic data generation** | Generate data (tiles, images etc) dynamically based on application requests. | +## Source -The `Source` instance provides methods to query metadata, and to query data for specific geospatial areas. +A `Source` object provides information for creating a `DataSource` ## DataSource Interfaces -A `Source` can (and sometimes must) expose a completely unique API. However a big advantages comes when a `Source` conforms to an existing Source interface. +A `DateSource` instance provides methods to query metadata, and to query data for specific geospatial areas. + +A `DataSource` can (and sometimes must) expose a completely unique API. However a big advantages comes when a `DataSource` conforms to an existing Source interface. This means that applications written against that interface can now support the new source without any changes to existing logic. @@ -27,6 +30,11 @@ This means that applications written against that interface can now support the | `ImageTileSource` | Load image covering a specific tile index | WMTS (N/A) | | `VectorTileSource` | Load "features" in a specific tile index | Mapbox Vector Tiles, `PMTilesSource` | +## Metadata + +A `DateSource` instance provides methods to query metadata: `await dataSource.getMetadata()`. + + ## Adapter Sources While most `Source` implementations provide an interface for interacting with a specific web service or cloud archive file format (e.g. `PMtilesSource`), it is also possible to create adapters: diff --git a/docs/docs-sidebar.json b/docs/docs-sidebar.json index ccb1c48dcb..fe54afb4c9 100644 --- a/docs/docs-sidebar.json +++ b/docs/docs-sidebar.json @@ -97,7 +97,7 @@ "items": [ "modules/pmtiles/api-reference/pmtiles-source", "modules/mvt/api-reference/mvt-source", - "modules/mvt/api-reference/geojson-tile-source", + "modules/mvt/api-reference/table-tile-source", "modules/wms/api-reference/csw-service", "modules/wms/api-reference/wms-service" ] diff --git a/docs/modules/mvt/README.md b/docs/modules/mvt/README.md index f7e5bdda35..eef7a05bae 100644 --- a/docs/modules/mvt/README.md +++ b/docs/modules/mvt/README.md @@ -22,7 +22,7 @@ npm install @loaders.gl/core | Component | | ------------------------------------------------------------------------ | | [`MVTSource`](/docs/modules/mvt/api-reference/mvt-source) | -| [`TableTileSource`](/docs/modules/mvt/api-reference/geojson-tile-source) | +| [`TableTileSource`](/docs/modules/mvt/api-reference/table-tile-source) | ## Attribution diff --git a/docs/modules/mvt/api-reference/geojson-tile-source.md b/docs/modules/mvt/api-reference/geojson-tile-source.md deleted file mode 100644 index e1a1f3d531..0000000000 --- a/docs/modules/mvt/api-reference/geojson-tile-source.md +++ /dev/null @@ -1,113 +0,0 @@ -# TableTileSource - -The `TableTileSource` slices large GeoJSON datasets into small vector tiles on the fly. -Can enable rendering and interacting with large geospatial datasets -in the browser without requiring data to be pre-tiled and tiles to be served from a server. - -| Source | Characteristic | -| -------------- | ---------------------------------------------------- | -| File Extension | N/A - Any table with geometries | -| File Type | Binary Archive | -| File Format | [Mapbox Vector Tiles](/docs/modules/mvt/formats/mvt) | -| Data Format | GeoJSON | - -Features: - -- **Visualize bigger datasets** - Useful for datasets in the "mid-size" range (perhaps from 100MB-1GB), where the dataset is "small" enough to be fully loaded into the browser, -but is big enough that rendering the entire dataset every frame is too slow. -- **`MVTLoader` compatibility*** - The resulting tiles conform to the output of the [`MVTLoader`](./mvt-loader) -(which loads pre-tiled tiles into GeoJSON format). -- **Geometry simplification** - The geometry content in the generated tiles -is cut out from the larger input GeoJSON, and optimized further to only -retain the minimum level of detail appropriate for each zoom level -(shapes are simplified and tiny polygons and line segments are filtered out). - - - -### Install - -```sh -npm install @loaders.gl/mvt -``` - -Or just import via a browser script tag: - -```html - -``` - -### Usage - -```typescript -import {TableTileSource} from '@loaders.gl/mvt'; -import {GeoJSONLoader} from '@loaders.gl/json'; - -// build an initial index of tiles. Convieniently, -const tileSource = new TableTileSource(load(url, GeoJSONLoader)); - -// request a particular tile -const features = tileSource.getTile(z, x, y).features; -``` - -## Output Format - -The tiles are in geojson table format. - -## Options - -You can fine-tune the results with an options object, -although the defaults are sensible and work well for most use cases. - -| Option | Default | Description | -| ---------------- | --------- | -------------------------------------------------------------------- | -| `coordinates` | `'wgs84'` | Set to`'local'` to return tile-relative coordinates [`0-1`]. | -| `maxZoom` | `14` | Max zoom to preserve detail on; can't be higher than 24 | -| `generateId` | `false` | Whether to generate feature ids. | -| `promoteId` | N/A | Name of a feature property to use for feature.id. | -| `tolerance` | `3` | Simplification tolerance (higher means simpler) | -| `indexMaxZoom` | `5` | Max zoom in the initial tile index | -| `indexMaxPoints` | `100000` | Max number of points per tile in the index | -| `debug` | `0` | Logging level (0 to disable, 1 or 2) | -| `lineMetrics` | `false` | Enable line metrics tracking for LineString/MultiLineString features | -| `extent` | `4096` | tile extent (both width and height) | -| `buffer` | `64` | Tile buffer on each side | - - -```typescript -import {TableTileSource} from '@loaders.gl/mvt` -const tileSource = new TableTileSource(parsedGeojson, { - maxZoom: 14, // max zoom to preserve detail on; can't be higher than 24 - tolerance: 3, // simplification tolerance (higher means simpler) - debug: 0, // logging level (0 to disable, 1 or 2) - lineMetrics: false, // whether to enable line metrics tracking for LineString/MultiLineString features - promoteId: null, // name of a feature property to promote to feature.id. Cannot be used with `generateId` - generateId: false, // whether to generate feature ids. Cannot be used with `promoteId` - indexMaxZoom: 5, // max zoom in the initial tile index - indexMaxPoints: 100000, // max number of points per tile in the index - extent: 4096, // tile extent (both width and height) - buffer: 64, // tile buffer on each side -}); -``` - -Remarks: - -- `generateId` and `promoteId` options cannot both be specified at the same time. -- `generateId` and `promoteId` options ignore existing `id` values on the feature objects. -- By default, tiles at zoom levels above `indexMaxZoom` are generated on the fly, but you can pre-generate all possible tiles for `data` by setting `indexMaxZoom` and `maxZoom` to the same value, setting `indexMaxPoints` to `0`. -- `TableTileSource` only generates tiles zoom levels up to 24. - - -## Methods - -### constructor - -```ts -new TableTileSource(geojson: GeoJSONTable | Promise); -``` - - -## Attribution - -Includes a fork of Mapbox / Vladimir Agafonkin's [geojson-vt](https://github.com/mapbox/geojson-vt) module which is under ISC License. diff --git a/docs/whats-new.mdx b/docs/whats-new.mdx index 8817a52ca4..c2c7ebeda9 100644 --- a/docs/whats-new.mdx +++ b/docs/whats-new.mdx @@ -2,9 +2,27 @@ ## v4.3 (in development) +Target Release Date: June 2024 + +A minor release that includes: + +- **[`Source`](/docs/developer-guide/using-sources) support** - Improvements for multi-step data loading. +- **examples** - modernized to latest React and minimized boilerplate code. +- **website** - more format examples are now available. + +**@loaders.gl/core** + +- [`createDataSource`](/docs/modules/core/api-reference/create-data-source) - Create a `DataSource` from a list of `Source` objects. +- [`selectSource`](/docs/modules/core/api-reference/select-source) - Select the appropriate `Source` from a list of `Source` objects. + **@loaders.gl/mvt** -- `TableTileSource` - tables can be tiled dynamically in the browser for better rendering performance. +- [`TableTileSource`](/docs/modules/mvt/api-reference/table-tile-source) - tables can now be vector tiled dynamically in the app. + +**@loaders.gl/textures** + +- [`Comp[ressedTextureLoader]`](/docs/modules/textures/api-reference/compressed-texture-loader) - Now supports mipmaps in KTX2 textures. + ## v4.2 diff --git a/modules/mvt/test/index.ts b/modules/mvt/test/index.ts index 1e2bd52573..364f279fcc 100644 --- a/modules/mvt/test/index.ts +++ b/modules/mvt/test/index.ts @@ -5,9 +5,9 @@ // geojson-vt import './lib/vector-tiler/clip-features.spec'; import './lib/vector-tiler/simplify-path.spec'; -// './get-tile.spec.ts' Was used as basis for geojson-tile-source.spec -// './full.spec' Was used as basis for geojson-tile-source-full.spec -// './multi-world.spec' Was used as basis for geojson-tile-source-multi-world.spec +// './get-tile.spec.ts' Was used as basis for table-tile-source.spec +// './full.spec' Was used as basis for table-tile-source-full.spec +// './multi-world.spec' Was used as basis for table-tile-source-multi-world.spec import './lib/utils/geometry-utils.spec';