From 393dcfd4e2f5cac309a615d129a59e0baf6348ae Mon Sep 17 00:00:00 2001 From: Enrico Eberhard <32450951+eeberhard@users.noreply.github.com> Date: Tue, 8 Oct 2024 15:39:30 +0200 Subject: [PATCH] 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 --- .../schemas/draft/2-0-0/application.d.ts | 65 ++++++++++++ .../draft/2-0-0/application.schema.json | 100 ++++++++++++++++++ schemas/applications/CHANGELOG.md | 3 + .../schema/application.schema.json | 3 + .../applications/schema/frames.schema.json | 76 +++++++++++++ schemas/applications/schema/graph.schema.json | 28 ++++- 6 files changed, 273 insertions(+), 2 deletions(-) create mode 100644 schemas/applications/schema/frames.schema.json diff --git a/docs/static/schemas/draft/2-0-0/application.d.ts b/docs/static/schemas/draft/2-0-0/application.d.ts index c2df659..892e952 100644 --- 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 index 6c08ec0..2fb9873 100644 --- 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 index 06b2fac..279e43a 100644 --- 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 index 6d49eb5..f5e6ecb 100644 --- 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 new file mode 100644 index 0000000..d01ef21 --- /dev/null +++ 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" + ] + } + } +} \ No newline at end of file diff --git a/schemas/applications/schema/graph.schema.json b/schemas/applications/schema/graph.schema.json index 70970d2..69bc593 100644 --- 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": [