Raster Extension Specification

Title: Raster
Identifier: https://stac-extensions.github.io/raster/v1.1.0/schema.json
Field Name Prefix: raster
Scope: Item, Collection
Extension Maturity Classification: Candidate
Owner: @emmanuelmathot

This document explains the Raster Extension to the SpatioTemporal Asset Catalog (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). A raster is often strongly linked with the georeferencing transform and coordinate system definition of all bands (using the projection extension). In many applications, it is interesting to have some metadata about the rasters in the asset (values statistics, value interpretation, transforms).

Examples:
- Planet Item example: Shows the basic usage of the extension in a STAC Item
- Sentinel-2 Item example: Shows the statistics about individual bands and some RGB composites example
JSON Schema
Changelog

Item Asset fields

Field Name	Type	Description
raster:bands	[Raster band Object]	An array of available bands where each object is a [Band Object]. If given, requires at least one band.

Raster Band Object

When specifying a raster band object at asset level, it is recommended to use the 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.
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 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 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

Use Scale and offset as radiometric calibration parameters

In remote sensing, many imagery raster corresponds to raw data without any radiometric processing. Each pixel is given in digital numbers (DN), i.e. native pixel values from the sensor acquisition. Those digital numbers quantify the energy recorded by the detector (optical or radar). The sensor radiometric calibration aims to turn back the DN value into a physical unit value (radiance, light power, backscatter). Hereafter, some examples of the usage of the values dictionary to perform radiometric correction.

Digital Numbers to Radiance (optical sensor)

A conventional way of deriving Top Of Atmosphere (TOA) Radiance from $\mathrm{DN}$ values using scale and offset in the following formula:

$$L_\lambda=\mathrm{scale}\times\mathrm{DN}+\mathrm{offset}$$

where $L_\lambda$ is TOA Radiance in $\mathrm{W}!\cdot!sr^{-1}!\cdot!m^{-3}$.

For example, the above value conversion is described in the values dictionary as

"assets": {
  "B4": {
      "title": "TOA radiance band 4",
      "raster:bands": [{
        "nodata": 0,
        "unit": "W⋅sr−1⋅m−2",
        "scale": 0.0145,
        "offset": 3.48
      }]
  }
}

Radiance to TOA Reflectance (optical sensor)

In order to convert the above TOA radiance to TOA reflectance, the following formula can be used:

$$R=\frac{pi \times L \times d \times d}{ESUN(b) \times cos(s)}$$

where:

$L$ is the spectral radiance for the band (see previous section)
$d$ is the earth-sun distance (in astronomical units) and depends on the acquisition’s day and month (Core STAC specification)
$ESUN(b)$ is the mean TOA solar irradiance (or solar illumination) in $W/m^2/micrometers$
$s$ is the solar zenith angle in degrees.

source: https://www.orfeo-toolbox.org/CookBook/Applications/app_OpticalCalibration.html

Transform height measurement to water level

In remote sensing, radar altimeter instruments measures an absolute height from an absolute georeference (e.g. WGS 84 geoid). In hydrology, you prefer having the water level relative to the "0 limnimetric scale". Therefore, a usage of the value object here would be to indicate the offset between the reference height 0 of the sensor and the 0 limnimetric scale to compute a water level.

In the following value definition example, 185 meters must be substracted from the pixel value to correspond to the water level.

"assets": {
  "WaterLevel": {
      "title": "Water Level at station",
      "raster:bands": [{
        "unit": "m",
        "offset": -185
      }]
  }
}

Histogram Object

The distribution of pixel values of a band can be provided with a histogram object. Those values are sampled in buckets. A histogram object is atomic and all fields are REQUIRED.

Field Name	Type	Description
count	number	number of buckets of the distribution.
min	number	minimum value of the distribution. Also the mean value of the first bucket.
max	number	minimum value of the distribution. Also the mean value of the last bucket.
buckets	[number]	Array of integer indicating the number of pixels included in the bucket.

The information in histogram objects may be useful to prepare a user interface in the perspective of the manipulation of the pixels value for raster visualization such as true color composite balancing.

For instance, to enhance an image by changing properties such as brightness, contrast, and gamma through multiple stretch types such as statistical functions.

Each bucket width all equals depending on the number of buckets. It can be computed with the following formula: Bucket width = ( max - min ) ÷ count

The Histogram Object is part of the JSON document produced by gdalinfo command line tool on the raster file with the -hist and -json argument. For instance

gdalinfo -json -hist PT01S00_842547E119_8697242018100100000000MS00_GG001002003/PT01S00_842547E119_8697242018100100000000MS00_GG001002003.tif

produces this file in wich there are histogram fields for each band. The planet example includes them.

Relation types

The following types should be used as applicable rel types in the Link Object.

Type	Description
gcps	This link points to a document providing with a list of Ground Control Points for the dataset, mapping between pixel/line coordinates and georeferenced coordinates

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples

stac-extensions / raster