Kanzi Maps backend¶

The Kanzi Maps backend is a platform-independent abstraction for different map services. Kanzi Maps backend provides a common API to access and manipulate map data and related services.

Kanzi Maps backend architecture¶

This diagram highlights the main components of the Kanzi Maps backend, using the Mapbox implementation as an example. These are also the main interfaces that you need to implement for any Kanzi Maps backend.

Backend¶

The main backend abstraction serves mainly as an access point for the subcomponents, such as the tile fetcher and tiling scheme.

As such the backend provides API for querying:

TileFetcher instance
TilingScheme
Router instance
Geocoder instance

TilingScheme¶

The Tiling Scheme defines:

How Kanzi Maps maps map locations to the addresses of map tiles.
How Kanzi Maps maps WGS84 coordinates to target projection.
The world projection, which Kanzi Maps currently uses as its target projection to avoid unnecessary conversion.

As such, the tiling scheme provides APIs for these operations:

Converting WGS84 latitude-longitude coordinates to world coordinates in the target projection in meters, and the other way around.
Converting WGS84 and world coordinates to tile addresses.
Querying information about tile addresses.
Querying tile boundaries and tile neighbors.

For Google the tiling scheme is provided and can be used by backend implementation, but backends may implement any tiling scheme they need.

TileFetcher¶

The main purpose of the Tile Fetcher is to retrieve data for a given map tile, and to parse and convert that data into an internal VectorTile representation.

VectorTile is a container for map features, where each feature consists of a collection of geometries and associated key-value metadata. Furthermore, VectorTile defines the shape and extent of a map tile.

The Tile Fetcher provides API for:

Mapping tile filters into tile sources.
Providing pipelines for fetching tiles at a given tile address, from a given tile source.

The Tile Fetcher supports these geometry types:

2D points
2D line strings
3D line strings
2D and 3D concave and convex polygons with holes, but preferably non-self-intersecting for best quality
- Extruded polygons for 3D structures, such as buildings
2D triangle meshes (pre-triangulated polygons)
3D triangle meshes with optional normals and UVs with associated textures

TileSource¶

The Tile Source represents a distinct data source from which requests retire independently. For example, two separate servers can be represented as different tile sources, as well as sources from the same server that must be made with different requests.

TileFilter¶

The Tile Filter in the context of the Tile Fetcher defines the layer from which Kanzi Maps requests tile data. The backend can take the layer information and map the layer into a tile source. For example, the traffic layer can be sourced from a different server than the building layer.

Router¶

The Router provides abstraction for querying routing information from a server by specifying a list of way points that Kanzi Maps maps to route response with zero or more valid routes. Each route contains geometry of the route for rendering purposes, as well as turn-by-turn instructions and other crucial tile information.

Geocoder¶

The Geocoder API allows to reverse geocode based on a given WGS84 location. The result is a collection of map features that you can show on a map.

Pipeline and asynchronous computing¶

The Tile Fetcher, Router, and Geocoder all make use of a pipeline abstraction. All these APIs return pipeline instances.

The basic idea of the pipeline is to pre-specify asynchronous tasks and their direct dependencies by ordering those tasks into a directed tree. This directed tree of tasks is referred to as the Pipeline. Kanzi Maps does not currently support ordering tasks into a directed acyclic graph (DAG).

To interact with the pipeline instances that the APIs return, add new stages (tasks) to the end of the pipeline.

For example, this way it is possible to run triangulation in a worker pool without having to control it in the UI thread, or without the need to use explicit locking. Thread safety is typically handled already by schedulers outside the pipeline.

You can specify for each pipeline stage the execution context in which that stage can run. Kanzi Maps currently supports these execution contexts:

MAIN: The UI thread.
IO: Tasks that are mainly blocking or waiting.
COMPUTE: CPU-intensive computation tasks, such as parsing, triangulation, and so on.

After Kanzi Maps constructs a pipeline, a scheduler can execute that pipeline. In the Kanzi Maps API documentation see AsyncScheduler. If you no longer need the result of a pipeline, you can cancel it mid-execution.

Kanzi Maps backend¶