adding feature tags to captures segments

sigmf · Mar 18, 2022 · 5e249ee · 5e249ee
1 parent 6438561
commit 5e249ee
Show file tree

Hide file tree

Showing 2 changed files with 47 additions and 1 deletion.
diff --git a/sigmf-spec.md b/sigmf-spec.md
@@ -500,9 +500,10 @@ Segment Objects:
 | ----------------| -------- | ------ | --------------------------------------------------------------------------------------------|
 | `sample_start`  | true     | uint   | The sample index in the Dataset file at which this Segment takes effect.                    |
 | `global_index`  | false    | uint   | The index of the sample referenced by `sample_start` relative to an original sample stream. |
-| `header_bytes`  | false    | uint   | The number of bytes preceding a chunk of samples that are not sample data, used for NCDs.  |
+| `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`.|
+| `segment_tags`  | false    | array  | A list of short form human/machine-readable strings indicating features of this segment.    |
 
 ##### The `sample_start` Field
 
@@ -611,6 +612,46 @@ 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 `segment_tags` Field
+
+This field provides high level contextual information to specific captures
+segments. For example, this can flag parts of a Recording containing saturated
+data, or can be used to specify segments of data that should be ignored by
+subsequent processing stages, or that are especially important.
+
+This field is a list of one or more strings, and in general the most important
+tag should be the first list item. This field MAY be used by visualization
+software to style a given segment a certain way.
+
+Standard tags are: `default`, `invalid`, `important`. The tag `default` is
+implied in the absense of this field, but an empty list is NOT valid. Any string
+is allowed as an entry in this list, but it is RECOMMENDED that strings be
+limited to no more than 20 characters. The following example shows this field
+used to indicate 1000 samples of saturated data:
+
+```json
+{
+  "global": {...},
+  "captures": [
+    {
+      "core:sample_start": 0,
+      "core:segment_tags": ["default"]
+    },
+    {
+      "core:sample_start": 100000,
+      "core:segment_tags": ["invalid", "saturated"]
+      ]
+    },
+    {
+      "core:sample_start": 101000,
+      "core:segment_tags": ["default"]
+      ]
+    }
+  ],
+  "annotations": []
+}
+```
+
 #### Annotations Array
 
 The `annotations` value is an array of `annotation segment objects` that

diff --git a/sigmf/schema-meta.json b/sigmf/schema-meta.json
@@ -159,6 +159,11 @@
                 "required": false,
                 "pattern": "",
                 "help": "An ISO-8601 string indicating the timestamp of the sample index specified by sample_start. (e.g., 2017-02-01T15:05:03.000Z)"
+            },
+            "core:captures_tags": {
+                "type": "string_list",
+                "required": false,
+                "help": "A list of short form human/machine-readable strings indicating features of this segment."
             }
         }
     },