Skip to content

Commit

Permalink
Update to use STAC 1.1 bands (#45)
Browse files Browse the repository at this point in the history 
* update field names

* update scale and offset examples and fix KaTeX formulas

* updated CHANGELOG

* update items using bands instead of raster:bands

* update CHANGELOG

* updaed schema to use STAC 1.1 bands

* Revert "update scale and offset examples and fix KaTeX formulas"

This reverts commit 24c3e48.

* Fix examples and schema

* Simplify examples

* Update README and Changelog

* Update version number of eo extension

---------

Co-authored-by: Matthias Mohr <webmaster@mamo-net.de>
  • Loading branch information
@matthewhanson @m-mohr
matthewhanson and m-mohr authored Aug 1, 2024
1 parent 9187cf2 commit 5e1f010
Show file tree
Hide file tree
Showing 5 changed files with 374 additions and 733 deletions.
20 changes: 18 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
Expand All @@ -8,11 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- Add link `rel="gcps"` to Ground Control Points document
- Add link relation type `gcps` for Ground Control Points documents
- `raster:sampling`, `raster:bits_per_sample`, `raster:spatial_resolution`, `raster:scale`, `raster:offset` and `raster:histogram`
can be used in Assets and Item Properties

### Changed

- Some clarifications abd fixes in the README and examples [#41](https://github.com/stac-extensions/raster/pull/41)
- Some clarifications and fixes in the README and examples [#41](https://github.com/stac-extensions/raster/pull/41)
- `raster:bands` is now using the more general `bands` construct from STAC common metadata
- The following fields in the Band Object have been moved/renamed:
- `nodata`, `data_type`, `statistics` and `unit` were *not* renamed, but have been moved to STAC common metadata
- `sampling` has been renamed to `raster:sampling`
- `bits_per_sample` has been renamed to `raster:bits_per_sample`
- `spatial_resolution` has been renamed to `raster:spatial_resolution`
- `scale` has been renamed to `raster:scale`
- `offset` has been renamed to `raster:offset`
- `histogram` has been renamed to `raster:histogram`

### Removed

- `raster:bands` - use `bands` in instead

## [v1.1.0]

Expand Down
87 changes: 23 additions & 64 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
This document explains the Raster Extension to the [SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification.

An item can describe assets that are rasters of one or multiple bands with some information common to them all (raster size, projection)
and also specific to each of them (data type, unit, number of bits used, nodata).
and also specific to each of them (number of bits used).
A raster is often strongly linked with the georeferencing transform and coordinate system definition
of all bands (using the [projection extension](https://github.com/radiantearth/stac-spec/tree/master/extensions/projection)).
In many applications, it is interesting to have some metadata about the rasters in the asset (values statistics, value interpretation, transforms).
Expand All @@ -21,72 +21,31 @@ In many applications, it is interesting to have some metadata about the rasters
- [JSON Schema](json-schema/schema.json)
- [Changelog](./CHANGELOG.md)

## Item Asset fields
## Fields

| Field Name | Type | Description |
| ------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| raster:bands | \[[Raster band Object](#raster-band-object)] | An array of available bands where each object is a \[[Band Object](#raster-band-object)]. If given, requires at least one band. |
The fields in the table below can be used in these parts of STAC documents:

## Raster Band Object
- [ ] Catalogs
- [ ] Collections
- [x] Item Properties (incl. Summaries in Collections)
- [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
- [x] Bands
- [ ] Links

When specifying a raster band object at asset level, it is recommended to use
When using the raster extension, it is recommended to use
the [projection](https://github.com/radiantearth/stac-spec/tree/master/extensions/projection) extension
to specify information about the raster projection, especially `proj:shape` to specify the height and width of the raster.

| Field Name | Type | Description |
| ------------------ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| nodata | number\|string | Pixel values used to identify pixels that are nodata in the band either by the pixel value as a number or `nan`, `inf` or `-inf` (all strings). |
| sampling | string | One of `area` or `point`. Indicates whether a pixel value should be assumed to represent a sampling over the region of the pixel or a point sample at the center of the pixel. |
| data_type | string | The data type of the pixels in the band. One of the [data types as described below](#data-types). |
| bits_per_sample | number | The actual number of bits used for this band. Normally only present when the number of bits is non-standard for the `datatype`, such as when a 1 bit TIFF is represented as byte. |
| spatial_resolution | number | Average spatial resolution (in meters) of the pixels in the band. |
| statistics | [Statistics Object](#statistics-object) | Statistics of all the pixels in the band. |
| unit | string | Unit denomination of the pixel value. |
| scale | number | Multiplicator factor of the pixel value to transform into the value (i.e. translate digital number to reflectance). |
| offset | number | Number to be added to the pixel value (after scaling) to transform into the value (i.e. translate digital number to reflectance). |
| histogram | [Histogram Object](#histogram-object) | Histogram distribution information of the pixels values in the band. |

`scale` and `offset` define parameters to compute another value. The following paragraphs describe some use cases.

### Data Types

The data type gives information about the values in the file.
This can be used to indicate the (maximum) range of numerical values expected.
For example `uint8` indicates that the numbers are in a range between 0 and 255,
they can never be smaller or larger. This can help to pick the optimal numerical
data type when reading the files to keep memory consumption low.
Nevertheless, it doesn't necessarily mean that the expected values fill the whole range.
For example, there can be use cases for `uint8` that just use the numbers 0 to 10 for example.
Through other extensions it might be possible to specify an exact value range so
that visualizations can be optimized.
The allowed values for `data_type` are:

- `int8`: 8-bit integer
- `int16`: 16-bit integer
- `int32`: 32-bit integer
- `int64`: 64-bit integer
- `uint8`: unsigned 8-bit integer (common for 8-bit RGB PNG's)
- `uint16`: unsigned 16-bit integer
- `uint32`: unsigned 32-bit integer
- `uint64`: unsigned 64-bit integer
- `float16`: 16-bit float
- `float32`: 32-bit float
- `float64`: 64-big float
- `cint16`: 16-bit complex integer
- `cint32`: 32-bit complex integer
- `cfloat32`: 32-bit complex float
- `cfloat64`: 64-bit complex float
- `other`: Other data type than the ones listed above (e.g. boolean, string, higher precision numbers)

### Statistics Object

| Field Name | Type | Description |
| ------------- | ------ | -------------------------------------------------- |
| mean | number | mean value of all the pixels in the band |
| minimum | number | minimum value of the pixels in the band |
| maximum | number | maximum value of the pixels in the band |
| stddev | number | standard deviation value of the pixels in the band |
| valid_percent | number | percentage of valid (not `nodata`) pixel |
| raster:sampling | string | One of `area` or `point`. Indicates whether a pixel value should be assumed to represent a sampling over the region of the pixel or a point sample at the center of the pixel. |
| raster:bits_per_sample | number | The actual number of bits used for this band. Normally only present when the number of bits is non-standard for the `datatype`, such as when a 1 bit TIFF is represented as byte. |
| raster:spatial_resolution | number | Average spatial resolution (in meters) of the pixels in the band. |
| raster:scale | number | Multiplicator factor of the pixel value to transform into the value (i.e. translate digital number to reflectance). |
| raster:offset | number | Number to be added to the pixel value (after scaling) to transform into the value (i.e. translate digital number to reflectance). |
| raster:histogram | [Histogram Object](#histogram-object) | Histogram distribution information of the pixels values in the band. |

`raster:scale` and `raster:offset` define parameters to compute another value. The following paragraphs describe some use cases.

### Scale and Offset Uses and Examples

Expand Down Expand Up @@ -133,11 +92,11 @@ For example, the above value conversion is described in the values dictionary as
"assets": {
"B4": {
"title": "TOA radiance band 4",
"raster:bands": [{
"bands": [{
"nodata": 0,
"unit": "W⋅sr−1⋅m−2",
"scale": 0.0145,
"offset": 3.48
"raster:scale": 0.0145,
"raster:offset": 3.48
}]
}
}
Expand Down Expand Up @@ -172,9 +131,9 @@ In the following value definition example, 185 meters must be substracted from t
"assets": {
"WaterLevel": {
"title": "Water Level at station",
"raster:bands": [{
"bands": [{
"unit": "m",
"offset": -185
"raster:offset": -185
}]
}
}
Expand Down
92 changes: 35 additions & 57 deletions examples/item-planet.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
"stac_extensions": [
"https://stac-extensions.github.io/sat/v1.0.0/schema.json",
"https://stac-extensions.github.io/view/v1.0.0/schema.json",
"https://stac-extensions.github.io/projection/v1.0.0/schema.json",
"https://stac-extensions.github.io/eo/v1.0.0/schema.json",
"https://stac-extensions.github.io/projection/v1.1.0/schema.json",
"https://stac-extensions.github.io/eo/v2.0.0-beta.1/schema.json",
"https://stac-extensions.github.io/processing/v1.0.0/schema.json",
"https://stac-extensions.github.io/raster/v1.1.0/schema.json"
],
Expand All @@ -16,49 +16,30 @@
"data"
],
"href": "PT01S00_842547E119_8697242018100100000000MS00_GG001002003/PT01S00_842547E119_8697242018100100000000MS00_GG001002003.tif",
"eo:bands": [
{
"name": "band-1",
"common_name": "red",
"center_wavelength": 0.63
},
{
"name": "band-2",
"common_name": "green",
"center_wavelength": 0.545
},
{
"name": "band-3",
"common_name": "blue",
"center_wavelength": 0.485
},
{
"name": "band-4",
"common_name": "nir",
"center_wavelength": 0.82
}
],
"proj:shape": [
8966,
4411
],
"raster:bands": [
"data_type": "uint16",
"nodata": 0,
"raster:sampling": "area",
"raster:spatial_resolution": 3,
"bands": [
{
"sampling": "area",
"name": "Red TOA reflectance",
"data_type": "uint16",
"scale": 0.01,
"offset": 0,
"nodata": 0,
"spatial_resolution": 3,
"name": "band-1",
"description": "Red TOA reflectance",
"statistics": {
"maximum": 32925,
"mean": 8498.9400644319,
"minimum": 1962,
"stddev": 5056.1292002722,
"valid_percent": 61.09
},
"histogram": {
"eo:common_name": "red",
"eo:center_wavelength": 0.63,
"raster:scale": 0.01,
"raster:offset": 0,
"raster:histogram": {
"count": 256,
"min": 1901.288235294118,
"max": 32985.71176470588,
Expand Down Expand Up @@ -323,21 +304,20 @@
}
},
{
"sampling": "area",
"name": "Green TOA reflectance",
"data_type": "uint16",
"scale": 0.0000196236732904,
"offset": 0,
"nodata": 0,
"spatial_resolution": 3,
"name": "band-2",
"description": "Green TOA reflectance",
"statistics": {
"maximum": 22063,
"mean": 7185.2123645206,
"minimum": 3884,
"stddev": 3799.4562788636,
"valid_percent": 61.09
},
"histogram": {
"eo:common_name": "green",
"eo:center_wavelength": 0.545,
"raster:scale": 0.0000196236732904,
"raster:offset": 0,
"raster:histogram": {
"count": 256,
"min": 3848.354901960784,
"max": 22098.64509803921,
Expand Down Expand Up @@ -602,21 +582,20 @@
}
},
{
"sampling": "area",
"name": "Blue TOA reflectance",
"data_type": "uint16",
"scale": 0.0000218499248607,
"offset": 0,
"nodata": 0,
"spatial_resolution": 3,
"name": "band-3",
"description": "Blue TOA reflectance",
"statistics": {
"maximum": 29693,
"mean": 5829.583942362,
"minimum": 1061,
"stddev": 4683.0650025253,
"valid_percent": 61.09
},
"histogram": {
"eo:common_name": "blue",
"eo:center_wavelength": 0.485,
"raster:scale": 0.0000218499248607,
"raster:offset": 0,
"raster:histogram": {
"count": 256,
"min": 1004.858823529412,
"max": 29749.14117647059,
Expand Down Expand Up @@ -881,21 +860,20 @@
}
},
{
"sampling": "area",
"name": "NIR TOA reflectance",
"data_type": "uint16",
"scale": 0.0000218499248607,
"offset": 0,
"nodata": 0,
"spatial_resolution": 3,
"name": "band-4",
"description": "NIR TOA reflectance",
"statistics": {
"maximum": 31836,
"mean": 6785.2511255265,
"minimum": 1685,
"stddev": 3842.4324936707,
"valid_percent": 61.09
},
"histogram": {
"eo:common_name": "nir",
"eo:center_wavelength": 0.82,
"raster:scale": 0.0000218499248607,
"raster:offset": 0,
"raster:histogram": {
"count": 256,
"min": 1625.880392156863,
"max": 31895.11960784314,
Expand Down
Loading

0 comments on commit 5e1f010

Please sign in to comment.