Map Widget
The Map Widget displays the aircraft's state and nearby fly zones. It also includes a UserAccountLoginWidget for ease of use with unlockable fly zones because in order to unlock a fly zone, the user must be logged in.
- Usage
- Configuration
- Map Customizations
- Marker Customizations
- Line Customizations
- Camera Customizations
- Fly Zone Customizations
<dji.ux.beta.map.widget.map.MapWidget
android:id="@+id/widget_map"
android:layout_width="match_parent"
android:layout_height="match_parent" />-
public UserAccountLoginWidget getUserAccountLoginWidget()- Gets the User Account Login Widget that is contained within the Map Widget
You have a choice of multiple map providers for use in the map widget, but you must add your own API keys to your app's AndroidManifest.xml. Currently the Map Widget supports the following providers:
Follow Google's Get API Key documentation to get a Google Maps API key and add it to your app's AndroidManifest.xml
Then call MapWidget.initGoogleMap(OnMapReadyListener) or add app:uxsdk_mapProvider="GoogleMap" to the MapWidget item in your layout file.
Additionally, the following lifecycle methods in your activity must call the corresponding methods in MapWidget in order for the map to render correctly: onCreate(Bundle), onResume(), onPause(), onDestroy(), onSaveInstanceState(Bundle), and onLowMemory().
There is no need to add additional dependencies to your build.gradle since they are included with the UX SDK.
Note: Google Maps only works on devices with Google Play Services (which excludes the DJI Crystal Sky).
Follow HERE's Authentication Guide to get your HERE credentials and add them to your AndroidManifest.xml file. Then follow the steps in the Map Service Guide to embed a map service in your application. Make sure to note the limitations in Android 8.0 and above with regards to starting services.
You will also need to download their SDK from your project's page and add it to your libs folder (See their Sample Application guide for more details), then add the following dependency to your build.gradle:
api 'com.here.android:HERE-sdk:3.15.0@aar'
Then call MapWidget.initHereMap(OnMapReadyListener) or add app:uxsdk_mapProvider="HereMap" to the MapWidget item in your layout file.
Note: Please check their System Requirements. Currently, HERE Android SDK does not support x86 and x86_64 devices.
Follow Gaode's Get Key documentation to get your API key and follow their Create Android Studio Project - Integrated SDK through Gradle documentation to add the following dependencies to your build.gradle:
implementation 'com.amap.api:3dmap:6.9.2'
implementation 'com.amap.api:search:6.9.2'
implementation 'com.amap.api:location:4.7.0'
Then call MapWidget.initAMap(OnMapReadyListener) or add app:uxsdk_mapProvider="AMap" to the MapWidget item in your layout file.
Follow Mapbox's First Steps Guide to get a Mapbox account and access token.
Then call initMapboxMap(@Nullable final OnMapReadyListener listener, @NonNull String mapboxAccessToken) or add app:uxsdk_mapProvider="MapBox" and app:uxsdk_mapBoxToken="<token>" to the MapWidget item in your layout file.
Additionally, the following lifecycle methods in your activity must call the corresponding methods in MapWidget in order for the map to render correctly: onCreate(Bundle), onResume(), onPause(), onDestroy(), onSaveInstanceState(Bundle), and onLowMemory().
Once you have initialized your MapWidget object using one of the providers above, you can get the DJIMap object using the OnMapReadyListener callback. This will enable you to set the map type, add markers and shapes, move the camera, and add listeners for click events. For additional documentation on customization of the DJIMap object, see DJIMap.
List of the map customizable XML attributes
-
uxsdk_djiMap_mapType- Sets the MapType of the DJIMap object. The options are normal, satellite, or hybrid, and they correspond to the values of the MapType enum in DJIMap. -
uxsdk_mapProvider- Initializes the map with the given provider. See the Configuration section above for details on how to configure the MapWidget for each provider.
List of the map customization APIs
-
public void setOnMarkerClickListener(DJIMap.OnMarkerClickListener onMarkerClickListener)- Sets the OnMarkerClickListener for this widget. MapWidget.setOnMarkerClickListener should be used instead of DJIMap.setOnMarkerClickListener in order to preserve the fly zone unlocking functionality. -
@Nullable public DJIMap getMap()- Gets the DJIMap object contained within the MapWidget. This can also be retrieved using the OnMapReadyListener callback during initialization.
There are three markers that we have added to the map by default - aircraft, home point, and gimbal attitude. Each of these icons can be customized as follows.
This marker shows the aircraft's location and rotates to indicate the heading.
List of the aircraft location marker customizable XML attributes
-
uxsdk_aircraftMarkerIcon- The icon of the aircraft marker. -
uxsdk_aircraftMarkerEnabled- The visibility of the aircraft marker.
List of the aircraft location marker customization APIs
-
public void setAircraftMarkerIcon(@NonNull Drawable drawable, float x, float y)- Set the icon of the aircraft marker with an (x,y) anchor. -
public void setAircraftMarkerIcon(@NonNull Drawable drawable)- Set the icon of the aircraft marker -
@NonNull public Drawable getAircraftMarkerIcon()- Get the icon of the aircraft marker. -
public boolean isAircraftMarkerEnabled()- Get the visibility of the aircraft marker. -
public void setAircraftMarkerEnabled(boolean isEnabled)- Set the visibility of the aircraft marker.
This marker shows the aircraft's home location.
List of the home location marker customizable XML attributes
-
uxsdk_homeMarkerIcon- The icon of the home point marker. -
uxsdk_homeMarkerEnabled- The visibility of the home point marker.
List of the home location marker customization APIs
-
public void setHomeMarkerIcon(@NonNull Drawable drawable, float x, float y)- Set the icon of the home point marker with an (x,y) anchor. -
public void setHomeMarkerIcon(@NonNull Drawable drawable)- Set the icon of the home point marker. -
@NonNull public Drawable getHomeMarkerIcon()- Get the icon of the home point marker. -
public boolean isHomeMarkerEnabled()- Get the visibility of the home point marker. -
public void setHomeMarkerEnabled(boolean isEnabled)- Set the visibility of the home point marker.
This marker is centered at the aircraft's home location and rotates to indicate the gimbal's heading.
List of the gimbal attitude customizable XML attributes
-
uxsdk_gimbalMarkerIcon- The icon of the gimbal attitude marker. -
uxsdk_gimbalAttitudeEnabled- The visibility of the gimbal attitude marker.
List of the gimbal attitude customization APIs
-
public void setGimbalMarkerIcon(@NonNull Drawable drawable)- Set the icon of the gimbal attitude marker. -
@NonNull public Drawable getGimbalMarkerIcon()- Get the icon of the gimbal attitude marker. -
public boolean isGimbalAttitudeEnabled()- Get the visibility of the gimbal attitude marker. -
public void setGimbalAttitudeEnabled(boolean isEnabled)- Set the visibility of the gimbal attitude marker.
There are two lines that we have added to the map - direction to home and flight path. Each of these lines can be customized as follows.
This line is drawn from the aircraft's location to the aircraft's home location.
List of the direction to home customizable XML attributes
-
uxsdk_homeDirectionEnabled- The visibility of the path from aircraft to home point. -
uxsdk_homeDirectionColor- The color of the path from aircraft to home point. -
uxsdk_homeDirectionWidth- The width of the path from aircraft to home point.
List of the direction to home customization APIs
-
public boolean isDirectionToHomeEnabled()- Indicates whether the map displays a path from aircraft to home point. -
public void setDirectionToHomeEnabled(boolean isEnabled)- Sets the visibility of the path from aircraft to home point. -
@ColorInt public int getDirectionToHomeColor()- Gets the color of the path from aircraft to home point. -
public void setDirectionToHomeColor(@ColorInt int color)- Sets the color of the path from aircraft to home point. -
public float getDirectionToHomeWidth()- Gets the width of the path from aircraft to home point. -
public void setDirectionToHomeWidth(float width)- Sets the width of the path from aircraft to home point.
This line shows the path the aircraft has taken during its flight.
List of the flight path customizable XML attributes
-
uxsdk_flightPathEnabled- The visibility of the flight path. -
uxsdk_flightPathColor- The color of the flight path. -
uxsdk_flightPathWidth- The line width, in pixels, of the flight path.
List of the flight path customization APIs
-
public void clearFlightPath()- Clears the flight path up to the current location. The flight path is removed even if it is hidden. -
public boolean isFlightPathEnabled()- Gets the flight path visibility. -
public void setFlightPathEnabled(boolean isEnabled)- Sets the flight path visibility. -
@ColorInt public int getFlightPathColor()- Gets the color of the flight path. -
public void setFlightPathColor(@ColorInt int color)- Sets the color of the flight path. -
public float getFlightPathWidth()- Gets the line width, in pixels, for the flight path. -
public void setFlightPathWidth(float width)- Sets the line width, in pixels, of the flight path.
There are two features that can be enabled or disabled which will change the map's camera position: auto-framing and map centering.
When auto-framing is enabled, the map will zoom out automatically to ensure both the aircraft and the home position stay on the screen.
List of the auto-framing customizable XML attributes
-
uxsdk_autoFrameMapEnabled- Whether auto-framing is enabled.
List of the auto-framing customization APIs
-
public boolean isAutoFrameMapEnabled()- Check if auto-framing is enabled. -
public void setAutoFrameMapEnabled(boolean isEnabled)- Enable or disable auto-framing.
When map centering is enabled, the map will stay centered on the aircraft or home position. To disable, set the MapCenterLock mode to NONE.
List of the map centering customizable XML attributes
-
uxsdk_mapCenterLock- The MapCenterLock mode.
List of the map centering customization APIs
-
@NonNull public MapCenterLock getMapCenterLock()- Gets the MapCenterLock mode. -
public void setMapCenterLock(@NonNull MapCenterLock mapCenterLock)- Sets the MapCenterLock mode to the specified mode.
All current DJI aircraft use the GEO system which consists of flight restriction zones and an unlocking system. There are two types of unlockable zones: custom unlock zones, and self-unlock zones.
Many of these customization methods can be accessed through the FlyZoneHelper, which can be retrieved from the MapWidget by calling getFlyZoneHelper().
There are four categories of fly zones: Restricted, Enhanced Warning, Warning, and Authorization. Additionally, any of these fly zones can have a maximum altitude, which can be seen in the Restricted example below.
| Restricted | Enhanced Warning | Warning | Authorization |
|---|---|---|---|
 |
 |
 |
 |
Each fly zone category can have a custom color and custom alpha. The color is applied to the border, and the color with the given alpha is used to fill the shape.
List of the fly zone customizable XML attributes
-
uxsdk_warningFlyZoneColor- The color of the warning fly zones. -
uxsdk_enhancedWarningZoneColor- The color of the enhanced warning fly zones. -
uxsdk_authorizedFlyZoneColor- The color of the authorization fly zones. -
uxsdk_restrictedFlyZoneColor- The color of the restricted fly zones. -
uxsdk_maximumHeightColor- The color of the altitude fly zones. -
uxsdk_warningFlyZoneAlpha- The alpha of the warning fly zones. -
uxsdk_enhancedWarningZoneAlpha- The alpha of the enhanced warning fly zones. -
uxsdk_authorizedFlyZoneAlpha- The alpha of the authorization fly zones. -
uxsdk_restrictedFlyZoneAlpha- The alpha of the restricted fly zones. -
uxsdk_maximumHeightAlpha- The alpha of the altitude fly zones. -
uxsdk_flyZoneBorderWidth- The border width of all fly zones.
List of the fly zone category customization APIs
-
public boolean isFlyZoneVisible(@NonNull FlyZoneCategory flyZoneCategory)- Get the visibility of the given fly zone category. -
public void setFlyZoneVisible(@NonNull FlyZoneCategory flyZoneCategory, boolean isVisible)- Set the visibility of the given fly zone category. -
public int getFlyZoneColor(@NonNull FlyZoneCategory category)- Get the color of the given fly zone category. -
public void setFlyZoneColor(@NonNull FlyZoneCategory category, @ColorInt int color)- Set the color of the given fly zone category. -
public int getFlyZoneAlpha(@NonNull FlyZoneCategory category)- Get the alpha of the given fly zone category. -
public void setFlyZoneAlpha(@NonNull FlyZoneCategory category, int alpha)- Set the alpha of the given fly zone category. -
public float getFlyZoneBorderWidth()- Get the border width of all fly zones. -
public void setFlyZoneBorderWidth(float width)- Set the border width of all fly zones.
Authorization zones can be self-unlocked on-site and lasts for 24 hours. Self-unlocking can also be scheduled ahead of time.
| Locked | Unlocked |
|---|---|
 |
 |
List of the self-unlock fly zone customizable XML attributes
-
uxsdk_selfUnlockedFlyZoneColor- The color of the self-unlock fly zones. -
uxsdk_selfUnlockedFlyZoneAlpha- The alpha of the self-unlock fly zones. -
uxsdk_flyZoneLockedIcon- The icon of the locked self-unlock fly zone markers. -
uxsdk_flyZoneUnLockedIcon- The icon of the unlocked self-unlock fly zone markers.
List of the self-unlock fly zone customization APIs
-
@ColorInt public int getSelfUnlockColor()- Get the color of the self-unlock fly zones. -
public void setSelfUnlockColor(@ColorInt int color)- Set the color of the self-unlock fly zones. -
public int getSelfUnlockAlpha()- Get the alpha of the self-unlock fly zones. -
public void setSelfUnlockAlpha(int alpha)- Set the alpha of the self-unlock fly zones. -
public void setSelfUnlockedMarkerIcon(@NonNull Drawable drawable)- Set the icon of the unlocked self-unlock fly zones. -
public void setSelfUnlockedMarkerIcon(@NonNull Drawable drawable, float x, float y)- Set the icon of the unlocked self-unlock fly zones with an (x,y) anchor. -
public void setSelfLockedMarkerIcon(@NonNull Drawable drawable)- Set the icon of the locked self-unlock fly zone markers. -
public void setSelfLockedMarkerIcon(@NonNull Drawable drawable, float x, float y)- Set the icon of the locked self-unlock fly zone markers with an (x,y) anchor.
Restricted zones or any subsection of a restricted zone can be custom unlocked by following these steps:
- Send a request to unlock an area ahead of time through the website.
- Once the request is approved, the custom unlock zone is tied to your account. To see the list of custom unlock zones on your account, call
requestCustomUnlockZonesFromServer. - To sync the zones from your account to the aircraft, call
syncCustomUnlockZonesToAircraft. - Only one custom unlock zone can be enabled at a time, and flight is restricted to only within the zone while it is enabled. This means the aircraft CANNOT fly outside the zone while the custom unlock zone is enabled! Tap the unlock icon to enable, and tap the lock icon to disable.
| Custom Unlock Zone | On Aircraft | Enabled |
|---|---|---|
 |
 |
 |
List of the custom unlock fly zone customizable XML attributes
-
uxsdk_customUnlockedFlyZoneColor- The color of the custom unlock fly zones. -
uxsdk_customUnlockedFlyZoneOnAircraftColor- The color of the custom unlock fly zones that have been sent to the aircraft. -
uxsdk_customUnlockedFlyZoneEnabledColor- The color of the currently enabled custom unlock fly zone. -
uxsdk_customUnlockedFlyZoneAlpha- The alpha of the custom unlock fly zones. -
uxsdk_customUnlockedFlyZoneOnAircraftAlpha- The alpha of the custom unlock fly zones that have been sent to the aircraft. -
uxsdk_customUnlockedFlyZoneEnabledAlpha- The alpha of the currently enabled custom unlock fly zone. -
uxsdk_customFlyZoneOnAircraftIcon- The icon of the markers for custom unlock zones that have been sent to the aircraft. -
uxsdk_customFlyZoneEnabledIcon- The icon of the markers for currently enabled custom unlock zones.
List of the custom unlock fly zone customization APIs
-
public void requestCustomUnlockZonesFromServer()- Request the custom unlock zones from the server. Once the request is complete, the fly zone helper will be notified. -
public void syncCustomUnlockZonesToAircraft()- Upload custom unlock zones to the aircraft.
List of the custom unlock fly zone customization APIs
-
@ColorInt public int getCustomUnlockFlyZoneColor()- Get the color of the custom unlock fly zones. -
public void setCustomUnlockFlyZoneColor(@ColorInt int customUnlockColor)- Set the color of the custom unlock fly zones. -
@ColorInt public int getCustomUnlockFlyZoneSentToAircraftColor()- Get the color of the custom unlock fly zones that have been sent to the aircraft. -
public void setCustomUnlockFlyZoneSentToAircraftColor(@ColorInt int customUnlockSentToAircraftColor)- Set the color of the custom unlock fly zones that have been sent to the aircraft. -
@ColorInt public int getCustomUnlockFlyZoneEnabledColor()- Get the color of the currently enabled custom unlock fly zone. -
public void setCustomUnlockFlyZoneEnabledColor(@ColorInt int customUnlockEnabledColor)- Set the color of the currently enabled custom unlock fly zone. -
public int getCustomUnlockFlyZoneAlpha()- Get the alpha of the custom unlock fly zones. -
public void setCustomUnlockFlyZoneAlpha(int customUnlockAlpha)- Set the alpha of the custom unlock fly zones. -
public int getCustomUnlockFlyZoneSentToAircraftAlpha()- Get the alpha of the custom unlock fly zones that have been sent to the aircraft. -
public void setCustomUnlockFlyZoneSentToAircraftAlpha(int customUnlockSentToAircraftAlpha)- Set the alpha of the custom unlock fly zones that have been sent to the aircraft. -
public int getCustomUnlockFlyZoneEnabledAlpha()- Get the alpha of the currently enabled custom unlock fly zone. -
public void setCustomUnlockFlyZoneEnabledColor(int customUnlockEnabledAlpha)- Set the alpha of the currently enabled custom unlock fly zone. -
public void setCustomUnlockSentToAircraftMarkerIcon(@NonNull Drawable drawable)- Set the icon of the markers for custom unlock fly zones that have been sent to the aircraft. -
public void setCustomUnlockSentToAircraftMarkerIcon(@NonNull Drawable drawable, float x, float y)- Set the icon of the markers for custom unlock fly zones that have been sent to the aircraft with an (x,y) anchor. - `public void setCustomUnlockEnabledMarkerIcon(@NonNull Drawable drawable) - Set the icon of the markers for currently enabled custom unlock fly zone.
-
public void setCustomUnlockEnabledMarkerIcon(@NonNull Drawable drawable, float x, float y)- Set the icon of the markers for currently enabled custom unlock fly zone with an (x,y) anchor.
The fly zone legend displays a list of all fly zone types with their corresponding colors.
List of the fly zone legend APIs
-
public boolean isFlyZoneLegendEnabled()- Gets the visibility of the fly zone legend. -
public void setFlyZoneLegendEnabled(boolean isEnabled)- Sets the visiblity of the fly zone legend.