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 ofthen strongly linked with the 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).
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.
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 above. 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 defines parameters to compute another value. Next paragraphs describe some use cases.
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 file:data_type are:
int8: 8-bit integerint16: 16-bit integerint32: 32-bit integerint64: 64-bit integeruint8: unsigned 8-bit integer (common for 8-bit RGB PNG's)uint16: unsigned 16-bit integeruint32: unsigned 32-bit integeruint64: unsigned 64-bit integerfloat16: 16-bit floatfloat32: 32-bit floatfloat64: 64-big floatcint16: 16-bit complex integercint32: 32-bit complex integercfloat32: 32-bit complex floatcfloat64: 64-bit complex floatother: Other data type than the ones listed above (e.g. boolean, string, higher precision numbers)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.
A conventional way of deriving Top Of Atmosphere (TOA) Radiance in from DN values using scale and offset in the following formula:
For example, the above value conversion is described in the values dictionary as
"assets": {
"B4": {
"title": "TOA reflectance",
"raster:bands": [{
"nodata": 0,
"unit": "W⋅sr−1⋅m−3",
"scale": 0.0145,
"offset": 3.48
}]
}
} 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
}]
}
}
The histogram object provides with distribution of pixel values in the band. Those values are sampled in buckets. An 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 object 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.
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
