Skip to main content

Show location on map

|

The location of the device is shown by default using an arrow position tracker. If the data source has been successfully set and the required permissions were granted then the position tracker showing the current location should be visible on the map as an arrow.

Default position tracker showing current position

At the moment it is not possible to have multiple position trackers on the map.

info

GPS accuracy may be limited in environments such as indoor spaces, areas with weak GPS signals, or locations with significant obstructions, such as narrow streets or between tall buildings. In these situations, the tracker may exhibit erratic movement within a confined area. Additionally, the performance of device sensors, such as the accelerometer and gyroscope, can further impact GPS positioning accuracy.

This behavior is more pronounced when the device is stationary.

Start follow position​

Following the position tracker can be done by calling the startFollowingPosition() method on the MapView.

mapView.startFollowingPosition()

When the startFollowingPosition() method is called, the camera enters a mode where it automatically follows the movement and rotation of the position tracker. This ensures the user's current location and orientation are consistently centered and updated on the map.

The startFollowingPosition() method can take parameters such as animation, which controls the movement from the current map camera position to the position of the tracker, zoomLevel and viewAngle.

Set map rotation mode​

When following position, it is possible to have the map rotated with the user orientation:

val prefs = mapView.preferences?.followPositionPreferences
prefs?.setMapRotationMode(EFollowPositionMapRotationMode.PositionHeading)

If you want to use the compass sensor for map rotation use EFollowPositionMapRotationMode.Compass:

val prefs = mapView.preferences?.followPositionPreferences
prefs?.setMapRotationMode(EFollowPositionMapRotationMode.Compass)

The map rotation can also be fixed to a given angle using the EFollowPositionMapRotationMode.Fixed value and providing a mapAngle value:

val prefs = mapView.preferences?.followPositionPreferences
prefs?.setMapRotationMode(EFollowPositionMapRotationMode.Fixed, angle = 30.0)

A value of 0.0 given for the angle parameter represents north-up alignment.

The mapRotationMode returns a Pair containing:

  • the current EFollowPositionMapRotationMode mode
  • the map angle set in case of EFollowPositionMapRotationMode.Fixed

Exit follow position​

The stopFollowingPosition() method from the MapView can be used to programmatically stop following the position.

mapView.stopFollowingPosition()

The follow mode will be exited automatically if the user interacts with the map. Actions such as panning, or tilting will disable the camera's automatic tracking. This can be deactivated by setting touchHandlerExitAllow to false (see the section below).

Customize follow position settings​

The FollowPositionPreferences class has options which can be used to customize the behavior of following the position. This can be accessed from the preferences property of the MapView.

The fields defined in FollowPositionPreferences take effect only when the camera is in follow position mode. To customize camera behavior when not following the position, refer to the fields available in MapViewPreferences and MapView.

FieldTypeExplanation
cameraFocusXyFThe position on the viewport where the position tracker is located on the screen.
timeBeforeTurnPresentationIntThe time interval before starting a turn presentation
touchHandlerExitAllowBooleanIf set to false then gestures made by the user will exit follow position mode
touchHandlerModifyPersistentBooleanIf set to true then changes made by the user using gestures are persistent
viewAngleDoubleThe viewAngle used within follow position mode
zoomLevelIntThe zoomLevel used within follow position mode
accuracyCircleVisibleBooleanSpecifies if the accuracy circle should be visible (regardless if is in follow position mode or not)
isTrackObjectFollowingMapRotationBooleanSpecifies if the track object should follow the map rotation

Please refer to the adjust map guide for more information about the viewAngle, zoomLevel and cameraFocus fields.

If no zoom level is set, a default value is used.

Use of touchHandlerModifyPersistent​

When the camera enters follow position mode and manually adjusts the zoom level or view angle, these modifications are retained until the mode is exited, either manually or programmatically.

If touchHandlerModifyPersistent is set to true, then invoking startFollowingPosition() (with default parameters for zoom and angle) will restore the zoom level and view angle from the previous follow position session.

If touchHandlerModifyPersistent is set to false, then calling startFollowingPosition() (with default zoom and angle parameters) will result in appropriate values for the zoom level and view angle being recalculated.

Tip

It is recommended to set the touchHandlerModifyPersistent property value right before calling the startFollowingPosition() method.

Use of touchHandlerExitAllow​

If the camera is in follow position mode and the touchHandlerExitAllow property is set to true, a two-finger pan gesture in a non-vertical direction will cause the camera to exit follow position mode.

If touchHandlerExitAllow is set to false, the user cannot manually exit follow position mode through touch gestures. In this case, the mode can only be exited programmatically by calling the stopFollowingPosition() method.

Set circle visibility​

For example, in order to show the accuracy circle visibility on the map (which is by default hidden):

val prefs = mapView.preferences?.followPositionPreferences
prefs?.accuracyCircleVisible = true
Accuracy circle turned on

Customize circle color​

The accuracy circle color can be set using the setDefPositionTrackerAccuracyCircleColor() static method from the MapSceneObject class:

val setErrorCode = MapSceneObject.setDefPositionTrackerAccuracyCircleColor(Rgba(255, 0, 0, 255))
Log.d(TAG, "Error code for setting the circle color: $setErrorCode")
Tip

It is recommended to use colors with partial opacity instead of fully opaque colors for improved visibility and usability.

The current color can be retrieved using the getDefPositionTrackerAccuracyCircleColor() static method:

val color = MapSceneObject.getDefPositionTrackerAccuracyCircleColor()

The color can be reset to the default value using the resetDefPositionTrackerAccuracyCircleColor() static method:

val resetErrorCode = MapSceneObject.resetDefPositionTrackerAccuracyCircleColor()
Log.d(TAG, "Error code for resetting the circle color: $resetErrorCode")

Set position of the position tracker on the viewport​

In order to set the position tracker on a particular spot of the viewport while in follow position mode the cameraFocus property can be used:

// Calculate the position relative to the viewport
val twoThirdsX = 2.0f / 3.0f
val threeFifthsY = 3.0f / 5.0f
val position = XyF(twoThirdsX, threeFifthsY)

// Set the position of the position tracker in the viewport
// while in follow position mode
val prefs = mapView.preferences?.followPositionPreferences
prefs?.cameraFocus = position

mapView.startFollowingPosition()

The cameraFocus property uses a coordinate system relative to the viewport, not physical pixels. In this way XyF(0.0f, 0.0f) corresponds with top left corner and XyF(1.0f, 1.0f) corresponds with right bottom corner.

Customize position icon​

The SDK supports customizing the position tracker to suit your application's requirements. For example, you can set a simple PNG as the position tracker using the following approach:

// Read the file and load the image as a binary resource
val inputStream = assets.open("navArrow.png")
val imageByteArray = inputStream.readBytes()

// Customize the position tracker
MapSceneObject.customizeDefPositionTracker(imageByteArray, SceneObjectFileFormat.tex)

Besides simple 2D icons, 3D objects as glb files can be set. The format parameter of the customizeDefPositionTracker() should be set to SceneObjectFileFormat.glb in this case.

At this moment it is not possible to set different icons for different maps.

danger

Make sure the resource (in this example navArrow.png) is correctly placed in the assets folder. See the Android documentation for more information.

Custom position tracker

Other position tracker settings​

Other settings such as scale and the visibility of the position tracker can be changed using the methods available on the MapSceneObject which can be obtained using MapSceneObject.getDefPositionTracker().

Change the position tracker scale​

To change the scale of the position tracker we can use the scale property:

// Get the position tracker
val mapSceneObject = MapSceneObject.getDefPositionTracker()

// Change the scale
mapSceneObject?.scale = 0.5f

A value of 1.0 corresponds with the default scale value. The parameter passed to the property should be in the range (0, mapSceneObject.maxScale]. The code snippet from above sets half the scale.

info

The scale of the position tracker stays constant on the viewport regardless of the map zoom level.

Change the position tracker visibility​

To change the visibility of the position tracker we can use the visibility property:

// Get the position tracker
val mapSceneObject = MapSceneObject.getDefPositionTracker()

// Change the visibility
mapSceneObject?.visibility = false

The snippet above makes the position tracker invisible.

Follow position events​

The SDK provides callbacks to monitor when the MapView enters or exits follow position mode:

mapView.onEnterFollowingPosition = {
    Log.d(TAG, "Entered follow position mode")
    // Hide GPS button or update UI
}

mapView.onExitFollowingPosition = {
    Log.d(TAG, "Exited follow position mode")
    // Show GPS button or update UI
}

You can also check if the MapView is currently following position:

val isFollowing = mapView.isFollowingPosition()
Log.d(TAG, "Currently following position: $isFollowing")
Last updated on