diff --git a/sigmf-spec.md b/sigmf-spec.md index 97df325..4581d97 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 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,35 +402,11 @@ 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 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. **The `extensions` Field** @@ -475,7 +451,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. @@ -498,6 +474,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 at the start of this Captures segment.| **The `sample_start` Field** @@ -606,6 +583,41 @@ 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 (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. + +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: + +```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