Example of how to load tile data
In this section, you can learn how to work with the OCM load tile example.
Add a catalog
To start working with the load tile example, you need to add a catalog or catalogs from which you want to request decoded or encoded tile data. You need to add a catalog to the DataStoreServer
instance first, and then add it to the DataStoreClient
instance.
To add a catalog:
-
To access data from the HERE platform, create a Network
instance.
#include <olp/core/client/OlpClientSettingsFactory.h>
...
auto network = olp::client::OlpClientSettingsFactory::
CreateDefaultNetworkRequestHandler( );
-
To handle requests asynchronously, create a TaskScheduler
instance and specify the number of threads that the SDK should use.
Note: If you do not define the TaskScheduler
explicitly or set the number of threads to 1, HERE Data SDK for C++ will handle all requests synchronously.
#include <olp/core/client/OlpClientSettingsFactory.h>
...
const std::shared_ptr< olp::thread::TaskScheduler > task_scheduler
= olp::client::OlpClientSettingsFactory::CreateDefaultTaskScheduler( 4u );
-
To access the OCM data from the HERE platform, create a DataStoreServer
instance using the Network
and TaskScheduler
instances.
#include <olp/clientmap/datastore/DataStoreServer.h>
...
olp::clientmap::datastore::DataStoreServerSettings server_settings;
server_settings.network_request_handler = network;
server_settings.task_scheduler = task_scheduler;
auto server = std::make_shared< olp::clientmap::datastore::DataStoreServer >(
server_settings );
-
Initialize the DataStoreServer
instance and cache.
server->Init();
If the operation is successful, you get the kNone
error.
-
Create a DataStoreClient
instance using a shared pointer to the DataStoreServer
instance.
Note: Multiple DataStoreClient
instances can use the same DataStoreServer
instance.
#include <olp/clientmap/datastore/DataStoreClient.h>
...
olp::clientmap::datastore::DataStoreClientSettings client_settings;
olp::clientmap::datastore::DataStoreClient client( server, client_settings );
-
To access data from the OCM catalog, create an AuthenticationCredentials
instance using the here.access.key.іd
and here.access.key.secret
values from your platform credentials.
For instructions on how to get platform credentials, see the Get credentials section in the Getting Started Guide.
>**Note:** You can also load credentials from a file. For instruction,
>see Read authentication credentials from a file in the
>[Add catalog to DataStoreServer and DataStoreClient instances](developer_guide/add_catalog.md).
```cpp
#include <olp/authentication/AuthenticationCredentials.h>
...
olp::authentication::AuthenticationCredentials credentials(
"your-here-access-key-id", "your-here-access-key-secret" );
```
-
Сreate an AuthenticationSettings
instance using the AuthenticationCredentials
, Network
, and TaskScheduler
instances.
#include <olp/authentication/TokenProvider.h>
#include <olp/clientmap/datastore/Settings.h>
...
olp::authentication::Settings settings( credentials );
settings.network_request_handler = network;
settings.task_scheduler = task_scheduler;
olp::client::AuthenticationSettings authentication_settings;
authentication_settings.provider
= olp::authentication::TokenProviderDefault( std::move( settings ) );
-
Create a CatalogSettings
instance using the AuthenticationSettings
instance.
#include <olp/clientmap/datastore/Settings.h>
...
olp::clientmap::datastore::CatalogSettings catalog_settings;
catalog_settings.authentication_settings = authentication_settings;
-
Configure DataStoreClient
to get data from a specific version of the OCM catalog.
If you do not set the version explicitly or set it to boost::none
, the catalog version is set internally to the latest version that is available on the HERE platform when the catalog is added.
Note: You cannot add two versions of the same catalog to the same DataStoreClient
instance. To get data from different versions of the same catalog, create a DataStoreClient
instance for each catalog version and add different versions of the catalog to different DataStoreClient
instances.
catalog_settings.version = "version_number";
-
Add a catalog to the DataStoreServer
instance using the HERE Resource Name (HRN) of the catalog and the CatalogSettings
instance.
const auto add_catalog_server =
server->AddCatalog( kCatalogHrn, catalog_settings );
-
Check if the AddCatalog
operation is successful.
if ( !add_catalog_server.IsSuccessful( ) )
{
OLP_SDK_LOG_WARNING_F( kLogTag, "Failed to add a catalog to server - error=%s",
ToString( add_catalog_server.GetError( ) ).c_str( ) );
return EXIT_SUCCESS;
}
The operation can be unsuccessful if one of the following is true:
- The catalog with the requested HRN does not exist.
-
DataStoreClient
fails to check if the catalog with the requested HRN exists. Catalog existence is checked only if the catalog version is not set or set to boost::none
.
-
Add the same catalog to the DataStoreClient
instance using the HRN of the catalog and the CatalogSettings
instance.
const auto add_catalog_result =
client.AddCatalog( kCatalogHrn, catalog_settings );
-
Check if the AddCatalog
operation is successful.
if ( !add_catalog_client.IsSuccessful( ) )
{
OLP_SDK_LOG_WARNING_F( kLogTag, "Failed to add a catalog to client - error=%s",
ToString( add_catalog_client.GetError( ) ).c_str( ) );
return EXIT_SUCCESS;
}
The operation can be unsuccessful if one of the following is true:
- The catalog with the requested HRN does not exist.
-
DataStoreClient
fails to check if the catalog with the requested HRN exists. Catalog existence is checked only if the catalog version is not set or set to boost::none
.
-
If the AddCatalog
operation is successful, to access data from the added catalog, save its CatalogHandle
.
const auto catalog_handle = add_catalog_result.GetResult( );
Now, you can use the handle of the added catalog to get encoded and decoded tile data.
Load decoded tile data
You can load decoded map data for all map layers from all catalogs that you added to the DataStoreClient
instance.
To load the decoded tile data:
-
Add catalogs from which you want to load decoded tile data to the DataStoreServer
and DataStoreClient
instances.
For instructions, see Add a catalog to the DataStoreServer and DataStoreClient instances.
-
To get decoded map data for a specific tile from all successfully added catalogs, use the Load
method of the DataStoreClient
class.
The Load
method downloads and decodes the tile data synchronously.
Note: 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 ClientMapTiles
instances outside the callback.
const auto row_number=128;
const auto column_number=1256;
const auto level = 14;
const auto tile_key
= olp::geo::TileKey::FromRowColumnLevel( row_number, column_number, level );
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 code snippet above, the following objects and parameters are used:
-
client
– the DataStoreClient
instance that you created when you added the 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. -
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.
You can use the data that you get in the callback or copy it for future purposes.
Load encoded tile data
You can get encoded tile data for all map layers from all catalogs that are added to the DataStoreClient
instances.
Note: Unbundling happens whenever you request encoded map data for a tile.
To load the encoded tile data:
-
Add catalogs from which you want to load decoded tile data to the DataStoreServer
and DataStoreClient
instances.
For instructions, see Add catalog to DataStoreServer and DataStoreClient instances.
-
To get encoded map data for a specific tile from all successfully added catalogs, use the LoadEncoded
method of the DataStoreClient
class.
The LoadEncoded
method synchronously loads map data for all map layers from all catalogs that are added to the DataStoreClient
instance.
Note: It is not recommended 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 EncodedClientMapTile
or LayerPayloadData
instances outside the callback.
const auto row_number=128;
const auto column_number=1256;
const auto level = 14;
const auto tile_key
= olp::geo::TileKey::FromRowColumnLevel( row_number, column_number, level );
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(
olp::clientmap::datastore::TileRequest( )
.WithTileKey( tile_key )
.WithLayerGroup( clientmap::layergroup::kRendering )
.WithLayer( clientmap::rendering::kRoadNameLayerName ),
std::move( callback ) );
In the code snippet 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 EncodedClientMapTile
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.
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.