Decoded tile data
After you create the DataStoreClient
instance and add the OCM catalog, you can request decoded map data for a specific tile. The data is synchronously passed to you via a callback.
Note: Downloading and decoding of the tile data happens synchronously. It is strongly recommended not to do any time-consuming operations inside the callback. As the data may change or expire at any time, it is not recommended to store references to the ClientMapTile
or ClientMapTiles
instances outside the callback.
In this section, learn how to:
Get decoded tile data from one catalog
You can get decoded map data for a specific tile from a catalog defined by CatalogHandle
.
Example:
const auto tile_key = olp::geo::TileKey::FromRowColumnLevel( 6486, 8801, 14 );
clientmap::decoder::LayerPtr< const clientmap::decoder::RoadNameLayer >
road_name_layer;
clientmap::decoder::LayerConfigurationPtr road_name_layer_configuration;
auto callback =
[&]( const olp::clientmap::datastore::ClientMapTile& tile ) {
road_name_layer = tile.road_name_layer;
road_name_layer_configuration = tile.road_name_layer_configuration;
};
const auto error = client.Load(
catalog_handle,
olp::clientmap::datastore::TileRequest( )
.WithTileKey( tile_key )
.WithLayerGroup( clientmap::layergroup::kRendering ),
std::move( callback ) );
In the example above, the following objects and parameters are used:
-
client
– the previously created DataStoreClient
instance. -
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. -
tile
– the ClientMapTile
instance that contains the decoded tile data from the specified catalog. -
road_name_layer
– the layer data that is requested. -
road_name_layer_configuration
– the configuration of the layer that is requested.
Check if the Load
operation is successful.
Example:
if ( error != olp::clientmap::datastore::Error::kNone )
{
LOG_ERROR( "Failed to load decoded data" );
}
If the Load
operation is unsuccessful, check if the error is retryable. Retryable errors are temporary and are likely to disappear if the Load
operation is repeated.
Example:
if ( olp::clientmap::datastore::IsRetryable( error ) )
{
LOG_INFO( "The Load operation can be repeated" );
}
Get decoded tile data from all catalogs
You can get decoded map data for a specific tile from all successfully added catalogs.
Example:
const auto tile_key = olp::geo::TileKey::FromRowColumnLevel( 6486, 8801, 14 );
clientmap::decoder::LayerPtr< const clientmap::decoder::RoadNameLayer >
road_name_layer;
clientmap::decoder::LayerConfigurationPtr road_name_layer_configuration;
auto callback =
[&]( const olp::clientmap::datastore::ClientMapTiles& catalog_tiles ) {
const auto& tile = catalog_tiles[ catalog_handle ];
road_name_layer = tile.road_name_layer;
road_name_layer_configuration = tile.road_name_layer_configuration;
};
const auto error
= client.Load( olp::clientmap::datastore::TileRequest( )
.WithTileKey( tile_key )
.WithLayerGroup( clientmap::layergroup::kRendering ),
std::move( callback ) );
In the example above, the following objects and parameters are used:
-
client
– the previously created DataStoreClient
instance. -
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. -
catalog_tiles
– std::vector
of the ClientMapTile
structures that contain the decoded tile data from all successfully added catalogs. -
catalog_handle
– the handle of the added catalog. -
tile
– the ClientMapTile
instance that contains the decoded tile data from the specified catalog. -
road_name_layer
– the layer data that is requested. -
road_name_layer_configuration
– the configuration of the layer that is requested.
Specify the layers to decode
To specify the layers that you want to decode, use the WithLayers
or WithLayer
method of the TileRequest
class.
Note: It is always recommended to specify the layers that you want to decode.
Example:
const olp::clientmap::datastore::TileRequest::Layers layers{
clientmap::rendering::kRoadGeometryLayerName,
clientmap::rendering::kRoadNameLayerName};
const auto error = client.Load(
olp::clientmap::datastore::TileRequest( )
.WithTileKey( tile_key )
.WithLayerGroup( clientmap::layergroup::kRendering )
.WithLayers( layers ),
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. -
kRoadGeometryLayerName
and kRoadNameLayerName
– the names of the layers that you want to decode. -
callback
– the callback that passes the tile data to the user.
Download and decode data asynchronously
To download and decode tile data asynchronously and get it from the memory tile cache when the data is ready, use the TryLoad
method of the DataStoreClient
class.
Example:
const auto error
= client.TryLoad( olp::clientmap::datastore::TileRequest( )
.WithTileKey( tile_key )
.WithLayerGroup( clientmap::layergroup::kRendering )
.WithLayers( layers ),
std::move( callback ) );
if ( error == olp::clientmap::datastore::Error::kNotReady )
{
LOG_INFO( "The data is being downloaded and decoded in the background" );
}
else if ( error == olp::clientmap::datastore::Error::kNone )
{
LOG_INFO(
"The decoded data is retrieved from the memory tile cache and passed "
"to the user via the callback" );
}
else
{
LOG_ERROR( "Failed to get the decoded tile data" );
}
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. -
layers
– the names of the layers that you want to decode. -
callback
– the callback that passes the tile data to the user.
Access decoded layer data
To access decoded layer data:
-
Copy the fields of the corresponding ClientMapTile
structure.
Example:
clientmap::decoder::LayerPtr< const clientmap::decoder::RoadNameLayer >
road_name_layer;
auto callback =
[&]( const olp::clientmap::datastore::ClientMapTiles& catalog_tiles ) {
const auto& tile = catalog_tiles[ catalog_handle ];
road_name_layer = tile.road_name_layer;
...
};
In the example above, catalog_handle
is the handle of the added catalog.
-
Check if the layer data is present and decoded successfully.
Example:
if ( !road_name_layer )
{
LOG_ERROR( "RoadNameLayer is not present for the requested tile" );
}
-
If the layer data is present and decoded successfully, to access the data, use the corresponding LayerPtr
instance.
Example:
const auto roads_size = road_name_layer->roads_size( );
Access layer configurations
To access layer configurations:
-
Copy the fields of the corresponding ClientMapTile
structure.
Example:
clientmap::decoder::LayerConfigurationPtr road_name_layer_configuration;
auto callback =
[&]( const olp::clientmap::datastore::ClientMapTiles& catalog_tiles ) {
const auto& tile = catalog_tiles[ catalog_handle ];
road_name_layer_configuration = tile.road_name_layer_configuration;
...
};
In the example above, catalog_handle
is the handle of the added catalog.
-
Check if the layer is present in the catalog.
Example:
if ( !road_name_layer_configuration )
{
LOG_ERROR( "RoadNameLayer is not present in the catalog" );
}
-
If the layer is present, to access the layer configuration, use the corresponding LayerConfigurationPtr
instance.
Example:
const auto world_coordinate_bits
= road_name_layer_configuration->world_coordinate_bits( );
Cache decoded map data
Decoded map data is cached internally by every DataStoreClient
instance. For every tile, the DataStoreClient
instance stores the decoded map data from every requested layer group. The data is evicted from the cache using the least recently used (LRU) principle.
To set the maximum number of ClientMapTiles
instances that can be stored in the memory cache of the DataStoreClient
instance, use the cache_size
field of the DataStoreClientSettings
structure.
If cache_size
is not set explicitly, 32 ClientMapTiles
instances are stored in the cache by default.
Note: You cannot change the size of the cache once a DataStoreClient
instance is created.
Example:
olp::clientmap::datastore::DataStoreClientSettings client_settings;
client_settings.cache_size = 64u;
...
olp::clientmap::datastore::DataStoreClient client( client_settings );