Routes (v2.0.x)

The core component responsible for working with routes and navigation in Navmii SDK is NMRoutingService. This class provides you an API for working with the SDK's routing features. You can calculate and apply single or multiple routes with this class's instance.  

CALCULATING ROUTES

If you have an array of NMMapCoordinates representing waypoints for a route, you can calculate the route (and alternative routes, if applicable) using an NMRoutePlan instance and calculateRouteWithRoutePlan: method. Alternatively, use calculateRouteFromCurrentPositionWithRoutePlan: method if you you want the route to be calculated from the user's current GPS position. This way you don't need to pass the current position coordinates as the first element in the NMMapCoordinates array.

//creates a routePlan instance with waypoints
NMRoutePlan *routePlan = [[NMRoutePlan alloc] init];
routePlan.waypoints = arrayOfCoordinates;
//calculates routes starting from the first coordinates in the array
[[NMSdk sharedInstance].routingService calculateRouteWithRoutePlan:routePlan];
//performs the same operation but starting with the user's current position
[[NMSdk sharedInstance].routingService calculateRouteFromCurrentPositionWithRoutePlan:routePlan];

The methods described above have a sibling pair of methods: calculateRouteWithRoutePlan:andSettings: and calculateRouteFromCurrentPositionWithRoutePlan:andSettings:. You can use them for customization of route calculation passing an NMRoutingSettings instance as the second parameter. For more information on NMRoutingSettings please refer to ROUTING SETTINGS section.

//creates a NMRoutePlan instance with waypoints
NMRoutePlan *routePlan = [[NMRoutePlan alloc] init];
routePlan.waypoints = coordinatesArray; 
//creates a NMRoutingSettings instance with pedestrian routing mode
NMRoutingSettings *settings = [[NMRoutingSettings alloc] init];
[settings setRoutingMode:NMRoutingModePedestrian];
//applies the settings and calculates routes starting from the first coordinates in the array
[[NMSdk sharedInstance].routingService calculateRouteWithRoutePlan:routePlan andSettings:settings];
//performs the same operation but starting with the user's current position
[[NMSdk sharedInstance].routingService calculateRouteFromCurrentPositionWithRoutePlan:routePlan andSettings:settings];

Please note that the SDK will initiate rerouting process only if the current route was calculated from the current position, i.e. using calculateRouteFromCurrentPositionWithRoutePlan: or calculateRouteFromCurrentPositionWithRoutePlan:andSettings: methods.

ROUTE SERVICE STATUS

There is three possible NMRouteService states that can be obtained through routeStatus readonly property:

• No routes are presented on the map (NMRouteStatusNoRoute)
• A route (or routes) is presented on the map, but the navigation hasn't started (NMRouteStatusChoosing)
• A route is applied and navigation is in process (NMRouteStatusHasActiveRoute)

HANDLING ROUTE CALCULATION EVENTS

The SDK can notifies a subscriber object on the following route calculation events:

• calculation started
• calculation succeeded
• calculation failed
• route is cleared

To receive these notifications make one of your objects conform to NMRoutingDelegate protocol and add it to NMRoutingService delegates with the following code:

@interface SubscriberViewController () <NMRoutingDelegate>
 
@end
 
@implementation SubsriberViewController
 
- (void)viewDidLoad {
    [[NMSdk sharedInstance].routingService addDelegate:self];
}
 
#pragma mark - NMRoutingDelegate Methods
- (void)onRouteCalculationStartedWithReason:(NMRouteCalculationReason)calculationReason {
    //handle route calculation start here
}

- (void)onRouteCalculationSucceededWithReason:(NMRouteCalculationReason)calculationReason andInfo:(NMRoutingSuccesInfo *)info {
    //handle successful route calculation finish here
    //this line logs out number of calculated routes
    NSLog(@"number of routes calculated %d",(int)[info routesCount]);
}

- (void)onRouteCalculationFailedWithReason:(NMRouteCalculationReason)calculationReason andInfo:(NMRoutingFailureInfo *)info {
    //handle route failure here
}

- (void)onRouteCleared {
    //handle 'route cleared' event here
}
@end

 You can add multiple delegates to an NMRoutingService instance, so you can have multiple objects notified on route calculation events. You can unsubscribe objects from these notifications using removeDelegate: method.

[[NMSdk sharedInstance].routingService removeDelegate:objectToUnsubscribe];

Use isCalculatingRoute BOOL property to find out if the SDK's route calculation is in process.

MANAGING CALCULATED ROUTES

By default, the SDK calculates up to 3 routes with a particular route plan if possible and renders them on the map. You can disable this type of behaviour with alternativeRoutesDrawingEnabled property.

//disables rendering of alternative routes on the map
[[NMSdk sharedInstance].routingService setAlternativeRoutesDrawingEnabled:NO];

The NSUInteger representing the number of all routes rendered on the map is stored in routesCount property, and the index of the currently selected route is stored in selectedRouteIndex property. 

//logs out the numbers of routes and the selected route index
NMRouteService *service = [NMSdk sharedInstance].routingService;
NSLog(@"number of routes %d, selected route index %d", service.routesCount, service.selectedRouteIndex);

To select the route at the desired index use selectRouteAtIndex: method. The clearRoutes method removes all the calculated routes from the map. The abort method cancels route calculation that is currently in progress.

ROUTING SETTINGS

Navmii SDK allows you to customize the parameters that will be used for route calculation. You can do it via NMRoutingSettings's properties. You can define if the traffic will be taken into consideration and if toll roads and motorways will be avoided on route calculation:

NMRoutingSettings *settings = [[NMRoutingSettings alloc] init];
settings.considerTraffic = YES;
settings.avoidTollRoads = YES;
settings.avoidMotorways = YES;

There are also parameters that define:

• routing mode (pedestrian or vehicle)
• optimization type (fastest, easiest, economical, shortest)
• vehicle type (car, motorcycle, cycle, lorry, truck, delivery truck)

They are represented as routingMode, optimization and vehicleType properties respectively.

NMRoutingSettings *settings = [[NMRoutingSettings alloc] init];
settings.routingMode = NMRoutingModeVehicle;
settings.routingMode = NMRoutingOptimizationShortest;
settings.vehicleType = NMVehicleTypeTruck;