Functions
Tango Service: Area Description Interface

Functions for handling Area Descriptions for localization. Note that there is no direct function for loading an area description. To load an Area Description, use the TangoConfig_setString() function to set the configuration item config_load_area_description_UUID to the UUID of the Area Description you want to load, and the Tango Service loads that area when you call TangoService_connect(). More...

Functions

TangoErrorType TangoAreaDescriptionMetadata_free (TangoAreaDescriptionMetadata metadata)
TangoErrorType TangoAreaDescriptionMetadata_get (TangoAreaDescriptionMetadata metadata, const char *key, size_t *value_size, char **value)
TangoErrorType TangoAreaDescriptionMetadata_listKeys (TangoAreaDescriptionMetadata metadata, char **key_list)
TangoErrorType TangoAreaDescriptionMetadata_set (TangoAreaDescriptionMetadata metadata, const char *key, size_t value_size, const char *value)
TangoErrorType TangoService_deleteAreaDescription (const TangoUUID uuid)
TangoErrorType TangoService_exportAreaDescription (const TangoUUID uuid, const char *dst_file_dir)
TangoErrorType TangoService_getAreaDescriptionMetadata (const TangoUUID uuid, TangoAreaDescriptionMetadata *metadata)
TangoErrorType TangoService_getAreaDescriptionUUIDList (char **uuid_list)
TangoErrorType TangoService_importAreaDescription (const char *src_file_path, TangoUUID *uuid)
TangoErrorType TangoService_saveAreaDescription (TangoUUID *uuid)
TangoErrorType TangoService_saveAreaDescriptionMetadata (const TangoUUID uuid, TangoAreaDescriptionMetadata metadata)

Detailed Description

Functions for handling Area Descriptions for localization. Note that there is no direct function for loading an area description. To load an Area Description, use the TangoConfig_setString() function to set the configuration item config_load_area_description_UUID to the UUID of the Area Description you want to load, and the Tango Service loads that area when you call TangoService_connect().

See the following pages for more info:


Function Documentation

Frees the memory allocated by a call to TangoService_getAreaDescriptionMetadata().

Parameters:
metadataThe handle to the metadata to be deallocated.
Returns:
TANGO_SUCCESS if the metadata was deleted.
TangoErrorType TangoAreaDescriptionMetadata_get ( TangoAreaDescriptionMetadata  metadata,
const char *  key,
size_t *  value_size,
char **  value 
)

Searches through the metadata list for a key that matches the parameter key. If such a key is found, returns the value_size and value associated with that key. If the key has not been initialized in the map the value_size will be 0 and the value will be NULL.

The supported keys are:

  • name : The name of the ADF in a null-terminated char array. Default value for a new map is "unnamed". The value can be set by calling TangoAreaDescriptionMetadata_set().
  • transformation : The transformation of the ADF's global coordinate system.

For the transformation key, the transformation data consists of 7 double precision elements:

  • x, y, z : ECEF (earth centered earth fixed) Cartesian frame of reference at the center of the earth which rotates with the earth).
  • qx, qy, qz, qw : Hamilton Quaternion.

The default corresponding values are: (x, y, z, qx, qy, qz, qw) = (0, 0, 0, 0, 0, 0, 1).

Parameters:
metadataThe metadata list to search through.
keyThe string key value of the parameter to set.
value_sizeThe size in bytes of value, as allocated by the caller. value will be written only up to this size in bytes.
valueThe value of the data with the corresponding key stored in the metadata. The value will be returned as a binary data blob (The endianness of the binary block is platform dependent). The array memory should not be allocated by the caller, and will go out of scope after a call to TangoAreaDescriptionMetadata_free(). The value will be NULL if the key does not exist or has not been set yet.
Returns:
TANGO_SUCCESS if the key is found. If the key is valid but does not have a valid value, size will be set to 0 and value will contain NULL. Returns TANGO_INVALID if any of the arguments are NULL or the key is not found.

Returns a comma separated list of all keys in the metadata. Memory should not be deallocated outside the API.

Parameters:
metadataThe metadata from which to read the keys.
key_listPlace to store the comma separated list
Returns:
TANGO_SUCCESS on success, or TANGO_INVALID if the metadata was not valid or key_list is NULL.
TangoErrorType TangoAreaDescriptionMetadata_set ( TangoAreaDescriptionMetadata  metadata,
const char *  key,
size_t  value_size,
const char *  value 
)

Sets the value associated with an area description key to a new value.

For a list of supported keys, see TangoAreaDescriptionMetadata_get().

Parameters:
metadataThe metadata for which to set the key-value pair.
keyThe string key value of the parameter to set.
value_sizeThe size in bytes of value, as allocated by the caller. value will be written only up to this size in bytes.
valueThe value to which to set the key.
Returns:
TANGO_SUCCESS if the key is set, or TANGO_INVALID if the key is not found in the metadata or any of the arguments is NULL.

Deletes an area description with the specified unique ID. This method should not be called to delete the ADF that is currently loaded.

Parameters:
uuidThe area description to delete.
Returns:
TANGO_SUCCESS if area description file with specified unique ID is found and can be removed; otherwise TANGO_ERROR on failure to delete or if the service needs to be initialized.
TangoErrorType TangoService_exportAreaDescription ( const TangoUUID  uuid,
const char *  dst_file_dir 
)

Export an area with the UUID from the default area storage location to the destination file directory with the UUID as its name.

Parameters:
uuidthe UUID of the area.
dst_file_dirThe destination file directory.
Returns:
TANGO_SUCCESS if the file was exported, TANGO_ERROR if the export failed, or TANGO_INVALID if dst_file_dir was NULL.

Gets the metadata handle associated with a single area description unique ID. Allocates memory which should be freed by calling TangoAreaDescriptionMetadata_free().

Parameters:
uuidThe TangoUUID for which to load the metadata.
metadataThe metadata handle associated with the uuid.
Returns:
TANGO_SUCCESS on successful load of metadata, TANGO_ERROR if the service needs to be initialized or if the metadata could not be loaded, or TANGO_INVALID if metadata was NULL.

Gets the full list of unique area description IDs available on a device as a comma-separated list of TangoUUIDs. Memory should not be deallocated outside the API.

Parameters:
uuid_listUpon successful return, uuid_list will contain a comma separated list of available UUIDs.
Returns:
TANGO_SUCCESS on success, TANGO_ERROR on failure to retrieve the list or if the service needs to be initialized, or TANGO_INVALID if the uuid_list argument was NULL.
TangoErrorType TangoService_importAreaDescription ( const char *  src_file_path,
TangoUUID uuid 
)

Import an area description from the source file path to the default area storage location.

Parameters:
src_file_pathThe source file path of the area to be imported.
uuidPopulated with the UUID of the new file. This will be the same as the source file's UUID.
Returns:
TANGO_SUCCESS on successful import, TANGO_ERROR if the file could not be imported, or TANGO_INVALID if uuid or src_file_path was NULL.

Optimizes and saves the area description, returning the unique ID associated with the saved ADF.

You can only save an area description while connected to the Tango Service (after calling TangoService_connect() but before calling TangoService_disconnect()), and if you have enabled Area Learning mode by setting config_enable_learning_mode to true in the TangoConfig when connecting.

If you enabled Area Learning mode and you also loaded an ADF when connecting (specified using config_load_area_description_UUID ) then calling this method appends any new learned areas to the loaded areas and returns a new UUID for the new ADF (the original ADF is not modified).

This method may be long-running (do not call it on the UI thread). Since the Tango Service locks internally, other API calls (such as TangoService_getPoseAtTime()) will block while this method is running. Feedback about the progress of this operation is provided via a TangoEvent of type TANGO_EVENT_AREA_LEARNING with key "AreaDescriptionSaveProgress".

Calling this method will permanently stop motion tracking and area learning. After this method completes you may use TangoService_getPoseAtTime() repeatedly to query for the optimized pose estimate for any pose from the past using its timestamp. To re-start motion tracking or localize on the learned area description you must call TangoService_disconnect() and then connect again as normal.

Parameters:
uuidUpon saving, the TangoUUID to refer to this ADF is returned in uuid .
Returns:
TANGO_SUCCESS on success, TANGO_ERROR if a failure occurred when saving or if the service needs to be initialized, or TANGO_INVALID if uuid is NULL, or of incorrect length, or if Area Learning Mode was not set (see logcat for details).

Saves the metadata associated with a single area description unique ID.

Parameters:
uuidThe TangoUUID associated with the metadata.
metadataThe metadata to be saved.
Returns:
TANGO_SUCCESS on successful save, TANGO_ERROR on failure or if the service needs to be initialized, or TANGO_INVALID if metadata was NULL.


tango_client_api
Author(s):
autogenerated on Thu Jun 6 2019 19:49:50