Raster Extension Specification
- Title: Raster
- Identifier: https://stac-extensions.github.io/raster/v2.0.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 (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). 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
Fields
The fields in the table below can be used in these parts of STAC documents:
- Catalogs
- Collections
- Item Properties (incl. Summaries in Collections)
- Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
- Bands
- Links
When using the raster extension, 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 |
|---|---|---|
| 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 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
In remote sensing, most imagery raster corresponds to just unitless raw pixel values that may be converted into specific units given a scale and an offset. The raw pixel values are referred to as Digital Numbers (DN). Using a Scale and Offset simply provide a more efficient way to store data with less bytes. In these cases the data provider will include scale and offset values for transforming the data into a physical measurement, such as radiance, power, altitude, or backscatter. Several examples are given below.
Users should be careful to always apply any provided scale and offset
DN to Reflectance
A very common use case is to store reflectance values, which range from 0 - 1.0, as integers rather than utilizing the larger floating point data type. Data is stored in a 2-byte Integer and ranges from 1 to 10,0000 by using a scale of 0.0001, resulting in a file half the size of one using 4 byte floats.
"assets": { "B4": { "title": "TOA radiance band 4", "bands": [{ "nodata": 0, "raster:scale": 0.0001, "raster:offset": 0.0 }] } }
Digital Numbers to Optical Radiance
A conventional way of deriving Top Of Atmosphere (TOA) Radiance from