feat(schema): add frames and graph edge information (#181)

* feat(schema): add edge paths to graph property * feat(schema): add frames to application * refactor: add titles and descriptions to properties * build: update static draft schema * docs: CHANGELOG
aica-technology · Oct 8, 2024 · 393dcfd · 393dcfd
1 parent fbc22dc
commit 393dcfd
Show file tree

Hide file tree

Showing 6 changed files with 273 additions and 2 deletions.
diff --git a/docs/static/schemas/draft/2-0-0/application.d.ts b/docs/static/schemas/draft/2-0-0/application.d.ts
@@ -367,6 +367,10 @@ export type SequenceStep = Events | DelayStep | CheckConditionStep;
  * The ordered sequence steps to either trigger events, wait for a predefined time or check a condition
  */
 export type SequenceSteps = SequenceStep[];
+/**
+ * The reference frame that the positive and orientation of the frame is defined relative to
+ */
+export type ReferenceFrame = string;
 /**
  * The human-readable name to display on the button
  */
@@ -379,6 +383,10 @@ export type XPosition = number;
  * The Y position of the element on the graph
  */
 export type YPosition = number;
+/**
+ * Custom edge path coordinates as x, y pairs
+ */
+export type EdgePath = Position[];
 
 /**
  * An AICA application graph description using YAML syntax.
@@ -393,6 +401,7 @@ export interface YAMLApplicationDescription {
     components?: Components;
     conditions?: Conditions;
     sequences?: Sequences;
+    frames?: Frames;
     graph?: Graph;
 }
 
@@ -866,6 +875,44 @@ export interface BlockingConditionStepWithTimeout {
     else?: Events;
 }
 
+/**
+ * A description of the static frames available in the application
+ */
+export interface Frames {
+    [k: string]: Frame;
+}
+
+/**
+ * The position and orientation of a static frame in the application
+ *
+ * This interface was referenced by `Frames`'s JSON-Schema definition
+ * via the `patternProperty` "^[a-z]([a-z0-9_]?[a-z0-9])*$".
+ */
+export interface Frame {
+    position: FramePosition;
+    orientation: FrameOrientation;
+    reference_frame?: ReferenceFrame;
+}
+
+/**
+ * The frame position as Cartesian coordinates
+ */
+export interface FramePosition {
+    x: number;
+    y: number;
+    z: number;
+}
+
+/**
+ * The frame orientation in a unit quaternion representation
+ */
+export interface FrameOrientation {
+    w: number;
+    x: number;
+    y: number;
+    z: number;
+}
+
 /**
  * Information for the graphical representation of the application
  */
@@ -890,6 +937,7 @@ export interface Graph {
             [k: string]: Position;
         };
     };
+    edges?: GraphEdges;
 }
 
 /**
@@ -933,3 +981,20 @@ export interface Position {
     x: XPosition;
     y: YPosition;
 }
+
+/**
+ * A description of edges in the application with additional graphical information
+ */
+export interface GraphEdges {
+    [k: string]: GraphEdge;
+}
+
+/**
+ * Additional graphical information about a specific edge in the application
+ *
+ * This interface was referenced by `GraphEdges`'s JSON-Schema definition
+ * via the `patternProperty` "^[a-z]([a-z0-9_]?[a-z0-9])*$".
+ */
+export interface GraphEdge {
+    path?: EdgePath;
+}
diff --git a/docs/static/schemas/draft/2-0-0/application.schema.json b/docs/static/schemas/draft/2-0-0/application.schema.json
@@ -918,6 +918,82 @@
         }
       }
     },
+    "frames": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "Frames",
+      "description": "A description of the static frames available in the application",
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z]([a-z0-9_]?[a-z0-9])*$": {
+          "title": "Frame",
+          "description": "The position and orientation of a static frame in the application",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "position": {
+              "title": "Frame Position",
+              "description": "The frame position as Cartesian coordinates",
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "x": {
+                  "type": "number"
+                },
+                "y": {
+                  "type": "number"
+                },
+                "z": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "x",
+                "y",
+                "z"
+              ]
+            },
+            "orientation": {
+              "title": "Frame Orientation",
+              "description": "The frame orientation in a unit quaternion representation",
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "w": {
+                  "type": "number"
+                },
+                "x": {
+                  "type": "number"
+                },
+                "y": {
+                  "type": "number"
+                },
+                "z": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "w",
+                "x",
+                "y",
+                "z"
+              ]
+            },
+            "reference_frame": {
+              "title": "Reference Frame",
+              "description": "The reference frame that the positive and orientation of the frame is defined relative to",
+              "type": "string",
+              "default": "world",
+              "pattern": "^[a-z]([a-z0-9_]?[a-z0-9])*$"
+            }
+          },
+          "required": [
+            "position",
+            "orientation"
+          ]
+        }
+      }
+    },
     "graph": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "title": "Graph",
@@ -1002,6 +1078,30 @@
               "$ref": "#/properties/graph/$defs/position_group"
             }
           }
+        },
+        "edges": {
+          "title": "Graph Edges",
+          "description": "A description of edges in the application with additional graphical information",
+          "type": "object",
+          "additionalProperties": false,
+          "patternProperties": {
+            "^[a-z]([a-z0-9_]?[a-z0-9])*$": {
+              "title": "Graph Edge",
+              "description": "Additional graphical information about a specific edge in the application",
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "path": {
+                  "title": "Edge Path",
+                  "description": "Custom edge path coordinates as x, y pairs",
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/properties/graph/$defs/position"
+                  }
+                }
+              }
+            }
+          }
         }
       },
       "$defs": {

diff --git a/schemas/applications/CHANGELOG.md b/schemas/applications/CHANGELOG.md
@@ -32,7 +32,10 @@ Release Versions:
 - Hardware control rate can be supplemented with a `rate_tolerance` to determine the allowable deviation from the
   intended control rate, and an optional `strict` flag that immediately shuts down the hardware in case of rate
   deviation or other error
+- Static frames can be defined in the application with a position, orientation, name, and reference frame under the new
+  top-level `frames` property
 - Graph positions can be expressed for all elements, including sequences, conditions and a stop application node
+- Edge path information for custom edge routing can be stored under the `edges` sub-property of `graph`
 - Sequences have a property to support automatic looping
 - Sequences, conditions and controllers now support display names
 - The event structures for lifecycle transitions, service calls and setting parameters now always require the target

diff --git a/schemas/applications/schema/application.schema.json b/schemas/applications/schema/application.schema.json
@@ -142,6 +142,9 @@
     "sequences": {
       "$ref": "sequences.schema.json"
     },
+    "frames": {
+      "$ref": "frames.schema.json"
+    },
     "graph": {
       "$ref": "graph.schema.json"
     }

diff --git a/schemas/applications/schema/frames.schema.json b/schemas/applications/schema/frames.schema.json
@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Frames",
+  "description": "A description of the static frames available in the application",
+  "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^[a-z]([a-z0-9_]?[a-z0-9])*$": {
+      "title": "Frame",
+      "description": "The position and orientation of a static frame in the application",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "position": {
+          "title": "Frame Position",
+          "description": "The frame position as Cartesian coordinates",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "x": {
+              "type": "number"
+            },
+            "y": {
+              "type": "number"
+            },
+            "z": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "x",
+            "y",
+            "z"
+          ]
+        },
+        "orientation": {
+          "title": "Frame Orientation",
+          "description": "The frame orientation in a unit quaternion representation",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "w": {
+              "type": "number"
+            },
+            "x": {
+              "type": "number"
+            },
+            "y": {
+              "type": "number"
+            },
+            "z": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "w",
+            "x",
+            "y",
+            "z"
+          ]
+        },
+        "reference_frame": {
+          "title": "Reference Frame",
+          "description": "The reference frame that the positive and orientation of the frame is defined relative to",
+          "type": "string",
+          "default": "world",
+          "pattern": "^[a-z]([a-z0-9_]?[a-z0-9])*$"
+        }
+      },
+      "required": [
+        "position",
+        "orientation"
+      ]
+    }
+  }
+}
diff --git a/schemas/applications/schema/graph.schema.json b/schemas/applications/schema/graph.schema.json
@@ -34,6 +34,30 @@
           "$ref": "#/$defs/position_group"
         }
       }
+    },
+    "edges": {
+      "title": "Graph Edges",
+      "description": "A description of edges in the application with additional graphical information",
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z]([a-z0-9_]?[a-z0-9])*$": {
+          "title": "Graph Edge",
+          "description": "Additional graphical information about a specific edge in the application",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "path": {
+              "title": "Edge Path",
+              "description": "Custom edge path coordinates as x, y pairs",
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/position"
+              }
+            }
+          }
+        }
+      }
     }
   },
   "$defs": {
@@ -47,13 +71,13 @@
           "title": "X Position",
           "description": "The X position of the element on the graph",
           "type": "number",
-          "multipleOf" : 20
+          "multipleOf": 20
         },
         "y": {
           "title": "Y Position",
           "description": "The Y position of the element on the graph",
           "type": "number",
-          "multipleOf" : 20
+          "multipleOf": 20
         }
       },
       "required": [