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).
The fields in the table below can be used in these parts of STAC documents:
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.
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.
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
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": [{
"raster: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 $\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",
"bands": [{
"nodata": 0,
"unit": "W⋅sr−1⋅m−2",
"raster:scale": 0.0145,
"raster:offset": 3.48
}]
}
} Radiance to TOA Optical Reflectance
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:
source: https://www.orfeo-toolbox.org/CookBook/Applications/app_OpticalCalibration.html
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",
"bands": [{
"unit": "m",
"raster:offset": -185
}]
}
}
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.
The following types should be used as applicable rel types in the Link Object.
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.
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:
Then to check markdown formatting and test the examples against the JSON schema, you can run:
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:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4
