From 2b9c1727d271883e4ab86826b01c087aa5df9b4f Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Tue, 22 Sep 2026 09:23:03 +0200 Subject: [PATCH 1/4] Add 'bands' as a name-based alternative to 'bidx' and deprecate 'bidx' in documentation --- CHANGELOG.md | 12 ++++++++++++ README.md | 27 ++++++++++++++++++++++++++- json-schema/schema.json | 12 ++++++++++++ 3 files changed, 50 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b7a6d4..072f3f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- Add `bands`, a name-based alternative to `bidx` that references a `name` from the asset's `eo:bands`, + `raster:bands`, or the STAC 1.1+ common `bands` construct, resolving the ambiguity over whether a band + reference must correspond to STAC band metadata ([#18](https://github.com/stac-extensions/render/issues/18)) + +### Deprecated + +- `bidx` is deprecated in favor of `bands`, and is now documented as a 1-based index (matching the + GDAL/rio-tiler/titiler convention) with no required correspondence to any STAC band metadata + ([#18](https://github.com/stac-extensions/render/issues/18)) + ### Fixed - Document that `expression` accepts `string`, `object`, or `array`, matching the schema ([#8](https://github.com/stac-extensions/render/issues/8)) diff --git a/README.md b/README.md index a919f80..26fed15 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,8 @@ The fields in the table below can be used in these parts of STAC documents: | resampling | string | Resampling algorithm to apply to the referenced assets. See [GDAL resampling algorithm](https://gdal.org/programs/gdalwarp.html#cmdoption-gdalwarp-r) for some examples. | | expression | string, object, array | Band arithmetic formula to apply to the referenced assets. The format is defined by the rendering application, e.g. a [TiTiler](https://developmentseed.org/titiler/) band math string or a [MapLibre](https://maplibre.org/maplibre-style-spec/expressions/) style expression array. | | minmax_zoom | \[int] | Zoom levels range applicable for the visualization | +| bidx | \[int] | **Deprecated**, use `bands` instead. 1-based band indexes into the referenced assets (matching the GDAL/rio-tiler/titiler convention), with no required correspondence to any band metadata. See [Band references](#band-references). | +| bands | \[string] | Band names to use for the rendering, one per referenced asset's band. Each name MUST match the `name` of a Band Object declared on the corresponding asset (via `eo:bands`, `raster:bands`, or the STAC [common `bands`](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) construct). Preferred over `bidx`. See [Band references](#band-references). | The `render` object is open ended, so additional fields can be provided according to the needs of the rendering application. @@ -69,6 +71,29 @@ the second the green band and the third the blue band. "assets": [ "red", "green", "blue" ] ``` +## Band references + +When one of the referenced `assets` is itself a multi-band raster, `bidx` or `bands` selects which band(s) of +that asset to use. + +`bidx` is **deprecated** because it indexes directly into the underlying raster file +and has no required correspondence to any STAC band metadata — a `bidx` value is only meaningful if you already +know how the file's bands are physically ordered. + +`bands` replaces it with a name-based reference: each entry MUST match the `name` of a +[Band Object](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) declared +on the corresponding asset, whether via that asset's `eo:bands`, `raster:bands`, or the STAC 1.1+ common +`bands` construct (all three use the same `name` property). This ties the reference to metadata already present +in the Item or Asset, rather than to an implementation's internal band ordering. + +```json +"assets": [ "COG" ], +"bands": [ "red", "nir" ] +``` + +A renderer that only accepts a numeric band index (e.g. titiler's `bidx`) resolves a `bands` name to one by +looking up its position in the referenced asset's band metadata. + ## Rescaling A rescaling of the values from the source asset(s) to the destination asset can be defined using the `vrt:rescale` field. @@ -113,7 +138,7 @@ by simply specifying the `url` and `assets` query parameters. | `colormap` | `colormap` | Color map JSON definition as defined in `colormap` object of the `asset` (overrides `colormap_name` if present ) | | `color_formula` | `color_formula` | Color formula as defined in `color_formula` field of the `asset` | | `resampling` | `resampling` | Resampling method to use when reprojecting the raster. | -| `bidx` | `bidx` | Dataset band indexes | +| `bidx` | `bidx` (deprecated), or `bands` resolved to a 1-based index via the asset's band metadata | Dataset band indexes. See [Band references](#band-references). | #### Shortwave Infra-red visual thermal signature example diff --git a/json-schema/schema.json b/json-schema/schema.json index 889c1f9..1da095a 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -210,6 +210,12 @@ "required": [ "bidx" ] + }, + { + "type": "object", + "required": [ + "bands" + ] } ] }, @@ -270,6 +276,12 @@ "items": { "type": "number" } + }, + "bands": { + "type": "array", + "items": { + "type": "string" + } } }, "additionalProperties": true From 01002d971741e59b5e758404f3930b202cf07961 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Tue, 22 Sep 2026 09:36:14 +0200 Subject: [PATCH 2/4] Update CHANGELOG, README, and JSON schema to support 'bands' and add Planet example --- CHANGELOG.md | 6 +- README.md | 56 +++++++++---- examples/item-landsat8.json | 10 +-- examples/item-planet.json | 152 ++++++++++++++++++++++++++++++++++++ json-schema/schema.json | 5 +- 5 files changed, 203 insertions(+), 26 deletions(-) create mode 100644 examples/item-planet.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 072f3f3..f826a66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add `bands`, a name-based alternative to `bidx` that references a `name` from the asset's `eo:bands`, `raster:bands`, or the STAC 1.1+ common `bands` construct, resolving the ambiguity over whether a band - reference must correspond to STAC band metadata ([#18](https://github.com/stac-extensions/render/issues/18)) + reference must correspond to STAC band metadata. Structured as one array per position in `assets`, so a + band selection can be tied unambiguously to a specific asset when there is more than one + ([#18](https://github.com/stac-extensions/render/issues/18)) +- Add a Planet example (`examples/item-planet.json`), demonstrating `bands` on a genuine single multi-band + asset (PlanetScope's 8-band analytic product), using STAC 1.1.0's common `bands` construct ### Deprecated diff --git a/README.md b/README.md index 26fed15..dd6ec30 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Rendering extension aims at providings consumers with the possible rendering of - Examples: - [Landsat-8 example](examples/item-landsat8.json): Shows the basic usage of the extension in a landsat-8 STAC Item - [Sentinel-2 example](examples/item-sentinel2.json): Shows the basic usage of the extension in a Sentinel-2 STAC Item + - [Planet example](examples/item-planet.json): Shows `bands` selecting named bands from a single multi-band asset - [Collection example](examples/collection.json): Shows the basic usage of the extension in a collection - [JSON Schema](json-schema/schema.json) - [Changelog](./CHANGELOG.md) @@ -47,7 +48,7 @@ The fields in the table below can be used in these parts of STAC documents: | expression | string, object, array | Band arithmetic formula to apply to the referenced assets. The format is defined by the rendering application, e.g. a [TiTiler](https://developmentseed.org/titiler/) band math string or a [MapLibre](https://maplibre.org/maplibre-style-spec/expressions/) style expression array. | | minmax_zoom | \[int] | Zoom levels range applicable for the visualization | | bidx | \[int] | **Deprecated**, use `bands` instead. 1-based band indexes into the referenced assets (matching the GDAL/rio-tiler/titiler convention), with no required correspondence to any band metadata. See [Band references](#band-references). | -| bands | \[string] | Band names to use for the rendering, one per referenced asset's band. Each name MUST match the `name` of a Band Object declared on the corresponding asset (via `eo:bands`, `raster:bands`, or the STAC [common `bands`](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) construct). Preferred over `bidx`. See [Band references](#band-references). | +| bands | \[\[string]] | Band names to select from each referenced asset. One entry per position in `assets` (an asset that needs no sub-selection uses an empty array `[]`); each name MUST match the `name` of a Band Object declared on that asset (via `eo:bands`, `raster:bands`, or the STAC [common `bands`](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) construct). Preferred over `bidx`. See [Band references](#band-references). | The `render` object is open ended, so additional fields can be provided according to the needs of the rendering application. @@ -73,26 +74,51 @@ the second the green band and the third the blue band. ## Band references -When one of the referenced `assets` is itself a multi-band raster, `bidx` or `bands` selects which band(s) of -that asset to use. +When one or more of the referenced `assets` is itself a multi-band raster, `bidx` or `bands` selects which +band(s) of each asset to use. -`bidx` is **deprecated** because it indexes directly into the underlying raster file -and has no required correspondence to any STAC band metadata — a `bidx` value is only meaningful if you already -know how the file's bands are physically ordered. +`bidx` is **deprecated**. Beyond indexing directly into the underlying raster file with no required +correspondence to any STAC band metadata, it never specified how to relate its values back to more than one +asset at a time, which is exactly the ambiguity `bands` is designed to resolve. -`bands` replaces it with a name-based reference: each entry MUST match the `name` of a +`bands` is an array with **one entry per position in `assets`** (`bands.length` MUST equal `assets.length`), +where each entry is itself an array of the band name(s) selected from that asset, in output order. An asset +that needs no sub-selection (e.g. it is already single-band, or all its bands should be used in their existing +order) uses an empty array `[]`. Each band name MUST match the `name` of a [Band Object](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) declared -on the corresponding asset, whether via that asset's `eo:bands`, `raster:bands`, or the STAC 1.1+ common -`bands` construct (all three use the same `name` property). This ties the reference to metadata already present -in the Item or Asset, rather than to an implementation's internal band ordering. +on that asset, whether via its `eo:bands`, `raster:bands`, or the STAC 1.1+ common `bands` construct (all three +use the same `name` property). This ties the reference to metadata already present in the Item or Asset, rather +than to an implementation's internal band ordering. Note that JSON Schema cannot enforce the +`bands.length == assets.length` rule itself; it is a MUST, not a validated constraint. ```json -"assets": [ "COG" ], -"bands": [ "red", "nir" ] +"assets": [ "B04", "stacked" ], +"bands": [ [], [ "red", "nir" ] ] ``` -A renderer that only accepts a numeric band index (e.g. titiler's `bidx`) resolves a `bands` name to one by -looking up its position in the referenced asset's band metadata. +Here, `B04` is used as-is (empty array: no sub-selection needed), while two bands, `red` and `nir`, are +selected from the multi-band `stacked` asset, in that order. + +See the [Planet example](examples/item-planet.json) for a realistic case: PlanetScope's 8-band analytic +product is delivered as a single multi-band GeoTIFF asset (unlike Sentinel-2/Landsat-8, which split each band +into its own asset), so `bands` is the only way to select, say, a true-color RGB composite from it: + +```json +"assets": [ "analytic" ], +"bands": [ [ "red", "green", "blue" ] ] +``` + +A renderer that only accepts a numeric, per-asset band index (e.g. titiler's inline +`assets=|bidx=,` syntax) resolves each `bands` name to a 1-based index by looking up its +position in that asset's own band metadata: + +```text +assets=B04&assets=stacked|bidx=3,5 +``` + +(assuming `red` and `nir` are, respectively, the 3rd and 5th band declared on the `stacked` asset). Titiler +also accepts an inline `|bands=,` option; consult the target renderer's documentation for +whether it can resolve band names directly, or whether a client must perform this lookup itself. ## Rescaling @@ -138,7 +164,7 @@ by simply specifying the `url` and `assets` query parameters. | `colormap` | `colormap` | Color map JSON definition as defined in `colormap` object of the `asset` (overrides `colormap_name` if present ) | | `color_formula` | `color_formula` | Color formula as defined in `color_formula` field of the `asset` | | `resampling` | `resampling` | Resampling method to use when reprojecting the raster. | -| `bidx` | `bidx` (deprecated), or `bands` resolved to a 1-based index via the asset's band metadata | Dataset band indexes. See [Band references](#band-references). | +| `assets=\|bidx=,` (or the legacy `bidx` param) | `bidx` (deprecated), or `bands` resolved to a 1-based index via the asset's band metadata | Per-asset dataset band indexes. See [Band references](#band-references). | #### Shortwave Infra-red visual thermal signature example diff --git a/examples/item-landsat8.json b/examples/item-landsat8.json index e1e8b60..9a2d1f8 100644 --- a/examples/item-landsat8.json +++ b/examples/item-landsat8.json @@ -48,16 +48,8 @@ ], "colormap_name": "rainbow", "resampling": "bilinear", - "bidx": [ - 1 - ], "width": 1024, - "height": 1024, - "bands": [ - "B4", - "B3", - "B2" - ] + "height": 1024 }, "ndvi": { "title": "Normalized Difference Vegetation Index", diff --git a/examples/item-planet.json b/examples/item-planet.json new file mode 100644 index 0000000..828035b --- /dev/null +++ b/examples/item-planet.json @@ -0,0 +1,152 @@ +{ + "type": "Feature", + "stac_version": "1.1.0", + "stac_extensions": [ + "https://stac-extensions.github.io/render/v2.0.0/schema.json" + ], + "id": "planet-psscene-8b-example", + "bbox": [ + 4.32, + 50.82, + 4.42, + 50.9 + ], + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + 4.32, + 50.82 + ], + [ + 4.32, + 50.9 + ], + [ + 4.42, + 50.9 + ], + [ + 4.42, + 50.82 + ], + [ + 4.32, + 50.82 + ] + ] + ] + }, + "properties": { + "datetime": "2024-06-01T10:30:00Z", + "platform": "PlanetScope", + "instruments": [ + "PSB.SD" + ], + "gsd": 3, + "renders": { + "true-color": { + "title": "True color composite", + "assets": [ + "analytic" + ], + "bands": [ + [ + "red", + "green", + "blue" + ] + ], + "rescale": [ + [ + 0, + 10000 + ], + [ + 0, + 10000 + ], + [ + 0, + 10000 + ] + ], + "resampling": "bilinear" + }, + "false-color": { + "title": "False color (NIR-Red-Green) composite", + "assets": [ + "analytic" + ], + "bands": [ + [ + "nir", + "red", + "green" + ] + ], + "rescale": [ + [ + 0, + 10000 + ], + [ + 0, + 10000 + ], + [ + 0, + 10000 + ] + ], + "resampling": "bilinear" + } + } + }, + "links": [], + "assets": { + "analytic": { + "title": "8-band analytic surface reflectance", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "roles": [ + "data" + ], + "href": "https://example.com/data/planet/psscene_8b_analytic.tif", + "bands": [ + { + "name": "coastal", + "description": "Coastal Blue, 431-452nm" + }, + { + "name": "blue", + "description": "Blue, 465-515nm" + }, + { + "name": "green05", + "description": "Green I, 513-549nm" + }, + { + "name": "green", + "description": "Green, 547-583nm" + }, + { + "name": "yellow", + "description": "Yellow, 600-620nm" + }, + { + "name": "red", + "description": "Red, 650-680nm" + }, + { + "name": "rededge", + "description": "Red Edge, 697-713nm" + }, + { + "name": "nir", + "description": "Near-Infrared, 845-885nm" + } + ] + } + } +} \ No newline at end of file diff --git a/json-schema/schema.json b/json-schema/schema.json index 1da095a..6606957 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -280,7 +280,10 @@ "bands": { "type": "array", "items": { - "type": "string" + "type": "array", + "items": { + "type": "string" + } } } }, From ce73dd41c564d4f7616c0fb1e719471f96bbe8b7 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Wed, 23 Sep 2026 07:46:03 +0200 Subject: [PATCH 3/4] Update CHANGELOG, README, examples, and schema to support 'bidx' as a name-based selector for bands --- CHANGELOG.md | 20 +++++--------- README.md | 55 +++++++++++++++++++++------------------ examples/item-planet.json | 34 ++++++++++++------------ json-schema/schema.json | 14 +--------- 4 files changed, 55 insertions(+), 68 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f826a66..5099bb3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,19 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Add `bands`, a name-based alternative to `bidx` that references a `name` from the asset's `eo:bands`, - `raster:bands`, or the STAC 1.1+ common `bands` construct, resolving the ambiguity over whether a band - reference must correspond to STAC band metadata. Structured as one array per position in `assets`, so a - band selection can be tied unambiguously to a specific asset when there is more than one - ([#18](https://github.com/stac-extensions/render/issues/18)) -- Add a Planet example (`examples/item-planet.json`), demonstrating `bands` on a genuine single multi-band - asset (PlanetScope's 8-band analytic product), using STAC 1.1.0's common `bands` construct - -### Deprecated - -- `bidx` is deprecated in favor of `bands`, and is now documented as a 1-based index (matching the - GDAL/rio-tiler/titiler convention) with no required correspondence to any STAC band metadata - ([#18](https://github.com/stac-extensions/render/issues/18)) +- Extend `bidx` to accept a band name (matching the `name` of a Band Object declared on the asset via + `eo:bands`, `raster:bands`, or the STAC 1.1+ common `bands` construct) alongside a 1-based index, and + restructure it as one array per position in `assets`, so a band selection can be tied unambiguously to a + specific asset when there is more than one. Documents `bidx`'s indexing convention, which was previously + unspecified ([#18](https://github.com/stac-extensions/render/issues/18)) +- Add a Planet example (`examples/item-planet.json`), demonstrating `bidx` name-based selectors on a genuine + single multi-band asset (PlanetScope's 8-band analytic product), using STAC 1.1.0's common `bands` construct ### Fixed diff --git a/README.md b/README.md index dd6ec30..f4a059d 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Rendering extension aims at providings consumers with the possible rendering of - Examples: - [Landsat-8 example](examples/item-landsat8.json): Shows the basic usage of the extension in a landsat-8 STAC Item - [Sentinel-2 example](examples/item-sentinel2.json): Shows the basic usage of the extension in a Sentinel-2 STAC Item - - [Planet example](examples/item-planet.json): Shows `bands` selecting named bands from a single multi-band asset + - [Planet example](examples/item-planet.json): Shows `bidx` selecting named bands from a single multi-band asset - [Collection example](examples/collection.json): Shows the basic usage of the extension in a collection - [JSON Schema](json-schema/schema.json) - [Changelog](./CHANGELOG.md) @@ -47,8 +47,7 @@ The fields in the table below can be used in these parts of STAC documents: | resampling | string | Resampling algorithm to apply to the referenced assets. See [GDAL resampling algorithm](https://gdal.org/programs/gdalwarp.html#cmdoption-gdalwarp-r) for some examples. | | expression | string, object, array | Band arithmetic formula to apply to the referenced assets. The format is defined by the rendering application, e.g. a [TiTiler](https://developmentseed.org/titiler/) band math string or a [MapLibre](https://maplibre.org/maplibre-style-spec/expressions/) style expression array. | | minmax_zoom | \[int] | Zoom levels range applicable for the visualization | -| bidx | \[int] | **Deprecated**, use `bands` instead. 1-based band indexes into the referenced assets (matching the GDAL/rio-tiler/titiler convention), with no required correspondence to any band metadata. See [Band references](#band-references). | -| bands | \[\[string]] | Band names to select from each referenced asset. One entry per position in `assets` (an asset that needs no sub-selection uses an empty array `[]`); each name MUST match the `name` of a Band Object declared on that asset (via `eo:bands`, `raster:bands`, or the STAC [common `bands`](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) construct). Preferred over `bidx`. See [Band references](#band-references). | +| bidx | \[\[int, string]] | Band(s) to select from each referenced asset, one entry per position in `assets` (an asset needing no sub-selection uses an empty array `[]`). Each selector is either a 1-based band index (matching the GDAL/rio-tiler/titiler convention) or a band name matching the `name` of a Band Object declared on that asset (via `eo:bands`, `raster:bands`, or the STAC [common `bands`](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) construct) — useful since `name` is not required on a Band Object. See [Band references](#band-references). | The `render` object is open ended, so additional fields can be provided according to the needs of the rendering application. @@ -74,43 +73,49 @@ the second the green band and the third the blue band. ## Band references -When one or more of the referenced `assets` is itself a multi-band raster, `bidx` or `bands` selects which -band(s) of each asset to use. +When one or more of the referenced `assets` is itself a multi-band raster, `bidx` selects which band(s) of +each asset to use. -`bidx` is **deprecated**. Beyond indexing directly into the underlying raster file with no required -correspondence to any STAC band metadata, it never specified how to relate its values back to more than one -asset at a time, which is exactly the ambiguity `bands` is designed to resolve. +`bidx` is an array with **one entry per position in `assets`** (`bidx.length` MUST equal `assets.length`), +where each entry is itself an array of the band selector(s) for that asset, in output order. An asset that +needs no sub-selection (e.g. it is already single-band, or all its bands should be used in their existing +order) uses an empty array `[]`. Note that JSON Schema cannot enforce the `bidx.length == assets.length` rule +itself; it is a MUST, not a validated constraint. -`bands` is an array with **one entry per position in `assets`** (`bands.length` MUST equal `assets.length`), -where each entry is itself an array of the band name(s) selected from that asset, in output order. An asset -that needs no sub-selection (e.g. it is already single-band, or all its bands should be used in their existing -order) uses an empty array `[]`. Each band name MUST match the `name` of a -[Band Object](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) declared -on that asset, whether via its `eo:bands`, `raster:bands`, or the STAC 1.1+ common `bands` construct (all three -use the same `name` property). This ties the reference to metadata already present in the Item or Asset, rather -than to an implementation's internal band ordering. Note that JSON Schema cannot enforce the -`bands.length == assets.length` rule itself; it is a MUST, not a validated constraint. +Each selector is either: + +- a 1-based band index (matching the GDAL/rio-tiler/titiler convention: the first band is `1`, not `0`), with + no required correspondence to any STAC band metadata — only meaningful if you already know how that asset's + bands are physically ordered; or +- a band name, which MUST match the `name` of a + [Band Object](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) + declared on that asset, whether via its `eo:bands`, `raster:bands`, or the STAC 1.1+ common `bands` + construct (all three use the same `name` property). This ties the reference to metadata already present in + the Item or Asset, rather than to an implementation's internal band ordering. Since `name` is not a required + property of a Band Object, a name-based selector is only usable when the asset's bands actually declare one + — fall back to an index otherwise. ```json "assets": [ "B04", "stacked" ], -"bands": [ [], [ "red", "nir" ] ] +"bidx": [ [], [ 3, "nir" ] ] ``` -Here, `B04` is used as-is (empty array: no sub-selection needed), while two bands, `red` and `nir`, are -selected from the multi-band `stacked` asset, in that order. +Here, `B04` is used as-is (empty array: no sub-selection needed), while two bands are selected from the +multi-band `stacked` asset: its 3rd band by index, and the band named `nir`. See the [Planet example](examples/item-planet.json) for a realistic case: PlanetScope's 8-band analytic product is delivered as a single multi-band GeoTIFF asset (unlike Sentinel-2/Landsat-8, which split each band -into its own asset), so `bands` is the only way to select, say, a true-color RGB composite from it: +into its own asset), so `bidx` is the only way to select, say, a true-color RGB composite from it: ```json "assets": [ "analytic" ], -"bands": [ [ "red", "green", "blue" ] ] +"bidx": [ [ "red", "green", "blue" ] ] ``` A renderer that only accepts a numeric, per-asset band index (e.g. titiler's inline -`assets=|bidx=,` syntax) resolves each `bands` name to a 1-based index by looking up its -position in that asset's own band metadata: +`assets=|bidx=,` syntax, which replaced its older flat, non-per-asset `bidx` query parameter for +the same reason `bidx` here is now per-asset) resolves a name-based selector to a 1-based index by looking up +its position in that asset's own band metadata: ```text assets=B04&assets=stacked|bidx=3,5 @@ -164,7 +169,7 @@ by simply specifying the `url` and `assets` query parameters. | `colormap` | `colormap` | Color map JSON definition as defined in `colormap` object of the `asset` (overrides `colormap_name` if present ) | | `color_formula` | `color_formula` | Color formula as defined in `color_formula` field of the `asset` | | `resampling` | `resampling` | Resampling method to use when reprojecting the raster. | -| `assets=\|bidx=,` (or the legacy `bidx` param) | `bidx` (deprecated), or `bands` resolved to a 1-based index via the asset's band metadata | Per-asset dataset band indexes. See [Band references](#band-references). | +| `assets=\|bidx=,` (or the legacy `bidx` param) | `bidx`, resolving any name-based selector to a 1-based index via the asset's band metadata | Per-asset dataset band indexes. See [Band references](#band-references). | #### Shortwave Infra-red visual thermal signature example diff --git a/examples/item-planet.json b/examples/item-planet.json index 828035b..12b139e 100644 --- a/examples/item-planet.json +++ b/examples/item-planet.json @@ -51,13 +51,6 @@ "assets": [ "analytic" ], - "bands": [ - [ - "red", - "green", - "blue" - ] - ], "rescale": [ [ 0, @@ -72,20 +65,20 @@ 10000 ] ], - "resampling": "bilinear" + "resampling": "bilinear", + "bidx": [ + [ + "red", + "green", + "blue" + ] + ] }, "false-color": { "title": "False color (NIR-Red-Green) composite", "assets": [ "analytic" ], - "bands": [ - [ - "nir", - "red", - "green" - ] - ], "rescale": [ [ 0, @@ -100,7 +93,14 @@ 10000 ] ], - "resampling": "bilinear" + "resampling": "bilinear", + "bidx": [ + [ + "nir", + "red", + "green" + ] + ] } } }, @@ -149,4 +149,4 @@ ] } } -} \ No newline at end of file +} diff --git a/json-schema/schema.json b/json-schema/schema.json index 6606957..1a91808 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -210,12 +210,6 @@ "required": [ "bidx" ] - }, - { - "type": "object", - "required": [ - "bands" - ] } ] }, @@ -272,17 +266,11 @@ } }, "bidx": { - "type": "array", - "items": { - "type": "number" - } - }, - "bands": { "type": "array", "items": { "type": "array", "items": { - "type": "string" + "type": ["number", "string"] } } } From 3d5e957f7dce7574e9d05e6cbd6fe6dc780d4b49 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Tue, 6 Oct 2026 14:28:00 -0600 Subject: [PATCH 4/4] fix(schema): update bidx definition to enforce 1-based indexing and support string band names --- CHANGELOG.md | 16 ++++++++++++---- README.md | 15 ++++++++++++--- json-schema/schema.json | 11 ++++++++++- 3 files changed, 34 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cfcf4d2..6dfa3e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,13 +6,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- **Breaking:** `bidx` is now an array of arrays, with one inner array per position in `assets`, so a band + selection can be tied unambiguously to a specific asset when there is more than one. The previous flat array + of numbers (e.g. `"bidx": [1]`) is no longer valid; migrate it to `"bidx": [[1]]` for a single asset, or to + one inner array per asset (use `[]` for an asset that needs no sub-selection) + ([#18](https://github.com/stac-extensions/render/issues/18)) +- `bidx` index selectors are now documented and validated as 1-based integers (`minimum: 1`), matching the + GDAL/rio-tiler/titiler convention ([#18](https://github.com/stac-extensions/render/issues/18)) + ### Added - Extend `bidx` to accept a band name (matching the `name` of a Band Object declared on the asset via - `eo:bands`, `raster:bands`, or the STAC 1.1+ common `bands` construct) alongside a 1-based index, and - restructure it as one array per position in `assets`, so a band selection can be tied unambiguously to a - specific asset when there is more than one. Documents `bidx`'s indexing convention, which was previously - unspecified ([#18](https://github.com/stac-extensions/render/issues/18)) + `eo:bands`, `raster:bands`, or the STAC 1.1+ common `bands` construct) as an alternative to a 1-based index + ([#18](https://github.com/stac-extensions/render/issues/18)) - Add a Planet example (`examples/item-planet.json`), demonstrating `bidx` name-based selectors on a genuine single multi-band asset (PlanetScope's 8-band analytic product), using STAC 1.1.0's common `bands` construct diff --git a/README.md b/README.md index 4ad3acc..684330a 100644 --- a/README.md +++ b/README.md @@ -85,9 +85,9 @@ itself; it is a MUST, not a validated constraint. Each selector is either: -- a 1-based band index (matching the GDAL/rio-tiler/titiler convention: the first band is `1`, not `0`), with - no required correspondence to any STAC band metadata — only meaningful if you already know how that asset's - bands are physically ordered; or +- a 1-based band index (an integer `>= 1`, matching the GDAL/rio-tiler/titiler convention), with no required + correspondence to any STAC band metadata — only meaningful if you already know how that asset's bands are + physically ordered; or - a band name, which MUST match the `name` of a [Band Object](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md#bands) declared on that asset, whether via its `eo:bands`, `raster:bands`, or the STAC 1.1+ common `bands` @@ -104,6 +104,15 @@ Each selector is either: Here, `B04` is used as-is (empty array: no sub-selection needed), while two bands are selected from the multi-band `stacked` asset: its 3rd band by index, and the band named `nir`. +> **Warning:** +> Band indexes are **1-based**: the first band of an asset is `1`, not `0`. This is different from the +> 0-based position of a Band Object in the asset's `bands` array. Thus, the band at `bands[2]` has the index +> `3`. The JSON Schema rejects `0`, but it cannot detect an off-by-one error for other values. + +In v2.x and earlier, `bidx` was a flat array of numbers (e.g. `"bidx": [1]`) that was not tied to a specific +asset. This form is no longer valid. Change it to one inner array per asset, e.g. `"bidx": [[1]]` for a single +asset. + See the [Planet example](examples/item-planet.json) for a realistic case: PlanetScope's 8-band analytic product is delivered as a single multi-band GeoTIFF asset (unlike Sentinel-2/Landsat-8, which split each band into its own asset), so `bidx` is the only way to select, say, a true-color RGB composite from it: diff --git a/json-schema/schema.json b/json-schema/schema.json index 49ff32f..eaebd12 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -276,7 +276,16 @@ "items": { "type": "array", "items": { - "type": ["number", "string"] + "oneOf": [ + { + "type": "integer", + "minimum": 1 + }, + { + "type": "string", + "minLength": 1 + } + ] } } },