Map Widget

2026-11-05Loading rating…

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 CapabilityDescription
Map widgetsCreate, query, update, and delete annotations (point, line, polygon, circle) on the map
Layer managementGroup widgets into layers; toggle or clear an entire layer
Map elementsProject a single dataset onto both the map and the AR video feed
Map stateListen 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:

MapDrawerTypeOptionsKey fields
MARKER / PINMapMarkerOptionspoint, title, normalIConFileName, clickable, draggable
POLYLINEMapPolylineOptionspoints, width, color, dashed
POLYGONMapPolygonOptionspoints, fillColor, strokeColor, width
CIRCLEMapCircleOptionscenter, radius, fillColor, strokeColor

Note: MapWidget.name is a business identifier (for logging / query) only and is not shown on the map; to show text on the map, use MapMarkerOptions.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:

Batch add and query

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, first removeMapWidgetsByIds and then addMapWidgets again with the new layerId.

Preview:

Update and delete

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 returns LAYER_NOT_FOUND.

Preview:

Draw on layers

Create layer and draw

Hide a layer

Hide an entire layer

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 isArShow to false.
  • Temporarily hide / restore all server-side AR annotations: mapManager.hideARAnnotations(true, callback) (pass false to restore), which does not affect display on the map.

Preview:

Map element synced to AR


3. API Reference

For the full definitions of these interface methods (including parameter data models and enums), see the API documentation: IMapWidgetManageropen in new window.

IMapWidgetManager is the entry point of the server-side map interface, exposing the following methods:

ItemDescription
IMapWidgetManagerEntry point of the server-side map interface
addMapWidgetAdd a single map widget
addMapWidgetsBatch-add map widgets
updateMapWidgetsBatch-update map widgets (matched by id)
removeMapWidgetRemove a single map widget
removeMapWidgetsByIdsBatch-remove map widgets by id
queryMapWidgetsQuery all widgets added by this plugin
queryMapWidgetsByLayerQuery widgets by layer
addLayerAdd a layer
removeLayerRemove a layer (with its widgets)
setLayerVisibleSet layer visibility
clearLayerClear a layer (keep the layer itself)
insertMapElementInsert a map element (AR-syncable), returns UUID
updateMapElementUpdate a map element
deleteMapElementDelete a map element
queryMapElementQuery map elements
hideARAnnotationsHide / show server-side AR annotations
addMapStateListenerAdd a map state listener
removeMapStateListenerRemove a map state listener

4. Sample Source Code

Map Widget Sampleopen in new window


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 via addLayer.

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 MapElement with isArShow set to true (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 constantTriggerSuggested handling
REMOTE_DISCONNECTEDCalled before the connection is readyRetry after the connection state is ready
WIDGET_FIELD_IMMUTABLEModified id / source / layerId on updateRemove then re-add to change layers; see Q1
WIDGET_NOT_FOUNDThe widget id does not exist on the serverEnsure the id comes from an added / queried widget
PAYLOAD_TOO_LARGEA single batch exceeds 512KBSplit into smaller batches; see Q2
LAYER_READONLYOperated on the read-only default layerOperate only on layers you created; see Q3
LAYER_NOT_FOUNDThe layer id does not existConfirm the layer was created; see Q3
NO_SUCH_ELEMENTThe map element does not exist on the serverEnsure the element comes from an insert / query result
NOT_SUPPORTED_MAP_DRAWER_TYPEAn unsupported drawerType was usedUse a supported type (MARKER / POLYLINE / POLYGON / CIRCLE / PIN)
ELEMENT_POINTS_MUST_NOT_BE_NONEThe element's coordinate points are emptyEnsure points is set before inserting
Last Updated: