diff --git a/CHANGELOG.md b/CHANGELOG.md index 623362c..d004fb4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- `sar:beam_ids` property to describe the swath in the SAR acquisition. + ### Changed - Required properties of type `string` require a minimum length of `1`. diff --git a/README.md b/README.md index c663069..182d946 100644 --- a/README.md +++ b/README.md @@ -24,27 +24,31 @@ To describe frame start and end times, use the - Examples: - [Envisat](examples/envisat.json) - - [Sentinel-1](examples/sentinel-1.json) + - [Sentinel-1 GRD EW](examples/sentinel-1-grd-ew.json) + - [Sentinel-1 GRD S4](examples/sentinel-1-grd-s4.json) + - [Sentinel-1 SLC IW](examples/sentinel-1-slc-iw.json) - [JSON Schema](json-schema/schema.json) - [Changelog](./CHANGELOG.md) ## Item Properties or Asset Fields -| Field Name | Type | Description | -| --------------------------- | --------- | ------------------------------------------------------------ | +| Field Name | Type | Description | +| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | sar:instrument_mode | string | **REQUIRED.** The name of the sensor acquisition mode that is commonly used. This should be the short name, if available. For example, `WV` for "Wave mode" of Sentinel-1 and Envisat ASAR satellites. | -| sar:frequency_band | string | **REQUIRED.** The common name for the frequency band to make it easier to search for bands across instruments. See section "Common Frequency Band Names" for a list of accepted names. | -| sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | -| sar:polarizations | \[string] | **REQUIRED.** Any combination of polarizations. | -| sar:product_type | string | ***DEPRECATED** in favor of [`product:type`](https://github.com/stac-extensions/product).* The product type, for example `SSC`, `MGD`, or `SGC` | -| sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | -| sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | -| sar:pixel_spacing_range | number | The range pixel spacing, which is the distance between adjacent pixels perpendicular to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | -| sar:pixel_spacing_azimuth | number | The azimuth pixel spacing, which is the distance between adjacent pixels parallel to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | -| sar:looks_range | number | Number of range looks, which is the number of groups of signal samples (looks) perpendicular to the flight path. | -| sar:looks_azimuth | number | Number of azimuth looks, which is the number of groups of signal samples (looks) parallel to the flight path. | -| sar:looks_equivalent_number | number | The equivalent number of looks (ENL). | -| sar:observation_direction | string | Antenna pointing direction relative to the flight trajectory of the satellite, either `left` or `right`. | +| sar:frequency_band | string | **REQUIRED.** The common name for the frequency band to make it easier to search for bands across instruments. See section "Common Frequency Band Names" for a list of accepted names. | +| sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | +| sar:polarizations | \[string] | **REQUIRED.** Any combination of polarizations. | +| sar:product_type | string | ***DEPRECATED** in favor of [`product:type`](https://github.com/stac-extensions/product).* The product type, for example `SSC`, `MGD`, or `SGC` | +| sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | +| sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | +| sar:pixel_spacing_range | number | The range pixel spacing, which is the distance between adjacent pixels perpendicular to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | +| sar:pixel_spacing_azimuth | number | The azimuth pixel spacing, which is the distance between adjacent pixels parallel to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | +| sar:looks_range | number | Number of range looks, which is the number of groups of signal samples (looks) perpendicular to the flight path. | +| sar:looks_azimuth | number | Number of azimuth looks, which is the number of groups of signal samples (looks) parallel to the flight path. | +| sar:looks_equivalent_number | number | The equivalent number of looks (ENL). | +| sar:observation_direction | string | Antenna pointing direction relative to the flight trajectory of the satellite, either `left` or `right`. | +| sar:relative_burst | number | Identification number that uniquely identifies a burst cycle within each repeat cycle. | +| sar:beam_ids | \[string] | Composition of the swath of the SAR acquision referencing the beam identifiers. | **Note:** In this specification *range* values are meant to be measured perpendicular to the flight path and *azimuth* values are meant to be measured parallel to the flight path. @@ -61,36 +65,42 @@ for instance for `HH+HV` add both `HH` and `HV`. **Important:** In the `properties` of a STAC Item `sar:polarizations` must be a set with unique elements. In assets `sar:polarizations` can contain duplicate elements and, if possible, the polarizations must appear in the same order as in the file. +#### sar:beam_ids + +The `sar:beam_ids` field is used to reference the beam identifiers of the SAR acquisition. According to the mission and the sensor mode, +the beam identifiers can be used to identify the composition of the swath of the SAR acquisition. +The beam identifiers are usually provided in the metadata of the SAR data. + ### Common Frequency Band Names The `sar:frequency_band` is the name that is commonly used to refer to that band's spectral properties. The table below shows the common name based on the wavelength and frequency ranges for several SAR satellites. -| Common Name | Wavelength Range (cm) | Frequency Range (GHz) | Satellites | -| ----------- | --------------------- | --------------------- | ---------- | -| P | 30 - 120 | 0.25 - 1 | | -| L | 15 - 30 | 1 - 2 | ALOS, JERS, NISAR, SOACOM | -| S | 7.5 - 15 | 2 - 4 | HJ-1C | -| C | 3.8 - 7.5 | 4 - 8 | EnviSat, ERS, Radarsat, Risat-1, Sentinel-1 | +| Common Name | Wavelength Range (cm) | Frequency Range (GHz) | Satellites | +| ----------- | --------------------- | --------------------- | -------------------------------------------------- | +| P | 30 - 120 | 0.25 - 1 | | +| L | 15 - 30 | 1 - 2 | ALOS, JERS, NISAR, SOACOM | +| S | 7.5 - 15 | 2 - 4 | HJ-1C | +| C | 3.8 - 7.5 | 4 - 8 | EnviSat, ERS, Radarsat, Risat-1, Sentinel-1 | | X | 2.4 - 3.8 | 8 - 12.5 | Cosmo-SkyMed, TerraSAR-X, TanDEM-X, PAZ, KOMPSat-5 | -| Ku | 1.7 - 2.4 | 12.5 - 18 | | -| K | 1.1 - 1.7 | 18 - 26.5 | | -| Ka | 0.75 - 1.1 | 26.5 - 40 | | +| Ku | 1.7 - 2.4 | 12.5 - 18 | | +| K | 1.1 - 1.7 | 18 - 26.5 | | +| Ka | 0.75 - 1.1 | 26.5 - 40 | | ### Product type The product type for SAR data defines the type of processed data contained in the assets. A list of suggestions for [`product:type`](https://github.com/stac-extensions/product) include: -| product:type | Type | Description | -| ------------ | --------- | ----------- | -| SSC | complex | Single-look Slant-range Complex image (standard SLC) | -| MGD | amplitude | Multilooked Ground-range Detected image | -| GRD | amplitude | Multilooked Ground-range Detected image (used by Sentinel-1) | -| GEC | amplitude | Geocoded Ellipsoid Corrected image | -| GTC | amplitude | Geocoded Terrain Corrected image | -| RTC | amplitude | Geocoded Radiometrically Terrain Corrected image | -| SGC | complex | Single-look Ground projected Complex image | +| product:type | Type | Description | +| ------------ | --------- | --------------------------------------------------------------- | +| SSC | complex | Single-look Slant-range Complex image (standard SLC) | +| MGD | amplitude | Multilooked Ground-range Detected image | +| GRD | amplitude | Multilooked Ground-range Detected image (used by Sentinel-1) | +| GEC | amplitude | Geocoded Ellipsoid Corrected image | +| GTC | amplitude | Geocoded Terrain Corrected image | +| RTC | amplitude | Geocoded Radiometrically Terrain Corrected image | +| SGC | complex | Single-look Ground projected Complex image | | SLC | complex | Single-look Ground projected Complex image (used by Sentinel-1) | This can vary by data provider, who all may use slightly different names. @@ -113,19 +123,19 @@ to provide clients with more information about the assets in an item. The follow This list should not be considered definitive, and implementors are welcome to use other asset roles. If consensus and tooling consolidates around these role names then they will be specified in the future as more standard than just 'best practices'. -| Role Name | Description | -| --------- | ---------------------------------------------------------------------- | -| local-incidence-angle | Points to the local incidence angle file. | -| ellipsoid-incidence-angle | Points to the ellipsoid incidence angle file. | -| noise-power | Points to the noise power file. | -| amplitude | Points to the intensity file with focused SAR data that has been ground range detected (e.g. GRD). | -| magnitude | Points to the intensity file where data are represented as complex numbers containing amplitude and phase information (e.g SLC). | -| sigma0 | Points to the radar backscatter file where data is referenced in ground surface. It is often derived from an `amplitude` or a `magnitude` role asset. | -| beta0 | Points to the radar backscatter file where data is referenced in the slant range plane and is radiometrically calibrated. It is often derived from an `amplitude` or a `magnitude` role asset. | -| gamma0 | Points to the radar backscatter file where data is referenced in the plane perpendicular to the line of sight. It is often derived from an `amplitude` or a `magnitude` role asset. | -| date-offset | Points to the date-offset file. | -| covmat | Points to the Points to the Normalized Polarimetric Radar Covariance Matrix (CovMat) file. | -| prd | Points to the Polarimetric Radar Decomposition (PRD) file. | +| Role Name | Description | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| local-incidence-angle | Points to the local incidence angle file. | +| ellipsoid-incidence-angle | Points to the ellipsoid incidence angle file. | +| noise-power | Points to the noise power file. | +| amplitude | Points to the intensity file with focused SAR data that has been ground range detected (e.g. GRD). | +| magnitude | Points to the intensity file where data are represented as complex numbers containing amplitude and phase information (e.g SLC). | +| sigma0 | Points to the radar backscatter file where data is referenced in ground surface. It is often derived from an `amplitude` or a `magnitude` role asset. | +| beta0 | Points to the radar backscatter file where data is referenced in the slant range plane and is radiometrically calibrated. It is often derived from an `amplitude` or a `magnitude` role asset. | +| gamma0 | Points to the radar backscatter file where data is referenced in the plane perpendicular to the line of sight. It is often derived from an `amplitude` or a `magnitude` role asset. | +| date-offset | Points to the date-offset file. | +| covmat | Points to the Points to the Normalized Polarimetric Radar Covariance Matrix (CovMat) file. | +| prd | Points to the Polarimetric Radar Decomposition (PRD) file. | ## Contributing diff --git a/examples/sentinel-1.json b/examples/sentinel-1-grd-ew.json similarity index 98% rename from examples/sentinel-1.json rename to examples/sentinel-1-grd-ew.json index f51407c..adab1a5 100644 --- a/examples/sentinel-1.json +++ b/examples/sentinel-1-grd-ew.json @@ -28,6 +28,9 @@ "sar:looks_equivalent_number": 2.7, "sar:frequency_band": "C", "sar:center_frequency": 5.405, + "sar:beam_ids": [ + "EW" + ], "product:type": "GRD" }, "geometry": { diff --git a/examples/sentinel-1-grd-s4.json b/examples/sentinel-1-grd-s4.json new file mode 100644 index 0000000..515cd08 --- /dev/null +++ b/examples/sentinel-1-grd-s4.json @@ -0,0 +1,107 @@ +{ + "type": "Feature", + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/sar/v1.0.0/schema.json", + "https://stac-extensions.github.io/sat/v1.0.0/schema.json", + "https://stac-extensions.github.io/processing/v1.2.0/schema.json", + "https://stac-extensions.github.io/product/v0.1.0/schema.json" + ], + "id": "S1A_S4_GRDH_1SDV_20240531T073124_20240531T073144_054112_06947D_072C", + "collection": "SENTINEL-1", + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + -24.488338, + 14.122218 + ], + [ + -24.251352, + 15.285328 + ], + [ + -24.985012, + 15.424737 + ], + [ + -25.217945, + 14.262449 + ], + [ + -24.488338, + 14.122218 + ] + ] + ] + }, + "bbox": [ + -25.217945, + 14.122218, + -24.251352, + 15.424737 + ], + "properties": { + "sat:absolute_orbit": 54112, + "sat:orbit_state": "descending", + "processing:datetime": "2024-05-31T11:25:04.541000+00:00", + "sar:instrument_mode": "SM", + "processing:level": "L1", + "sar:beam_ids": [ + "S4" + ], + "processing:facility": "Production Service-SERCO", + "processing:version": "003.71", + "constellation": "sentinel-1", + "Instruments": [ + "SAR" + ], + "sat:relative_orbit": 140, + "sar:polarizations": [ + "VV", + "VH" + ], + "platforn": "sentinel-1a", + "datetime": "2024-05-31T07:31:24.961Z", + "end_datetime": "2024-05-31T07:31:44.204Z", + "start_datetime": "2024-05-31T07:31:24.961Z", + "product:type": "S4_GRDH_1S-COG", + "sar:frequency_band": "C" + }, + "assets": { + "vh": { + "href": "https://example.com/collections/sentinel-1/items/S1A_S4_GRDH_1SDV_20240531T073124_20240531T073144_054112_06947D_072C/assets/s1a-s4-grd-vh-20240531t073124-20240531t073144-054112-06947d-002-cog.tiff", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "VH Band", + "sar:polarizations": [ + "VH" + ] + }, + "vv": { + "href": "https://example.com/collections/sentinel-1/items/S1A_S4_GRDH_1SDV_20240531T073124_20240531T073144_054112_06947D_072C/assets/s1a-s4-grd-vv-20240531t073124-20240531t073144-054112-06947d-001-cog.tiff", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "VV Band", + "sar:polarizations": [ + "VV" + ] + }, + "thumbnail": { + "href": "https://example.com/collections/sentinel-1/items/S1A_S4_GRDH_1SDV_20240531T073124_20240531T073144_054112_06947D_072C/assets/s1a-s4-grd-thumbnail-20240531t073124-20240531t073144-054112-06947d-072c.png", + "type": "image/png", + "title": "Thumbnail" + } + }, + "links": [ + { + "rel": "root", + "href": "../../catalog.json", + "type": "application/json" + }, + { + "rel": "collection", + "href": "../collection.json", + "type": "application/json" + } + ] +} \ No newline at end of file diff --git a/examples/sentinel-1-slc-iw.json b/examples/sentinel-1-slc-iw.json new file mode 100644 index 0000000..a17a605 --- /dev/null +++ b/examples/sentinel-1-slc-iw.json @@ -0,0 +1,133 @@ +{ + "type": "Feature", + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/alternate-assets/v1.1.0/schema.json", + "https://stac-extensions.github.io/storage/v1.0.0/schema.json" + ], + "id": "S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4.SAFE", + "collection": "SENTINEL-1", + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + 2.356894, + 42.962765 + ], + [ + 5.475332, + 43.360218 + ], + [ + 5.12441, + 44.977203 + ], + [ + 1.917198, + 44.579765 + ], + [ + 2.356894, + 42.962765 + ] + ] + ] + }, + "properties": { + "sat:absolute_orbit": 54381, + "sat:orbit_state": "ascending", + "processing:datetime": "2024-06-18T18:24:17.837861+00:00", + "sar:instrument_mode": "IW", + "processing:level": "L1", + "sar:beam_ids": [ + "IW1", + "IW2", + "IW3" + ], + "processing:facility": "Production Service-SERCO", + "processor:version": "003.80", + "platform": "sentinel-1a", + "instruments": [ + "SAR" + ], + "sat:relative_orbit": 59, + "sar:polarizations": [ + "VV", + "VH" + ], + "constellation": "sentinel-1", + "datetime": "2024-06-18T17:39:36.336Z", + "end_datetime": "2024-06-18T17:40:03.297Z", + "start_datetime": "2024-06-18T17:39:36.336Z", + "product:type": "IW_SLC__1S" + }, + "bbox": [ + 1.917198, + 42.962765, + 5.475332, + 44.977203 + ], + "links": [ + { + "rel": "root", + "href": "../../catalog.json", + "type": "application/json" + }, + { + "rel": "collection", + "href": "../collection.json", + "type": "application/json" + } + ], + "assets": { + "iw1-vh": { + "href": "https://sentinel1.s3.us-west-2.amazonaws.com/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4_IW1_VH.tif", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "IW1 VH Band", + "roles": [ + "data" + ] + }, + "iw1-vv": { + "href": "https://sentinel1.s3.us-west-2.amazonaws.com/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4_IW1_VV.tif", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "IW1 VV Band", + "roles": [ + "data" + ] + }, + "iw2-vh": { + "href": "https://sentinel1.s3.us-west-2.amazonaws.com/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4_IW2_VH.tif", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "IW2 VH Band", + "roles": [ + "data" + ] + }, + "iw2-vv": { + "href": "https://sentinel1.s3.us-west-2.amazonaws.com/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4_IW2_VV.tif", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "IW2 VV Band", + "roles": [ + "data" + ] + }, + "iw3-vh": { + "href": "https://sentinel1.s3.us-west-2.amazonaws.com/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4_IW3_VH.tif", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "IW3 VH Band", + "roles": [ + "data" + ] + }, + "iw3-vv": { + "href": "https://sentinel1.s3.us-west-2.amazonaws.com/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4/S1A_IW_SLC__1SDV_20240618T173936_20240618T174003_054381_069DC0_C1A4_IW3_VV.tif", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "IW3 VV Band", + "roles": [ + "data" + ] + } + } +} \ No newline at end of file diff --git a/json-schema/schema.json b/json-schema/schema.json index 9ab00f4..afeb531 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -118,13 +118,7 @@ "type": "array", "minItems": 1, "items": { - "type": "string", - "enum": [ - "HH", - "VV", - "HV", - "VH" - ] + "$ref": "#/definitions/polarizations" } }, "sar:product_type": { @@ -179,6 +173,13 @@ "left", "right" ] + }, + "sar:beam_ids": { + "title": "Beam identifiers", + "type": "array", + "items": { + "type": "string" + } } }, "patternProperties": { @@ -187,6 +188,15 @@ } }, "additionalProperties": false + }, + "polarizations": { + "type": "string", + "enum": [ + "HH", + "VV", + "HV", + "VH" + ] } } -} +} \ No newline at end of file