Merge pull request #1 from COURAGEOUS-isf/meeting-changes

Meeting changes

CHANGELOG.md

@@ -0,0 +1,4 @@
+# 0.3.0
+- Improve docs
+- Replace `alarm` and `alarm_certainty` members with single `alarm` member that contains both and is optional on detection
+- Rename `height` to `height_amsl` on `Position3d`s

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "courageous-format"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

courageous.schema.json

@@ -1 +1 @@
-{"$schema":"http://json-schema.org/draft-07/schema#","title":"Document","type":"object","required":["detection","static_cuas_location","system_name","tracks","vendor_name"],"properties":{"detection":{"description":"A list containing the detection sets present in the document.","type":"array","items":{"$ref":"#/definitions/Detection"}},"static_cuas_location":{"description":"The 3D GPS location of the CUAS. Can be overriden per Record, but even if overriden this value must exist and be a valid position.","allOf":[{"$ref":"#/definitions/Position3d"}]},"system_name":{"type":"string"},"tracks":{"description":"A list containing the tracks present in the document.","type":"array","items":{"$ref":"#/definitions/Track"}},"vendor_name":{"type":"string"}},"definitions":{"Arc":{"description":"Describes a circular arc between two clockwise angles from true north.","type":"object","required":["from","to"],"properties":{"from":{"description":"Minimum compass angle from the CUAS System to the UAS in degrees.","type":"number","format":"double"},"to":{"description":"Maximum compass angle from the CUAS System to the UAS in degrees.","type":"number","format":"double"}}},"Classification":{"type":"string","enum":["Unknown","UAV","GCS","Other"]},"Detection":{"type":"object","required":["records"],"properties":{"name":{"description":"Free-form text describing the detection set. Can be, for instance, the name present on the HMI.","type":["string","null"]},"records":{"description":"A list of records associated with this detection.","type":"array","items":{"$ref":"#/definitions/Record"}},"uas_id":{"description":"An unique ID used to associate this detection with a specific UAS. The number itself is not relevant, it just needs to be unique per UAS.\n\nIf null, means the system was not able to identify the records present along with this object with any specific UAS.","type":["integer","null"],"format":"uint64","minimum":0.0}}},"Location":{"description":"Location of an UAS, which may be relative to the CUAS.","oneOf":[{"description":"Circular arc relative to the CUAS within which the UAS resides.","type":"object","required":["c","t"],"properties":{"c":{"$ref":"#/definitions/Arc"},"t":{"type":"string","enum":["Arc"]}}},{"description":"Compass quadrant where the UAS has been observed.","type":"object","required":["c","t"],"properties":{"c":{"$ref":"#/definitions/Quad"},"t":{"type":"string","enum":["Quad"]}}},{"description":"Clockwise angle in degrees from true north where the UAS has been observed.","type":"object","required":["c","t"],"properties":{"c":{"type":"number","format":"double"},"t":{"type":"string","enum":["Bearing"]}}},{"description":"Flat 2D position given in latitude and longitude.","type":"object","required":["c","t"],"properties":{"c":{"$ref":"#/definitions/Position2d"},"t":{"type":"string","enum":["Position2d"]}}},{"description":"3D position given in latitude, longitude and height.","type":"object","required":["c","t"],"properties":{"c":{"$ref":"#/definitions/Position3d"},"t":{"type":"string","enum":["Position3d"]}}},{"description":"Ray where the UAS has been observed given in bearing and elevation.","type":"object","required":["c","t"],"properties":{"c":{"type":"object","required":["bearing","elevation"],"properties":{"bearing":{"description":"Clockwise angle in degrees from true north where the UAS has been observed.","type":"number","format":"double"},"elevation":{"description":"Elevation angle in degrees over the horizon where the UAS has been observed.","type":"number","format":"double"}}},"t":{"type":"string","enum":["BearingElevation"]}}},{"description":"3D position of the UAS given in bearing, elevation angle and distance.","type":"object","required":["c","t"],"properties":{"c":{"type":"object","required":["bearing","distance","elevation"],"properties":{"bearing":{"description":"Clockwise angle in degrees from true north where the UAS has been observed.","type":"number","format":"double"},"distance":{"description":"Distance from the UAS to the CUAS given in meters.","type":"number","format":"double"},"elevation":{"description":"Elevation angle in degrees over the horizon where the UAS has been observed.","type":"number","format":"double"}}},"t":{"type":"string","enum":["BearingElevationDistance"]}}}]},"Position2d":{"description":"2D WGS84 position given in latitude and longitude.","type":"object","required":["lat","lon"],"properties":{"lat":{"description":"GPS WGS84 latitude measured in degrees.","type":"number","format":"double"},"lon":{"description":"GPS WGS84 longitude measured in degrees.","type":"number","format":"double"}}},"Position3d":{"description":"3D WGS84 position given in latitude, longitude and height.","type":"object","required":["height","lat","lon"],"properties":{"height":{"description":"Height measured in meters from sea level.","type":"number","format":"double"},"lat":{"description":"GPS WGS84 latitude measured in degrees.","type":"number","format":"double"},"lon":{"description":"GPS WGS84 longitude measured in degrees.","type":"number","format":"double"}}},"Quad":{"description":"Describes a compass quadrant.","type":"string","enum":["North","East","South","West"]},"Record":{"type":"object","required":["alarm","alarm_certainty","classification","location","record_number","time"],"properties":{"alarm":{"description":"Whether the alarm function of the CUAS system is active or not. An Alarm is defined as the function of a CUAS system alerting an Operator via the HMI and the generation of associated data in the UAS Activity Log, as a result of Declared UAS activity.","type":"boolean"},"alarm_certainty":{"description":"How certainly should the alarm be on, as a value from 0 (Least likely) to 1 (Most likely).","type":"number","format":"double","maximum":1.0,"minimum":0.0},"classification":{"description":"Classification of the record.","allOf":[{"$ref":"#/definitions/Classification"}]},"cuas_location":{"description":"The 3D GPS location of the CUAS recorded on this instant. Overrides the document's static_cuas_location.","anyOf":[{"$ref":"#/definitions/Position3d"},{"type":"null"}]},"identification":{"description":"Free form text, possibly describing the model or configuration of the UAS identified.","type":["string","null"]},"location":{"description":"The UAS location, which may be given in one of several declaration types.","allOf":[{"$ref":"#/definitions/Location"}]},"record_number":{"description":"A unique number that identifies this record between all other ones present in the document.","type":"integer","format":"uint64","minimum":0.0},"time":{"description":"UTC time as an Unix millisecond timestamp.","type":"integer","format":"uint64","minimum":0.0}}},"Track":{"type":"object","required":["records","uas_id"],"properties":{"name":{"description":"Free-form text describing the track. Can be, for instance, the name present on the HMI.","type":["string","null"]},"records":{"description":"A list of records associated with this track.","type":"array","items":{"$ref":"#/definitions/Record"}},"uas_id":{"description":"An unique ID used to associate this track with a specific UAS. The number itself is not relevant, it just needs to be unique per UAS.","type":"integer","format":"uint64","minimum":0.0}}}}}
+{"$schema":"http://json-schema.org/draft-07/schema#","title":"Document","type":"object","required":["detection","static_cuas_location","system_name","tracks","vendor_name"],"properties":{"detection":{"description":"A list containing the detection sets present in the document.","type":"array","items":{"$ref":"#/definitions/Detection"}},"static_cuas_location":{"description":"The 3D GPS location of the CUAS. Can be overriden per Record, but even if overriden this value must exist and be a valid position.","allOf":[{"$ref":"#/definitions/Position3d"}]},"system_name":{"type":"string"},"tracks":{"description":"A list containing the tracks present in the document.","type":"array","items":{"$ref":"#/definitions/Track"}},"vendor_name":{"type":"string"}},"definitions":{"Alarm":{"description":"An Alarm is defined as the function of a CUAS system alerting an Operator via the HMI and the generation of associated data in the UAS Activity Log, as a result of Declared UAS activity.","type":"object","required":["active","alarm_certainty"],"properties":{"active":{"description":"Whether the alarm function of the CUAS system is active or not.","type":"boolean"},"alarm_certainty":{"description":"How certain is the system of an active alarm, as a value from 0 (Least likely) to 1 (Most likely).","type":"number","format":"double","maximum":1.0,"minimum":0.0}}},"Arc":{"description":"Describes a circular arc between two clockwise angles from true north.","type":"object","required":["from","to"],"properties":{"from":{"description":"Minimum compass angle from the CUAS System to the UAS in degrees.","type":"number","format":"double"},"to":{"description":"Maximum compass angle from the CUAS System to the UAS in degrees.","type":"number","format":"double"}}},"Classification":{"type":"string","enum":["Unknown","UAV","GCS","Other"]},"Detection":{"type":"object","required":["records"],"properties":{"name":{"description":"Free-form text describing the detection set. Can be, for instance, the name present on the HMI.","type":["string","null"]},"records":{"description":"A list of records associated with this detection.","type":"array","items":{"$ref":"#/definitions/Record"}},"uas_id":{"description":"A unique ID used to associate this detection with a specific UAS. The number itself is not relevant, it just needs to be unique per UAS.\n\nIf null, means the system was not able to identify the records present along with this object with any specific UAS.","type":["integer","null"],"format":"uint64","minimum":0.0}}},"Location":{"description":"Location of an UAS, which may be relative to the CUAS.\nLocation objects are composed of a tag 't' which indicates the variant and a contents element 'c' which contains the variant's data.","oneOf":[{"description":"Circular arc relative to the CUAS within which the UAS resides.","type":"object","required":["c","t"],"properties":{"c":{"$ref":"#/definitions/Arc"},"t":{"type":"string","enum":["Arc"]}}},{"description":"Compass quadrant where the UAS has been observed.","type":"object","required":["c","t"],"properties":{"c":{"$ref":"#/definitions/Quad"},"t":{"type":"string","enum":["Quad"]}}},{"description":"Clockwise angle in degrees from true north where the UAS has been observed.","type":"object","required":["c","t"],"properties":{"c":{"type":"number","format":"double"},"t":{"type":"string","enum":["Bearing"]}}},{"description":"Flat 2D position given in latitude and longitude.","type":"object","required":["c","t"],"properties":{"c":{"$ref":"#/definitions/Position2d"},"t":{"type":"string","enum":["Position2d"]}}},{"description":"3D position given in latitude, longitude and height.","type":"object","required":["c","t"],"properties":{"c":{"$ref":"#/definitions/Position3d"},"t":{"type":"string","enum":["Position3d"]}}},{"description":"Ray where the UAS has been observed given in bearing and elevation.","type":"object","required":["c","t"],"properties":{"c":{"type":"object","required":["bearing","elevation"],"properties":{"bearing":{"description":"Clockwise angle in degrees from true north where the UAS has been observed.","type":"number","format":"double"},"elevation":{"description":"Elevation angle in degrees over the horizon where the UAS has been observed.","type":"number","format":"double"}}},"t":{"type":"string","enum":["BearingElevation"]}}},{"description":"3D position of the UAS given in bearing, elevation angle and distance.","type":"object","required":["c","t"],"properties":{"c":{"type":"object","required":["bearing","distance","elevation"],"properties":{"bearing":{"description":"Clockwise angle in degrees from true north where the UAS has been observed.","type":"number","format":"double"},"distance":{"description":"Distance from the UAS to the CUAS given in meters.","type":"number","format":"double"},"elevation":{"description":"Elevation angle in degrees over the horizon where the UAS has been observed.","type":"number","format":"double"}}},"t":{"type":"string","enum":["BearingElevationDistance"]}}}]},"Position2d":{"description":"2D WGS84 position given in latitude and longitude.","type":"object","required":["lat","lon"],"properties":{"lat":{"description":"GPS WGS84 latitude measured in degrees.","type":"number","format":"double"},"lon":{"description":"GPS WGS84 longitude measured in degrees.","type":"number","format":"double"}}},"Position3d":{"description":"3D WGS84 position given in latitude, longitude and height.","type":"object","required":["height_amsl","lat","lon"],"properties":{"height_amsl":{"description":"Height measured in meters from sea level.","type":"number","format":"double"},"lat":{"description":"GPS WGS84 latitude measured in degrees.","type":"number","format":"double"},"lon":{"description":"GPS WGS84 longitude measured in degrees.","type":"number","format":"double"}}},"Quad":{"description":"Describes a compass quadrant.","type":"string","enum":["North","East","South","West"]},"Record":{"type":"object","required":["classification","location","record_number","time"],"properties":{"alarm":{"description":"If the record has Alarm data on this record, it may be specified here.\n\nOn tracking data, this element SHOULD be present. If a parser finds a null alarm member on a tracking record, the behavior is left as implementation-defined.","anyOf":[{"$ref":"#/definitions/Alarm"},{"type":"null"}]},"classification":{"description":"Classification of the record.","allOf":[{"$ref":"#/definitions/Classification"}]},"cuas_location":{"description":"The 3D GPS location of the CUAS recorded on this instant. Overrides the document's static_cuas_location.","anyOf":[{"$ref":"#/definitions/Position3d"},{"type":"null"}]},"identification":{"description":"Free form text, possibly describing the model or configuration of the UAS identified.","type":["string","null"]},"location":{"description":"The UAS location, which may be given in one of several declaration types.","allOf":[{"$ref":"#/definitions/Location"}]},"record_number":{"description":"A unique number that identifies this record between all other ones present in the document.","type":"integer","format":"uint64","minimum":0.0},"time":{"description":"UTC time as an Unix millisecond timestamp.","type":"integer","format":"uint64","minimum":0.0}}},"Track":{"type":"object","required":["records","uas_id"],"properties":{"name":{"description":"Free-form text describing the track. Can be, for instance, the name present on the HMI.","type":["string","null"]},"records":{"description":"A list of records associated with this track.","type":"array","items":{"$ref":"#/definitions/Record"}},"uas_id":{"description":"A unique ID used to associate this track with a specific UAS. The number itself is not relevant, it just needs to be unique per UAS.","type":"integer","format":"uint64","minimum":0.0}}}}}

src/lib.rs

@@ -21,7 +21,7 @@ pub struct Document {
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "schemars", derive(JsonSchema))]
 pub struct Detection {
-    /// An unique ID used to associate this detection with a specific UAS.
+    /// A unique ID used to associate this detection with a specific UAS.
     /// The number itself is not relevant, it just needs to be unique per UAS.
     ///
     /// If null, means the system was not able to identify the records present along with this
@@ -36,7 +36,7 @@ pub struct Detection {
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "schemars", derive(JsonSchema))]
 pub struct Track {
-    /// An unique ID used to associate this track with a specific UAS.
+    /// A unique ID used to associate this track with a specific UAS.
     /// The number itself is not relevant, it just needs to be unique per UAS.
     pub uas_id: u64,
     /// A list of records associated with this track.
@@ -45,11 +45,6 @@ pub struct Track {
     pub name: Option<String>,
 }
 
-// for the company: schema + documentation
-// TODO better docs
-// TODO fix required *
-// TODO change detection & tracking to arrays
-
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "schemars", derive(JsonSchema))]
 pub struct Record {
@@ -59,14 +54,11 @@ pub struct Record {
     pub record_number: u64,
     /// Classification of the record.
     pub classification: Classification,
-    /// Whether the alarm function of the CUAS system is active or not.
-    /// An Alarm is defined as the function of a CUAS system alerting an Operator via the HMI and
-    /// the generation of associated data in the UAS Activity Log, as a result of Declared UAS
-    /// activity.
-    pub alarm: bool,
-    /// How certainly should the alarm be on, as a value from 0 (Least likely) to 1 (Most likely).
-    #[cfg_attr(feature = "schemars", validate(range(min = 0., max = 1.)))]
-    pub alarm_certainty: f64,
+    /// If the record has Alarm data on this record, it may be specified here.
+    ///
+    /// On tracking data, this element SHOULD be present. If a parser finds a null alarm member on a tracking record,
+    /// the behavior is left as implementation-defined.
+    pub alarm: Option<Alarm>,
     /// The UAS location, which may be given in one of several declaration types.
     pub location: Location,
     /// Free form text, possibly describing the model or configuration of the UAS identified.
@@ -76,6 +68,19 @@ pub struct Record {
     pub cuas_location: Option<Position3d>,
 }
 
+/// An Alarm is defined as the function of a CUAS system alerting an Operator via the HMI and
+/// the generation of associated data in the UAS Activity Log, as a result of Declared UAS
+/// activity.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Copy)]
+#[cfg_attr(feature = "schemars", derive(JsonSchema))]
+pub struct Alarm {
+    /// Whether the alarm function of the CUAS system is active or not.
+    pub active: bool,
+    /// How certain is the system of an active alarm, as a value from 0 (Least likely) to 1 (Most likely).
+    #[cfg_attr(feature = "schemars", validate(range(min = 0., max = 1.)))]
+    pub alarm_certainty: f64,
+}
+
 #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Copy)]
 #[cfg_attr(feature = "schemars", derive(JsonSchema))]
 pub enum Classification {
@@ -91,6 +96,8 @@ pub enum Classification {
 #[cfg_attr(feature = "schemars", derive(JsonSchema))]
 #[serde(tag = "t", content = "c")]
 /// Location of an UAS, which may be relative to the CUAS.
+#[schemars(description = "Location of an UAS, which may be relative to the CUAS.
+Location objects are composed of a tag 't' which indicates the variant and a contents element 'c' which contains the variant's data.")]
 pub enum Location {
     // clockwise: from -> to (degrees)
     /// Circular arc relative to the CUAS within which the UAS resides.
@@ -161,5 +168,5 @@ pub struct Position3d {
     /// GPS WGS84 longitude measured in degrees.
     pub lon: f64,
     /// Height measured in meters from sea level.
-    pub height: f64,
+    pub height_amsl: f64,
 }