From 3f2d7cfffc2a72fb0feb289e75e2c905cd3e310b Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Wed, 19 Apr 2023 15:18:39 -0400 Subject: [PATCH 1/8] first cut --- sigmf-spec.md | 63 +++++++++++++++++++++++++++------------------------ 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/sigmf-spec.md b/sigmf-spec.md index 97df325..49ac938 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -361,7 +361,7 @@ Object: | `dataset` | false | string | The full filename of the Dataset file this Metadata file describes.| | `trailing_bytes`| false | uint | The number of bytes to ignore at the end of a Non-Conforming Dataset file.| | `metadata_only` | false | bool | Indicates the Metadata file is intentionally distributed without the Dataset.| -| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system.| +| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system. Using geolocation within captures is preferred | | `extensions` | false | array | A list of JSON Objects describing extensions used by this Recording.| | `collection` | false | string | The base filename of a `collection` with which this Recording is associated.| @@ -402,35 +402,7 @@ conjunction with Non-Conforming Datasets or the `core:dataset` field. **The `geolocation` Field** -The `core:geolocation` field in the Global Object is used to store the -location of the recording system. The location is stored as a single -[RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.txt) GeoJSON `point` Object -using the convention defined by [RFC 5870](https://www.rfc-editor.org/rfc/rfc5870.txt). -Per the GeoJSON specification, the point coordinates use the WGS84 coordinate -reference system and are `longitude`, `latitude` (REQUIRED, in decimal degrees), -and `altitude` (OPTIONAL, in meters above the WGS84 ellipsoid) - in that order. An -example including the altitude field is shown below: - -```JSON - "global": { - ... - "core:geolocation": { - "type": "Point", - "coordinates": [-107.6183682, 34.0787916, 2120.0] - } - ... - } -``` - -GeoJSON permits the use of *Foreign Members* in GeoJSON documents per RFC 7946 -Section 6.1. Because the SigMF requirement for the `geolocation` field is to be -a valid GeoJSON `point` Object, users MAY include *Foreign Member* fields here -for user-defined purposes (position valid indication, GNSS SV counts, dillution -of precision, accuracy, etc). It is strongly RECOMMENDED that all fields be -documented in a SigMF Extension document. - -*Note:* Objects named `geometry` or `properties` are prohibited Foreign Members -as specified in RFC 7946 Section 7.1. +See the `geolocation` field within `Captures`. While it can also be provided within Global, Captures is preferred. **The `extensions` Field** @@ -606,6 +578,37 @@ The ABNF description is: Thus, timestamps take the form of `YYYY-MM-DDTHH:MM:SS.SSSZ`, where any number of digits for fractional seconds is permitted. +**The `geolocation` Field** + +The `core:geolocation` field in the Captures or Global Object (Captures is preferred) is used to store the +location of the recording system. The location is stored as a single +[RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.txt) GeoJSON `point` Object +using the convention defined by [RFC 5870](https://www.rfc-editor.org/rfc/rfc5870.txt). +Per the GeoJSON specification, the point coordinates use the WGS84 coordinate +reference system and are `longitude`, `latitude` (REQUIRED, in decimal degrees), +and `altitude` (OPTIONAL, in meters above the WGS84 ellipsoid) - in that order. An +example including the altitude field is shown below: + +```JSON + ... + "core:geolocation": { + "type": "Point", + "coordinates": [-107.6183682, 34.0787916, 2120.0] + } + ... + } +``` + +GeoJSON permits the use of *Foreign Members* in GeoJSON documents per RFC 7946 +Section 6.1. Because the SigMF requirement for the `geolocation` field is to be +a valid GeoJSON `point` Object, users MAY include *Foreign Member* fields here +for user-defined purposes (position valid indication, GNSS SV counts, dillution +of precision, accuracy, etc). It is strongly RECOMMENDED that all fields be +documented in a SigMF Extension document. + +*Note:* Objects named `geometry` or `properties` are prohibited Foreign Members +as specified in RFC 7946 Section 7.1. + #### Annotations Array The `annotations` value is an array of `annotation` Objects that describe From ff3ab616086d94c362a37286c4a644b1fcaf2d86 Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Wed, 19 Apr 2023 15:19:47 -0400 Subject: [PATCH 2/8] added to list --- sigmf-spec.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sigmf-spec.md b/sigmf-spec.md index 49ac938..71243cf 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -470,6 +470,7 @@ Segment Objects: | `header_bytes` | false | uint | The number of bytes preceding a chunk of samples that are not sample data, used for NCDs. | | `frequency` | false | double | The center frequency of the signal in Hz. | | `datetime` | false | string | An ISO-8601 string indicating the timestamp of the sample index specified by `sample_start`.| +| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system. | **The `sample_start` Field** From abfa82ff70ea2cf59f2acac14a8e5db7c639ceed Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Wed, 19 Apr 2023 15:20:21 -0400 Subject: [PATCH 3/8] Captures --- sigmf-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sigmf-spec.md b/sigmf-spec.md index 71243cf..695ae2a 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -361,7 +361,7 @@ Object: | `dataset` | false | string | The full filename of the Dataset file this Metadata file describes.| | `trailing_bytes`| false | uint | The number of bytes to ignore at the end of a Non-Conforming Dataset file.| | `metadata_only` | false | bool | Indicates the Metadata file is intentionally distributed without the Dataset.| -| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system. Using geolocation within captures is preferred | +| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system. Using geolocation within Captures is preferred | | `extensions` | false | array | A list of JSON Objects describing extensions used by this Recording.| | `collection` | false | string | The base filename of a `collection` with which this Recording is associated.| From 54da29d303a0b8a0ae2eb198a97daeb30a5ab7dd Mon Sep 17 00:00:00 2001 From: Jacob Gilbert Date: Thu, 20 Apr 2023 16:45:50 -0600 Subject: [PATCH 4/8] formatting --- sigmf-spec.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/sigmf-spec.md b/sigmf-spec.md index 695ae2a..597f415 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -361,7 +361,7 @@ Object: | `dataset` | false | string | The full filename of the Dataset file this Metadata file describes.| | `trailing_bytes`| false | uint | The number of bytes to ignore at the end of a Non-Conforming Dataset file.| | `metadata_only` | false | bool | Indicates the Metadata file is intentionally distributed without the Dataset.| -| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system. Using geolocation within Captures is preferred | +| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system, using the Captures scope `geolocation` field is preferred.| | `extensions` | false | array | A list of JSON Objects describing extensions used by this Recording.| | `collection` | false | string | The base filename of a `collection` with which this Recording is associated.| @@ -402,7 +402,9 @@ conjunction with Non-Conforming Datasets or the `core:dataset` field. **The `geolocation` Field** -See the `geolocation` field within `Captures`. While it can also be provided within Global, Captures is preferred. +See the `geolocation` field within the Captures metadata. While fixed recording +systems may still provide position information within the Global object, using +the Captures scope `geolocation` is preferred. **The `extensions` Field** @@ -447,7 +449,7 @@ field to associate up to the relevant `sigmf-collection` file. #### Captures Array -The `captures` value is an array of `capture segment` Objects that describe the +The `captures` Object is an array of `capture segment` Objects that describe the parameters of the signal capture. It MUST be sorted by the value of each capture segment's `core:sample_start` key, ascending. @@ -470,7 +472,7 @@ Segment Objects: | `header_bytes` | false | uint | The number of bytes preceding a chunk of samples that are not sample data, used for NCDs. | | `frequency` | false | double | The center frequency of the signal in Hz. | | `datetime` | false | string | An ISO-8601 string indicating the timestamp of the sample index specified by `sample_start`.| -| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system. | +| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system.| **The `sample_start` Field** @@ -581,14 +583,15 @@ of digits for fractional seconds is permitted. **The `geolocation` Field** -The `core:geolocation` field in the Captures or Global Object (Captures is preferred) is used to store the -location of the recording system. The location is stored as a single -[RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.txt) GeoJSON `point` Object -using the convention defined by [RFC 5870](https://www.rfc-editor.org/rfc/rfc5870.txt). -Per the GeoJSON specification, the point coordinates use the WGS84 coordinate -reference system and are `longitude`, `latitude` (REQUIRED, in decimal degrees), -and `altitude` (OPTIONAL, in meters above the WGS84 ellipsoid) - in that order. An -example including the altitude field is shown below: +The `core:geolocation` field in the Captures (preferred) or Global object is +used to store the location of the recording system. The location is stored as a +single [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.txt) GeoJSON `point` +Object using the convention defined by [RFC +5870](https://www.rfc-editor.org/rfc/rfc5870.txt). Per the GeoJSON +specification, the point coordinates use the WGS84 coordinate reference system +and are `longitude`, `latitude` (REQUIRED, in decimal degrees), and `altitude` +(OPTIONAL, in meters above the WGS84 ellipsoid) - in that order. An example +including the altitude field is shown below: ```JSON ... From 130db14df6afd6c0def411a6a7a2b40e064a4d46 Mon Sep 17 00:00:00 2001 From: Jacob Gilbert Date: Thu, 24 Aug 2023 06:34:58 -0600 Subject: [PATCH 5/8] updating language --- sigmf-spec.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/sigmf-spec.md b/sigmf-spec.md index 597f415..3c09f07 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -472,7 +472,7 @@ Segment Objects: | `header_bytes` | false | uint | The number of bytes preceding a chunk of samples that are not sample data, used for NCDs. | | `frequency` | false | double | The center frequency of the signal in Hz. | | `datetime` | false | string | An ISO-8601 string indicating the timestamp of the sample index specified by `sample_start`.| -| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system.| +| `geolocation` | false | GeoJSON `point` Object | The location of the Recording system at the start of this Captures segment.| **The `sample_start` Field** @@ -584,9 +584,11 @@ of digits for fractional seconds is permitted. **The `geolocation` Field** The `core:geolocation` field in the Captures (preferred) or Global object is -used to store the location of the recording system. The location is stored as a -single [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.txt) GeoJSON `point` -Object using the convention defined by [RFC +used to store the location of the recording system at the first sample in the +captures segment. For emitters that are moving, this provides a means to manage +location through different captures segments. The location is stored as a single +[RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.txt) GeoJSON `point` Object +using the convention defined by [RFC 5870](https://www.rfc-editor.org/rfc/rfc5870.txt). Per the GeoJSON specification, the point coordinates use the WGS84 coordinate reference system and are `longitude`, `latitude` (REQUIRED, in decimal degrees), and `altitude` From 4a9611b80a4bc5caea60660aea7b98ec36481aa2 Mon Sep 17 00:00:00 2001 From: Jacob Gilbert Date: Thu, 24 Aug 2023 07:06:13 -0600 Subject: [PATCH 6/8] updating language --- sigmf-spec.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/sigmf-spec.md b/sigmf-spec.md index 3c09f07..5dc1c4d 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -585,15 +585,16 @@ of digits for fractional seconds is permitted. The `core:geolocation` field in the Captures (preferred) or Global object is used to store the location of the recording system at the first sample in the -captures segment. For emitters that are moving, this provides a means to manage -location through different captures segments. The location is stored as a single -[RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.txt) GeoJSON `point` Object -using the convention defined by [RFC -5870](https://www.rfc-editor.org/rfc/rfc5870.txt). Per the GeoJSON +captures segment. For moving emitters, this provides a rudimentary means to +manage location through different captures segments. + +The geolocation field is a GeoJSON `point` Object defined by section 3.1.2 of +[RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.txt). Per the GeoJSON specification, the point coordinates use the WGS84 coordinate reference system and are `longitude`, `latitude` (REQUIRED, in decimal degrees), and `altitude` -(OPTIONAL, in meters above the WGS84 ellipsoid) - in that order. An example -including the altitude field is shown below: +(OPTIONAL, in meters above the WGS84 ellipsoid) - in that order. + +An example including the altitude field is shown below: ```JSON ... From 97c5b94fd193967d870cb2c424f2170a6f58cee4 Mon Sep 17 00:00:00 2001 From: Jacob Gilbert Date: Thu, 24 Aug 2023 07:08:45 -0600 Subject: [PATCH 7/8] updating language --- sigmf-spec.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/sigmf-spec.md b/sigmf-spec.md index 5dc1c4d..b9c32b1 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -403,8 +403,10 @@ conjunction with Non-Conforming Datasets or the `core:dataset` field. **The `geolocation` Field** See the `geolocation` field within the Captures metadata. While fixed recording -systems may still provide position information within the Global object, using -the Captures scope `geolocation` is preferred. +systems may still provide position information within the Global object. While +using the Captures scope `geolocation` is preferred, it is RECOMMENDED that +applications check and use this field if the Captures `geolocation` field is not +present. **The `extensions` Field** @@ -586,7 +588,7 @@ of digits for fractional seconds is permitted. The `core:geolocation` field in the Captures (preferred) or Global object is used to store the location of the recording system at the first sample in the captures segment. For moving emitters, this provides a rudimentary means to -manage location through different captures segments. +manage location through different captures segments. The geolocation field is a GeoJSON `point` Object defined by section 3.1.2 of [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946.txt). Per the GeoJSON From f6e377df5ae6d75004356af38746f92501b7f0a3 Mon Sep 17 00:00:00 2001 From: Jacob Gilbert Date: Thu, 24 Aug 2023 10:27:16 -0600 Subject: [PATCH 8/8] updating language --- sigmf-spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sigmf-spec.md b/sigmf-spec.md index b9c32b1..4581d97 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -402,9 +402,9 @@ conjunction with Non-Conforming Datasets or the `core:dataset` field. **The `geolocation` Field** -See the `geolocation` field within the Captures metadata. While fixed recording -systems may still provide position information within the Global object. While -using the Captures scope `geolocation` is preferred, it is RECOMMENDED that +See the `geolocation` field within the Captures metadata. While using the +Captures scope `geolocation` is preferred, fixed recording systems may still +provide position information within the Global object so it is RECOMMENDED that applications check and use this field if the Captures `geolocation` field is not present.