Level 1C 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_L1C_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
`bandIntegrationTimes`	Provides the integration time for each band, as a pair of units and a value

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, example, 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.
bandIntegrationTimes (object): The integration time in microseconds for each of the band IDs available. If multiple sensor assemblies are published separately, the integration times are provided per bandId. Examples of IDs include 'SCA1_PAN', 'SCA1_RED', where another group could be 'SCA2_PAN', 'SCA2_RED'.
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 (e.g., 'EPSG:32629').
        
        quality (object): The quality of the geometric corrections applied (e.g., 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 IDs 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 'DN' denoting raw digital numbers, or 'TOA Reflectance x 10k' denoting x10,000 scaled top-of-atmosphere reflectance, or 'TOA Brightness Temperature x 10 (K)' denoting x10 scaled top-of-atmosphere brightness temperature in Kelvin).
        
        pixelValueStatistics (array): A list of statistics for the pixel data for each band.
        
        Items (object)
        
        band (string): The name of the imaging band.
        
        statistics (array): The statistics of the pixel data of the imaging band.
        
        Items (object)
        
        max (number, format: double): The maximum value of the band in question.
        
        mean (number, format: double): The mean value of the band in question.
        
        min (number, format: double): The minimum value of the band in question.
        
        stdDev (number, format: double): The standard deviation value of the band in question.
        
        units (string): The pixel value representation of the statistic data (either 'TOA Reflectance x 10k' denoting x10,000 scaled top-of-atmosphere reflectance, or 'TOA Brightness Temperature x 10 (K)' denoting x10 scaled top-of-atmosphere brightness temperature in Kelvin), or 'W / (m^2 * sr * um)' denoting top-of-atmosphere radiance.
        
        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.
    - 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 L1C 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

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.

Sample file​

Property details​

Feature properties​

Product descriptor​

Sensors​

Images​

Image geometry​

Image radiometry​

Reflective bands​

Emissive bands​

Angles​

Orthorectification quality​

Systematic orthorectification​

Precision orthorectification​

Feature geometry​

Reference: product metadata​

Definitions​