From 80c79f68d2509c8010a4331d6cda8440a1a9061a Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 9 Aug 2024 14:49:21 +0200 Subject: [PATCH] Radar Profile (#4) * Started SAR work --- radar-source.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++ radar.md | 109 ++++++++++++++++++++++++----- 2 files changed, 269 insertions(+), 17 deletions(-) create mode 100644 radar-source.md diff --git a/radar-source.md b/radar-source.md new file mode 100644 index 0000000..2db1946 --- /dev/null +++ b/radar-source.md @@ -0,0 +1,177 @@ +# CEOS-ARD for Radar - Source Data + +- **Scope:** Item, Collection +- **Extension [Maturity Classification]:** Proposal +- **Owner**: @m-mohr + +This extension specifies how to create [STAC] Items for Source Data that +comply to the [CEOS-ARD product family specifications] (PFS) for radar sensors. + +> \[!IMPORTANT] +> See also the [main specification document](radar.md) for CEOS ARD for Radar, +> which includes the specification for [Product Data](radar.md#stac-items-ard-product). + +> \[!NOTE] +> This document is a draft and not finalized yet. +> We welcome feedback from early adopters. + +**Additional resources:** + +- Examples (ToDo) +- JSON Schema (ToDo) + +**Table of Contents:** + +- [STAC Items (Source Data)](#stac-items-source-data) + - [Extensions](#extensions) + - [Common Metadata](#common-metadata) + - [Processing](#processing) + - [Projection](#projection) + - [SAR](#sar) + - [Satellite](#satellite) + - [View Geometry](#view-geometry) + - [Assets](#assets) + - [Data](#data) +- [Notes / ToDo](#notes--todo) + +## STAC Items (Source Data) + +Metadata for the source data could also be provided in a different form, +e.g. in the CEOS ARD XML metadata format or in the source metadata. +Nevertheless, it is recommended to provide them as STAC Items for a consistent interface. + +STAC Items must always be valid, but not all STAC Item requirements are covered here, +only additional requirements and mappings to fulfill the CEOS-ARD requirements are listed here: + +| Field Name | Req. | Description | +| --------------- | ----- | ------------------------------------------------------------ | +| stac_extensions | *n/a* | **REQUIRED.** Must contain [all implemented STAC extensions](radar.md#stac-extensions). | +| id | 1.6.6 | **REQUIRED.** The source product ID / file name. If another type of ID is provided, the file name can also be extracted from the asset with role `data`. | +| geometry | 1.6.7 | **REQUIRED.** The geometry of the acquisition in WGS84. | + +Generally, CEOS-ARD requests to provide DOIs for various resources. +For STAC, DOIs (e.g. `10.1109/5.771073`) must be converted to URLs (e.g. `https://doi.org/10.1109/5.771073`). +See [Resolve a DOI name](https://dx.doi.org/) for details. + +### Extensions + +The following [STAC extensions](radar.md#stac-extensions) are relevant for the source Items: + +| Name | Required | +| --------------- | :------: | +| [CEOS-ARD] | ✓ | +| [Processing] | ✓ | +| [Projection] | ✓ | +| [SAR] | ✓ | +| [Satellite] | ✓ | +| [View Geometry] | ✗ | + +Providing the CEOS-ARD [fields](README.md#fields) and [links](README.md#relation-types) fulfills req. 1.3 and 1.4. +The fields can be provided either in the [Collection](radar.md#stac-collections) or in each Item. + +### Common Metadata + +| Field Name | Req. | Description | +| ----------- | ----- | ------------------------------------------------------------ | +| datetime | 1.6.3 | **REQUIRED.** The start date and time of the source data. Can also be expressed as `start_datetime` and `end_datetime` instead. | +| instruments | 1.6.2 | **REQUIRED.** Instruments in lower-case. | +| platform | 1.6.2 | **REQUIRED.** Satellite name in lower-case. | + +Requirement 1.6.2 asks to provide links to: + +- [CEOS Missions Database] record(s) +- [CEOS Instruments Database] record(s) +- [CEOS Measurements Database] record(s) + +### Processing + +| Field Name | Req. | Description | +| --------------- | ----- | ---------------------------- | +| processing:facility | 1.6.6 | **REQUIRED.** Processing facility | +| processing:datetime | 1.6.6 | **REQUIRED.** Processing date and time | +| processing:software / processing:version | 1.6.6 | **REQUIRED.** Software version(s) | +| processing:level | 1.6.6 | **REQUIRED.** Processing level | +| processing:facility | 1.6.6 | **REQUIRED.** Processing facility | +| processing:facility | 1.6.6 | **REQUIRED.** Processing facility | + +### Projection + +| Field Name | Req. | Description | +| ------------------------------------- | ----- | ------------------------------------------------------------ | +| proj:code / proj:wkt2 / proj:projjson | 1.6.7 | **REQUIRED**. Coordinate Reference System (CRS). One of the fields is required to be provided. | +| proj:bbox | 1.7.7 | **REQUIRED**. The source data geometry in the given CRS. | + +### SAR + +| Field Name | Req. | Description | +| -------------------- | ----- | ------------------------------------------------------------ | +| sar:frequency_band | 1.6.4 | **REQUIRED.** Radar band | +| sar:center_frequency | 1.6.4 | **REQUIRED.** Center frequency | +| sar:polarizations | 1.6.4 | **REQUIRED.** Polarization(s) | +| sar:instrument_mode | n/a | **REQUIRED.** Name of the sensor acquisition mode | +| sar:product_type | n/a | **REQUIRED.** The product type for the source data, e.g. `GRD`. | +| sar:looks_azimuth | 1.6.6 | **REQUIRED.** Azimuth number of looks | +| sar:looks_range | 1.6.6 | **REQUIRED.** Range number of looks | + +### Satellite + +| Field Name | Req. | Description | +| --------------- | ----- | ---------------------------- | +| sat:orbit_state | 1.6.5 | **REQUIRED.** Pass direction | + +### View Geometry + +| Field Name | Req. | Description | +| ------------ | ----- | ---------------------- | +| view:azimuth | 1.6.5 | Platform heading angle | + +### Assets + +**Data Access:** Requirement 1.6.1 **requires** information about data access. +This requirement is automatically fulfilled by STAC if the referenced assets are publicly accessible. +If authentication or other steps are required to access the data, this should at least be described in the Collection or Item description. +For a more machine-readable way implementors could also use other means, such as the [Authentication] extension. + +**Roles:** The role names specify the values to be used in the Asset's `roles`. +Each of the assets can either be exposed individually or grouped together in any form. +In the latter case the role names can simply be merged to a set of unique role names. +Roles can also be combined for a single file. + +#### Data + +For non-metadata requirements that refer to how the data must be created and processed +please consult the relevant CEOS-ARD specification. +There can be one or multiple data assets per acquisition. + +For data assets, the following properties are relavant in the context of CEOS-ARD: + +| Field Name | Req. | Description | +| ---------- | --------- | ------------------------------------------------------------ | +| roles | *various* | **REQUIRED.** All data assets must to include the `data` role. | + +## Notes / ToDo + +- Req. 1.6.4: The following requirements can't be expressed in STAC yet: + - Observation mode (i.e., Beam mode name) + - Antenna pointing (Right/Left) + - Beam ID (i.e., Beam mode Mnemonic) +- Req. 1.6.5: The orbit data source can't be specified in STAC yet. +- Req. 1.6.6: STAC can only specify a single value in `sar:looks_range` (i.e. for a single beam), + but for multiple beams CEOS ARD requires to provide separate values for each beam. + +[CEOS-ARD product family specifications]: + +[CEOS Missions Database]: +[CEOS Instruments Database]: +[CEOS Measurements Database]: + +[STAC]: +[Maturity Classification]: + +[Authentication]: +[CEOS-ARD]: +[Processing]: +[Projection]: +[SAR]: +[Satellite]: +[View Geometry]: diff --git a/radar.md b/radar.md index 0f8ec64..42d08cb 100644 --- a/radar.md +++ b/radar.md @@ -1,9 +1,6 @@ -# CEOS-ARD for Radar data +# CEOS-ARD for Radar -- **Title:** CEOS-ARD for Radar -- **Identifier:** -- **Field Name Prefix:** - -- **Scope:** Item +- **Scope:** Item, Collection - **Extension [Maturity Classification]:** Proposal - **Owner**: @m-mohr @@ -18,23 +15,26 @@ and includes the specifications for: - Geocoded Single-Look Complex (`GSLC`) > \[!NOTE] -> THis document is a draft and not finalized yet. +> This document is a draft and not finalized yet. > We welcome feedback from early adopters. **Additional resources:** - Examples (ToDo) -- JSON Schema (ToDo) +- JSON Schema: not provided **Table of Contents:** - [Document Structure](#document-structure) - [STAC Extensions](#stac-extensions) - [STAC Collections](#stac-collections) -- [STAC Items](#stac-items) +- [STAC Items (ARD Product)](#stac-items-ard-product) + - [Extensions](#extensions) - [Common Metadata](#common-metadata) -- [Links](#links) -- [Notes](#notes) + - [Projection](#projection) + - [Links](#links) +- [STAC Items (Source Data)](#stac-items-source-data) +- [Notes / ToDo](#notes--todo) ## Document Structure @@ -54,9 +54,22 @@ This profile doesn't define new STAC fields, it's just a profile that uses As the identifier for this profile is just a collection of existing extensions and only defines required fields, you get a good bit of validation already without providing the identifier/schema of this profile in `stac_extensions`. If your metadata is already compliant to this profile, you can omit the identifier for this profile in -`stac_extensions` to avoid costly regeneration of the Items. You won't get validation whether all required +`stac_extensions` to avoid costly regeneration of the Items. You won't get validation whether all required fields are present, but this could be checked manually in the CEOS assessment/review. +The following STAC extensions are relevant for this profile: + +| Name | Schema URI for `stac_extensions` | +| ------------ | ------------------------------------------------------------ | +| [CEOS-ARD] | `https://stac-extensions.github.io/ceos-ard/v0.2.0/optical/schema.json` | +| [Processing] | `https://stac-extensions.github.io/processing/v1.1.0/schema.json` | +| [Projection] | `https://stac-extensions.github.io/projection/v1.0.0/schema.json` | +| [Raster] | `https://stac-extensions.github.io/raster/v2.0.0/schema.json` | +| [SAR] | `https://stac-extensions.github.io/sar/v1.0.0/schema.json` | + +For details about the CEOS-ARD extension, please see the separate [CEOS-ARD extension README](README.md#fields). +The CEOS-ARD extension fields can either be provided in the Collection or in the Items. + ## STAC Collections CEOS-ARD lists a lot of requirements (and fields) that have common values across all generated STAC Items and assets. @@ -67,19 +80,75 @@ you can de-duplicate links and assets by putting common links once into the STAC Also, common assets can be just put once into the STAC Collection using [Collection Assets]. All this is still CEOS-ARD compliant as it doesn't require all information to be in a single file. -## STAC Items +## STAC Items (ARD Product) + +STAC Items must always be valid, but not all STAC Item requirements are covered here, +only additional requirements and mappings to fulfill the CEOS-ARD requirements are listed here: + +| Field Name | Req. | Description | +| --------------- | ----- | ------------------------------------------------------------ | +| stac_extensions | *n/a* | **REQUIRED.** Must contain [all implemented STAC extensions](#stac-extensions). | +| geometry | 1.4 | **REQUIRED.** The geometry of the acquisition in WGS84. | +| bbox | 1.7.8 | **REQUIRED.** The bounding box of the acquisition in WGS84. | + +Generally, CEOS-ARD requests to provide DOIs for various resources. +For STAC, DOIs (e.g. `10.1109/5.771073`) must be converted to URLs (e.g. `https://doi.org/10.1109/5.771073`). +See [Resolve a DOI name](https://dx.doi.org/) for details. + +### Extensions + +The following [STAC extensions](#stac-extensions) are relevant for the product Items: + +| Name | Required | +| ------------ | :------: | +| [CEOS-ARD] | ✓ | +| [Processing] | ✗ | +| [Projection] | ✓ | +| [Raster] | ✗ | +| [SAR] | ✓ | + +Providing the CEOS-ARD [fields](README.md#fields) and [links](README.md#relation-types) fulfills req. 1.3 and 1.4. +The fields can be provided either in the [Collection](#stac-collections) or in each Item. ### Common Metadata -... +| Field Name | Req. | Description | +| -------------- | ---- | ------------------------------------------------------------ | +| start_datetime | 1.5 | **REQUIRED.** The datetime of the earliest start datetime of all relevant acquisitions. | +| end_datetime | 1.5 | **REQUIRED.** The datetime of the latest end datetime of all relevant acquisitions. | +| attribution | 1.3 | Attribution / Copyright information if required by the data provider. | -## Links +### Projection -... +The metadata is **required** to specify the coordinate reference system through either `proj:code` or one of the alternatives. -## Notes +| Field Name | Req. | Description | +| ------------------------------------- | ------ | ------------------------------------------------------------ | +| proj:code / proj:wkt2 / proj:projjson | 1.7.11 | **REQUIRED**. One of the fields is required to be provided, recommended is `proj:code`. If there's no suitable CRS code, set `proj:code` to `null` and add either `proj:wkt2` or `proj:projjson`. | +| proj:bbox | 1.7.7 | **REQUIRED**. The bounding box of the acquisition in the projection defined in proj:code / proj:wkt2 / proj:projjson. | -... +### Links + +All links can be provided either in the Collection or in the Item, +unless the links are specific for each Item and/or differ between the Items (such as `derived_from`). +If that's the case, they must be provided per Item. + +In addition to the links defined in specific extensions above, the following relation types are relevant: + +| Relation Type | Req. | Description | +| ------------- | ---- | ------------------------------------------------------------ | +| derived_from | 1.5 | **REQUIRED.** URL to the source data acquisitions, ideally as STAC metadata. The source metadata files must comply to the requirements [below](#stac-items-source-data). The number of links with this relation type identify the number of source data acquisitions. | + +## STAC Items (Source Data) + +The specification for STAC Items that cover the source data, please see the "CEOS ARD for Radar - Source Data" specification + +## Notes / ToDo + +- Req. 1.5 / 1.6 / 2.8: It is not clear how to specify the Acquisition ID Image + as the `derived_from` links don't contain a numeric indice. See also [#26]. + +[#26]: [CEOS-ARD product family specifications]: [Combined CEOS-ARD for Synthetic Aperture Radar, version 1.0]: @@ -88,3 +157,9 @@ All this is still CEOS-ARD compliant as it doesn't require all information to be [Maturity Classification]: [Collection Summaries]: [Collection Assets]: + +[CEOS-ARD]: +[Processing]: +[Projection]: +[Raster]: +[SAR]: