Add orbit state vectors (#8)

* Add orbit state vectors * updated changelog * json schema * Remove .vscode/settings.json * feat: Add validation for orbit state vectors with date-time strings * updated versions for validation * Update README.md Co-authored-by: Matthias Mohr <[email protected]> * feat: Update date-time string pattern in JSON schema for improved validation * Update README.md Co-authored-by: Matthias Mohr <[email protected]> * docs: Improve clarity in README regarding state vector file references --------- Co-authored-by: Matthias Mohr <[email protected]>
stac-extensions · Dec 18, 2024 · 1bf9b01 · 1bf9b01
1 parent 902f94e
commit 1bf9b01
Show file tree

Hide file tree

Showing 6 changed files with 125 additions and 18 deletions.
diff --git a/.github/remark.yaml b/.github/remark.yaml
@@ -1,4 +1,6 @@
 plugins:
+# GitHub Flavored Markdown
+  - remark-gfm
 # Check links
   - validate-links
 # Apply some recommended defaults for consistency
@@ -8,6 +10,7 @@ plugins:
 # General formatting
   - - remark-lint-emphasis-marker
     - '*'
+  - remark-lint-no-undefined-references
   - remark-lint-hard-break-spaces
   - remark-lint-blockquote-indentation
   - remark-lint-no-consecutive-blank-lines
@@ -37,7 +40,7 @@ plugins:
   - - remark-lint-unordered-list-marker-style
     - '-'
   - - remark-lint-list-item-indent
-    - space 
+    - space
 # Tables
   - remark-lint-table-pipes
   - remark-lint-no-literal-urls
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added `orbit_cycle` field ([#6](https://github.com/stac-extensions/sat/issues/6))
+- Added sat:orbit_state_vectors field ([#8](https://github.com/stac-extensions/sat/issues/8))
 
 ### Changed
 

diff --git a/README.md b/README.md
@@ -21,14 +21,15 @@ It will often be combined with other extensions that describe the actual data, s
 
 ## Item Properties
 
-| Field Name                            | Type    | Description                                                                                                                                                                                             |
-| ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| sat:platform_international_designator | string  | The International Designator, also known as COSPAR ID, and NSSDCA ID                                                                                                                                    |
-| sat:orbit_state                       | string  | The state of the orbit. Either `ascending` or `descending` for polar orbiting satellites, or `geostationary` for geosynchronous satellites                                                              |
-| sat:orbit_cycle                       | integer | The number of repeat cycle done by the satellite at the time of the acquisition. [Repeat cycle](https://ltb.itc.utwente.nl/page/498/concept/81577) is the time between two successive identical orbits. |
-| sat:absolute_orbit                    | integer | The absolute orbit number at the time of acquisition.                                                                                                                                                   |
-| sat:relative_orbit                    | integer | The relative orbit number at the time of acquisition.                                                                                                                                                   |
-| sat:anx_datetime                      | string  | The [Ascending Node](https://en.wikipedia.org/wiki/Orbital_node) Crossing (ANX) time, in UTC. It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).    |
+| Field Name                            | Type                  | Description                                                                                                                                                                                             |
+| ------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| sat:platform_international_designator | string                | The International Designator, also known as COSPAR ID, and NSSDCA ID                                                                                                                                    |
+| sat:orbit_state                       | string                | The state of the orbit. Either `ascending` or `descending` for polar orbiting satellites, or `geostationary` for geosynchronous satellites                                                              |
+| sat:absolute_orbit                    | integer               | The absolute orbit number at the time of acquisition.                                                                                                                                                   |
+| sat:relative_orbit                    | integer               | The relative orbit number at the time of acquisition.                                                                                                                                                   |
+| sat:orbit_cycle                       | integer               | The number of repeat cycle done by the satellite at the time of the acquisition. [Repeat cycle](https://ltb.itc.utwente.nl/page/498/concept/81577) is the time between two successive identical orbits. |
+| sat:orbit_state_vectors               | Map<string, \[number]> | The state vectors of the satellite at the time of acquisition.                                                                                                                                         |
+| sat:anx_datetime                      | string                | The [Ascending Node](https://en.wikipedia.org/wiki/Orbital_node) Crossing (ANX) time, in UTC. It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).    |
 
 *At least one of the fields must be specified.*
 
@@ -73,6 +74,61 @@ The repeat cycle of the satellite. The repeat cycle is the number of orbits requ
 position in its orbit. It is used to determine the relative orbit number. For instance, a satellite with a 16-day repeat cycle
 will have 16 relative orbits.
 
+#### sat:orbit_state_vectors
+
+The state vectors of the satellite at the time of acquisition. The state vectors are a set of parameters that describe the
+position and velocity of the satellite at a given time. The state vectors are used to compute the position of the satellite
+at any time during the acquisition. 
+The state vectors are usually provided in the [ECI](https://en.wikipedia.org/wiki/Earth-centered_inertial) frame.
+The field is a map where the key is the time of the state vector and the value is an array of 6 elements (optional 9).
+The first 3 elements are the position of the satellite in meters and the last 3 elements are the velocity of the satellite in meters per second.
+The optional 3 additional elements are the acceleration of the satellite in meters per second squared.
+
+Example:
+
+```json
+{
+  "sat:orbit_state_vectors": {
+    "2015-03-05T05:19:40.103Z": [
+      5082939.4189831074,
+      1595651.7369050409,
+      4648033.5588545678,
+      5173.8779329387489,
+      -269.5432365485845,
+      -5550.246440359806
+    ],
+    "2015-03-05T05:19:45.449Z": [
+      5110519.0376543682,
+      1594174.328112772,
+      4618284.7202579351,
+      5143.1200754073143,
+      -283.12343661734587,
+      -5578.2160610647188
+    ],
+    "2015-03-05T05:19:50.449Z": [
+      5136162.3887853986,
+      1592727.024757518,
+      4590328.5904560406,
+      5114.1961953273549,
+      -295.79384304587683,
+      -5604.2108611458289
+    ]
+  }
+}
+```
+
+It is recommended that the state vectors are provided in a separate file and referenced as a link with relationship type `sat:osv`.
+The file should correspond to the example above.
+
+## Relation types
+
+The following types should be used as applicable `rel` types in the
+[Link Object](https://github.com/radiantearth/stac-spec/tree/master/item-spec/item-spec.md#link-object).
+
+| Type    | Description                                        |
+| ------- | -------------------------------------------------- |
+| sat:osv | Link to a file containing the orbit state vectors. |
+
 ## Contributing
 
 All contributions are subject to the

diff --git a/examples/example-sentinel1.json b/examples/example-sentinel1.json
@@ -55,6 +55,32 @@
     "sat:relative_orbit": 95,
     "sat:anx_datetime": "2015-03-05T04:41:46.5788740Z",
     "sat:orbit_cycle": 407,
+    "sat:orbit_state_vectors": {
+      "2015-03-05T05:19:40.103Z": [
+        5082939.418983107,
+        1595651.736905041,
+        4648033.558854568,
+        5173.877932938749,
+        -269.5432365485845,
+        -5550.246440359806
+      ],
+      "2015-03-05T05:19:45.449Z": [
+        5110519.037654368,
+        1594174.328112772,
+        4618284.720257935,
+        5143.120075407314,
+        -283.1234366173459,
+        -5578.216061064719
+      ],
+      "2015-03-05T05:19:50.449Z": [
+        5136162.388785399,
+        1592727.024757518,
+        4590328.590456041,
+        5114.196195327355,
+        -295.7938430458768,
+        -5604.210861145829
+      ]
+    },
     "sar:instrument_mode": "IW",
     "sar:polarizations": [
       "VV",

diff --git a/json-schema/schema.json b/json-schema/schema.json
@@ -61,6 +61,11 @@
                   "required": [
                     "sat:orbit_cycle"
                   ]
+                },
+                {
+                  "required": [
+                    "sat:orbit_state_vectors"
+                  ]
                 }
               ]
             },
@@ -133,6 +138,21 @@
         "sat:orbit_cycle": {
           "type": "integer",
           "minimum": 1
+        },
+        "sat:orbit_state_vectors": {
+          "type": "object",
+          "$comment": "The key is a date-time string, and the value is an array of numbers.",
+          "patternProperties": {
+            "^(\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d\\.\\d+([+-][0-2]\\d:[0-5]\\d|Z))|(\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d([+-][0-2]\\d:[0-5]\\d|Z))|(\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d([+-][0-2]\\d:[0-5]\\d|Z))$": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 6,
+              "maxItems": 9
+            }
+          },
+          "additionalProperties": false
         }
       },
       "patternProperties": {

diff --git a/package.json b/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "stac-extensions",
+  "name": "stac-extension-sat",
   "version": "1.0.0",
   "scripts": {
     "test": "npm run check-markdown && npm run check-examples",
@@ -8,13 +8,14 @@
     "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/sat/v1.0.0/schema.json=./json-schema/schema.json"
   },
   "dependencies": {
-    "remark-cli": "^8.0.0",
-    "remark-lint": "^7.0.0",
-    "remark-lint-no-html": "^2.0.0",
-    "remark-preset-lint-consistent": "^3.0.0",
-    "remark-preset-lint-markdown-style-guide": "^3.0.0",
-    "remark-preset-lint-recommended": "^4.0.0",
-    "remark-validate-links": "^10.0.0",
-    "stac-node-validator": "^1.0.0"
+    "remark-cli": "^12.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-lint": "^9.1.2",
+    "remark-lint-no-html": "^3.1.2",
+    "remark-preset-lint-consistent": "^5.1.2",
+    "remark-preset-lint-markdown-style-guide": "^5.1.3",
+    "remark-preset-lint-recommended": "^6.1.3",
+    "remark-validate-links": "^13.0.0",
+    "stac-node-validator": "^1.3.0"
   }
 }