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.

See also

Supported backends

Implementing a Kanzi Maps backend

Map backend configuration reference