Format book: Level 1C

This document describes the Level 1C product created by FarEarth. The machine-readable schemas are published alongside this resource on our GitHub repository.

The document matches the FarEarth Executors with the same version numbers.

Schemas

Each metadata file in a FarEarth product has a schema associated with it. Relevant descriptions for each file are also provided. The various Level 1C product files and schemas have been listed below for reference.

File	Schemas
Main metadata	JSON
Product metadata	XML
STAC product
Tile metadata	XML
Tile info	JSON
Viewing angle metadata	JSON
Pointing metadata	JSON
Geometric verification (Absolute)	JSON
Geometric verification (Relative)	JSON

Introduction

A Level 1C product produced by FarEarth is orthorectified in the UTM/WGS84 projection. The Level 1C product's pixel values are presented in top-of-atmosphere reflectance or radiance. This standard map-ready product is suitable for downstream analysis for further correction.

A Level 1C product is processed in the Level 1 product process. Generated by using the Level 1B as input.

The diagram below shows a high-level overview of where the Level 1C product fits in the scope of other FarEarth products.

Terminology and document conventions

The following terminology is used in this document.

Term	Definition
Asset	An asset is a file that makes up part of a product
GeoJSON	An IETF standard of encoding various geographic data structures based on RFC 7946
ISO-8601	Describes a format for date and time information. FarEarth uses UTC dates; an example of an ISO-8601-formatted string in FarEarth is: "2019-10-25T09:00:00Z"
NavAtt	Navigation and attitude data
Product	A product in FarEarth is a satellite image with its related metadata and consist of a collection of related files
Tiepoint	A tiepoint is a collection of pixels representing a feature used to spatially correlate two or more images or bands
UTM/WGS84	The Universal Transverse Mercator map projection using the World Geodetic System 84 ellipsoid
Cloud Optimised GeoTIFF (COG)	A Cloud Optimized GeoTIFF (COG) is a regular GeoTIFF file with an internal organization enabling more efficient workflows in the cloud

Sample product

A Level 1C product sample is provided below as a resource referenced throughout this document. This is a Landsat-9 OLI sensor FarEarth Level 1C product.

Sample: LANDSAT-9_OLI_20220804T083603_20220804T083634_L1C_R1C1.zip

Product data files

A Level 1C product produced by FarEarth is a Cloud Optimised GeoTIFF (COG) with embedded geospatial data. This allows you to open the product file in 3rd party tools. The COG file will automatically show at the correct geolocation on the Earth.

Bands of similar dimensions can be grouped together in the COG file. Bands in this file appear in the same order as in the bands section of the main metadata file. LZW compression and a block size of 512 are used. Level 1C products by default use a data format of Int16 and a no data value of -9999.

The scale of the pixel values is given in the radiometric section of the metadata file.

Data format and units

The following Level 1C product data options are available and are dependent on the workflow and satellite.

Option	Description
Digital Numbers	Pixel values in digital numbers as acquired by the sensor. Values have not been scaled to any units
Radiance	Pixel values in radiance. Images in radiance have absolute radiometric calibration applied to their digital numbers. The value of each pixel is in $W/m^2 sr \mu m$
Top-of-Atmosphere Reflectance ($\times 10,000$)	The value of the pixels is the ratio of radiation reflected to the incident solar radiation, that is measured by a sensor above the atmosphere multiplied by $10\\^4$. The values are unitless

Pixel nesting

Pixels can be nested in two ways depending on the configuration of the processors.

1. Point nesting
   • Ensures that the centre point of each pixel in a lower-resolution image is aligned with the centre point of a corresponding pixel in the higher-resolution image
   • This means that the bounding box of the images will not match
2. Area nesting
   • Ensures that the top-left pixel of the lowest resolution image aligns with the top-left corner of the corresponding pixels in higher resolution images
   • The bounding box of all images in the product will match

Images processed by FarEarth from satellites with similar resolutions and projections over the same areas will have pixels that nest.

Level 1C thumbnail file

A thumbnail file is a low-resolution version of the actual product image. It is a small file meant to give you an overview of the product without the need to download the full data. A FarEarth product will contain at least one thumbnail. Multiple thumbnails may be included for to show different band combinations, masks or other information. Thumbnails may have different file types.

Sample: LANDSAT-9_OLI_20220804T083603_20220804T083634_L1C_R1C1_RGB.png

Products may also include overview, visual or graphic assets that provide similar benefits but have a different format and are more specific to an aspect of the product.

Angle image files

Viewing angle and solar angle data are also provided in .tif data files. This data is geolocated to the same projection as the image. This file may be stacked on the image data to process it further.

Two types of containing angle data are provided in the viewing angle image folder:

Solar angle

A single solar angle file is provided. The extent of this image may exceed the dimensions of the processed image. Data is encoded in the following bands:

Band	Description
Band 1: Solar zenith	Solar zenith values where the scene is subdivided in a grid of averaged values
Band 2: Solar azimuth	Solar azimuth values where the scene is subdivided in a grid of averaged values

Sample: LANDSAT-9_OLI_20220804T083603_20220804T083634_L1C_R1C1_SOLAR_ANGLE.tif

View-angle

A view-angle file is provided for each processed band. Data is encoded in the following bands:

Band	Description
Band 1: View incidence zenith	The angle between the vertical (normal) to the intercepting surface at the centre point of the image or block and the line of sight back to the satellite. Measured in degrees ($0°-90°$)
Band 2: View incidence azimuth	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°$)

Sample: LANDSAT-9_OLI_20220804T083603_20220804T083634_L1C_R1C1_PAN_PAN_1_VIEW_ANGLE.tif

Geometric verification files

The geometric verification files are produced as quality assessment files for every image. Two variants of the files are available, absolute and relative:

• Absolute products compare a specific band of the image with reference data and contain the measured geometric error of tiepoints found on the image

• Relative products compare bands of the image and contain the measured geometric error of tiepoints found on the image

The comparison between a specific band of an image and a reference image, and between the two bands of an image, is performed in the same way. Tiepoints are collected for both. These tiepoints were determined independently. The distance between the location of the tiepoints on the reference image and the processed image is measured and reported as disparities in X and Y together with coordinates. Disparities are given in meters.

Geometric verification absolute thumbnail

The geometric verification thumbnail that is produced by FarEarth is a visual indication of the tiepoints that were matched as part of the process above. The colour of the points gives an indication of the size of the disparity between the reference in terms of the pixel size of the image. The colour mapping is given in the relevant metadata file.

Sample: LANDSAT-9_OLI_20220804T083603_20220804T083634_L1C_R1C1_GVER_ABS_RED.png

Geometric verification relative thumbnail

The relative geometric verification thumbnails produced by FarEarth are a visual indication of the tiepoints that were matched as part of the process above between the bands of the image. The colour of the points indicates the difference between the reference and image in pixels at the GSD of the image. These thumbnails are compressed into an archive before being included in the product.

Sample: LANDSAT-9_OLI_20220804T083603_20220804T083634_L1C_R1C1_GVER_REL_BLUE_GREEN.png

Interpreting the geometric verification thumbnails

The geometric verification thumbnails are used to determine the quality of the processed image.

An accurately processed image will have a uniform distribution of tiepoints across the whole image that have small disparities. The difference in response between the different bands needs to be considered when interpreting the geometric verification results.

For example, typical BLUE and GREEN bands are spectrally very similar when comparing the bands individually but, the BLUE and NIR bands are spectrally separated, and less correlation is expected and normal.

Patterns in the disparities generally indicate that there is some satellite movement that is not being accounted for in the processing.

Isolated islands of tiepoints that are different from their surroundings can indicate an inaccurate DEM or inaccurate modelling of the radiometric properties of the sensor.

Product quality mask files

A Level 1C product has one product quality mask file per group listed in the metadata file.

A product quality mask file is an image file containing the quality assessment mask for the group. Each pixel in the mask indicates the quality of the corresponding pixel in the band data. The mask is therefore in the same map projection as the band data. The possible pixel values of the mask are listed in the table below.

Value	Description
0	No special information regarding this pixel
1	The pixel is under saturated. The value of the pixel is below the minimum threshold of what the sensor is capable of measuring, therefore this pixel is uncertain
2	The pixel is over saturated. The value of the pixel is above the maximum threshold of what the sensor is capable of measuring, therefore this pixel is uncertain

Metadata files

One or more files containing metadata are created with each FarEarth product. These files describe the product and conditions under which the data was acquired, as well as processing information.

An overview of the different files containing metadata of the Level 1C product are listed below.

File	Description
Product file	The product file contains metadata and references to the other files that make up a product
Main metadata	The main metadata file for the product. Typically has the extension .geojson and is readable by third-party applications
Viewing angles	FarEarth may be configured to publish viewing-angle data for blocks of pixels as well as average values for the scenes. This file has JSON structures that present the viewing angle data in a machine-readable format
Pointing	The pointing file contains pointing information of the product at different processing levels in a .json data structure
GVerify - absolute	Quality of the absolute geometric orthorectification
GVerify - relative	Quality of the relative geometric band-alignment
Spectral response	A .csv file with data representing the radiometric spectral response of the sensor

Radiometric response

The radiometric response of the sensor is included in the L1C product as a CSV file.

The CSV file has a header row, the first column is the x-axis wavelength in micrometers (μm). Following this is the radiometric response for each band.

An example of a radiometric response file format is given below:

x-axis(μm)	band1	band2	band3	band4	...
0.4000128478	0.0	0.0	1.53017677E-4	0.0
0.4006134492	0.0	0.0	-1.6947116E-4	2.66482800E-4
0.4012140505	0.0	-6.8684477E-5	-4.6930260E-5	1.46200368E-4
…

Sample: LANDSAT-9_OLI_20220804T083603_20220804T083634_L1C_R1C1_SPECTRAL_RESPONSE.csv

Document history

This section details the changes between version 1.2 and 1.3 of the Level 1C Format book.

Main metadata file

New properties

The following new properties were added to the file:

Property	Description
properties.product.ancestry	A list of references comprising the inputs used to create the product. Details include product IDs, product types, properties, software names and versions

Changed properties

The following properties were modified, within properties product:

Version 1.2	Version 1.3
descriptor.generationDate	descriptor.generationDate
sensors[ ].images[ ].geometric.dimensions	sensors[ ].images[ ].geometric.imageDimensions
sensors[ ].images[ ].geometric.resolution	sensors[ ].images[ ].geometric.spatialResolution

Removed properties

The following properties were removed:

• properties.product.sensors[ ].quality.geometric.metrics

Units added

Units have been added to the following properties:

• properties.product.elevation.averageHae
• properties.product.elevation.averageMsl
• properties.product.sensors[ ].images[ ].angles.sunAzimuth
• properties.product.sensors[ ].images[ ].angles.sunElevation
• properties.product.sensors[ ].images[ ].angles.viewAzimuth
• properties.product.sensors[ ].images[ ].angles.viewIncidence
• properties.product.sensors[ ].images[ ].angles.viewOffNadir

Each of the properties listed above are now represented as a JSON object, containing a "units" and "value" element. For example:

"averageMsl": {
   "units" : "METERS",
   "value" : 1102.769
},
"averageHae": {
   "units" : "METERS",
   "value" : 1095.134
}

STAC product file

New properties

The following new properties were added to the file:

Property	Description
properties.processingBaseline	A string containing the processing baseline (algorithm) version
properties.eo:cloud_cover	A number containing an estimate of cloud cover as a percentage. See STAC EO Extension documentation on GitHub

Tile info file

A new tile info file has been added as an optional metadata file for Level 1C products. The tile info JSON file contains details regarding the product outline. The properties of this file refer to the Military Grid Reference System (MGRS).

For more information about the contents of this file, refer to our online documentation.

Pointing metadata file

The content of the pointing metadata has been reworked completely. The new pointing JSON file contains measurements for each sensor, detailing the type of orthorectification model used. These metrics provide insights into the accuracy of the satellite's sensors.

For more information about the contents of this file, refer to our online documentation.