Observation-Lib

Observation-Lib contains methods that allow you to save features or observations to cloud storage supported by HERE and also retrieve them from this storage after Live Sense SDK for Linux detects them. This can be leveraged for real time alerts between vehicles in the vicinity.

Note

Currently, observation library supports HERE Data Hub as the data storage platform.

Requirements and Assumptions

The following list describes assumptions and requirements for this function:

  • The customer owns and maintains the cloud storage.
  • This library is not available for self-serve customers. To contact us for more details, see Help.
  • To locate the detected features accurately on any given map, add geolocation to the feature details.

Usage - Data Hub

1. Initialization

Initialize an instance of LSODataHubClient that is used to call the methods of observation library.

ls::LSODataHubClient::make(const std::string &spaceId, const std::string &token);

Parameters:

  • spaceId: ID of Data Hub space where data is to be stored
  • token: Authorization token to authorize the interfacing. Token should have get, put and read access to Data Hub space

Example:

auto observationClient = ls::LSODataHubClient::make("YOUR_SPACE_ID", "YOUR_SPACE_TOKEN");

2. Put Observations

Pushes a list of observations to the Data Hub space.

ls::LSOClientResponse putObservations(LSOData obsData);

Parameters:

  • obsData: LSOData the collection of observations to be uploaded.

Return:

  • LSOClientResponse: response received from uploading the observations from Data Hub.

    If the upload request is successfully completed, the response will have a 2xx status and observationData will be populated with the uploaded observations. If the request is unsuccessful or an error occurs, the response will have a status of the HTTP status code or 0 and message will be populated with the error description.

Example:

// Custom object that can be used for storing additional observation  
std::map<std::string, std::string> customPayload;
customPayload["key1"] = "value1";

// Additional strings describing the observation, which may be used for searching.
std::vector<std::string> tags = {"Linuxtest"};

//Geo-location of the observation
ls::LocationCoordinates coordinates;
coordinates.latitude = 52.53098377;
coordinates.longitude = 13.384567;
coordinates.altitude = 0.0;
coordinates.bearing = 60.0;
coordinates.bearingAccuracy = 0.5;
coordinates.locationAccuracy = 20.0;

ls::SensorInfo sensorInfo;
sensorInfo.pitch = 0.5;
sensorInfo.yaw = 9.8;

// Creating an object of `LSOObservation`
// The detection label and model name can be passed in `value` and `type` field of the constructor.

std::string modelName = "Example Model";
LSOObservation obData = LSOObservation("SIGN_SPEEDLIMIT_MAX_135",
                                        "1232134", modelName,
                                        coordinates,
                                        0.6, ls::getCurrentTimestamp(),
                                        customPayload, tags, sensorInfo);


ls::LSOData dataToPush = LSOData({obData}, "YOUR_CUSTOMER_ID");

ls::LSOClientResponse putResponse = observationClient->putObservations(dataToPush);
if (putResponse.status == 200) {
    std::cout << "Upload request was successful. " << std::endl;
} else {
    std::cout << "Upload request failed with error with code : " << putResponse.status
              << " and message : " << putResponse.message.c_str() << std::endl;
}

4. Get Observations

Retrieve observations asynchronously within a specified area centered at given coordinates (latitude, longitude). To filter the observations for a specific date range, you need to specify the range in from and to parameters.

 ls::LSOClientResponse getObservations(double latitude, double longitude, int searchRadius, int64_t to = 0, int64_t from = 0);

Parameters:

  • latitude: Latitude (in degrees) of the search area's center point
  • longitude: Longitude (in degrees) of the search area's center point
  • searchRadius: Radius (in meters) of the search area. Capped at 2000 meters
  • to: End time (in milliseconds since unix epoch) for fetching observations based on their timestamp, optional
  • from: Start time (in milliseconds since unix epoch) for fetching observations based on their timestamp, optional

Return:

  • LSOClientResponse: response received from fetching the observations from Data Hub.

If the upload request is successfully completed, the response will have a 2xx status and observationData will be populated with the uploaded observations. If the request is unsuccessful or an error occurs, the response will have a status of the HTTP status code or 0 and message will be populated with the error description.

Example:

ls::LSOClientResponse getResponse = observationClient->getObservations(
      52.53098377, 13.384567, 1000, ls::getCurrentTimestamp(), 0);

if (getResponse.status == 200) {
    std::cout << "Get request was successful. " << std::endl;
} else {
    std::cout << "Get request failed with error with code : " << getResponse.status
              << " and message : " << getResponse.message.c_str() << std::endl;
}

Points to Remember

  • Live Sense SDK for Linux does not cache any data or feature that was have not successfully saved to the cloud due to any reason like network unavailability, server/cloud service unavailability, or invalid credentials.
  • Data Hub was previously named as 'XYZ'.
  • To add any extra detail to each feature, you can use the customPayload object.
  • Every public method throws runtime exception with message Unauthorized if the current license is not entitled to use the observation library.

Additional Resources

  • There is an example bundled within the download package where a very basic usage of this library is demonstrated. Feel free to experiment with the code of the example. It includes a readme that lists the steps required to run the example.

results matching ""

    No results matching ""