Municipal API for 2D

Introduction

Municipal navigation is the feature that allows drivers to be navigated in the mode suitable for execution of municipal services. That is, when one needs a navigation in complicated trajectories not always matching the official road network. An example is the waste management service where the vehicle sometimes needs to go off-road or into a forbidden zone and where driver needs to be given custom instructions such as "collect the bin on the right side".
The Municipal feature is supported by use of municipal API functions and OFG json route object, and it is reflected by a special navigation mode called municipal navigation mode, which is triggered by use of LoadOFGRoute API function.

Requirements and limitations

The feature is currently supported only for the 2D navigation version Sygic Fleet 2D release 15i or newer, and under extra licensing

Usecase example

OFG routes can be imported to navigation from any web based solution, which allows construction and editing of routes. Such tool can apply a simple json conversion and import a route through the Sygic API call loadOFGRoute.
An example of a Municipal route generator shown bellow can be quickly designed using Sygic maps services.

Json Municipal Route object

This route object is used with the SDK function LoadOFGRoute, through which one can send a guided route to the navigation while the navigation switches to the special navigation mode, in which it tries to navigate drivers using the defined geometry, i.e. even on the roads or trajectories not covered by current maps.
Such routes can be extended with additional information such as coloring for visualization and possible TTS messaging.

Route format

The json specification of the supported structure is shown in the diagram bellow. The filenames of this type of route have the suffix ofg.
The fields denoted with * are mandatory.

Table of json fields

Field

Type

Default value

Description

name

string

caption on the point

version

string

n/a

the file format version, supported: 1.0.0.2

lat

int

n/a

latitude position defined as WGS84 multiplied by 100,000

lon

int

n/a

longitude position defined as WGS84 multiplied by 100,000

color

string

#C0C0C080

the color string defined in the format RGBA format, example #FFA0522D. The color is applied on the point and the roadline starting from this point to the next one

instruction

int

-1

defines instruction to be given at the point, -1 denotes the instruction to be inferred automatically, -2 denotes no instruction is given, see the Instruction table bellow for details

Usecases

load OFG route and get into municipal navigation mode and back to standard navigation mode

2. Navigate to beginning of OFG route

navigate to beginning of OFG route in order to get ready for OFG navigation mode

3. Pause OFG route

Pause OFG route navigation in order to resume later

4. Resume OFG route

Resume OFG navigation mode at the point it has been previosuly paused

5. Handle off-route scenario

React on off-route events in an appropriate way

6. Join OFG route

Join OFG route in order to handle road obstacles

7. Missed segments

Save missed segments as OFG routes for possibly deferred execution

1. Load and unload OFG route

In order to load OFG route, call ApiNavigation.loadOFGRoute(pathToOFGFile, 0, FLAG_OFG_DEFAULT, timeout). Navigation will switch to the OFG navigation mode. In this mode vehicle is not snapped to a road network but rather red thin line appears, showing the point on the OFG route closest from your vehicle. If you want to unload OFG route, call ApiNavigation.stopNavigation(timeout). Navigation is then switched back to the standard navigation mode (vehicle snapped to a road network).

2. Navigate to beginning of OFG route

Before loading OFG route, you can consider that driver should be navigated to the beginning of the OFG route using standard navigation mode. First, you will have to discover the start point of the OFG route and the direction of the first OFG segment, so that you are navigated to this point in a correct direction. To get these values, you have to parse the OFG file by yourself or you can use the helper class OfgSegmentInfo (shown in the appendix) to support this functionality. Then you can call ApiNavigation.startNavigation(startOfOFGRoute, 0, false, routeComputeSettings, timeout), where routeComputeSettings is instance of the RouteComputeSettings class and contains the direction angle information. If you want to see the OFG route during navigation to its start, but you don't want to be switched to the OFG navigation mode, call loadOFGRoute with FLAG_OFG_SHOW_ONLY. This will ensure that an OFG route will be visible, but you will stay in standard navigation mode. When arriving to the start point, you will receive EVENT_ROUTE_FINISH. To switch to the OFG navigation just call loadOFGRoute with flag FLAG_OFG_DEFAULT.
Note: You may consider whether to use or not the navigation to the start point of the OFG route. For example if the vehicle is close to the start of an OFG route, you may want to skip navigating to the start point.

3. Pause OFG route

For some cases you may want to pause the current OFG navigation, get navigated from it in a standard navigation mode and return to the pause point later to continue. First you have to get the current status of the OFG navigation. Use ApiNavigation.getOFGRouteStatus(). From the resulting JSON string you can parse out the current index of OFG route (represents state and the progress of the OFG route execution) and GPS coordinates of vehicle's current position on OFG route. Store these values for the purpose of resuming the route and call ApiNavigation.stopNavigation().

5. Handle off-route situation

If the driver gets too far from an OFG route, EVENT_OFF_ROUTE is triggered. Event data is equal to "1". If the driver comes back in a near proximity to the route, the same event is triggered but with the data equal to "0".
Note that driver will be guided to the point where he left the route. If this point is not reachable, he should be given the possibility to "join" the route (see this usecase in a next section).

6. Join OFG route

If the user is off route and he cannot reach his abandoned position on the OFG route, he should be able to continue following the route from his current position. In this case call loadOFGRoute with startIndex -1. This will reset driver's current position on the OFG route to the closest point on route to vehicle.

7. Missed segments

If the driver avoids a part of the route (e.g. due to it was not reachable), you may want to store this part of the route as a missed segment for future handling. Use saveOFGRoute(fileName, fromIndex, fromPos, toIndex, toPos, timeout) to save a particular subroute of the currently loaded OFG route. There are 3 scenarios for this case:

1. Driver could not reach the start point (Start following)
Driver should be able to join the route. After joining the route, get the current OFG route status. This will give you his current position and route index. Use these values as parameters (toPos and toIndex) for saveOFGRoute. Setting start point to null and start index to -1 will ensure that the saved subroute will have the start in the same point as the original route.

2. Driver could not reach the end of the route
Driver should be able to end the route prematurely (e.g. due to the end point is not reachable). Before unloading the route, get the route status to get actual point and index. Use these values as parameters (fromPos and fromIndex) for saveOFGRoute. Setting end point to null and end index to -1 will ensure that the saved subroute will the end in the same point as the original route.

3. Driver had to avoid an inner part of the route
In this situation you have to work with Off route event. If the driver gets too far from a route, get the route status to get current point and current index on the OFG route (start of missed segment) and store it. After joining the route, do the same to get the end point and end index of missed segment.

Note: You can set the minimal length of the missed segment in the application's settings.ini file (m_nGuidedMinSaveRouteLength). If you try to save a shorter subroute, function will fail and will give you a notification about this.