Route Visualization (v2.1.x – 2.2.x)

Owned by Dmitry Stepanov
Last updated: Dec 03, 2021 by Dmitry Lykov
3 min read

The core component of Navmii SDK responsible for visualization of route-related data is NMRouteVisualizer. This class provides the API to render routes, alternative routes and waypoint markers on map.

CREATING ROUTE VISUALIZER

NMSdk class contains the routeVisualizer property providing access to the instance of route visualizer. The route visualizer instance can be accessed only after the SDK was started.

VISUALIZING THE DATA

NMRouteVisualizer class has the performRequest: method which allows to execute a route-related data visualization request. The specified request parameter contains data to visualize.

Note that visualization request, once performed, affects global SDK state, therefore it's user's responsibility to handle the state correctly.

Route visualization request is the instance of NMRouteVisualizerRequest class.

NMRouteVisualizerRequest can be configured to perform the following actions:

  • set or remove an active route (active route polyline is rendered with route color and traffic is displayed on it);
  • set or remove any number of alternative routes (alternative routes are rendered with grey color and traffic is displayed on it);
  • set or remove route waypoint markers, including special markers for start and finish points.

CREATING ROUTE VISUALIZATION REQUEST

Navmii SDK contains the NMRouteVisualizerRequest class which should be used to create requests configured to render the required data on map.

As you can see from the interface of NMRouteVisualizerRequest class, it allows to construct a request which performs multiple operations (i.e. to set an active route, to set one or multiple alternative routes and to set way-point markers) within the single request. This is the preferred way to handle the visualizer state in terms of performance as each route visualizer request, once executed, requires map tiles to be re-created.

If possible, try to create a single request configured to perform all the required actions rather than creating a new request for each action. The less often the performRequest: method of NMRouteVisualizer is called, the better.

VISUALIZING ROUTES

The NMRouteVisualizerRequest class contains the requestDisplayingPolylineOfRoute: method which allows to create an NMRouteVisualizerRequest instance configured so that the new request, in addition to the previously configured actions, will display the active route polyline on map. The route parameter is an instance of NMRoute class which is used to get a polyline to render. The active route polyline is rendered with the route color (magenta by default). You can change it using the routeLineColor property of NMMapView. Traffic is displayed on the route polyline if the route contains it.

The requestDisplayingPolylineAndWaypointsOfRoute: method allows to create an NMRouteVisualizerRequest instance configured so that the new request, in addition to the previously configured actions, will display the active route polyline along with its waypoints on map. The route parameter is an instance of NMRoute class which is used to get a polyline and a route plan. The special start point marker (the blue flag) is used for route origin, special finish point marker (black-and-white flag) is used for route destination, intermediate waypoints are rendered with yellow flag.

The requestDisplayingPolylinesOfAlternativeRoutes: method allows to create an NMRouteVisualizerRequest instance configured so that the new request, in addition to the previously configured actions, will display alternative route polylines on map. The routes parameter is an array of alternative routes. Each route is an instance of NMRoute class which is used to get a polyline to render. Alternative routes are rendered with grey color and traffic is displayed on each polyline if the route contains it.

The requestRemovingRoutePolyline and requestRemovingAlternativeRoutePolylines methods allow to create an NMRouteVisualizerRequest instance configured so that the new request, in addition to the previously configured actions, will remove the active and the alternative route polylines respectively.

VISUALIZING WAYPOINT MARKERS

The NMRouteVisualizerRequest contains the requestDisplayingWaypointMarkersAtCoordinates:consideringFirstOneAsStart: method which allows to render waypoint markers on map. The coordinates parameter specifies an array of waypoint marker coordinates. Each coordinate is an instance of NMMapCoordinates class. The special finish marker (black-and-white flag) is used for the last waypoint. The special start marker (blue flag) is used for the first waypoint if YES is specified for the consideringFirstOneAsStart parameter, otherwise the regular waypoint marker (yellow flag) is used. The regular marker is also used for all other waypoints.

The requestRemovingWaypointMarkers method allows to create an NMRouteVisualizerRequest instance configured so that the new request, in addition to the previously configured actions, will remove all the waypoint markers from map.

ROUTE VISUALIZER BINDING

NMRouteVisualizer class conforms to the NMRouteVisualizerRequestListener protocol which allows to bind it to a source of route visualizer requests. The only source of route visualizer requests in Navmii SDK is NMRouteNavigator class, which is able to render the route being navigated. To achieve such a behaviour you need to connect the route visualizer (routeVisualizer property of NMSdk) to the route navigator (routeNavigator property of NMSdk) using addRouteVisualizerRequestListener: method of NMRouteNavigator. You are also able to implement your own route visualizer request source if you need to.