Skip to content

Commit a4a8fd3

Browse files
m-mohrm-mohr
committed
Deprecate sar:instrument_mode in favor of altm:instrument_mode, add instrument related best practices
1 parent ca48c1e commit a4a8fd3

File tree

3 files changed

+51
-31
lines changed

3 files changed

+51
-31
lines changed

‎CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1010
### Added
1111

1212
- Added `LH`, `LV`, `RH`, `RV`, `CH` and `CV` enumerations to `sar:polarizations` to support compact polarization.
13+
- Best practices for `altm:instrument_mode` and `altm:instrument_type`
14+
15+
### Deprecated
16+
17+
- `sar:instrument_mode` in favor of `altm:instrument_mode`
1318

1419
## [v1.1.0] - 2024-12-18
1520

‎README.md

Lines changed: 46 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -32,26 +32,37 @@ To describe frame start and end times, use the
3232

3333
## Item Properties or Asset Fields
3434

35-
| Field Name | Type | Description |
36-
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
37-
| 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. |
38-
| 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. |
39-
| sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). |
40-
| sar:polarizations | \[string] | **REQUIRED.** Any combination of polarizations. |
41-
| 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` |
42-
| 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). |
43-
| 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). |
44-
| 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`. |
45-
| 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`. |
46-
| sar:looks_range | number | Number of range looks, which is the number of groups of signal samples (looks) perpendicular to the flight path. |
47-
| sar:looks_azimuth | number | Number of azimuth looks, which is the number of groups of signal samples (looks) parallel to the flight path. |
48-
| sar:looks_equivalent_number | number | The equivalent number of looks (ENL). |
49-
| sar:observation_direction | string | Antenna pointing direction relative to the flight trajectory of the satellite, either `left` or `right`. |
50-
| sar:relative_burst | number | Identification number that uniquely identifies a burst cycle within each repeat cycle. |
51-
| sar:beam_ids | \[string] | Composition of the swath of the SAR acquision referencing the beam identifiers. |
52-
53-
**Note:** In this specification *range* values are meant to be measured perpendicular to the flight path and *azimuth* values
54-
are meant to be measured parallel to the flight path.
35+
> \[!IMPORTANT]
36+
>
37+
> In this specification *range* values are meant to be measured perpendicular to the flight path
38+
> and *azimuth* values are meant to be measured parallel to the flight path.
39+
40+
| Field Name | Type | Description |
41+
| --------------------------- | --------- | ----------- |
42+
| sar:polarizations | \[string] | **REQUIRED.** Any combination of polarizations. |
43+
| 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. |
44+
| sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). |
45+
| 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). |
46+
| 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). |
47+
| 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`. |
48+
| 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`. |
49+
| sar:looks_range | number | Number of range looks, which is the number of groups of signal samples (looks) perpendicular to the flight path. |
50+
| sar:looks_azimuth | number | Number of azimuth looks, which is the number of groups of signal samples (looks) parallel to the flight path. |
51+
| sar:looks_equivalent_number | number | The equivalent number of looks (ENL). |
52+
| sar:observation_direction | string | Antenna pointing direction relative to the flight trajectory of the satellite, either `left` or `right`. |
53+
| sar:relative_burst | number | Identification number that uniquely identifies a burst cycle within each repeat cycle. |
54+
| sar:beam_ids | \[string] | Composition of the swath of the SAR acquision referencing the beam identifiers. |
55+
| sar:product_type | string | ***DEPRECATED** in favor of [`product:type`](https://github.com/stac-extensions/product).* See [Product type](#product-type). |
56+
| sar:instrument_mode | string | ***DEPRECATED** in favor of [`altm:instrument_mode`](https://github.com/stac-extensions/altimetry).* See [Instrument details](#instrument-details). |
57+
58+
> \[!CAUTION]
59+
>
60+
> - v1.0 of the extension did require `sar:product_type` and `sar:instrument_mode`.
61+
> - v1.1 deprecates `sar:product_type` and it's not required any longer, but
62+
> [`product:type`](https://github.com/stac-extensions/product) is **strongly recommended**.
63+
> - v1.2 deprecates `sar:instrument_mode` and it's not required any longer, but
64+
> [`altm:instrument_mode` and `altm:instrument_type`](https://github.com/stac-extensions/altimetry) are **strongly recommended**.
65+
> - v2.0 may require `product:type`, `altm:instrument_mode`, and `altm:instrument_type` as part of this extension and is going to remove `sar:product_type` and `sar:instrument_mode`.
5566
5667
### Additional Field Information
5768

@@ -62,8 +73,10 @@ Specifies a single polarization or a polarization combination. For single polari
6273
For dual polarized radars and alternating polarization, add the corresponding polarizations to the array.
6374
For instance, for `HH+HV`, add both `HH` and `HV`.
6475

65-
**Important:** In the `properties` of a STAC Item `sar:polarizations` must be a set with unique elements.
66-
In assets `sar:polarizations` can contain duplicate elements and, if possible, the polarizations must appear in the same order as in the file.
76+
> \[!IMPORTANT]
77+
>
78+
> In the `properties` of a STAC Item `sar:polarizations` must be a set with unique elements.
79+
> In assets `sar:polarizations` can contain duplicate elements and, if possible, the polarizations must appear in the same order as in the file.
6780
6881
#### sar:beam_ids
6982

@@ -106,11 +119,14 @@ A list of suggestions for [`product:type`](https://github.com/stac-extensions/pr
106119
This can vary by data provider, who all may use slightly different names.
107120
Sentinel-1 for instance uses `GRD`, which is the same as the more general `MGD` and `SLC` instead of `SGC`.
108121

109-
> [!NOTE]
110-
>
111-
> - v1.0 of the extension did require `sar:product_type`.
112-
> - v1.1 deprecates `sar:product_type` and it's not required any longer, but `product:type` is **strongly recommended**.
113-
> - v2.0 will require `product:type` as part of this extension and remove `sar:product_type`.
122+
### Instrument details
123+
124+
The instrument type and mode can be provided using the [Altimetry Extension](https://github.com/stac-extensions/altimetry):
125+
126+
- `altm:instrument_type`: The instrument type, must be set to `sar`,
127+
- `altm:instrument_mode`: The name of the sensor acquisition mode that is commonly used.
128+
This should be the short name, if available.
129+
For example, `WV` for "Wave mode" of Sentinel-1 and Envisat ASAR satellites.
114130

115131
### Date and Time
116132

@@ -119,9 +135,9 @@ The center time of the frame should be specified with the `datetime` property fo
119135

120136
## Best Practices
121137

122-
One of the emerging best practices is to use [Asset Roles](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#asset-roles)
123-
to provide clients with more information about the assets in an item. The following list includes a shared vocabulary for some common SAR assets.
124-
This list should not be considered definitive, and implementors are welcome to use other asset roles. If consensus and tooling consolidates around
138+
One of the emerging best practices is to use [Asset Roles](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#asset-roles)
139+
to provide clients with more information about the assets in an item. The following list includes a shared vocabulary for some common SAR assets.
140+
This list should not be considered definitive, and implementors are welcome to use other asset roles. If consensus and tooling consolidates around
125141
these role names then they will be specified in the future as more standard than just 'best practices'.
126142

127143
| Role Name | Description |

‎json-schema/schema.json

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,6 @@
3232
"allOf": [
3333
{
3434
"required": [
35-
"sar:instrument_mode",
3635
"sar:frequency_band",
3736
"sar:polarizations"
3837
],

0 commit comments

Comments
 (0)