Encoded tile data

In this section, learn how to work with encoded tile data:

Get encoded tile data

After you create the DataStoreClient instance and add the OCM catalog, you can request encoded map data for a specific tile. The data is synchronously passed to you via a callback.

Note: Unbundling happens every time when encoded map data for a tile is requested.

Get encoded data from one catalog

You can get encoded map data for a specific tile from a catalog defined by CatalogHandle.

Example:

const auto tile_key
    = olp::geo::TileKey::FromRowColumnLevel( 6486, 8801, 14 );

auto callback = [&]( const olp::clientmap::datastore::EncodedClientMapTile&
                         tile ) {
    const auto road_name_layer = std::find_if(
        tile.begin( ), tile.end( ),
        [&]( const olp::clientmap::datastore::LayerPayloadData& layer ) {
            return layer.Name( )
                   == clientmap::rendering::kRoadNameLayerName;
        } );

    if ( road_name_layer != tile.end( ) )
    {
        const auto data = road_name_layer->Data( );
        const auto size = road_name_layer->Size( );
        const auto configuration = road_name_layer->Configuration( );
        ...
    }
};

const auto error = client.LoadEncoded(
    catalog_handle,
    olp::clientmap::datastore::TileRequest( )
        .WithTileKey( tile_key )
        .WithLayerGroup( clientmap::layergroup::kRendering )
        .WithLayer( clientmap::rendering::kRoadNameLayerName ),
    std::move( callback ) );

In the example above, the following objects and parameters are used:

  • catalog_handle – the handle of the added catalog.
  • tile_key – the key of the tile for which the data is requested.
  • kRendering – the name of the layer group from which the data is requested.
  • kRoadNameLayerName – the short name of the layer from which the data is requested.
  • tile – std::vector of the LayerPayloadData instances that contain the encoded map data.
  • road_name_layer – the LayerPayloadData instance that contains the encoded map data of the specified layer.

Note: If you need to keep any layer data outside the callback scope, copy the data at which the LayerPayloadData instance points. The pointers are not guaranteed to be valid outside the callback scope.

Get encoded data from all catalogs

You can get encoded map data for a specific tile from all successfully added catalogs.

Example:

const auto tile_key
    = olp::geo::TileKey::FromRowColumnLevel( 6486, 8801, 14 );

auto callback = [&]( const olp::clientmap::datastore::EncodedClientMapTiles&
                         tiles ) {
    // Use the CatalogHandle as an index to find the appropriate tile
    const auto& tile = tiles[catalog_handle];

    const auto road_name_layer = std::find_if(
        tile.begin( ), tile.end( ),
        [&]( const olp::clientmap::datastore::LayerPayloadData& layer ) {
            return layer.Name( )
                   == clientmap::rendering::kRoadNameLayerName;
        } );

    if ( road_name_layer != tile.end( ) )
    {
        const auto data = road_name_layer->Data( );
        const auto size = road_name_layer->Size( );
        const auto configuration = road_name_layer->Configuration( );
    }
};

const auto error = client.LoadEncoded(
    olp::clientmap::datastore::TileRequest( )
        .WithTileKey( tile_key )
        .WithLayerGroup( clientmap::layergroup::kRendering )
        .WithLayer( clientmap::rendering::kRoadNameLayerName ),
    std::move( callback ) );

In the example above, the following objects and parameters are used:

  • tile_key – the key of the tile for which the data is requested.
  • kRendering – the name of the layer group from which the data is requested.
  • kRoadNameLayerName – the short name of the layer from which the data is requested.
  • catalog_tiles – std::vector of the EncodedClientMapTiles instances that contain the encoded map data from all successfully added catalogs.
  • catalog_handle – the handle of the added catalog.
  • tile – std::vector of the LayerPayloadData instances that contain the encoded map data.
  • road_name_layer – the LayerPayloadData instance that contains the encoded map data of the specified layer.

Note: If you need to keep any layer data outside the callback scope, copy the data at which the LayerPayloadData instance points. The pointers are not guaranteed to be valid outside the callback scope.

Access encoded map data from a layer

To access the encoded map data from a specific layer, use the methods of the LayerPayloadData instance.

Example:

const auto data = layer.Data( );
const auto size = layer.Size( );

In the example above, the following objects are used:

  • layer – the LayerPayloadData instance.
  • data – the pointer to the beginning of the specified tile layer data.
  • size – the size (in bytes) of the map data.

It is guaranteed that data is valid inside the callback.

Access layer configurations

To access layer configurations:

  1. Use the Configuration method of the LayerPayloadData instance.

    Example:

     const auto configuration = layer.Configuration( );

    In the example above, layer is the LayerPayloadData instance.

  2. Check if the layer is present.

    Example:

     if (!configuration)
 {
     LOG_ERROR( "The layer is not present." );
 }

  3. If the layer is present, use the corresponding LayerConfiguration instance.

    Example:

     const auto world_crdinate_bits = configuration->world_coordinate_bits( );

Prefetch encoded tile data

To speed up loading tile data, use the Prefetch method of the DataStoreClient class. The Prefetch method asynchronously downloads bundles that contain the requested tiles and puts them into the cache of HERE Data SDK for C++.

Note: Prefetch does not guarantee that all tiles are always available offline because the cache may overflow and the data may be evicted at any point.

Example:

const auto tile_keys = olp::clientmap::datastore::TileKeys{
    olp::geo::TileKey::FromRowColumnLevel( 6486, 8800, 14 ),
    olp::geo::TileKey::FromRowColumnLevel( 6486, 8801, 14 )};

const auto cancellation_token = client.Prefetch(
    catalog_handle,
    olp::clientmap::datastore::PrefetchRequest( )
        .WithTileKeys( tile_keys )
        .WithLayerGroup( clientmap::layergroup::kRendering ),
    std::move( callback ) );

In the example above, the following objects and parameters are used:

  • catalog_handle – the handle of the added catalog.
  • tile_keys – the keys of the tiles for which the data is requested.
  • kRendering – the name of the layer group from which the data is requested.
  • cancellation_token – the return value of the Prefetch call that can be used to cancel the prefetch request.
  • callback – the callback that passes the prefetch result to the user.

To check if the data is loaded successfully, check the error code in the callback.

Example:

auto callback = []( const olp::clientmap::datastore::PrefetchResponse&
                        prefetch_response ) {
    if ( !prefetch_response.IsSuccessful( ) )
    {
        const auto& error = prefetch_response.GetError( );
        LOG_ERROR( "Failed to prefetch the tiles" );
        return;
    }

    const auto& prefetch_result = prefetch_response.GetResult( );
    const auto& loaded_tile_keys = prefetch_result.GetTileKeys( );
    const auto& layer_group = prefetch_result.GetLayerGroup( );
    ...
};

In the example above, the following objects are used:

  • loaded_tile_keys – the keys of the tiles for which the data is loaded successfully.
  • layer_group – the name of the layer group from which the data is loaded.

Prefetch a bounding box

To prefetch the bundle data for all tiles of a given level that cover a certain bounding box, use the FromGeoRectangle method of the PrefetchRequest class.

Example:

const auto geo_rectangle = olp::geo::GeoRectangle(
    olp::geo::GeoCoordinates::FromDegrees( 52.513470, 13.368160 ),
    olp::geo::GeoCoordinates::FromDegrees( 52.519117, 13.384339 ) );

const auto level = 14u;

const auto prefetch_request
    = olp::clientmap::datastore::PrefetchRequest::FromGeoRectangle(
        clientmap::layergroup::kRendering, geo_rectangle, level );

In the example above, the following objects and parameters are used:

  • geo_rectangle – the geographical rectangle that has to be covered by tiles.
  • level – the level of the tiles to cover the rectangle with.
  • kRendering – the name of the layer group from which the data is requested.

Set up linked layer groups

When a tile is requested, to start prefetching the encoded map data for the same tile from other layer groups in the background, use the AddPrefetchGroup method of the DataStoreServer class.

To get the catalog handle that you need to pass to the AddPrefetchGroup method, use the GetCatalogHandle method of the DataStoreServer class. Do not pass the catalog handle that is returned by the AddCatalog method of the DataStoreClient class to the AddPrefetchGroup method.

Example:

auto linked_layer_groups
    = {olp::clientmap::datastore::LinkedLayerGroup(
            clientmap::layergroup::kNavigation ),
        olp::clientmap::datastore::LinkedLayerGroup(
            clientmap::layergroup::kSearch )};

const auto error = server->AddPrefetchGroup(
    catalog_handle,
    olp::clientmap::datastore::LinkedLayerGroupsRequest( )
        .WithMasterLayerGroup( clientmap::layergroup::kRendering )
        .WithLinkedLayerGroups( linked_layer_groups ) );

In the example above, the following objects and parameters are used:

  • server – a shared pointer to the previously created DataStoreServer instance.
  • catalog_handle – the handle of the catalog from which you want to prefetch the data.
  • kRendering – the name of the master layer group.
  • kNavigation and kSearch – the names of the linked layer groups from which you want to prefetch the encoded tile data when a tile from the master layer group is requested.

Set up linked tile keys

For a given tile key, when the tile is requested, you can set up other tile keys for which you want to prefetch the encoded map data from other layer groups in the background.

To get the catalog handle that you need to pass to the AddPrefetchGroup method, use the GetCatalogHandle method of the DataStoreServer class. Do not pass the catalog handle that is returned by the AddCatalog method of the DataStoreClient class to the AddPrefetchGroup method.

Example:

auto linked_layer_groups
    = {olp::clientmap::datastore::LinkedLayerGroup(
            clientmap::layergroup::kNavigation,
            [=]( const olp::geo::TileKey& tile_key ) {
                return olp::clientmap::datastore::TileKeys{
                    linked_tile_key_1, linked_tile_key_2};
            } ),
        olp::clientmap::datastore::LinkedLayerGroup(
            clientmap::layergroup::kNavigation,
            [=]( const olp::geo::TileKey& kSearch ) {
                return olp::clientmap::datastore::TileKeys{
                    linked_tile_key_1, linked_tile_key_2};
            } )};

const auto error = server->AddPrefetchGroup(
    catalog_handle,
    olp::clientmap::datastore::LinkedLayerGroupsRequest( )
        .WithMasterLayerGroup( clientmap::layergroup::kRendering )
        .WithLinkedLayerGroups( linked_layer_groups ) );

In the example above, the following objects and parameters are used:

  • server – a shared pointer to the previously created DataStoreServer instance.
  • catalog_handle – the handle of the catalog from which you want to prefetch the data.
  • kRendering – the name of the master layer group.
  • kNavigation and kSearch – the names of the linked layer groups from which you want to prefetch the encoded tile data when a tile from the master layer group is requested.
  • tile_key – the key of the tile to which you want to link other tile keys.
  • linked_tile_key_1 and linked_tile_key_2 – the keys of the tiles for which you want to prefetch the encoded tile data from the linked layer groups when tile_key is requested from the master layer group.

Remove linked layer groups and tile keys

To remove previously linked layer groups and tile keys, use the RemovePrefetchGroup method of the DataStoreServer class.

To get the catalog handle that you need to pass to the AddPrefetchGroup method, use the GetCatalogHandle method of the DataStoreServer class. Do not pass the catalog handle that is returned by the AddCatalog method of the DataStoreClient class to the RemovePrefetchGroup method.

Example:

const auto error = server->RemovePrefetchGroup(
    catalog_handle, clientmap::layergroup::kRendering );

In the example above, the following objects and parameters are used:

  • server – a shared pointer to the previously created DataStoreServer instance.
  • catalog_handle – the handle of the catalog from which you want to remove the linked layer groups and tile keys.
  • kRendering – the name of the layer group from which you want to remove the linked layer groups and tile keys.

results matching ""

    No results matching ""