The core component of Navmii SDK responsible for route calculation is NMRoutingService. This class provides the API for calculating new routes and snapping external routes to the map.
CREATING ROUTING SERVICE
NMSdk class contains routingService property which allows Navmii SDK user to access routing service instance. The routing service instance can only be created after the SDK was started.
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
/// RoutingServiceContainer.h
#import <Foundation/Foundation.h>
#import <NavmiiSDK/NMSdk.h>
#import <NavmiiSDK/NMRoutingService.h>
@interface RoutingServiceContainer : NSObject
@property (nonatomic, readonly, strong, nullable) NMRoutingService *routingService;
- (nullable instancetype)initWithSdk:(nonnull NMSdk *)sdk;
- (nullable instancetype)init NS_UNAVAILABLE;
+ (nullable instancetype)new NS_UNAVAILABLE;
@end
/// RoutingServiceContainer.m
#import "RoutingServiceContainer.h"
@implementation RoutingServiceContainer {
NMSdk *sdk;
}
@synthesize routingService;
- (nullable NMRoutingService *)routingService {
if (routingService == nil) {
routingService = sdk.routingService;
}
return routingService;
}
- (nullable instancetype)initWithSdk:(nonnull NMSdk *)sdk {
if (self = [super init]) {
self->sdk = sdk;
}
return self;
}
@end
|
ROUTING SERVICE BASICS
Routing service can be used to calculate new routes or to snap external routes to the map. Routing service handles both processes in the same way.
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
/// SimpleRouteCalculator.h
#import <Foundation/Foundation.h>
#import <NavmiiSDK/NMSdk.h>
#import <NavmiiSDK/NMRoutePlanPoint.h>
#import <NavmiiSDK/NMRouteCalculationOptions.h>
@interface SimpleRouteCalculator : NSObject
- (void)calculateRouteUsingRoutePlanPoints:(nonnull NSArray<NMRoutePlanPoint *> *)routePlanPoints
options:(nullable NMRouteCalculationOptions *)options;
- (void)cancelRouteCalculation;
- (nullable instancetype)initWithSdk:(nonnull NMSdk *)sdk;
- (nullable instancetype)init NS_UNAVAILABLE;
+ (nullable instancetype)new NS_UNAVAILABLE;
@end
/// SimpleRouteCalculator.m
#import "SimpleRouteCalculator.h"
#import "RoutingServiceContainer.h"
#import <NavmiiSDK/NMRouteCalculationSession.h>
#import <NavmiiSDK/NMRouteCalculationListener.h>
@interface SessionListener: NSObject<NMRouteCalculationListener>
- (nullable instancetype)init NS_UNAVAILABLE;
- (nullable instancetype)initWithWeakCalculator:(__weak SimpleRouteCalculator *)weakCalculator;
@end
@implementation SimpleRouteCalculator {
RoutingServiceContainer *routingServiceContainer;
NMRouteCalculationSession *session;
SessionListener *sessionListener;
}
- (void)calculateRouteUsingRoutePlanPoints:(nonnull NSArray<NMRoutePlanPoint *> *)routePlanPoints
options:(nullable NMRouteCalculationOptions *)options {
NMRoutingService *routingService = routingServiceContainer.routingService;
if (routingService == nil) {
// Routing service is not available.
return;
}
[self cancelRouteCalculation];
SessionListener *sessionListener = [[SessionListener alloc] initWithWeakCalculator:self];
NMRouteCalculationSession *session = [routingService calculateRouteUsingRoutePlan:routePlanPoints
options:options
statusReportListener:sessionListener];
if (session == nil) {
// Couldn't start route calculation.
return;
}
// Store route calculation session and its listeners.
self->session = session;
self->sessionListener = sessionListener;
}
- (void)cancelRouteCalculation {
// Optional: you may not do this if you don't pass session elsewhere.
if (session != nil) {
[session cancel];
}
[self onSessionFinished];
}
- (void)onSessionFinished {
session = nil;
sessionListener = nil;
}
- (nullable instancetype)initWithSdk:(nonnull NMSdk *)sdk {
if (self = [super init]) {
routingServiceContainer = [[RoutingServiceContainer alloc] initWithSdk:sdk];
}
return self;
}
@end
@implementation SessionListener {
__weak SimpleRouteCalculator *weakCalculator;
}
- (void)onRouteCalculationSucceededWithResult:(nonnull NMRouteCalculationResult *)result {
// Route calculation succeeded: handling result.
// Releasing session and listeners.
SimpleRouteCalculator *calculator = weakCalculator;
if (calculator != nil) {
[calculator onSessionFinished];
}
}
- (void)onRouteCalculationFailedWithInfo:(nonnull NMRouteCalculationFailureInfo *)failureInfo {
// Route calculation failed: handling failure info.
// Releasing session and listeners.
SimpleRouteCalculator *calculator = weakCalculator;
if (calculator != nil) {
[calculator onSessionFinished];
}
}
- (void)onNonFatalRouteCalculationErrorOccurred:(NMRouteCalculationError)error {
// Non-fatal route calculation error occurred: handling it. Route calculation continues.
}
- (nullable instancetype)initWithWeakCalculator:(__weak SimpleRouteCalculator *)weakCalculator {
if (self = [super init]) {
self->weakCalculator = weakCalculator;
}
return self;
}
@end
|
CALCULATING ROUTES
CALCULATING A ROUTE USING ROUTE PLAN
Routing service allows to calculate new routes using the specified route plan. A route plan is a list of waypoints represented by instances of NMRoutePlanPoint class. A route plan should contain at least two points.
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
// ExtendedRouteCalculator.h
#import <Foundation/Foundation.h>
#import "SimpleRouteCalculator.h"
#import <NavmiiSDK/NMMapCoordinates.h>
#import <NavmiiSDK/NMPosition.h>
@interface ExtendedRouteCalculator : SimpleRouteCalculator
- (void)calculateRouteUsingRoutePlanCoords:(nonnull NSArray<NMMapCoordinates *> *)routePlanCoords
options:(nullable NMRouteCalculationOptions *)options;
- (void)calculateRouteFromCurrentPosition:(nonnull NMPosition *)currentPosition
usingRoutePlanCoords:(nonnull NSArray<NMMapCoordinates *> *)routePlanCoords
options:(nullable NMRouteCalculationOptions *)options;
@end
// ExtendedRouteCalculator.m
#import "ExtendedRouteCalculator.h"
@implementation ExtendedRouteCalculator
- (void)calculateRouteUsingRoutePlanCoords:(nonnull NSArray<NMMapCoordinates *> *)routePlanCoords
options:(nullable NMRouteCalculationOptions *)options {
NSArray<NMRoutePlanPoint *> *routePlanPoints = [ExtendedRouteCalculator pointsFromCoords:routePlanCoords];
[self calculateRouteUsingRoutePlanPoints:routePlanPoints options:options];
}
- (void)calculateRouteFromCurrentPosition:(nonnull NMPosition *)currentPosition
usingRoutePlanCoords:(nonnull NSArray<NMMapCoordinates *> *)routePlanCoords
options:(nullable NMRouteCalculationOptions *)options {
NSArray<NMRoutePlanPoint *> *routePlanPoints = [NSArray arrayWithObject:[[NMRoutePlanPoint alloc] initWithPosition:currentPosition]];
routePlanPoints = [routePlanPoints arrayByAddingObjectsFromArray:[ExtendedRouteCalculator pointsFromCoords:routePlanCoords]];
[self calculateRouteUsingRoutePlanPoints:routePlanPoints options:options];
}
+ (nonnull NSArray<NMRoutePlanPoint *> *)pointsFromCoords:(nonnull NSArray<NMMapCoordinates *> *)routePlanCoords {
NSMutableArray<NMRoutePlanPoint *> *routePlanPoints =
[[NSMutableArray<NMRoutePlanPoint *> alloc] initWithCapacity:routePlanCoords.count];
for (NMMapCoordinates *coords in routePlanCoords) {
[routePlanPoints addObject:[[NMRoutePlanPoint alloc] initWithCoordinates:coords]];
}
return routePlanPoints;
}
@end
|
ROUTING SERVICE SETTINGS
As you can see in the examples above user is able to pass route calculation options within each routing service request. The specified options are used during request handling. If no options were passed default options are used. NMRouteCalculationOptions class instances represent available route calculation optionsA NMRouteCalculationOptions instance is a convenient way to tailor your route calculation request.
Here's how you can create an instance: most typical example of the last three methods usage:
| Code Block | ||||
|---|---|---|---|---|
| ||||
// Common initializer:
NMRouteCalculationOptions *options = [NMRouteCalculationOptions new];
// Or with default values except the isWalkingMode property, which is initialized with YES:
NMRouteCalculationOptions *options = [[NMRouteCalculationOptions alloc] initInWalkingMode];
// Or with a custom NMTrafficSnapshot object:
NMRouteCalculationOptions *options = [[NMRouteCalculationOptions alloc] initWithTraffic: trafficSnapshot];
|
Following parameters can be set:
- isWalkingMode specifies whether walking mode is used. Default value is 'NO'.
- optimization specifies a route optimization. The property is ignored in walking mode. Default value is NMRoutingOptimization_Fastest.
- vehicleType specifies vehicle type. The property is ignored in walking mode. Default value is NMVehicleType_Car.
- avoidTollRoads specifies whether toll roads should be avoided. The property is ignored in walking mode. Default value is 'NO'.
- buildsAllDirections specifies whether to build all directions before the route calculation. Default value is 'NO'.
- considerTraffic specifies whether traffic data should be considered during route calculation. Default value is 'YES'.
- useServerTimesToCalculateEta specifies whether the ETA of a route should be calculated using time data received from routing server (if available). If 'NO' is specified, the ETA is based on time data obtained from maps locally on the device. Default value is 'YES'.
- maxAlternativeRoutesCount limits maximum number of alternative routes being calculated in route calculation session. Default value is 3.
- computeEstimatedTimeIgnoringTrafficDelay informs routing engine that it should compute the estimated route time not considering delays caused by traffic along with just estimated route time. The computed value is available via the estimatedTimeIgnoringTrafficDelay property ofNMRoute class. Default value is 'NO'.
- routingType specifies routing type. Default value is NMRoutingType_Combined.
- maxOnboardRoutingDistanceInMeters specifies whether on-board or server routing will be used if the routingType property is set. Default value is 30,000 meters.
- maxServerRoutesSnappingDistanceInMeters limits the distance of the route being snapped to map immediately after obtaining the route. Setting this property to -1 indicates that snapping distance is unlimited and the whole route will be snapped immediately after obtaining the route. Please note that setting large values or -1 to the property may slow down the whole calculation process, because the snapping process requires all the map tiles along the snapping route part being downloaded from web. This property is taken into account in case of server routing only. Default value is 100,000 meters.
- trafficSnapshot a traffic snapshot which is used in route calculation and visualisation of the route polyline. The source of the traffic snapshot is another SDK module. If you want to consider traffic in route calculation and display it on the route polyline after the route is calculated you need to set valid nonnull value to this property. Default value is 'nil'.
- externalRouteProvider route provider to be used to fetch routes from external routing server. If not specified default server is used. Default value is 'nil'.