Show location on map

_|

The location of the device is shown by default using an arrow position tracker. If a DataSource has been successfully set in PositionService and is being fed regularly with new position data objects 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.

note

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 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 and zoomLevel and viewAngle.

Set map rotation mode

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

auto prefs = mapView->preferences().followPositionPreferences();
prefs.setMapRotationMode(EFollowPositionMapRotationMode::FPMRM_PositionHeading);

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

prefs.setMapRotationMode(EFollowPositionMapRotationMode::FPMRM_Compass);

The map rotation can also be fixed to a given angle using the EFollowPositionMapRotationMode::FPMRM_Fixed value and providing an angle value:

prefs.setMapRotationMode(EFollowPositionMapRotationMode::FPMRM_Fixed, 30);

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

The getMapRotationMode returns a pair containing:

• the current EFollowPositionMapRotationMode mode
• the map angle set in case of EFollowPositionMapRotationMode::FPMRM_Fixed

Exit follow position

The stopFollowingPosition method from the mapController 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 setTouchHandlerExitAllow 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 getter 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.

Field / Method	Type	Explanation
setCameraFocus	XyF	The position on the viewport where the position tracker is located on the screen.
setTimeBeforeTurnPresentation	int	The time interval before starting a turn presentation. In seconds.
setTouchHandlerExitAllow	bool	If set to false then gestures made by the user will exit follow position mode
setTouchHandlerModifyPersistent	bool	If set to true then changes made by the user using gestures are persistent
setViewAngle	double	The viewAngle used within follow position mode
setZoomLevel	int	The zoomLevel used within follow position mode
setAccuracyCircleVisibility	bool	Specifies if the accuracy circle should be visible (regardless if is in follow position mode or not)
isTrackObjectFollowingMapRotation	bool	Specifies 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):

auto prefs = mapView->preferences().followPositionPreferences();
int error = prefs.setAccuracyCircleVisibility(true);

Accuracy circle turned on

Customize circle color

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

auto setErrorCode = MapSceneObject::setDefPositionTrackerAccuracyCircleColor(Rgba(255, 0, 0, 0));
GEM_INFO_LOG("Error code for setting the circle color: %d", 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:

Rgba color = MapSceneObject::getDefPositionTrackerAccuracyCircleColor();

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 setCameraFocus method can be used:

// Calculate the position relative to the viewport
float twoThirdsX = 2. / 3.;
float threeFifthsY = 3. / 5.;
XyF position = XyF(twoThirdsX, threeFifthsY);

// Set the position of the position tracker in the viewport
// while in follow position mode
auto prefs = mapView->preferences().followPositionPreferences();
auto error = prefs.setCameraFocus(position);

mapView->startFollowingPosition();

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

Customize position icon

The SDK supports customizing the position tracker to suit your application's requirements. Check ESceneObjectFileFormat enum for supported formats.

    // Declare the scene data object list
    SceneObjectDataList objectList;

    // Populate the list with the desired scene data objects.
    
    // Customize the position tracker
    MapSceneObject::customizeDefPositionTracker(objectList);

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

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

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 setter:

// Get the position tracker
auto mapSceneObject = MapSceneObject::getDefPositionTracker();

// Change the scale 
mapSceneObject.first->setScaleFactor(0.5f);

A value of 1.0f corresponds with the default scale value. The parameter passed to the setter should be in the range (0.0f, mapSceneObject.first->getMaxScaleFactor()]. The code snippet from above sets half the scale.

Note

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 setter:

// Get the position tracker
auto mapSceneObject = MapSceneObject::getDefPositionTracker();

// Change the visibility
mapSceneObject.first->setVisibility(false);

The snippet above makes the position tracker invisible.