holoscan::PoseTree | Holoscan SDK Documentation

A temporal pose tree to store relative coordinate system transformations over time.

This implementation does not support multiple paths between the same coordinate systems at a given time. It does however allow to disconnect edge and create new connection using a different path. It also allows for multiple “roots”. In fact the transformation relationships form an acylic, bi-directional, not necessarily fully-connected graph. This PoseTree assigned a different version id to each operation that affects it, and this version can be used to make a query ignore later changes made to the tree.

#include <holoscan/pose_tree.hpp>

Methods

init

expected_t<void> holoscan::PoseTree::init(
    int32_t number_frames = 1024,
    int32_t number_edges = 16384,
    int32_t history_length = 1048576,
    int32_t default_number_edges = 16,
    int32_t default_history_length = 1024,
    int32_t edges_chunk_size = 4,
    int32_t history_chunk_size = 64
)

Allocate space for a given number of total frames and total number of edges.

Total amount of memory required is approximately: number_frames * 128 + number_edges * 64 + history_length * 72.

Returns: Success or error status.

Parameters

number_frames

int32_tDefaults to 1024

Maximum number of frames to support.

number_edges

int32_tDefaults to 16384

Maximum number of edges to support.

history_length

int32_tDefaults to 1048576

Maximum history length.

default_number_edges

int32_tDefaults to 16

Default number of edges per frame.

default_history_length

int32_tDefaults to 1024

Default history length per edge.

edges_chunk_size

int32_tDefaults to 4

Chunk size for edge allocation.

history_chunk_size

int32_tDefaults to 64

Chunk size for history allocation.

deinit

void holoscan::PoseTree::deinit()

Deinitialize the PoseTree and free all allocated resources.

set_multithreading_info

expected_t<void> holoscan::PoseTree::set_multithreading_info(
    frame_t start_frame_id,
    frame_t increment
)

Set information needed to avoid overlap in frame id creating across PoseTree.

Parameters

start_frame_id

frame_t

The first id to be assigned by this PoseTree (must be > 0(.

increment

frame_t

How much increment to leave between two frames id..

get_pose_tree_version

version_t holoscan::PoseTree::get_pose_tree_version() const

Get the current PoseTree version.

Returns: Current version of the PoseTree.

create_frame_with_id

expected_t<frame_t> holoscan::PoseTree::create_frame_with_id(
    frame_t frame_id,
    std::string_view name
)

Create a new frame in the PoseTree.

An optional name may be given to give a human-readable name to the frame. The name is a null-terminated string with at most 63 characters. User defined name cannot start with ”_”, which is reserved for auto generated names such as “_frame_i”, where i is the uid of the frame. A hint on the maximum number of edges this frame will be connected to can be provided.

Returns: Frame id on success, error on failure.

Parameters

frame_id

frame_t

Frame id to be assigned.

name

std::string_view

Human-readable name for the frame.

create_frame

Create a new frame in the `PoseTree`

Create a new frame in the `PoseTree` with a name

Overload 3

Overload 4

expected_t<frame_t> holoscan::PoseTree::create_frame(
    std::string_view name,
    int32_t number_edges
)

Create a new frame in the PoseTree.

Returns: Frame id on success, error on failure.

Parameters

name

std::string_view

Human-readable name for the frame.

number_edges

int32_t

Hint for maximum number of edges this frame will have.

find_frame

expected_t<frame_t> holoscan::PoseTree::find_frame(
    std::string_view name
) const

Find a frame with the given name.

Returns: Frame id on success, Error::kFrameNotFound if no such frame exists.

Parameters

name

std::string_view

Name of the frame to find.

find_or_create_frame

Find a frame with the given name

Find a frame with the given name (with number edges)

expected_t<frame_t> holoscan::PoseTree::find_or_create_frame(
    std::string_view name
)

Find a frame with the given name, or create it if it doesn’t exist.

Returns: Frame id on success, error on failure.

Parameters

name

std::string_view

Name of the frame to find or create.

create_edges

Create an edge between two frames

Overload 2

Overload 3

Overload 4

Overload 5

Overload 6

Overload 7

Overload 8

expected_t<version_t> holoscan::PoseTree::create_edges(
    frame_t lhs,
    frame_t rhs
)

Create an edge between two frames.

Returns: Version id of the change on success, error on failure.

Parameters

lhs

frame_t

Left hand side frame.

rhs

frame_t

Right hand side frame.

delete_frame

Overload 1

Overload 2

expected_t<version_t> holoscan::PoseTree::delete_frame(
    frame_t uid
)

Delete a frame in the PoseTree and all its relations to other frames.

This action permanently erases the history information and frees its memory. Upon success, it returns the version id of the change (however query made with a previous version will also consider the frame as deleted).

Returns: Version id of the change on success, error on failure.

Parameters

uid

frame_t

Frame id to delete.

delete_edge

Delete an edge and free the memory

Delete an edge by frame names and free the memory

expected_t<version_t> holoscan::PoseTree::delete_edge(
    frame_t lhs,
    frame_t rhs
)

Delete an edge and free the memory.

This action permanently erases the history. Upon success, it returns the version id of the change (however query made with a previous version will also consider the edge as deleted).

Returns: Version id of the change on success, error on failure.

Parameters

lhs

frame_t

Left hand side frame.

rhs

frame_t

Right hand side frame.

disconnect_frame

Overload 1

Overload 2

Deleted overload

expected_t<version_t> holoscan::PoseTree::disconnect_frame(
    frame_t uid,
    double time
)

Disconnect a frame from all the others starting at a given time.

Returns: Version id of the change on success, error on failure.

Parameters

uid

frame_t

Frame id to disconnect.

time

double

Time at which to start the disconnection.

disconnect_edge

Disconnect an edge starting at a given time

Overload 2

Deleted overload

expected_t<version_t> holoscan::PoseTree::disconnect_edge(
    frame_t lhs,
    frame_t rhs,
    double time
)

Disconnect an edge starting at a given time.

Returns: Version id of the change on success, error on failure.

Parameters

lhs

frame_t

Left hand side frame.

rhs

frame_t

Right hand side frame.

time

double

Time at which to start the disconnection.

get_frame_name

expected_t<std::string_view> holoscan::PoseTree::get_frame_name(
    frame_t uid
) const

Get the name of a frame.

Returns: Frame name on success, error on failure.

Parameters

uid

frame_t

Frame id.

get_init_parameters

expected_t<InitParameters> holoscan::PoseTree::get_init_parameters() constexpected_t<InitParameters> holoscan::PoseTree::get_init_parameters() const

Retrieve the parameters used to initialize this PoseTree.

Returns: Initialization parameters on success, or an error on failure.

get_latest

Const (1)

Const (2)

expected_t<std::pair<Pose3d, double>> holoscan::PoseTree::get_latest(
    frame_t lhs,
    frame_t rhs
) const

Get the latest pose between two frames as well as the time of that pose.

The two poses needs to be directly linked.

Returns: Pair of pose and time on success, error on failure.

Parameters

lhs

frame_t

Left hand side frame.

rhs

frame_t

Right hand side frame.

get

Const (with time and method and version) (1)

Const (with time and version) (1)

Const (with time and method) (1)

Const (with time) (1)

Const (with version) (1)

Const (1)

Const (with time and method and version) (2)

Const (with time and version) (2)

Const (with version) (2)

Const (with time and method) (2)

Const (with time) (2)

Const (2)

Deleted overloads

expected_t<Pose3d> holoscan::PoseTree::get(
    frame_t lhs,
    frame_t rhs,
    double time,
    PoseTreeEdgeHistory::AccessMethod method,
    version_t version
) const

Get the pose lhs_T_rhs between two frames in the PoseTree at the given time.

If the poses are not connected exactly at the given time, the indicated method is used to interpolate the data.

Returns: Pose on success, error on failure.

Parameters

lhs

frame_t

Left hand side frame.

rhs

frame_t

Right hand side frame.

time

double

Time at which to query the pose.

method

PoseTreeEdgeHistory::AccessMethod

Access method for interpolation.

version

version_t

Version of the PoseTree to query.

get_pose2_xy

template <class... Args>
expected_t<Pose2d> holoscan::PoseTree::get_pose2_xy(
    Args &&... args
) const

Helper function to get a Pose2d instead of Pose3d.

Returns: 2D pose on success, error on failure.

Template parameters

Args

class...

Argument types to forward to the get method.

Parameters

args

Args &&...

Arguments to forward to the get method.

set

Set the pose between two frames in the `PoseTree`

Overload 2

Overload 3

Overload 4

Deleted overloads

expected_t<version_t> holoscan::PoseTree::set(
    frame_t lhs,
    frame_t rhs,
    double time,
    const Pose3d &lhs_T_rhs
)

Set the pose between two frames in the PoseTree.

Note that poses can not be changed retrospectively. Thus for example once the pose at time t=2.0 is set it is no longer allowed to set the pose for time t <= 2.0. It is not allowed to form cycles. Frames are implicitly linked. If more than the maximum number of allowed poses are set the oldest pose is deleted.

Returns: Version id of the change on success, error on failure.

Parameters

lhs

frame_t

Left hand side frame.

rhs

frame_t

Right hand side frame.

time

double

Time at which to set the pose.

lhs_T_rhs

const Pose3d &

Pose transformation from lhs to rhs.

get_edge_uids

template <typename T>
expected_t<void> holoscan::PoseTree::get_edge_uids(
    T &container
) const

Get list of edge UIDs.

Returns: Success or error status.

Template parameters

typename

Container type that supports clear(), capacity(), size(), and push_back().

Parameters

container

T &

Container to fill with edge UIDs.

get_edge_names

template <typename T>
expected_t<void> holoscan::PoseTree::get_edge_names(
    T &container
) const

Get list of edge names.

Returns: Success or error status.

Template parameters

typename

Container type that supports clear(), capacity(), size(), and push_back().

Parameters

container

T &

Container to fill with edge names as pairs.

get_frame_uids

template <typename T>
expected_t<void> holoscan::PoseTree::get_frame_uids(
    T &container
) const

Get list of frame UIDs.

Returns: Success or error status.

Template parameters

typename

Container type that supports clear(), capacity(), size(), and push_back().

Parameters

container

T &

Container to fill with frame UIDs.

get_frame_names

template <typename T>
expected_t<void> holoscan::PoseTree::get_frame_names(
    T &container
) const

Get list of frame names.

Returns: Success or error status.

Template parameters

typename

Container type that supports clear(), capacity(), size(), and push_back().

Parameters

container

T &

Container to fill with frame names.

add_create_frame_callback

expected_t<uid_t> holoscan::PoseTree::add_create_frame_callback(
    CreateFrameCallback callback
)

Returns: Unique ID for the callback on success, error on failure.

Parameters

callback

CreateFrameCallback

Callback function to register.

remove_create_frame_callback

expected_t<void> holoscan::PoseTree::remove_create_frame_callback(
    uid_t cid
)

Deregister a callback function for frame creation.

Returns: Success or error status.

Parameters

cid

uid_t

Component ID of the callback to remove.

add_set_edge_callback

expected_t<uid_t> holoscan::PoseTree::add_set_edge_callback(
    SetEdgeCallback callback
)

Returns: Unique ID for the callback on success, error on failure.

Parameters

callback

SetEdgeCallback

Callback function to register.

remove_set_edge_callback

expected_t<void> holoscan::PoseTree::remove_set_edge_callback(
    uid_t cid
)

Deregister a callback function for edge setting.

Returns: Success or error status.

Parameters

cid

uid_t

Component ID of the callback to remove.

get_frame_name_unlocked

expected_t<std::string_view> holoscan::PoseTree::get_frame_name_unlocked(
    frame_t uid
) const

Internal version of get_frame_name that assumes the lock is already held.

find_or_create_frame_impl

expected_t<frame_t> holoscan::PoseTree::find_or_create_frame_impl(
    std::string_view name,
    int32_t number_edges
)

find_frame_impl

expected_t<frame_t> holoscan::PoseTree::find_frame_impl(
    std::string_view name
) const

create_frame_impl

expected_t<frame_t> holoscan::PoseTree::create_frame_impl(
    std::string_view name,
    int32_t number_edges,
    const frame_t *id
)

create_edges_impl

expected_t<version_t> holoscan::PoseTree::create_edges_impl(
    frame_t lhs,
    frame_t rhs,
    int32_t maximum_length,
    PoseTreeEdgeHistory::AccessMethod method
)

delete_edge_impl

expected_t<version_t> holoscan::PoseTree::delete_edge_impl(
    frame_t lhs,
    frame_t rhs,
    version_t version
)

update_root

expected_t<void> holoscan::PoseTree::update_root(
    frame_t root
)

get_impl

expected_t<Pose3d> holoscan::PoseTree::get_impl(
    frame_t lhs,
    frame_t rhs,
    double time,
    PoseTreeEdgeHistory::AccessMethod method,
    version_t version
) const

get_dfs_impl

expected_t<Pose3d> holoscan::PoseTree::get_dfs_impl(
    frame_t lhs,
    frame_t rhs,
    double time,
    PoseTreeEdgeHistory::AccessMethod method,
    version_t version
) const

get_latest_impl

expected_t<std::pair<Pose3d, double>> holoscan::PoseTree::get_latest_impl(
    frame_t lhs,
    frame_t rhs
) const

Static methods

error_to_str

static const char * holoscan::PoseTree::error_to_str(
    Error error
)

Convert an error code to a human readable error string.

Returns: Human-readable error string.

Parameters

error

Error

Error code to convert.

Types

Typedefs

Name	Definition	Description
`expected_t`	`nvidia::Expected< T, Error >`	Expected type used by this class.
`unexpected_t`	`nvidia::Unexpected< Error >`	Unexpected type used by this class.
`frame_t`	`uint64_t`	Type used to uniquely identify a frame.
`version_t`	`uint64_t`	Type used for versioning the `PoseTree`.
`history_t`	`uint64_t`	Type used as a key for the PoseTreeEdgeHistory map.
`uid_t`	`uint64_t`	Type used as a key for the PoseTreeEdgeHistory map.
`CreateFrameCallback`	`std::function< void(frame_t frame)>`	Type for callback functions that are called every time a frame is created.
`SetEdgeCallback`	`std::function< void(frame_t lhs, frame_t rhs, double time, const Pose3d &lhs_T_rhs)>`	Type for callback functions that are called every time an edge is set.

Error

Error codes used by this class.

Name	Value	Description
`kInvalidArgument`	`= 0`	kInvalidArgument is returned when a function is called with argument that does not make sense such as negative number of frames.
`kOutOfMemory`	`= 1`	kOutOfMemory is returned if `initialize` failed to allocate the requested memory, or if an edge/frame can’t be added because we run out of the pre-allocated memory.
`kFrameNotFound`	`= 2`	kFrameNotFound is returned if a query is made with a frame uid that does not match any existing frame.
`kAlreadyExists`	`= 3`	kAlreadyExists is returned if a frame or an edge that already exist is added.
`kCyclingDependency`	`= 4`	kCyclingDependency is returned if a pose is added that would create a cycle in the `PoseTree` structure.
`kFramesNotLinked`	`= 5`	kFramesNotLinked is returned if a query is made between two not connected frame or if we attempt to disconnect/delete an edge that does not exist.
`kPoseOutOfOrder`	`= 6`	kPoseOutOfOrder is returned if a query is made to update the three in the past.
`kLogicError`	`= 7`	kLogicError is used whenever an error that should not have happened happened.

Member variables

Name	Type	Description
`kFrameNameMaximumLength` static constexpr	`int32_t`	The maximum size for the name of a frame.
`kAutoGeneratedFrameNamePrefix` static constexpr	`char const *`	Auto generated frame names will start with this prefix, followed by the uid of the frame.
`mutex_`	`std::shared_timed_mutex`	Lock to protect access to the parameter below.
`dfs_mutex_`	`std::mutex`	Lock to protect access to get_dfs_impl.
`create_frame_callbacks_mutex_`	`std::shared_timed_mutex`	Lock to protect create_frame_callbacks_.
`create_frame_callbacks_`	`nvidia::UniqueIndexMap< CreateFrameCallback >`	Callback functions for the create frame operation.
`create_frame_callbacks_keys_`	`nvidia::FixedVector< uid_t >`
`set_edge_callbacks_mutex_`	`std::shared_timed_mutex`	Lock to protect set_edge_callbacks_.
`set_edge_callbacks_`	`nvidia::UniqueIndexMap< SetEdgeCallback >`	Callback functions for the set edge operation.
`set_edge_callbacks_keys_`	`nvidia::FixedVector< uid_t >`
`edges_map_`	`pose_tree::HashMap< std::pair< frame_t, frame_t >, history_t >`	Mapping from a frame to its index.
`edges_map_keys_`	`nvidia::FixedVector< std::pair< frame_t, frame_t > >`
`name_to_uid_map_`	`pose_tree::HashMap< std::string_view, frame_t >`	TODO(ben): We need to get rid of std::map, but for now UniqueIndexMap does not support iterating through all the elements.
`name_to_uid_map_keys_`	`nvidia::FixedVector< std::string_view >`
`frame_map_`	`pose_tree::HashMap< frame_t, FrameInfo >`	Store the list of the current frame of the `PoseTree`.
`next_frame_id_`	`frame_t`
`frame_id_increment_`	`frame_t`
`frames_stack_`	`std::unique_ptr< frame_t[]>`	Used to implement a dfs.
`histories_map_`	`nvidia::UniqueIndexMap< PoseTreeEdgeHistory >`	Store the list of PoseTreeEdgeHistory used by the frames.
`histories_management_`	`FirstFitAllocator< history_t >`	Helper to `allocate` an array of PoseTreeEdgeHistory (storing only the uid).
`poses_management_`	`FirstFitAllocator< PoseTreeEdgeHistory::TimedPose >`	Helper to `allocate` an array of TimedPose.
`version_`	`version_t`	Current version of the `PoseTree`.
`hint_version_`	`version_t`	Version of the hint. Mostly used to know if a node in the stack has been processed already.
`init_params_`	`InitParameters`	The initialization parameters.
`default_number_edges_`	`int32_t`	Default maximum number of edges a given frame can have.
`default_history_length_`	`int32_t`	Default length of the history used by an edge.
`frame_cb_latest_uid_`	`uid_t`
`edge_cb_latest_uid_`	`uid_t`

Inner classes

InitParameters

struct holoscan::PoseTree::InitParameters

Parameters used to initialize the PoseTree.

Name	Type	Description
`number_frames`	`int32_t`	Maximum number of frames to support.
`number_edges`	`int32_t`	Maximum number of edges to support.
`history_length`	`int32_t`	Maximum history length.
`default_number_edges`	`int32_t`	Default number of edges per frame.
`default_history_length`	`int32_t`	Default history length per edge.
`edges_chunk_size`	`int32_t`	Chunk size for edge allocation.
`history_chunk_size`	`int32_t`	Chunk size for history allocation.

FrameInfo

struct holoscan::PoseTree::FrameInfo

Helper structure that stores the information about a frame.

Name	Type	Description
`history`	`history_t *`	Array containing the list of edges.
`number_edges`	`int32_t`	Current number of edges.
`maximum_number_edges`	`int32_t`	Maximum number of edges allowed.
`name`	`char`	Name of the frame. It has to be null terminated, so it can hold at most 63 characters.
`name_view`	`std::string_view`
`distance_to_root`	`int32_t`	Hint to quickly find a path: Store the distance from the node to the root (== 0 if this frame is the root).
`node_to_root`	`frame_t`	Frame to follow to reach the root.
`root`	`frame_t`	Name of the root.
`hint_version`	`version_t`	Some helper id to computer the path between two nodes.
`dfs_link`	`frame_t`	Some helper to memorize the path we took during the dfs.
`uid`	`frame_t`	Name of the frame.

Methods

init

deinit

set_multithreading_info

get_pose_tree_version

create_frame_with_id

create_frame

Create a new frame in the PoseTree

Create a new frame in the PoseTree with a name

Overload 3

Overload 4

find_frame

find_or_create_frame

Find a frame with the given name

Find a frame with the given name (with number edges)

create_edges

Create an edge between two frames

Overload 2

Overload 3

Overload 4

Overload 5

Overload 6

Overload 7

Overload 8

delete_frame

Overload 1

Overload 2

delete_edge

Delete an edge and free the memory

Delete an edge by frame names and free the memory

disconnect_frame

Overload 1

Overload 2

Deleted overload

disconnect_edge

Disconnect an edge starting at a given time

Overload 2

Deleted overload

get_frame_name

get_init_parameters

get_latest

Const (1)

Const (2)

get

Const (with time and method and version) (1)

Const (with time and version) (1)

Const (with time and method) (1)

Const (with time) (1)

Const (with version) (1)

Const (1)

Const (with time and method and version) (2)

Const (with time and version) (2)

Const (with version) (2)

Const (with time and method) (2)

Const (with time) (2)

Const (2)

Deleted overloads

get_pose2_xy

set

Set the pose between two frames in the PoseTree

Overload 2

Overload 3

Overload 4

Deleted overloads

get_edge_uids

get_edge_names

get_frame_uids

get_frame_names

add_create_frame_callback

remove_create_frame_callback

add_set_edge_callback

remove_set_edge_callback

get_frame_name_unlocked

find_or_create_frame_impl

find_frame_impl

create_frame_impl

create_edges_impl

delete_edge_impl

update_root

get_impl

Create a new frame in the `PoseTree`

Create a new frame in the `PoseTree` with a name

Set the pose between two frames in the `PoseTree`