Map Data Structure
**Working Draft v5.4.0 **
This is a proposed data structure that can be used to store and transfer data between Maestro and its clients.
Root Node
| Element | Description |
|---|---|
| version | The Revision number of the Map Structure, this needs to be incremented each time a change is made and the structure is saved |
| dateGenerated | The date the data was exported on. |
| graphs | This is the data structure that contains the logical representation of the path graph (see logical section) |
| nodes | This is the array of node elements containing the description/definition of the nodes (see node section) |
| zones | This is the array of zone elements containing the zone type and any associated zone data (see zone section) |
| agents | A map of objects representing the agent types available and the version of the agent plugin |
Version
A version number for the data object. A save should require a commit message from the user for the Maestro versioning system to identify differences.
Date Generated
A simple date timestamp to indicate the map export date/time. We expect it in the following format 2021-06-24T18:02:08.768067
Graphs
The graph object contains all the graphs for all agent types. It contains all nodes, and the defined connections between them.
Root Element
| Element | Description |
|---|---|
| Root | Map<string, Profile> string is the Agent type string used to identify the agent type throughout the system. Profile is the data object unique to each layer (described below). |
Profile Element
| Element | Description |
|---|---|
| Root | Map<string, Nodes> string is the Profile type string (form factor) used to identify the agents form factor throughout the system. Nodes is a dictionary<string, Node> where the string is the node id, and the node contains the node definiton |
Node Element
| Element | Description |
|---|---|
| location | vector3 containing the location of a node in Cartesian space |
| inHeadingRadians | float a float describing the out-heading direction in radians calculated as 0 to 2$\pi$ from X+ moving counter-clockwise |
| outHeadingRadians | float a float describing the out-heading direction in radians calculated as 0 to 2$\pi$ from X+ moving counter-clockwise |
| edges | Dictionary<string, Edge> defining all edges that leave this node |
| actions | an array of action objects that can be performed at this node |
| metadata | dictionary<string, string> a dictionary of strings having no defined structure or defined keys, the consumer is responsible for knowing what data exists and how to consume it. |
Edge Element
| Element | Description |
|---|---|
| destNode | string the id of the destination node |
| distEstimate | float an estimated total length of the edge (this is used for weight calculations) |
| curves | curves[] and array of curve objects that define the edge's physical path in order of traversal |
| blockedNodes | string[] an array of blocked node id's |
| metadata | dictionary<string, string> a dictionary of strings it has no defined structure or defined keys, the consumer is responsible for knowing what data exists and how to consume it. |
Curve Element
| Element | Description |
|---|---|
| entryPoint | vector2 the entry point for the curve |
| exitPoint | vector2 the exit point for the curve |
| radius | float The radius of the curve, defaulting to the vehicle's turn radius. A value of 0 indicates a straight line. |
| circleCenter | vector2 the center of the circle the arc is on. |
| isClockwise | bool flag used as an efficient means of representing curve potential. This is null when the radius is 0. |
Actions Object
| Element | Description |
|---|---|
| zHeight | Optional: a float describing the z-height of the action location (if relevant) |
| action | An action id, this action id is shared across all of maestro system, and corresponds with a recognized action on the agent |
| locationId | Optional: if an action is tied to a location id, this would hold the string location id |
| blockedNodes | string[] an array of blocked node id's for this action |
Example
"graphs": {
"AgentType":{
"profile": {
"nodeId": {
"location": {"x": 100, "y": 100, "z": 100},
"outHeadingRadians": 30.4,
"inHeadingRadians": 30.4,
"actions": [],
"edges": {
"edgeId": {
"destNode": "DestNodeid",
"distEstimate": 30.5,
"curves": [
{
"entryPoint": {"x" : 100,"y" : 100},
"exitPoint": {"x" : 100,"y" : 100},
"radius": 2.79,
"circleCenter": {"x" : 100,"y" : 100},
"IsClockwise": false
}
],
"blockedNodes": ["nodeID", "nodeID"],
"metadata": {}
},
"edgeId": {
"destNode": "DestNodeid",
"distEstimate": 30.5,
"curves": [
{
"entryPoint": {"x" : 100,"y" : 100},
"exitPoint": {"x" : 100,"y" : 100},
"radius": 2.79,
"circleCenter": {"x" : 100,"y" : 100},
"IsClockwise": false
}
],
"blockedNodes": ["nodeID", "nodeID"],
"metadata": {}
},
},
"metadata": {"key": "value"}
},
"nodeId": {
"location": {"x": 100, "y": 100, "z": 100},
"outHeadingRadians": 30.4,
"inHeadingRadians": 30.4,
"actions": [],
"edges": {
"edgeId": {
"destNode": "DestNodeid",
"distEstimate": 30.5,
"curves": [
{
"entryPoint": {"x" : 100,"y" : 100},
"exitPoint": {"x" : 100,"y" : 100},
"radius": 2.79,
"circleCenter": {"x" : 100,"y" : 100},
"IsClockwise": false
}
],
"blockedNodes": ["nodeID", "nodeID"],
"metadata": {}
},
"edgeId": {
"destNode": "DestNodeid",
"distEstimate": 30.5,
"curves": [
{
"entryPoint": {"x" : 100,"y" : 100},
"exitPoint": {"x" : 100,"y" : 100},
"radius": 2.79,
"circleCenter": {"x" : 100,"y" : 100},
"IsClockwise": false
}
],
"blockedNodes": ["nodeID", "nodeID"],
"metadata": {}
},
},
"metadata": {"key": "value"}
},
}
}
},
Nodes
An array of Node elements that define the unique aspects of the node itself. This contains all logical nodes in the system.
Root Element
| Element | Description |
|---|---|
| nodeId | string the id of the node |
| label | description of the node |
| type | enum:{"node", "sharedNode"} the type of node this is on the graph. A sharedNode may have a locationId, and its id will be duplicated across graphs. A node has a completely unique id, and will not have a value for locationId. |
| locationId | string[] an array of optional location id's from the host WMS, typically used to represent an inventory location. This is a redundant quick reference for location id's tied to action in the action array |
| zones | string[] a array of zone id's a node belongs to |
Example
"nodes": {
"nodeId": {
"nodeId": "nodeid",
"label": "some description",
"type": "nodeTypeEnum",
"locationId": ["location1", "location2"],
"zones": ["zoneId", "zoneId",...]
},
"nodeId": {
"nodeId": "nodeid",
"label": "some description",
"type": "nodeTypeEnum",
"locationId": "",
"zones": ["zoneId", "zoneId",...]
}
}
Zones
Zones refer to an area on the map that a user wishes to contain special rules.
Root Element
| Element | Description |
|---|---|
| Root | zone[] an array of zone objects (defined below) |
Zone Element
| Element | Description |
|---|---|
| Id | String uuid for the zone |
| zoneActions | Array<string> This is a list of available action types for the zone. If maestro exists it must be actions defined and understood by maestro. |
| metaData | Map<string, string> This is the catch-all. any data specific to the edge that is not universal would be stored here. The consuming object must know what to look for and how to consume the data. |
| enclosedNodes | Array<string>, a list of the nodes enclosed by the zone. |
| polygonPoints | Array Vector2 , a list of points in the polygon |
Example
"zones": [
{
"id": "zoneId",
"zoneActions": ["actionId", "actionId", ...],
"metadata": {},
"enclosedNodes": ["nodeId", "nodeId", ...]
"polygonPoints" : [
{"x": 100, "y": 110},
{"x": 100, "y": 110},
{"x": 100, "y": 110},
{"x": 100, "y": 110},
]
},
{
"id": "zoneId",
"zoneActions": ["actionId", "actionId", ...],
"metadata": {},
"enclosedNodes": ["nodeId", "nodeId", ...]
"polygonPoints" : [
{"x": 100, "y": 110},
{"x": 100, "y": 110},
{"x": 100, "y": 110},
{"x": 100, "y": 110},
]
}
]
Agents
This is the array of distinct agent types used in the map, along with the version of the plugin used.
Root Element
| Element | Description |
|---|---|
| Root | AgentElement[] an array of agent objects (defined below) |
Agent Element
| Element | Description |
|---|---|
| Agent Id | The agent type name used to identify the Agent Type plugin |
| Version | The version number of the plugin used (semantic versioning) |
Example
{
"agents": [
{
"agentId": "agentId",
"version": "1.2.0"
},
{
"agentId": "agentId",
"version": "1.2.0"
}
]
}
Example Full Document
{
"version": "0.0.1",
"dateGenerated": "2021-06-24T18:02:08.768067",
"graphs": {
"AgentType":{
"profile": {
"nodeId": {
"location": {"x": 100, "y": 100, "z": 100},
"outHeadingRadians": 30.4,
"inHeadingRadians": 30.4,
"actions": [],
"edges": {
"edgeId": {
"destNode": "DestNodeid",
"distEstimate": 30.5,
"curves": [
{
"entryPoint": {"x" : 100,"y" : 100},
"exitPoint": {"x" : 100,"y" : 100},
"radius": 2.79,
"circleCenter": {"x" : 100,"y" : 100},
"IsClockwise": false
}
],
"blockedNodes": ["nodeID", "nodeID"],
"metadata": {}
},
"edgeId": {
"destNode": "DestNodeid",
"distEstimate": 30.5,
"curves": [
{
"entryPoint": {"x" : 100,"y" : 100},
"exitPoint": {"x" : 100,"y" : 100},
"radius": 2.79,
"circleCenter": {"x" : 100,"y" : 100},
"IsClockwise": false
}
],
"blockedNodes": ["nodeID", "nodeID"],
"metadata": {}
},
},
"metadata": {"key": "value"}
},
"nodeId": {
"location": {"x": 100, "y": 100, "z": 100},
"outHeadingRadians": 30.4,
"inHeadingRadians": 30.4,
"actions": [],
"edges": {
"edgeId": {
"destNode": "DestNodeid",
"distEstimate": 30.5,
"curves": [
{
"entryPoint": {"x" : 100,"y" : 100},
"exitPoint": {"x" : 100,"y" : 100},
"radius": 2.79,
"circleCenter": {"x" : 100,"y" : 100},
"IsClockwise": false
}
],
"blockedNodes": ["nodeID", "nodeID"],
"metadata": {}
},
"edgeId": {
"destNode": "DestNodeid",
"distEstimate": 30.5,
"curves": [
{
"entryPoint": {"x" : 100,"y" : 100},
"exitPoint": {"x" : 100,"y" : 100},
"radius": 2.79,
"circleCenter": {"x" : 100,"y" : 100},
"IsClockwise": false
}
],
"blockedNodes": ["nodeID", "nodeID"],
"metadata": {}
},
},
"metadata": {"key": "value"}
},
}
}
},
"nodes": {
"nodeId": {
"nodeId": "nodeid",
"label": "some description",
"type": "nodeTypeEnum",
"locationId": ["location1", "location2"],
"zones": ["zoneId", "zoneId",...]
},
"nodeId": {
"nodeId": "nodeid",
"label": "some description",
"type": "nodeTypeEnum",
"locationId": ["location1", "location2"],,
"zones": ["zoneId", "zoneId",...]
}
},
"zones": [
{
"id": "zoneId",
"zoneActions": ["actionId", "actionId", ...],
"metadata": {},
"enclosedNodes": ["nodeId", "nodeId", ...]
"polygonPoints" : [
{"x": 100, "y": 110},
{"x": 100, "y": 110},
{"x": 100, "y": 110},
{"x": 100, "y": 110},
]
},
{
"id": "zoneId",
"zoneActions": ["actionId", "actionId", ...],
"metadata": {},
"enclosedNodes": ["nodeId", "nodeId", ...]
"polygonPoints" : [
{"x": 100, "y": 110},
{"x": 100, "y": 110},
{"x": 100, "y": 110},
{"x": 100, "y": 110},
]
}
],
"agents": [
{
"agentId": "agentId",
"version": "1.2.0"
},
{
"agentId": "agentId",
"version": "1.2.0"
}
]
}