Skip to main content

Map

The Map plugin allows the agent to ingest a range of map types into the DroneDeploy map format. The DroneDeploy map format is a graph-based representation containing a list of nodes and edges.

Maps ingested into the DroneDeploy format have the following advantages:

  • Streamlined method to store these maps in the DroneDeploy cloud, and subsequently load them back into the agent and, where applicable, the source robot map system.
  • Querying and editing of maps in the DroneDeploy cloud.
  • Traversal of maps both in the cloud and live on the agent.
  • Easy and performant visualization of maps or other spatial data in the Robotics Portal.

There are three key terms to be familiar with when using the Map plugin: dynamic maps and their adapters, and static maps.

Dynamic Maps​

Dynamic maps contain live, up to date map data that is being actively used by the agent and associated robot systems. A dynamic map is a graph of nodes and edges; see Data Model for the services used to read and edit it.

Each dynamic map configured can have multiple adapters connected to it. The agent can run several dynamic maps at once, each with its own adapters, for example one for a robot's own map and another for a sensor feed.

Adapters​

Adapters are responsible for bringing external data into the dynamic map: ingesting specific map types, converting them into the standard DroneDeploy map format, then adding this data to the associated dynamic map. Some adapters are also able to do the inverse: taking data from the dynamic map and converting it back into the source map format, then loading this data into the connected robot. Adapters can also keep a node in the map synchronised with a file on disk, or load a static map into the dynamic map when the agent starts. The available adapters and their settings are described in Adapters.

Map Content​

Adapters write several kinds of content into a dynamic map, depending on the data they ingest and how they are configured. For example:

  • Voxels: points are stored in an octree and published as voxels. See Voxels.
  • Rasters: grids and images are stored as one or more 2D images, either as a single raster or as a set of tiles. See Rasters.
  • Frames and transforms: coordinate frames, and the transforms between them, including the robot's position. A transform can also place a frame at a latitude, longitude and altitude on the WGS84 ellipsoid.
  • Paths and polygons: ordered sets of nodes.

Static Maps​

A static map results from saving a dynamic map to disk. From this point on it cannot be altered. Static maps can be loaded back into dynamic maps, and subsequently loaded onto the source robot. This allows a user to map a specific area, save the dynamic map to a static map, and then at a later date reload this map onto the source robot. The source robot can then once again localize and navigate using this map.

Static maps also arrive on the robot from the DroneDeploy cloud. A map deployed to the robot from the Robot Maps tab is downloaded by the agent and then appears in the list of static maps, alongside any saved on the robot. A static map is only available to load or merge once its download has completed, which is reported as ready in the staticMaps telemetry.

Loading and Merging​

There are two ways of putting a static map into a dynamic map:

  • Load clears the dynamic map and then copies the static map into it. Use this for a map which holds a complete environment, since it replaces whatever was there. Adapters such as ros.tf will immediately repopulate the robot's live position.
  • Merge copies the static map into the dynamic map without clearing it first, so only what the static map describes is changed. Use this for a map which describes a single feature, or which is meant to be added to what is already there.

When a node or edge in the static map has the same ID as one already in the dynamic map, the two are merged following the following rules:

  • Two nodes with the same ID must have the same type. The exception is a generic FRAME node: if one of the two is a FRAME, the other's type is used and the properties of both are kept.
  • Two edges with the same ID must have the same type and connect the same nodes.
  • Properties are merged key by key. A key which is on only one side is kept. Where both sides have the key, simple values must be equal, objects are merged recursively, and arrays must be identical. A null value counts as absent. External data (such as an image or a voxel file) with the same key must refer to the same file.

If the two cannot be reconciled, the merge stops with an error naming the node or edge at fault. Nodes and edges merged before the conflict are left in place.

Both operations are available as services; see Data Model. The whenReady variants wait for a map to finish downloading before applying it, which is useful straight after a map has been deployed. The static map adapter does the same automatically, so that a deployed map is loaded or merged without anything having to call a service.

Static Map Hashing​

Static maps saved on the agent are identified only by their hash. The hash of a static map can be thought of as a unique identifier calculated from the content of the map. By identifying maps in this way, the agent can ensure that the same map is not saved multiple times, unnecessarily consuming disk space.

Identifying static maps in the robotics portal however can be done using a human readable name in the Robot Maps tab. This name is not used by the agent and is for the user's benefit. This allows a user to give meaningful names to maps, e.g. "Factory Floor".

A map deployed from the cloud also has a stable cloud ID. Its hash changes whenever its content changes, for example when the map is edited and redeployed, but its cloud ID stays the same. Services and adapters which load or merge a map accept either the hash (sourceHash) or the cloud ID (sourceId). Using the cloud ID means the latest deployed version is used.

Configuration​

To use the Map plugin, your agent will need a section in its agent-settings.json file which enables the map component, as shown below. For more information on how to configure the agent plugins, see Agent Configuration.

The example map configuration shown below has two dynamic maps configured: spot and ros.

The spot map has one spot adapter attached to it. This spot adapter is configured in the agent to handle ingesting GraphNav maps on Spot robots. It is also configured to handle loading these maps back onto Spot robots.

The ros map has two adapters attached to it. The ros.pointcloud2 adapter ingests ROS pointcloud2 messages as voxels. These voxels are then added as nodes to the standard DroneDeploy map format. This allows for easy and performant visualisation of the ROS pointcloud2 data in Local Ops. The static-map adapter loads a map deployed from the cloud into the dynamic map when the agent starts.

{
"enabled": true,
"id": "map",
"settings": {
"logLevel": 4,
"name": "map",
"dynamicMaps": {
"spot": {
"adapters": {
"spot": {
"enabled": true,
"type": "spot",
"settings": {
"colorTransformer": "auto",
"frame": "seed",
"outputMode": "disabled"
}
}
}
},
"ros": {
"adapters": {
"ros-adapter": {
"enabled": true,
"type": "ros.pointcloud2",
"settings": {
"colorTransformer": "auto",
"source": "/ros/camera/rgb/points",
"voxelSettings": {
"octreeDepth": 12,
"octreeResolution": 0.05,
"refreshOctree": true
}
}
},
"factory-floor": {
"enabled": true,
"type": "static-map",
"settings": {
"sourceId": "factory-floor",
"mode": "load"
}
}
}
}
}
}
}
NameDescriptionDefault
enabledWhether to enable the map plugin or not.false
logLevelThe logging verbosity: 1 - very quiet, 6 - very talkative.4
nameName to give the map component instance.map
dynamicMapsEach dynamic map can be configured under this heading and given a name of the user's choosing. The name is used in the topics and services of the dynamic map.
adaptersThe adapters to attach to the parent dynamic map, keyed by a name of the user's choosing. Each has an enabled flag, a type and its settings. Adapter settings are outlined here.
Warning

To empty a dynamic map call its clear service; to empty it and have its adapters start up again, such as reloading a static map, call restart. See Map Services.

Any change to the map component settings within agent-settings.json will result in the map component being reset, and its adapters being started again. Any points which have been accumulated in a dynamic map by running adapters - such as a collection of ingested voxels - will be lost.