From 69b4932c04f9dff00cee4bcdf04e4efb9a7a2727 Mon Sep 17 00:00:00 2001 From: romanziske <61801328+romanziske@users.noreply.github.com> Date: Tue, 20 Aug 2024 04:24:13 +0200 Subject: [PATCH 01/11] Update wording in annotations array section, added latex build artefacts to .gitignore removed unused packages (#320) * updated wording an annotations array * Add new latex build artefacts to .gitignore * Remove unused import in docs-generator.py --- .gitignore | 2 ++ docs-generator.py | 1 - sigmf-schema.json | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 7bcf43d..74aa7ea 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,8 @@ sigmf-spec.pdf sigmf-spec.out sigmf-spec.log sigmf-spec.aux +sigmf-spec.fls +sigmf-spec.fdb_latexmk svg-inkscape/ sigmf-spec.html main.css \ No newline at end of file diff --git a/docs-generator.py b/docs-generator.py index 9957195..46f7e24 100644 --- a/docs-generator.py +++ b/docs-generator.py @@ -1,6 +1,5 @@ import json import subprocess -import time from pylatex import (Command, Document, Figure, Package, Section, Subsection, Subsubsection, Tabular) diff --git a/sigmf-schema.json b/sigmf-schema.json index 86f451b..0b7903f 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -209,7 +209,7 @@ }, "annotations": { "default": [], - "description": "The `annotations` value is an array of annotation segment objects that describe anything regarding the signal data not part of the Captures and Global objects. It MUST be sorted by the value of each Annotation Segment's `core:sample_start` key, ascending. Annotation segment Objects contain key/value pairs and MUST contain a `core:sample_start` key/value pair, which indicates the first index at which the rest of the Segment's key/value pairs apply. There is no limit to the number of annotations that can apply to the same group of samples. If two annotations have the same `sample_start`, there is no defined ordering between them. If `sample_count` is not provided, it SHOULD be assumed that the annotation applies from `sample_start` through the end of the Dataset, in all other cases `sample_count` MUST be provided. ", + "description": "The `annotations` value is an array of annotation segment objects that describe anything regarding the signal data not part of the Captures and Global objects. It MUST be sorted by the value of each Annotation Segment's `core:sample_start` key, ascending. Annotation segment Objects contain key/value pairs and MUST contain a `core:sample_start` key/value pair, which indicates the first index at which the rest of the Segment's key/value pairs apply. There is no limit to the number of annotations that can apply to the same group of samples. If two annotations have the same `sample_start`, there is no defined ordering between them. If two annotations have the same `sample_start`, there is no defined ordering between them. If `sample_count` is not provided, it SHOULD be assumed that the annotation applies from `sample_start` through the end of the corresponding capture, in all other cases `sample_count` MUST be provided. ", "type": "array", "additionalItems": true, "items": { From 079cbb41ce7d0e0aca884c8d7d9db1f9c7a3c465 Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Wed, 28 Aug 2024 23:47:30 -0400 Subject: [PATCH 02/11] num_channels wording and updated github action to be able to view pdf/html as an artifact (#319) * num_channels wording * Update additional_content.md * Update generate_docs_pr.yml * Update generate_docs_pr.yml * Update README.md * Update additional_content.md * Update additional_content.md * Update .github/workflows/generate_docs_pr.yml Co-authored-by: Teque5 * Update README.md Co-authored-by: Teque5 * Update generate_docs.yml * Update generate_docs_pr.yml * Update generate_docs.yml * Update generate_docs_pr.yml * Update generate_docs.yml * Update generate_docs_pr.yml --------- Co-authored-by: Teque5 --- .github/workflows/generate_docs.yml | 4 +++- .github/workflows/generate_docs_pr.yml | 9 ++++++++- README.md | 2 ++ additional_content.md | 13 +++---------- sigmf-schema.json | 4 ++-- 5 files changed, 18 insertions(+), 14 deletions(-) diff --git a/.github/workflows/generate_docs.yml b/.github/workflows/generate_docs.yml index 2f9fa6e..53eb770 100644 --- a/.github/workflows/generate_docs.yml +++ b/.github/workflows/generate_docs.yml @@ -46,10 +46,12 @@ jobs: run: pandoc -v - name: Rename to index.html run: mv sigmf-spec.html index.html + - name: Remove pandoc lib + run: rm -r pandoc* - name: Setup Pages uses: actions/configure-pages@v5 - name: Upload artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@v3.0.1 with: path: '.' # Upload entire repository for now, TODO ONLY UPLOAD THE HTML AND PDF IN THE LONG TERM - name: Deploy to GitHub Pages diff --git a/.github/workflows/generate_docs_pr.yml b/.github/workflows/generate_docs_pr.yml index 51432c3..3fb8cda 100644 --- a/.github/workflows/generate_docs_pr.yml +++ b/.github/workflows/generate_docs_pr.yml @@ -1,4 +1,4 @@ -name: Build docs to check for errors +name: Build docs [PR] on: pull_request: @@ -29,3 +29,10 @@ jobs: run: ls -la - name: Check pandoc version run: pandoc -v + - name: Remove pandoc lib + run: rm -r pandoc* + - name: Upload output as artifact + uses: actions/upload-artifact@v4 + with: + name: compiled_docs + path: '.' diff --git a/README.md b/README.md index 246e98d..2c5ebfe 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,8 @@ The main pdf is generated using the following content: The script `docs-generator.py` uses Python, PyLaTeX, Pandoc, and Inkscape to create the specifications document in PDF and HTML formats. +Instead of generating the docs locally, you can make your change (e.g., using GitHub's web interface), open up a PR, and then under GitHub's "Actions" menu at the top, click the run that corresponds to your PR, scroll down to "Artifacts", download the artifact named "compiled_docs", unzip it, and you should be able to see the html and pdf. + ## Frequently Asked Questions ### Is this a GNU Radio effort? diff --git a/additional_content.md b/additional_content.md index 4029c77..be35614 100644 --- a/additional_content.md +++ b/additional_content.md @@ -160,16 +160,9 @@ The samples SHOULD be written to the Dataset file without separation, and the Dataset file MUST NOT contain any other characters (e.g., delimiters, whitespace, line-endings, EOF characters). -Complex samples MUST be interleaved, with the in-phase component first (i.e., -`I[0]` `Q[0]` `I[1]` `Q[1]` ... `I[n]` `Q[n]`). When `core:num_channels` in the -Global Object (described below) indicates that the Recording contains more than one channel, -samples from those channels MUST be interleaved in the same manner, with -the same index from each channel's sample serially in the Recording. For -example, a Recording with two channels of `ri16_le` representing real-valued -audio data from a stereo Recording and here labeled `L` for left and `R` for -right, the data MUST appear as `L[0]` `R[0]` `L[1]` `R[1]` ... `L[n]` `R[n]`. -The data type specified by `core:data_type` applies to all channels of data -both real and imaginary parts. +Complex samples MUST be interleaved, with the in-phase component first (i.e., `I[0]` `Q[0]` `I[1]` `Q[1]` ... `I[n]` `Q[n]`). + +When `core:num_channels` in the Global Object (described below) indicates that the Recording contains more than one channel, samples from those channels MUST be interleaved in the same manner with the same index from each channel's sample serially in the Recording. This is intended for use in situations where the native SigMF datatypes are not appropriate, such as audio or oscilloscope channels. For best compatibility, is RECOMMENDED that native complex type datatypes be used whenever possible (e.g.: RF data). The data type specified by core:data_type applies to all channels of data. For multiple channels of IQ data (e.g., array processing), it is RECOMMENDED to use SigMF Collections. \subsection{SigMF Metadata Format} diff --git a/sigmf-schema.json b/sigmf-schema.json index 0b7903f..a0f755e 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -65,7 +65,7 @@ "type": "string" }, "core:num_channels": { - "description": "Total number of interleaved channels in the Dataset file; if omitted this is implied to be 1. For multiple channels of IQ data, it is RECOMMENDED to use SigMF Collections instead of num_channels for widest application support.", + "description": "Number of interleaved channels in the Dataset file, if omitted this is implied to be 1, for multiple channels of IQ data, it is RECOMMENDED to use SigMF Collections instead of num_channels for widest application support.", "default": 1, "minimum": 1, "maximum": 1000, @@ -124,7 +124,7 @@ } }, "core:extensions": { - "description": "The `core:extensions` field in the Global Object is an array of extension objects that describe SigMF extensions. Extension Objects MUST contain the three key/value pairs defined below, and MUST NOT contain any other fields. \\rowcolors{1}{}{lightblue}\\begin{center}\\begin{tabular}{lllp{3.8in}} \\toprule \\textbf{Name} & \\textbf{Required} & \\textbf{Type} & \\textbf{Description} \\\\ \\midrule name & true & string & The name of the SigMF extension namespace. \\\\ version & true & string & The version of the extension namespace specification used. \\\\ optional & true & boolean & If this field is `false`, then the application MUST support this extension in order to parse the Recording; if the application does not support this extension, it SHOULD report an error. \\\\ \\bottomrule \\end{tabular} \\end{center} In the example below, `extension-01` is optional, so the application may ignore it if it does not support `extension-01`. But `extension-02` is not optional, so the application must support `extension-02` in order to parse the Recording. \\begin{verbatim}\"global\": {\n ...\n \"core:extensions\" : [\n {\n \"name\": \"extension-01\",\n \"version\": \"0.0.5\",\n \"optional\": true\n },\n {\n \"name\": \"extension-02\",\n \"version\": \"1.2.3\",\n \"optional\": false\n }\n ]\n ...\n }\\end{verbatim}", + "description": "The `core:extensions` field in the Global Object is an array of extension objects that describe SigMF extensions. Extension Objects MUST contain the three key/value pairs defined below, and MUST NOT contain any other fields. \\rowcolors{1}{}{lightblue}\\begin{center}\\begin{tabular}{lllp{3.8in}} \\toprule \\textbf{Name} & \\textbf{Required} & \\textbf{Type} & \\textbf{Description} \\\\ \\midrule name & true & string & The name of the SigMF extension namespace. \\\\ version & true & string & The version of the extension namespace specification used. \\\\ optional & true & boolean & If this field is `false`, then the application MUST support this extension in order to parse the Recording; if the application does not support this extension, it SHOULD report an error. \\\\ \\bottomrule \\end{tabular} \\end{center} \\\\ In the example below, `extension-01` is optional, so the application may ignore it if it does not support `extension-01`. But `extension-02` is not optional, so the application must support `extension-02` in order to parse the Recording. \\begin{verbatim}\"global\": {\n ...\n \"core:extensions\" : [\n {\n \"name\": \"extension-01\",\n \"version\": \"0.0.5\",\n \"optional\": true\n },\n {\n \"name\": \"extension-02\",\n \"version\": \"1.2.3\",\n \"optional\": false\n }\n ]\n ...\n }\\end{verbatim}", "type": "array", "default": [], "additionalItems": false, From feffbcdf54c81b52635a2c407b32e5b272686ae2 Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Fri, 13 Sep 2024 14:04:54 -0400 Subject: [PATCH 03/11] update id of json schema to be a valid url --- sigmf-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sigmf-schema.json b/sigmf-schema.json index a0f755e..41e2f98 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -1,5 +1,5 @@ { - "$id": "https://github.com/sigmf/SigMF/spec/1.2.0/sigmf-schema", + "$id": "https://github.com/sigmf/SigMF/blob/v1.2.1/sigmf-schema.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Schema for SigMF Meta Files", "description": "SigMF specifies a way to describe sets of recorded digital signal samples with metadata written in JSON. SigMF can be used to describe general information about a collection of samples, the characteristics of the system that generated the samples, features of signals themselves, and the relationship between different recordings.", From 88df48b536b1691c11992f5a9f0340a8ff4b5dbb Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Fri, 13 Sep 2024 14:06:43 -0400 Subject: [PATCH 04/11] Use the raw github url for json schema id --- sigmf-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sigmf-schema.json b/sigmf-schema.json index 41e2f98..de10ee6 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -1,5 +1,5 @@ { - "$id": "https://github.com/sigmf/SigMF/blob/v1.2.1/sigmf-schema.json", + "$id": "https://raw.githubusercontent.com/sigmf/SigMF/v1.2.2/sigmf-schema.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Schema for SigMF Meta Files", "description": "SigMF specifies a way to describe sets of recorded digital signal samples with metadata written in JSON. SigMF can be used to describe general information about a collection of samples, the characteristics of the system that generated the samples, features of signals themselves, and the relationship between different recordings.", From 1a3b070c63def9036dc69151bed895160bd003d7 Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Mon, 16 Sep 2024 14:14:14 -0400 Subject: [PATCH 05/11] Move extensions/wifi.sigmf-ext.md to community repo --- extensions/wifi.sigmf-ext.md | 39 ------------------------------------ 1 file changed, 39 deletions(-) delete mode 100644 extensions/wifi.sigmf-ext.md diff --git a/extensions/wifi.sigmf-ext.md b/extensions/wifi.sigmf-ext.md deleted file mode 100644 index 10b5c7b..0000000 --- a/extensions/wifi.sigmf-ext.md +++ /dev/null @@ -1,39 +0,0 @@ -## Wi-Fi Extension v1.0.0 - -The `wifi`namespace extension defines dynamic Wi-Fi burst parameters extending -`annotations`. - -## 1 Global - -`wifi` does not extend [Global](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#global-object). - -## 2 Captures - -`wifi` does not extend [Captures](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#captures-array). - -## 3 Annotations - -The following names are specified in the `wifi` namespace and should be used in the `annotations` object: - -|name|required|type|unit|description| -|----|--------|----|----|-----------| -|`standard`|true|string|N/A|Wireless standard of captured signal e.g. 802.11a/g.| -|`frame_type_phy`|true|string|N/A|Physical layer specification e.g. non-high throughput or very-high throughput.| -|`channel`|true|int|N/A|Wi-Fi channel of captured signal| -|`start_time_s`|true|double|seconds|Start time of RF burst (relative time to start time of main capture file).| -|`stop_time_s`|true|double|seconds|Stop time of RF burst (relative time to start time of main capture file).| -|`frame_duration_s`|true|double|seconds|Duration of RF burst (`stop_time_s` - `start_time_s`).| -|`MCS`|true|int|N/A|Wi-Fi signal Modulation and Coding Scheme (MCS).| -|`MAC_frame_type`|true|string|N/A|Wi-Fi MAC frame type.| -|`MAC_ta`|true|string|N/A|Wi-Fi transmitter MAC address.| -|`MAC_ra`|true|string|N/A|Wi-Fi receiver MAC address.| -|`manufacturer_ta`|true|string|N/A|Manufacturer of the Wi-Fi transmitter.| -|`MAC_frame`|true|string|N/A|Wi-Fi MAC frame data without CRC.| -|`CRC`|true|string|N/A|Wi-Fi MAC frame CRC.| -|`start_of_packet`|true|double|samples|Starting sample of captured Wi-Fi burst.| -|`stop_of_packet`|true|double|samples|Stopping sample of captured Wi-Fi burst.| -|`number_of_samples_in_packet`|true|double|samples|Number of downsampled IQ samples in Wi-Fi burst.| - -## 4 Examples - -No `wifi` examples. From a63ee0d84e424abbc79f0529d3bbac98f22a1f11 Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Mon, 16 Sep 2024 14:14:33 -0400 Subject: [PATCH 06/11] Move adsb extension to community repo --- extensions/adsb.sigmf-ext.md | 28 ---------------------------- 1 file changed, 28 deletions(-) delete mode 100644 extensions/adsb.sigmf-ext.md diff --git a/extensions/adsb.sigmf-ext.md b/extensions/adsb.sigmf-ext.md deleted file mode 100644 index 388a49a..0000000 --- a/extensions/adsb.sigmf-ext.md +++ /dev/null @@ -1,28 +0,0 @@ -# ADS-B Extension v1.0.0 - -The Automatic Dependent Surveillance-Broadcast (`adsb`) namespace extension -defines dynamic properties of ADS-B signals extending `annotations`. - -## 1 Global - -`adsb` does not extend [Global](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#global-object). - -## 2 Captures - -`signal` does not extend [Captures](https://github.com/sigmf/SigMF/blob/main/sigmf-spec.md#captures-array). - -## 3 Annotations - -The following names are specified in the `adsb` namespace and should be used in -the `annotations` object: - -|name|required|type|unit|description| -|----|--------|----|----|-----------| -|`downlink_format`|true|int|N/A|Indicates if an ADS-B signal is a Mode S Short (11) or a Mode S Extended (17) signal.| -|`message_type`|true|int|N/A|Indicates the type of data in a Mode S Extended signal. The message type code range is from 0 to 31. The type of messages are aircraft identification (1-4), surface position (5-8), airborne position with barometric (9-18), airborne velocities (19), airborne position with GNSS (20-22), testing (23), reserved (24-27, 30), Emergency/Airborne Collision Avoidance System (ACAS) status (28), trajectory change (29), and aircraft operational status (31). A signal with a Mode S Short downlink format does not contains a message and is represented by 0. -|`ICA_address`|true|double|N/A|The International Civil Aviation Organization (ICAO) address of the ADS-B signal.| -|`binary`|true|string|N/A|The binary signal, either 56 bits (Mode S Short) or 112 bits (Mode S Extended).| - -## 4 Examples - -No `adsb` examples. From 1243235b4626659f2827314bd78f2dbe9212e6ce Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Mon, 18 Nov 2024 11:44:07 -0500 Subject: [PATCH 07/11] Clarify NCD filename without directory (#322) --- sigmf-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sigmf-schema.json b/sigmf-schema.json index de10ee6..1759c84 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -34,7 +34,7 @@ "type": "string" }, "core:dataset": { - "description": "The full filename of the Dataset file this Metadata file describes, used ONLY with Non-Conforming Datasets. If provided, this string MUST be the complete filename of the Dataset file, including the extension. The Dataset file must be in the local directory, and this string MUST NOT include any aspects of filepath other than the filename. If a Recording does not have this field, it MUST have a compliant SigMF Dataset (NOT a Non-Conforming Dataset) which MUST use the same base filename as the Metadata file and use the `.sigmf-data` extension. If a SigMF Recording or Archive is renamed this field MUST also be updated, because of this it is RECOMMENDED that Compliant SigMF Recordings avoid use of this field. This field SHOULD NOT be used in conjunction the `core:metadata_only` field. If both fields exist and the file specified by `core:dataset` exists, then `core:metadata_only` SHOULD be ignored by the application.", + "description": "The full filename of the Dataset file this Metadata file describes, used ONLY with Non-Conforming Datasets. If provided, this string MUST be the complete filename of the Dataset file, including the extension. The Dataset file must be in the same directory as the .sigmf-meta file; note that this string only includes the filename, not directory. If a Recording does not have this field, it MUST have a compliant SigMF Dataset (NOT a Non-Conforming Dataset) which MUST use the same base filename as the Metadata file and use the `.sigmf-data` extension. If a SigMF Recording or Archive is renamed this field MUST also be updated, because of this it is RECOMMENDED that Compliant SigMF Recordings avoid use of this field. This field SHOULD NOT be used in conjunction the `core:metadata_only` field. If both fields exist and the file specified by `core:dataset` exists, then `core:metadata_only` SHOULD be ignored by the application.", "type": "string", "pattern": "^[^\\/\\\\:*?\"<>|]+(\\.[^\\/\\\\:*?\"<>|]+)*\\$" }, From 0124669964ed20a59a9d1a675a0a414338e2ff82 Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Fri, 22 Nov 2024 15:35:13 -0500 Subject: [PATCH 08/11] add geolocation to captures array (#323) Co-authored-by: Marc Lichtman --- sigmf-schema.json | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/sigmf-schema.json b/sigmf-schema.json index 1759c84..756ae42 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -99,7 +99,7 @@ "type": "string" }, "core:geolocation": { - "description": "The location of the recording system, as a single RFC 7946 GeoJSON `point` Object using the convention defined by RFC 5870. 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: \\begin{verbatim} \"global\": {\n ...\n \"core:geolocation\": {\n \"type\": \"Point\",\n \"coordinates\": [-107.6183682, 34.0787916, 2120.0]\n }\n ...\n } \\end{verbatim} 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. ", + "description": "The location of the Recording system (note, using the Captures scope `geolocation` field is preferred). See the `geolocation` field within the Captures metadata for details. 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.", "type": "object", "required": ["type", "coordinates"], "properties": { @@ -158,7 +158,7 @@ "additionalProperties": true }, "captures": { - "description": "The `captures` value 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. Capture Segment Objects are composed of key/value pairs, and each Segment describes a chunk of samples that can be mapped into memory for processing. Each Segment MUST contain a `core:sample_start` key/value pair, which indicates the sample index relative to the Dataset where this Segment's metadata applies. The fields that are described within a Capture Segment are scoped to that Segment only and need to be explicitly declared again if they are valid in subsequent Segments. ", + "description": "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. Capture Segment Objects are composed of key/value pairs, and each Segment describes a chunk of samples that can be mapped into memory for processing. Each Segment MUST contain a `core:sample_start` key/value pair, which indicates the sample index relative to the Dataset where this Segment's metadata applies. The fields that are described within a Capture Segment are scoped to that Segment only and need to be explicitly declared again if they are valid in subsequent Segments. ", "default": [], "type": "array", "additionalItems": false, @@ -200,6 +200,31 @@ "type": "integer", "minimum": 0, "maximum": 18446744073709552000 + }, + "core:geolocation": { + "description": "The location of the recording system at the start of this Captures segment, as a single RFC 7946 GeoJSON `point` Object. For moving emitters, this provides a rudimentary means to manage location through different captures segments. While `core:geolocation` is also allowed in the Global object for backwards compatibility reasons, adding it to Captures is preferred. 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: \\begin{verbatim} \"captures\": {\n ...\n \"core:geolocation\": {\n \"type\": \"Point\",\n \"coordinates\": [-107.6183682, 34.0787916, 2120.0]\n }\n ...\n } \\end{verbatim} 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.", + "type": "object", + "required": ["type", "coordinates"], + "properties": { + "type": { + "type": "string", + "enum": ["Point"] + }, + "coordinates": { + "type": "array", + "minItems": 2, + "items": { + "type": "number" + } + }, + "bbox": { + "type": "array", + "minItems": 4, + "items": { + "type": "number" + } + } + } } }, "additionalProperties": true @@ -209,7 +234,7 @@ }, "annotations": { "default": [], - "description": "The `annotations` value is an array of annotation segment objects that describe anything regarding the signal data not part of the Captures and Global objects. It MUST be sorted by the value of each Annotation Segment's `core:sample_start` key, ascending. Annotation segment Objects contain key/value pairs and MUST contain a `core:sample_start` key/value pair, which indicates the first index at which the rest of the Segment's key/value pairs apply. There is no limit to the number of annotations that can apply to the same group of samples. If two annotations have the same `sample_start`, there is no defined ordering between them. If two annotations have the same `sample_start`, there is no defined ordering between them. If `sample_count` is not provided, it SHOULD be assumed that the annotation applies from `sample_start` through the end of the corresponding capture, in all other cases `sample_count` MUST be provided. ", + "description": "The `annotations` Object is an array of annotation segment objects that describe anything regarding the signal data not part of the Captures and Global objects. It MUST be sorted by the value of each Annotation Segment's `core:sample_start` key, ascending. Annotation segment Objects contain key/value pairs and MUST contain a `core:sample_start` key/value pair, which indicates the first index at which the rest of the Segment's key/value pairs apply. There is no limit to the number of annotations that can apply to the same group of samples. If two annotations have the same `sample_start`, there is no defined ordering between them. If two annotations have the same `sample_start`, there is no defined ordering between them. If `sample_count` is not provided, it SHOULD be assumed that the annotation applies from `sample_start` through the end of the corresponding capture, in all other cases `sample_count` MUST be provided. ", "type": "array", "additionalItems": true, "items": { From dfd158496f7dd29f092e1bc7b6650ea9998249d9 Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Tue, 17 Dec 2024 14:29:38 -0500 Subject: [PATCH 09/11] Docs: Empty captures array implies start sample of 0 (#327) * Empty captures array implies start sample of 0 * Clarify `captures` object description in schema --- sigmf-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sigmf-schema.json b/sigmf-schema.json index 756ae42..5cc9c2d 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -158,7 +158,7 @@ "additionalProperties": true }, "captures": { - "description": "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. Capture Segment Objects are composed of key/value pairs, and each Segment describes a chunk of samples that can be mapped into memory for processing. Each Segment MUST contain a `core:sample_start` key/value pair, which indicates the sample index relative to the Dataset where this Segment's metadata applies. The fields that are described within a Capture Segment are scoped to that Segment only and need to be explicitly declared again if they are valid in subsequent Segments. ", + "description": "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. Capture Segment Objects are composed of key/value pairs, and each Segment describes a chunk of samples that can be mapped into memory for processing. Each Segment MUST contain a `core:sample_start` key/value pair, which indicates the sample index relative to the Dataset where this Segment's metadata applies. The fields that are described within a Capture Segment are scoped to that Segment only and need to be explicitly declared again if they are valid in subsequent Segments. While it is recommended there be at least one segment defined, if there are no items in the captures array it is implied that a single capture exists with `core:sample_start` equal to zero (no other metadata is implied), i.e., `\"captures\": []` implies `\"captures\": [{\"core:sample_start\": 0}]`.", "default": [], "type": "array", "additionalItems": false, From 6fed8e4390f3e1d406dce0785691a9e00da400dd Mon Sep 17 00:00:00 2001 From: bbc131 <36670201+bbc131@users.noreply.github.com> Date: Thu, 19 Dec 2024 07:09:28 +0100 Subject: [PATCH 10/11] Docs: fix short-descriptions that included a period (#328) --- docs-generator.py | 2 +- sigmf-schema.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-generator.py b/docs-generator.py index 46f7e24..45f5d93 100644 --- a/docs-generator.py +++ b/docs-generator.py @@ -34,7 +34,7 @@ def gen_table(table, d): dtype = value.get("type", "MISSING") # default = str(value.get("default", "")) longdescription = value.get("description", "") - shortdescription = longdescription[: longdescription.find(".")].replace("\n", "") # short description, which is up to the first period + shortdescription = longdescription[: longdescription.find(". ")].replace("\n", "") # short description, which is up to the first period followed by space table.add_row((field, required, dtype, shortdescription)) table.append(NoEscape("\\bottomrule")) diff --git a/sigmf-schema.json b/sigmf-schema.json index 5cc9c2d..c462274 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -94,7 +94,7 @@ "maximum": 18446744073709552000 }, "core:version": { - "description": "The version of the SigMF specification used to create the Metadata file, in the format X.Y.Z", + "description": "The version of the SigMF specification used to create the Metadata file, in the format X.Y.Z.", "pattern": "^\\d+\\.\\d+\\.\\d", "type": "string" }, From a11b160dc01b9d0545e628621e95db348c43359b Mon Sep 17 00:00:00 2001 From: Marc Lichtman Date: Thu, 19 Dec 2024 01:15:34 -0500 Subject: [PATCH 11/11] Docs: fix typo in annotations array description (#330) --- sigmf-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sigmf-schema.json b/sigmf-schema.json index c462274..2df9dd8 100644 --- a/sigmf-schema.json +++ b/sigmf-schema.json @@ -234,7 +234,7 @@ }, "annotations": { "default": [], - "description": "The `annotations` Object is an array of annotation segment objects that describe anything regarding the signal data not part of the Captures and Global objects. It MUST be sorted by the value of each Annotation Segment's `core:sample_start` key, ascending. Annotation segment Objects contain key/value pairs and MUST contain a `core:sample_start` key/value pair, which indicates the first index at which the rest of the Segment's key/value pairs apply. There is no limit to the number of annotations that can apply to the same group of samples. If two annotations have the same `sample_start`, there is no defined ordering between them. If two annotations have the same `sample_start`, there is no defined ordering between them. If `sample_count` is not provided, it SHOULD be assumed that the annotation applies from `sample_start` through the end of the corresponding capture, in all other cases `sample_count` MUST be provided. ", + "description": "The `annotations` Object is an array of annotation segment objects that describe anything regarding the signal data not part of the Captures and Global objects. It MUST be sorted by the value of each Annotation Segment's `core:sample_start` key, ascending. Annotation segment Objects contain key/value pairs and MUST contain a `core:sample_start` key/value pair, which indicates the first index at which the rest of the Segment's key/value pairs apply. There is no limit to the number of annotations that can apply to the same group of samples. If two annotations have the same `sample_start`, there is no defined ordering between them. If `sample_count` is not provided, it SHOULD be assumed that the annotation applies from `sample_start` through the end of the corresponding capture, in all other cases `sample_count` MUST be provided. ", "type": "array", "additionalItems": true, "items": {