Selections and blockages

Since version 9.10 the MapTrip SDK provides the opportunity for adding blockages in a convenient way by using the Selection API.

A blockage is always a geometric object, that might be a point, polyline or polygon. Each of these blockages may have an optional start and end time.

Types of blockages

Blockages can either be temporary or persisted. You can add a blockage to one of the new provided selections of the SDK:

Temporary

Selection.getTemporaryBlockages()

The blockages of this Selection are lost after a restart of the App.

Persisted

Selection.getPersistedBlockages()

The blockages of this Selection are saved into the user data path (blockages_selection.sfs) and will again be loaded after a restart.

Common usage

If you want to add a point, polyline or polygon, you will always have to create a Polygon object with

• One point, that later is treated as a point blockage
• Several points, where the first point is not equal than the last point, that later is treated as a polyline blockage
• Several points, where the first point is equal to last point, that later is treated as a polygon blockage

If you use a polyline as a blockage, the streets are only blocked in the direction of this polyline.

When you have created a Polygon object and have set the points with Polygon.setPoints() you can optionally set a start and end time with the new functions Polygon.setStartTime() and Polygon.setEndTime().

The time has to be set as timestamp in UTC (seconds since 1970).

Additionally you can set a radius for each of these blockage objects. The radius is not only used, when you have a point blockage. The radius is also added at polylines and polygons. The following picture shows, how the radius is used:

You can set the radius with Polygon.setAttributeAsDouble("BlockageRadius", radius)

If you do not set the radius, then it will taken from the settings.ini. For each object type you can set the radius as follows:

[ROUTING]
PointBlockageRadius=3
PolylineBlockageRadius=3
PolygonBlockageRadius=3

If the radius is not set in the settings.ini, 3 Meters are taken.

Once you have your new Polygon object, you can add this to the persisted or temporary Selection object. It will then be used for route calculation (offline and online!).

If you set a end time at a blockage and add this to the persisted selection, the blockage (still a Polygon object) will be deleted automatically for persistent blockages, when the time has exceeded.

Behavior

The persisted blockages are saved

• when the Application terminates correctly (uninitialize) and
• when a new route calculation is triggered (new route guidance or rerouting) and the selection was modified before.
• it is not saved after each single modification (adding or deleting a Polygon object), because this might result in some performance issues, if you do several modifications.

The blockage Selections are not automatically displayed in all of your Mapviewer. Therefore you have to call Mapviewer.showSelection(...) for the desired Mapviewer.

But if you modify a blockage Selection during a route guidance, a rerouting is automatically triggered with the next GPS update.

Example

The following example shows a Polygon blockage and the resulting route.

// Assumption: 
// You already have a Mapviewer object, called primaryMap

// 1. Get the temporary blockages
val temporaryBlocks = Selection.getTemporaryBlockages()

// 2. Create the points for the rectangle
val p1 = Point()
p1.setCoords(790126.0, 6572184.0)

val p2 = Point()
p2.setCoords(790261.0, 6572184.0)

val p3 = Point()
p3.setCoords(790261.0, 6572274.0)

val p4 = Point()
p4.setCoords(790126.0, 6572274.0)

val p5 = Point()
p5.setCoords(790126.0, 6572184.0)

// Create a list of the points
val pointsList = listOf(p1, p2, p3, p4, p5)

// 3. Create a Polygon and set the points
val newBlock = Polygon()
newBlock.setPoints(pointsList)

// 4. Add the Polygon to the temporary blockages selection.
// We provide a specific fill color ("#AARRGGBB" format).
temporaryBlocks.addPolygon(newBlock, "#FF808080")

// 5. Display the selection on the primary Mapviewer.
// The fill and border colors in this call are ignored for these polygons,
// because each block in the selection has its own individual color defined.
primaryMap.showSelection(temporaryBlocks, true, "#FFFFFFFF", "#FFFFFFFF", "")

Overview new functions

Point:
mta_pnt_setCoords

Polygon:
mta_plg_getAttributeAsInt64
mta_plg_setAttributeAsInt64
mta_plg_getStartTime
mta_plg_setStartTime
mta_plg_getEndTime
mta_plg_setEndTime
mta_plg_getID
mta_plg_setID

Attribute:
mta_att_getAsInt64
mta_att_setAsInt64

Selection:
mta_sel_addPoint
mta_sel_getPersistedBlockages
mta_sel_getTemporaryBlockages