Level 2A product metadata

This main GeoJSON metadata file describes the product that is readable by third-party applications. This file is made up of a feature collection representing the product properties, including sensor properties.

note

Only selected properties distinct to FarEarth are documented here. See reference for a full breakdown of all the properties in the file.

Sample file

Sample: LANDSAT-9_OLI_20220804T083603_20220804T083634_L2A_R1C1.geojson

Property details

The GeoJSON (.geojson) file contains an array of features.

Each GeoJSON feature contains three objects:

• type: Always "Feature"
• properties: FarEarth products contain a product property in the feature. See product descriptor
• geometry: See feature geometry

Feature properties

Each feature has a properties object, with one product property.

Product descriptor

This table details the most important properties of the descriptor object.

Property	Description
productId	An identifier for this product. Identifiers do not need to be unique within the FarEarth Catalogue. It is recommended that the naming scheme be designed to be unique
temporalRange	A pair of UTC dates and times. It indicates the start and end of the period when the sensor was capturing pixels

Sensors

Each sensor module listed in the descriptor:sensors property of the product section has a corresponding entry in the file.

This table details the most important properties of the sensors section.

Property	Description
images	The images section is an array of grouped bands, known as images in FarEarth. You can configure bands to certain groups. Bands with similar GSDs are typically grouped. Bands with dissimilar GSDs cannot be grouped. This grouping does not affect the processing; it only affects the generated products. See images

Images

The images section contains a list (array) of image-groups. Each group refers to a single file (typically a single GeoTIFF file with multiple bands). Each group contains a number of properties described below.

Property	Description
group	Unique ID of the group
image	Name of the image file this group refers to
ids	Unique band-IDs for all bands that belong to this group
bands	Non-unique band-names for all bands that belong to this group
angles	Solar and view angles for the image (see angles)
geometric	Details relating to the geometric data of the image (see image geometry)
radiometric	Details relating to the radiometric data of the image
qaMask	Reference to the image file containing the quality assessment mask for this band image. The pixel values and bit representations are provided : 0 (000) is a normal pixel, 1 (001) is under saturated, 2 (010) is over saturated, 5 (101) is under saturated and filled and 6 (110) is over saturated and filled

Image geometry

This table details certain properties of the geometric section under the images section.

Property	Description
quality	This property indicates whether a systematic or precision band alignment strategy was followed for the image
projection	The geometric projection of this image onto the Earth. EPSG projections are used in the form "EPSG:XXXXX"
imageDimensions	A pair of numbers representing the number of pixels in the horizontal and vertical directions respectively
spatialResolution	The target size of each pixel when projected onto the Earth across track and along track respectively. The along track value may be negative, to reflect the convention of the upper left corner of the image having coordinate [0, 0], while pixel rows are counted from the first row of the sensor. In this case the absolute value of the number is the along track GSD
geometry	A polygon representing the footprint on the image on Earth. Coordinates are for the projection above

Image radiometry

This table details certain properties of the radiometric section under the images section.

Property	Description
pixelUnits	Pixel units used to represent the image data. DN denotes the raw digital numbers. TOA Reflectance x 10k denotes scaled ToA reflectance, TOA Brightness Temperature x 10 (K) denotes scaled ToA brightness temperatures in Kelvin
emissiveConstants	A list of emissive conversion constant, for radiance to brightness temperature conversion, for each band (always 1 for reflective bands)
radianceConversion	A list of radiance conversion values for each band (reflective bands only)
earthSunDistance	Provides the average distance between the Earth and the sun at the time of acquiring this image in Astronomical Units (AUs)

The emissiveConstants is relevant to emissive bands, and the radianceConversion values are relevant to reflective bands.

Reflective bands

To convert from TOA reflectance to radiance:

$$L = (ρ - b) / g$$

Where:

• $ρ$ is the TOA reflectance $\times 10,000$ (i.e. the L1C pixel value)
• $b$ is the offset (from the radianceConversion tag)
• $g$ is the gain (from the radianceConversion tag)
• $L$ is the radiance in $[W / (m² · sr · μm)]$

The bias ($b$) and gain ($g$) depend on scene-level characteristics such as Earth-Sun distance and solar angle. This means they are the same for every pixel within a scene, but will differ from scene to scene.

Emissive bands

To convert from brightness temperature to radiance:

$$L = c1 / [ exp(c0 / (T + c2)) - 1 ]$$

Where:

• $T$ is the brightness temperature in [$K$] (i.e. the per-pixel L1C value. Note: not $BT \times 10$)
• $c0$, $c1$, $c2$ is the three emissive constants
• $L$ is the radiance in $[W / (m² · sr · μm)]$

$c0$, $c1$, and $c2$ are fixed constants determined by the band's spectral response function. The conversion must be applied per-pixel since the input T is different for each pixel. The constants themselves remain the same for each band.

Angles

This table details certain properties of the angles section.

Property	Description
sunAzimuth	Sun azimuth angle. From the scene centre point on the ground, this is the angle between true north and the sun. Measured clockwise in degrees (0° - 360°)
sunElevation	Sun elevation angle. The angle from the tangent of the scene centre point to the sun. Measured from the horizon in degrees (-90° - 90°). Negative values indicate the sun is below the horizon, e.g. sun elevation of -10° means the data was captured during nautical twilight
viewOffNadir	The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0°-90°)
viewIncidence	The incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0°-90°)
viewAzimuth	Viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0°-360°)

Orthorectification quality

This table documents the quality section under the sensors section.

Property	Description
orthorectification	The orthorectification type is either systematic or precision. The orthorectification type of an image is precision if the reference band has an orthorectification type of precision

Systematic orthorectification

Systematic orthorectification uses calibration coefficients, NavAtt data, and rough reference data such as the mean height above ellipsoid for the image.

Precision orthorectification

Precision orthorectification uses tiepoints and reference data to refine the geolocation of the image to higher accuracies. Individual pixels of the Digital Elevation Model (DEM) are used to determine precisely where the pixel is.

Feature geometry

The geometry section defines the full footprint of the image. It is formatted according to RFC 7946.

This table documents the descriptor section of the sensor.

Property	Description
type	The type of shape that is described in the coordinates property
coordinates	A list of (x,y) coordinates forming a closed image outline (with units in the stated projection)

Reference: product metadata

The following reference describes the content of the product metadata file.

• ancestry (array): A list of references comprising the inputs used to create the product.
  • Items (object)
    • productId (string): The unique product ID.
    • productType (string): The type or level of the product (example, RAW, DEM, L1A, L1C or L2A).
    • references (array): A list of references which was used to generate the product.
      • Items (object)
        • productId (string): The product ID uniquely identifying the reference.
        • productType (string): The product type of the reference.
        • properties (object): Any additional optional properties that serves to describe the reference product.
    • software (object): Details relating to the software responsible for generating the product.
      • buildDate (string): An ISO date timestamp describing when the software package was built.
      • name (string): The name or ID of the software package.
      • revision (string): A revision hash that further serves as identifying the exact software package version.
      • version (string): A version uniquely identifying the software package.
• atmosImage (string): The file name of the atmospheric data used for corrections.
• bandMapping (object): A mapping of band ID to index.
• cloudCover (number, format: float): The cloud cover percentage (0.0 to 100.0).
• cloudsImage (string): The file name of the cloud probability image.
• dayNight (string): Day/night depending on sun elevation (night when sun elevation is negative). Must be one of: ["DAY", "NIGHT"].
• descriptor (object): Meta-data relevant to the product (Spacecraft, sensor, date-range of the product).
  • processedDate (string, format: date-time): The date on which the product was generated.
  • productId (string): The ID identifying the product.
  • productType (string): The product type.
  • sceneCol (integer, format: int32): If an interval is subdivided into multiple scenes (or tiles), the column index will reflect adjacent tiles across track starting counting at 1 for left-most scene. The interval will have at least one column, even it the interval is not subdivided.
  • sceneRow (integer, format: int32): If an interval is subdivided into multiple scenes (or tiles), the row index will increment proportionally along track (starting at 1). The interval will have at least one row, even it the interval is not subdivided.
  • sensors (array): A list of sensor IDs relevant to the product (if required, with preference for hyphenated separators instead of spaces or underscores).
    • Items (string)
  • spacecraft (string): The ID of the spacecraft (if required, with preference for hyphenated separators instead of spaces or underscores, example, 'LANDSAT-7').
  • temporalRange (object): The UTC start and end date of the product (with leap-seconds included).
    • from
      • One of
        • string
        • number
    • to
      • One of
        • string
        • number
• elevation (object): Details relating to the elevation of the product.
  • averageHae: The average height above ellipsoid in meters. Refer to #/$defs/ValueMeters.
  • averageMsl: The average mean sea level in meters. Refer to #/$defs/ValueMeters.
• pixelCount (integer, format: int64): The total number of pixels across all bands of the product.
• processingParameters (object): Parameters used during processing.
  • resampler (string)
• sceneView (object): Details relating to the along/across/nadir track view of the product.
  • acrossTrack (number, format: double): The amount of degrees the scene center is off across track (roll).
  • alongTrack (number, format: double): The amount of degrees the scene center is off along track (pitch).
  • offNadirMode (string): Indicates if the scene is acquire (NADIR / ALONG_TRACK / ACROSS_TRACK). Must be one of: ["NADIR", "ALONG_TRACK", "ACROSS_TRACK"].
• sensors (array): Details relating to the sensors relevant to the product.
  • Items (object)
    • descriptor (object): Details relating to the imaging sensor (name, detector ID's, etc).
      • ancillaries (object): Ancillary reference files used as calibration input during processing.
        • apf (string): The name of the atmospheric calibration parameter file used during processing.
        • cpf (string): The name of the general geometric calibration parameter file used during processing.
        • rpf (string): The name of the radiometric calibration parameter file used during processing.
      • ids (array): The detector IDs associated with the sensor.
        • Items (string)
      • name (string): The name or unique ID for the sensor.
    • images (array): Details related to image that were generated that is associated with the sensor.
      • Items (object)
        • angles (object): Solar and view angles relevant to the image.
          • sunAzimuth: From the scene center point on the ground, this is the angle between truth north and the sun (measured clockwise in degrees between 0 and 360). Refer to #/$defs/ValueDegrees.
          • sunElevation: The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (-90 to 90). Negative values indicate the sun is below the horizon, e.g. sun elevation of -10 means the data was captured during nautical twilight. Refer to #/$defs/ValueDegrees.
          • viewAzimuth: The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north (Measured clockwise from north in degrees between 0 and 360). Refer to #/$defs/ValueDegrees.
          • viewIncidence: The angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center (in degrees, between 0 and 90). Refer to #/$defs/ValueDegrees.
          • viewOffNadir: The angle from the sensor between nadir and the scene center (in degrees, between 0 and 90). Refer to #/$defs/ValueDegrees.
        • bands (array): The names of the bands available in this group. Non-unique names that matches the band IDs. Examples could include PAN, RED, GREEN, SWIR1, TIR1.
          • Items (string)
        • geometric (object): Details relating to the geometric data of the image.
          • geometry (array): A multi-sequence of (x,y) coordinates forming a closed image outline (with units in the stated projection).
            • Items (array)
              • Items (array): Length must be equal to 2.
                • Items (number)
          • imageDimensions (array): The pixel dimensions of the image (total rows and columns). Length must be equal to 2.
            • Items (number)
          • projection (string): The projection string of the image (example, 'EPSG:32629').
          • quality (object): The quality of the geometric corrections applied (example, the band-to-band alignment).
            • bandAlignment (object): A listing of which bands were corrected to what quality level. Best results would require that all bands are precision aligned.
              • precisionBands (array): The names of the bands that were precision aligned against a reference ortho image, or other ground control points.
                • Items (string)
              • systematicBands (array): The name of the bands that were systematically aligned as fallback when precision alignment failed or were disabled.
                • Items (string)
          • spatialResolution (array): The spatial resolution for any pixel in the image (as meters). Length must be equal to 2.
            • Items (number)
        • group (string): The ID used to group different bands or their respective detector IDs together. Typically grouped together in the same image file by matching GSD resolutions. Examples include 'MS', 'RGB', 'VNIR' or 'VIS'.
        • ids (array): The IDs of the bands available in this group. If multiple sensor assemblies are published separately, these ID's will be unique to allow differentiation between bands available on different sensors. Examples include 'SCA1_PAN', 'SCA1_RED', where another group could be 'SCA2_PAN', 'SCA2_RED'.
          • Items (string)
        • image (string): The name of the file of which this group refers to.
        • qaMask (string): The name of the quality mask file of which this group refers to.
        • radiometric (object): Details relating to the radiometric data of the image.
          • earthSunDistance (number, format: double): The average distance between the center of the earth and the center of the sun in Astronomical Units (AU). Typical values are between 0.9832 and 1.0167.
          • emissiveConstants (array): A list of emissive conversion constant values for for each band. Emissive constants will vary only for emissive bands, with unity constants for reflective bands. Will be omitted if empty.
            • Items (object)
              • band (string): The name of the imaging band.
              • constants (array): The emissive constants are model parameters used for radiance to brightness temperature conversion.
                • Items (number, format: double)
          • esun (array): A list of mean exo-atmospheric solar irradiance (ESUN) values for each band. ESUN values will only be available for reflective bands. Will be omitted if empty.
            • Items (object)
              • band (string): The name of the imaging band.
              • units (string): Typically 'W / (m^2 * um)'.
              • value (number, format: double): The ESUN value of the band in question.
          • pixelUnits (string): The pixel value representation of the image data (either 'Surface Reflectance x 10k' denoting x10,000 scaled surface reflectance, or 'Surface Temperature x 10 (K)' denoting x10 scaled surface temperature in Kelvin).
          • radianceConversion (array): A list of radiance conversion values for for each band. The conversion values are only applicable to reflective bands. Will be omitted if empty.
            • Items (object)
              • band (string): The name of the imaging band.
              • gain (number, format: double): The gain of the imaging band.
              • offset (number, format: double): The offset of the imaging band.
          • spectral (array): The spectral band layout of the sensor.
            • Items (object)
              • band (string): The name of the imaging band.
              • centerWavelength (number, format: double): The center band wavelength (in nanometers).
              • fullWidthHalfMax (number, format: double): The full-width half-max bandwidth of the band in question (in nanometers).
    • quality (object): Quality metrics generated during processing.
      • atmospheric (object): Quality of the atmospheric data used during processing.
        • aerosols (object): The quality of the aerosol data used for atmospheric correction.
          • source: The source of the data for this atmospheric band. Refer to #/$defs/L2AAuxDataSource.
        • emissivity (object): The quality of the emissivity data used for atmospheric correction.
          • source: The source of the data for this atmospheric band. Refer to #/$defs/L2AAuxDataSource.
        • ozone (object): The quality of the ozone data used for atmospheric correction.
          • source: The source of the data for this atmospheric band. Refer to #/$defs/L2AAuxDataSource.
        • waterVapor (object): The quality of the water vapor data used for atmospheric correction.
          • source: The source of the data for this atmospheric band. Refer to #/$defs/L2AAuxDataSource.
      • geometric (object): Geometric quality metrics generated during processing.
        • orthorectification (string): To what model quality orthorectification was achieved (either 'systemic' or 'precision'). Any detector which failed precision refinement will result in a fallback to 'systematic'. Must be one of: ["systematic", "precision"].
• software (object): Details regarding the software used to generate the L2A product.
  • name (string)
  • version (string)
• spectralResponses (string): The file name in which all the spectral responses for all bands can be found.
• thumbnailImageType (string): The image format of the generated thumbnails. Must be one of: ["GEOTIFF_COG", "GEOTIFF", "BIG_GEOTIFF", "MEMORY", "PNG", "JPEG", "JP2000", "JP2000_LOSSLESS"].
• thumbnails (array): Thumbnails of different band or sensor combinations.
  • Items (object): Thumbnail details.
    • image (string): The file name of the thumbnail image.
    • name (string): The ID used to distinguish between different thumbnails.
• viewingAngles (string): The file name in which all the viewing of the product can be found.

Definitions

• L2AAuxDataSource (string): DETECTED: the atmospheric condition was detected/inferred using the input data itself. PREDICTED: the atmospheric condition was predicted using numeric weather prediction data. ANCILLARY: the atmospheric condition was obtained from a third party data source. FALLBACK: if the atmospheric condition could not be obtained in any fashion, then a sensible fallback value is used instead. Must be one of: ["DETECTED", "PREDICTED", "ANCILLARY", "FALLBACK"].
• ValueDegrees (object)
  • units (string): The SI unit the value is expressed in.
  • value (number, format: double): The scalar value quantity.
• ValueMeters (object)
  • units (string): The SI unit the value is expressed in.
  • value (number, format: double): The scalar value quantity.