Tango Service: Area Description Interface

Functions for handling Area Descriptions for localization.

Summary

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:

Functions

TangoAreaDescriptionMetadata_free(TangoAreaDescriptionMetadata metadata)
Frees the memory allocated by a call to TangoService_getAreaDescriptionMetadata().
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.
TangoAreaDescriptionMetadata_listKeys(TangoAreaDescriptionMetadata metadata, char **key_list)
Returns a comma separated list of all keys in the metadata.
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.
TangoService_deleteAreaDescription(const TangoUUID uuid)
Deletes an area description with the specified unique ID.
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.
TangoService_getAreaDescriptionMetadata(const TangoUUID uuid, TangoAreaDescriptionMetadata *metadata)
Gets the metadata handle associated with a single area description unique ID.
TangoService_getAreaDescriptionUUIDList(char **uuid_list)
Gets the full list of unique area description IDs available on a device as a comma-separated list of TangoUUIDs.
TangoService_importAreaDescription(const char *src_file_path, TangoUUID *uuid)
Import an area description from the source file path to the default area storage location.
TangoService_saveAreaDescription(TangoUUID *uuid)
Optimizes and saves the area description, returning the unique ID associated with the saved ADF.
TangoService_saveAreaDescriptionMetadata(const TangoUUID uuid, TangoAreaDescriptionMetadata metadata)
Saves the metadata associated with a single area description unique ID.

Functions

TangoAreaDescriptionMetadata_free

TangoErrorType TangoAreaDescriptionMetadata_free(
  TangoAreaDescriptionMetadata metadata
)

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

Details
Parameters
metadata
The handle to the metadata to be deallocated.
Returns
TANGO_SUCCESS if the metadata was deleted.

TangoAreaDescriptionMetadata_get

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:

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).

Details
Parameters
metadata
The metadata list to search through.
key
The string key value of the parameter to set.
value_size
The size in bytes of value, as allocated by the caller. value will be written only up to this size in bytes.
value
The 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.

TangoAreaDescriptionMetadata_listKeys

TangoErrorType TangoAreaDescriptionMetadata_listKeys(
  TangoAreaDescriptionMetadata metadata,
  char **key_list
)

Returns a comma separated list of all keys in the metadata.

Memory should not be deallocated outside the API.

Details
Parameters
metadata
The metadata from which to read the keys.
key_list
Place 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.

TangoAreaDescriptionMetadata_set

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().

Details
Parameters
metadata
The metadata for which to set the key-value pair.
key
The string key value of the parameter to set.
value_size
The size in bytes of value, as allocated by the caller. value will be written only up to this size in bytes.
value
The 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.

TangoService_deleteAreaDescription

TangoErrorType TangoService_deleteAreaDescription(
  const TangoUUID uuid
)

Deletes an area description with the specified unique ID.

This method should not be called to delete the ADF that is currently loaded.

Details
Parameters
uuid
The 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.

TangoService_exportAreaDescription

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.

Details
Parameters
uuid
the UUID of the area.
dst_file_dir
The 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.

TangoService_getAreaDescriptionMetadata

TangoErrorType TangoService_getAreaDescriptionMetadata(
  const TangoUUID uuid,
  TangoAreaDescriptionMetadata *metadata
)

Gets the metadata handle associated with a single area description unique ID.

Allocates memory which should be freed by calling TangoAreaDescriptionMetadata_free().

Details
Parameters
uuid
The TangoUUID for which to load the metadata.
metadata
The 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.

TangoService_getAreaDescriptionUUIDList

TangoErrorType TangoService_getAreaDescriptionUUIDList(
  char **uuid_list
)

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.

Details
Parameters
uuid_list
Upon 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.

TangoService_importAreaDescription

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.

Details
Parameters
src_file_path
The source file path of the area to be imported.
uuid
Populated 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.

TangoService_saveAreaDescription

TangoErrorType TangoService_saveAreaDescription(
  TangoUUID *uuid
)

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.

Details
Parameters
uuid
Upon 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).

TangoService_saveAreaDescriptionMetadata

TangoErrorType TangoService_saveAreaDescriptionMetadata(
  const TangoUUID uuid,
  TangoAreaDescriptionMetadata metadata
)

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

Details
Parameters
uuid
The TangoUUID associated with the metadata.
metadata
The 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.

Send feedback about...

Tango C API
Tango C API