Map Widget
1. Feature Overview
The map widget draws a plugin's geographic information onto Pilot's map in real time: mark points, sketch tracks, and outline areas. Every element is anchored to real latitude/longitude and follows the map as it zooms and pans. With layer grouping, you can organize hundreds or thousands of annotations into separate layers (e.g., layer1, layer2), toggling or clearing an entire layer at once.
There are two ways to overlay spatial information on Pilot: the map widget (this tutorial) draws elements onto the map (top-down 2D, persistable); AR projection draws annotations onto the video feed (first-person view, not persisted, see the AR Projection documentation). The two target different views and can be used together. This tutorial focuses on the map widget, and Section 2.6 shows how to use a single "map element" to project onto both the map and AR.



1.1 Capability Overview
| Map Capability | Description |
|---|---|
| Map widgets | Create, query, update, and delete annotations (point, line, polygon, circle) on the map |
| Layer management | Group widgets into layers; toggle or clear an entire layer |
| Map elements | Project a single dataset onto both the map and the AR video feed |
| Map state | Listen for map-ready, zoom level, and other states |
1.2 Use Cases
- Power line inspection: mark towers and inspection points on the map
- Border patrol: sketch patrol tracks and outline no-fly areas
- Forest fire monitoring: manage massive hotspots by layer, toggling per layer
- Site surveying: overlay live map elements and sync them to the AR video feed
2. Interface Call Examples
The examples below assume you have completed SDK initialization and the plugin is connected to Pilot (for connection state, see the Plugin Connection State documentation). All interfaces are called through the manager singleton MapWidgetManager.getInstance().
2.1 Add a Map Widget (addMapWidget)
A map widget is represented by MapWidget: each widget has an auto-generated unique id, its drawerType (MapDrawerType) decides which shape it is, and you fill in the matching Options. Using a marker as an example:
val mapManager = MapWidgetManager.getInstance() // get the manager singleton
val widget = MapWidget().apply {
drawerType = MapDrawerType.MARKER // widget type: marker
name = "Tower-A12" // business identifier, not shown on the map
markerOptions = MapMarkerOptions().apply {
setPoint(OpenLocation(0.0, 0.0, 0.0)) // TODO: replace with actual lat/lng
setTitle("Tower A12") // title shown on the map
setNormalIConFileName("tower.png") // icon file name (upload first, see note below)
setClickable(true)
}
}
mapManager.addMapWidget(widget, object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* keep widget.id for later update / delete */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
Each drawerType maps to a specific Options; to draw another shape, just change drawerType and fill the matching Options:
MapDrawerType | Options | Key fields |
|---|---|---|
MARKER / PIN | MapMarkerOptions | point, title, normalIConFileName, clickable, draggable |
POLYLINE | MapPolylineOptions | points, width, color, dashed |
POLYGON | MapPolygonOptions | points, fillColor, strokeColor, width |
CIRCLE | MapCircleOptions | center, radius, fillColor, strokeColor |
Note:
MapWidget.nameis a business identifier (for logging / query) only and is not shown on the map; to show text on the map, useMapMarkerOptions.setTitle(...).
A marker's normalIConFileName / clickedIConFileName take a file name; the icon must first be uploaded to Pilot via File Transfer, and is referenced here by file name.
Preview:




2.2 Batch Add and Query (addMapWidgets / queryMapWidgets / queryMapWidgetsByLayer)
Use batch add for bulk GIS sync—one IPC creates multiple widgets. Query is used to "fetch objects then update / delete" or to restore state when rebuilding a page:
// Batch add
mapManager.addMapWidgets(widgetList, object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* batch add succeeded */ }
override fun onFailure(error: IDJIError) { /* e.g., PAYLOAD_TOO_LARGE: split into smaller batches */ }
})
// Query all widgets added by this plugin
mapManager.queryMapWidgets(object : CommonCallbacks.CompletionCallbackWithParam<List<MapWidget>> {
override fun onSuccess(widgets: List<MapWidget>) {
// every widget's id is a valid server-side id, usable directly for later update / remove
}
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
To query a single layer, use queryMapWidgetsByLayer(layerId, callback); the callback also returns List<MapWidget>.
Caution: Due to the Android Binder transfer limit, a single batch must not exceed 512KB, or the callback returns
PAYLOAD_TOO_LARGE. Keep each batch under roughly 500 simple markers, or 200 polylines / polygons that carry coordinate lists; on overflow, split into smaller batches and retry.
Preview:

2.3 Update and Delete (updateMapWidgets / removeMapWidgetsByIds)
The recommended flow is "query → change fields → update": get the object from query, change mutable fields, then send it back. The server matches by id and updates in place:
// widget comes from queryMapWidgets; change the title then update
widget.markerOptions.setTitle("Tower A12 (inspected)")
mapManager.updateMapWidgets(listOf(widget), object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* updated */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
// Remove by id in batch
mapManager.removeMapWidgetsByIds(listOf(widget.id), object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* removed */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
id / source / layerId are immutable and cannot be changed on update.
Caution: Modifying an immutable field returns
WIDGET_FIELD_IMMUTABLE. To move a widget to another layer, firstremoveMapWidgetsByIdsand thenaddMapWidgetsagain with the newlayerId.
Preview:

2.4 Layer Management (addLayer / setLayerVisible / clearLayer / removeLayer)
A layer (MapWidgetLayer) is a logical grouping container for widgets. After you assign a layer with MapWidget.setLayerId(...), you can toggle or clear the whole layer. Widgets without a layerId fall into the default layer.
// 1. Create a layer; after success, layer.id is the layer id
val layer = MapWidgetLayer("layer1")
mapManager.addLayer(layer, object : CommonCallbacks.CompletionCallback {
override fun onSuccess() {
val layerId = layer.id
// 2. Assign the widget to this layer when adding
val w = MapWidget().apply {
drawerType = MapDrawerType.MARKER
setLayerId(layerId)
markerOptions = MapMarkerOptions().apply { setPoint(OpenLocation(0.0, 0.0, 0.0)) }
}
mapManager.addMapWidget(w, object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* added to layer1 */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
}
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
// Toggle layer / clear layer (keep the layer itself) / remove layer (with all its widgets)
mapManager.setLayerVisible(layerId, false, callback)
mapManager.clearLayer(layerId, callback)
mapManager.removeLayer(layerId, callback)
Caution: The default layer (empty layerId) is read-only—it cannot be removed, toggled, or cleared, or the callback returns
LAYER_READONLY; operating on a nonexistent layer returnsLAYER_NOT_FOUND.
Preview:


2.5 Listen for Map State (addMapStateListener)
Use the map state listener to confirm the map is ready before batch drawing. After registration it immediately fires once with the current cached state, then fires again when the map becomes ready or the zoom changes:
private val mapStateListener = IMapStateListener { mapState ->
val ready = mapState.isMapReady // whether the map is ready
val zoom = mapState.zoom // current zoom level
if (ready) { /* map ready; start batch drawing widgets */ }
}
mapManager.addMapStateListener(mapStateListener) // re-adding the same listener is de-duplicated
// Remove when the page is destroyed
mapManager.removeMapStateListener(mapStateListener)
2.6 Map Elements and AR Sync (insertMapElement / updateMapElement / deleteMapElement / queryMapElement)
The map widgets above are drawn only on the map. If you want a single dataset to appear on both the map and the AR video feed, use a "map element" MapElement—it carries an isArShow switch (default true) that, when on, also projects the same element as an AR annotation. This is the other path to overlay AR; compared with the standalone AR system in the AR Projection documentation, its advantage is "one dataset shown on both map and AR."
Map elements also form a complete create/query/update/delete set:
// Create: build an element and insert; the success callback returns a server UUID
val element = MapElement().apply {
drawerType = MapDrawerType.POLYLINE // element type: polyline
points = listOf( // TODO: replace with actual coordinate list
OpenLocation(0.0, 0.0, 50.0),
OpenLocation(0.0, 0.0, 50.0)
)
color = MapElementColor.YELLOW // element color (enum)
name = "element1"
isArShow = true // also project onto the AR video feed
}
mapManager.insertMapElement(element, object : CommonCallbacks.CompletionCallbackWithParam<UUID> {
override fun onSuccess(id: UUID) { /* server-assigned UUID, already synced to element.id */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
// Query: fetch all current map elements
mapManager.queryMapElement(object : CommonCallbacks.CompletionCallbackWithParam<List<MapElement>> {
override fun onSuccess(list: List<MapElement>) {
val target = list.firstOrNull { it.name == "element1" } ?: return
// Update: change fields then send back (server matches by id)
target.color = MapElementColor.RED
mapManager.updateMapElement(target, object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* updated */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
// Delete: located by id; pass the object back as-is
mapManager.deleteMapElement(target, object : CommonCallbacks.CompletionCallback {
override fun onSuccess() { /* deleted */ }
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
}
override fun onFailure(error: IDJIError) { /* error.errorCode() */ }
})
Common variations:
- Draw only on the map, not in AR: set
isArShowtofalse. - Temporarily hide / restore all server-side AR annotations:
mapManager.hideARAnnotations(true, callback)(passfalseto restore), which does not affect display on the map.
Preview:

3. API Reference
For the full definitions of these interface methods (including parameter data models and enums), see the API documentation: IMapWidgetManager.
IMapWidgetManager is the entry point of the server-side map interface, exposing the following methods:
| Item | Description |
|---|---|
IMapWidgetManager | Entry point of the server-side map interface |
addMapWidget | Add a single map widget |
addMapWidgets | Batch-add map widgets |
updateMapWidgets | Batch-update map widgets (matched by id) |
removeMapWidget | Remove a single map widget |
removeMapWidgetsByIds | Batch-remove map widgets by id |
queryMapWidgets | Query all widgets added by this plugin |
queryMapWidgetsByLayer | Query widgets by layer |
addLayer | Add a layer |
removeLayer | Remove a layer (with its widgets) |
setLayerVisible | Set layer visibility |
clearLayer | Clear a layer (keep the layer itself) |
insertMapElement | Insert a map element (AR-syncable), returns UUID |
updateMapElement | Update a map element |
deleteMapElement | Delete a map element |
queryMapElement | Query map elements |
hideARAnnotations | Hide / show server-side AR annotations |
addMapStateListener | Add a map state listener |
removeMapStateListener | Remove a map state listener |
4. Sample Source Code
5. FAQ
Q1: updateMapWidgets returns WIDGET_FIELD_IMMUTABLE?
You modified an immutable field. id / source / layerId cannot be changed on update. To move a widget to another layer, first removeMapWidgetsByIds, then addMapWidgets again with the new layerId.
Q2: Batch add returns PAYLOAD_TOO_LARGE?
Due to the Android Binder transfer limit, a single batch must not exceed 512KB. Split it into smaller batches (keep each under roughly 500 simple markers, or 200 polylines / polygons that carry coordinate lists).
Q3: Removing / toggling / clearing a layer returns LAYER_READONLY or LAYER_NOT_FOUND?
LAYER_READONLY: you removed / toggled / cleared the default layer (empty layerId), which is read-only. Operate only on layers you created.LAYER_NOT_FOUND: the layer id does not exist; confirm the layer was created successfully viaaddLayer.
Q4: The marker icon does not show?
normalIConFileName / clickedIConFileName take a file name; the icon must first be uploaded to Pilot via File Transfer. Confirm the file is uploaded and the file name matches exactly (case-sensitive).
Q5: Why do I get a callback immediately after registering the map state listener?
This is by design. After addMapStateListener succeeds, it immediately fires once with the current cached map state so you can read the initial state; it fires again when the map becomes ready or the zoom changes. Re-adding the same listener is de-duplicated, so you will not receive duplicate notifications.
Q6: How do I choose between a map element (MapElement) and a map widget (MapWidget)?
- To draw only on the map with richer interactions like click popups or layer grouping, use
MapWidget(2.1–2.5). - To have one dataset appear on both the map and the AR video feed, use
MapElementwithisArShowset totrue(2.6). - For AR only, without the map, the standalone AR system fits better; see the AR Projection documentation.
Appendix: Error Code Quick Reference
The error codes below come from dji.open.pilot.base.error.RemoteError:
| Error code constant | Trigger | Suggested handling |
|---|---|---|
REMOTE_DISCONNECTED | Called before the connection is ready | Retry after the connection state is ready |
WIDGET_FIELD_IMMUTABLE | Modified id / source / layerId on update | Remove then re-add to change layers; see Q1 |
WIDGET_NOT_FOUND | The widget id does not exist on the server | Ensure the id comes from an added / queried widget |
PAYLOAD_TOO_LARGE | A single batch exceeds 512KB | Split into smaller batches; see Q2 |
LAYER_READONLY | Operated on the read-only default layer | Operate only on layers you created; see Q3 |
LAYER_NOT_FOUND | The layer id does not exist | Confirm the layer was created; see Q3 |
NO_SUCH_ELEMENT | The map element does not exist on the server | Ensure the element comes from an insert / query result |
NOT_SUPPORTED_MAP_DRAWER_TYPE | An unsupported drawerType was used | Use a supported type (MARKER / POLYLINE / POLYGON / CIRCLE / PIN) |
ELEMENT_POINTS_MUST_NOT_BE_NONE | The element's coordinate points are empty | Ensure points is set before inserting |