NVIDIA Docs Hub NVIDIA Holoscan NVIDIA Holoscan SDK v3.4.0 Class PoseTree

Class PoseTree

Defined in File pose_tree.hpp

Class Documentation

class PoseTree

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.

Public Types

enum class Error

Error codes used by this class.

Values:

enumerator kInvalidArgument: kInvalidArgument is returned when a function is called with argument that does not make sense such as negative number of frames.

enumerator kOutOfMemory: 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.

enumerator kFrameNotFound: kFrameNotFound is returned if a query is made with a frame uid that does not match any existing frame.

enumerator kAlreadyExists: kAlreadyExists is returned if a frame or an edge that already exist is added.

enumerator kCyclingDependency: kCyclingDependency is returned if a pose is added that would create a cycle in the PoseTree structure.

enumerator kFramesNotLinked: 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.

enumerator kPoseOutOfOrder: kPoseOutOfOrder is returned if a query is made to update the three in the past. For example if we try to disconnect or update a pose at a time older than the latest update on this edge.

enumerator kLogicError: kLogicError is used whenever an error that should not have happened happened. This should never happen and are here only to prevent crashes/assert,

template<typename T> using expected_t = nvidia::Expected<T, Error>: Expected type used by this class.

using unexpected_t = nvidia::Unexpected<Error>: Unexpected type used by this class.

using frame_t = uint64_t: Type used to uniquely identify a frame.

using version_t = uint64_t: Type used for versioning the PoseTree.

using history_t = uint64_t: Type used as a key for the PoseTreeEdgeHistory map.

using uid_t = uint64_t: Type used as a key for the PoseTreeEdgeHistory map.

using CreateFrameCallback = std::function<void(frame_t frame)>: Type for callback functions that are called every time a frame is created.

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

Public Functions

expected_t<void> 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.

Parameters

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

Returns

Success or error status.

void deinit(): Deinitialize the PoseTree and free all allocated resources.

version_t get_pose_tree_version() const

Get the current PoseTree version.

Returns: Current version of the PoseTree.

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

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.

Parameters

name – Human-readable name for the frame.
number_edges – Hint for maximum number of edges this frame will have.

Returns

Frame id on success, error on failure.

expected_t<frame_t> create_frame(std::string_view name)

Create a new frame in the PoseTree with a name.

The maximum number of edges for this frame will be the default value.

Parameters: name – Human-readable name for the frame.
Returns: Frame id on success, error on failure.

expected_t<frame_t> create_frame(int32_t number_edges)

Create a new frame in the PoseTree with edge count hint.

A name will be generated automatically.

Parameters: number_edges – Hint for maximum number of edges this frame will have.
Returns: Frame id on success, error on failure.

expected_t<frame_t> create_frame()

Create a new frame in the PoseTree with default settings.

A name will be generated automatically and the maximum number of edges will be the default value.

Returns: Frame id on success, error on failure.

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

Find a frame with the given name.

Parameters: name – Name of the frame to find.
Returns: Frame id on success, Error::kFrameNotFound if no such frame exists.

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

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

Parameters: name – Name of the frame to find or create.
Returns: Frame id on success, error on failure.

expected_t<frame_t> find_or_create_frame(std::string_view name, int32_t number_edges)

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

Parameters

name – Name of the frame to find or create.
number_edges – Hint for maximum number of edges this frame will have.

Returns

Frame id on success, error on failure.

expected_t<version_t> create_edges(frame_t lhs, frame_t rhs)

Create an edge between two frames.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.

Returns

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

expected_t<version_t> create_edges(frame_t lhs, frame_t rhs, int32_t maximum_length)

Create an edge between two frames with maximum length hint.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
maximum_length – Hint for maximum history length.

Returns

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

expected_t<version_t> create_edges(frame_t lhs, frame_t rhs, PoseTreeEdgeHistory::AccessMethod method)

Create an edge between two frames with access method.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
method – Access method for the edge history.

Returns

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

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

Create an edge between two frames with maximum length and access method.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
maximum_length – Hint for maximum history length.
method – Access method for the edge history.

Returns

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

expected_t<version_t> create_edges(std::string_view lhs, std::string_view rhs)

Create an edge between two frames using string names.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.

Returns

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

expected_t<version_t> create_edges(std::string_view lhs, std::string_view rhs, int32_t maximum_length)

Create an edge between two frames using string names with maximum length hint.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
maximum_length – Hint for maximum history length.

Returns

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

expected_t<version_t> create_edges(std::string_view lhs, std::string_view rhs, PoseTreeEdgeHistory::AccessMethod method)

Create an edge between two frames using string names with access method.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
method – Access method for the edge history.

Returns

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

expected_t<version_t> create_edges(std::string_view lhs, std::string_view rhs, int32_t maximum_length, PoseTreeEdgeHistory::AccessMethod method)

Create an edge between two frames using string names with maximum length and access method.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
maximum_length – Hint for maximum history length.
method – Access method for the edge history.

Returns

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

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

Parameters: uid – Frame id to delete.
Returns: Version id of the change on success, error on failure.

expected_t<version_t> delete_frame(std::string_view name)

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

Parameters: name – Name of the frame to delete.
Returns: Version id of the change on success, error on failure.

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

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.

Returns

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

expected_t<version_t> delete_edge(std::string_view lhs, std::string_view rhs)

Delete an edge by frame names and free the memory.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.

Returns

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

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

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

Parameters

uid – Frame id to disconnect.
time – Time at which to start the disconnection.

Returns

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

expected_t<version_t> disconnect_frame(std::string_view name, double time)

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

Parameters

name – Name of the frame to disconnect.
time – Time at which to start the disconnection.

Returns

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

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

Disconnect an edge starting at a given time.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
time – Time at which to start the disconnection.

Returns

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

expected_t<version_t> disconnect_edge(std::string_view lhs, std::string_view rhs, double time)

Disconnect an edge by frame names starting at a given time.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
time – Time at which to start the disconnection.

Returns

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

template<class ...Args> expected_t<Pose3d> disconnect_frame(Args&&... args) = delete

template<class ...Args> expected_t<Pose3d> disconnect_edge(Args&&... args) = delete

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

Get the name of a frame.

Parameters: uid – Frame id.
Returns: Frame name on success, error on failure.

expected_t<std::pair<Pose3d, double>> 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.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.

Returns

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

expected_t<std::pair<Pose3d, double>> get_latest(std::string_view lhs, std::string_view rhs) const

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

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.

Returns

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

expected_t<Pose3d> 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.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
time – Time at which to query the pose.
method – Access method for interpolation.
version – Version of the PoseTree to query.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(frame_t lhs, frame_t rhs, double time, version_t version) const

Get the pose lhs_T_rhs between two frames at the given time and version.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
time – Time at which to query the pose.
version – Version of the PoseTree to query.

Returns

Pose on success, error on failure.

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

Get the pose lhs_T_rhs between two frames at the given time with access method.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
time – Time at which to query the pose.
method – Access method for interpolation.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(frame_t lhs, frame_t rhs, double time) const

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

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
time – Time at which to query the pose.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(frame_t lhs, frame_t rhs, version_t version) const

Get the pose lhs_T_rhs between two frames at a specific version.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
version – Version of the PoseTree to query.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(frame_t lhs, frame_t rhs) const

Get the latest pose lhs_T_rhs between two frames.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(std::string_view lhs, std::string_view rhs, double time, PoseTreeEdgeHistory::AccessMethod method, version_t version) const

Get the pose lhs_T_rhs between two frames by name at the given time.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
time – Time at which to query the pose.
method – Access method for interpolation.
version – Version of the PoseTree to query.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(std::string_view lhs, std::string_view rhs, double time, version_t version) const

Get the pose lhs_T_rhs between two frames by name at the given time and version.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
time – Time at which to query the pose.
version – Version of the PoseTree to query.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(std::string_view lhs, std::string_view rhs, version_t version) const

Get the pose lhs_T_rhs between two frames by name at a specific version.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
version – Version of the PoseTree to query.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(std::string_view lhs, std::string_view rhs, double time, PoseTreeEdgeHistory::AccessMethod method) const

Get the pose lhs_T_rhs between two frames by name at the given time with access method.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
time – Time at which to query the pose.
method – Access method for interpolation.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(std::string_view lhs, std::string_view rhs, double time) const

Get the pose lhs_T_rhs between two frames by name at the given time.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
time – Time at which to query the pose.

Returns

Pose on success, error on failure.

expected_t<Pose3d> get(std::string_view lhs, std::string_view rhs) const

Get the latest pose lhs_T_rhs between two frames by name.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.

Returns

Pose on success, error on failure.

template<class ...Args> expected_t<Pose3d> get(frame_t lhs, frame_t rhs, Args&&... args) const = delete

template<class ...Args> expected_t<Pose3d> get(std::string_view lhs, std::string_view rhs, Args&&... args) const = delete

template<class ...Args> inline expected_t<Pose2d> get_pose2_xy(Args&&... args) const

Helper function to get a Pose2d instead of Pose3d.

Template Parameters: Args – Argument types to forward to the get method.
Parameters: args – Arguments to forward to the get method.
Returns: 2D pose on success, error on failure.

expected_t<version_t> 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.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
time – Time at which to set the pose.
lhs_T_rhs – Pose transformation from lhs to rhs.

Returns

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

expected_t<version_t> set(std::string_view lhs, std::string_view rhs, double time, const Pose3d &lhs_T_rhs)

Set the pose between two frames by name in the PoseTree.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
time – Time at which to set the pose.
lhs_T_rhs – Pose transformation from lhs to rhs.

Returns

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

inline expected_t<version_t> set(frame_t lhs, frame_t rhs, double time, const Pose2d &lhs_T_rhs)

Helper function to set a Pose2d instead of Pose3d.

Parameters

lhs – Left hand side frame.
rhs – Right hand side frame.
time – Time at which to set the pose.
lhs_T_rhs – 2D pose transformation from lhs to rhs.

Returns

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

inline expected_t<version_t> set(std::string_view lhs, std::string_view rhs, double time, const Pose2d &lhs_T_rhs)

Helper function to set a Pose2d instead of Pose3d using frame names.

Parameters

lhs – Name of left hand side frame.
rhs – Name of right hand side frame.
time – Time at which to set the pose.
lhs_T_rhs – 2D pose transformation from lhs to rhs.

Returns

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

template<typename T, typename Pose> expected_t<version_t> set(frame_t lhs, frame_t rhs, T time, const Pose &lhs_T_rhs) = delete

template<typename T, typename Pose> expected_t<version_t> set(std::string_view lhs, std::string_view rhs, T time, const Pose &lhs_T_rhs) = delete

template<typename T> inline expected_t<void> get_edge_uids(T &container) const

Get list of edge UIDs.

Template Parameters: T – Container type that supports clear(), capacity(), size(), and push_back().
Parameters: container – Container to fill with edge UIDs.
Returns: Success or error status.

template<typename T> inline expected_t<void> get_edge_names(T &container) const

Get list of edge names.

Template Parameters: T – Container type that supports clear(), capacity(), size(), and push_back().
Parameters: container – Container to fill with edge names as pairs.
Returns: Success or error status.

template<typename T> inline expected_t<void> get_frame_uids(T &container) const

Get list of frame UIDs.

Template Parameters: T – Container type that supports clear(), capacity(), size(), and push_back().
Parameters: container – Container to fill with frame UIDs.
Returns: Success or error status.

template<typename T> inline expected_t<void> get_frame_names(T &container) const

Get list of frame names.

Template Parameters: T – Container type that supports clear(), capacity(), size(), and push_back().
Parameters: container – Container to fill with frame names.
Returns: Success or error status.

expected_t<uid_t> add_create_frame_callback(CreateFrameCallback callback)

Parameters: callback – Callback function to register.
Returns: Unique ID for the callback on success, error on failure.

expected_t<void> remove_create_frame_callback(uid_t cid)

Deregister a callback function for frame creation.

Parameters: cid – Component ID of the callback to remove.
Returns: Success or error status.

expected_t<uid_t> add_set_edge_callback(SetEdgeCallback callback)

Parameters: callback – Callback function to register.
Returns: Unique ID for the callback on success, error on failure.

expected_t<void> remove_set_edge_callback(uid_t cid)

Deregister a callback function for edge setting.

Parameters: cid – Component ID of the callback to remove.
Returns: Success or error status.

Public Static Functions

static const char *error_to_str(Error error)

Convert an error code to a human readable error string.

Parameters: error – Error code to convert.
Returns: Human-readable error string.

Public Static Attributes

static constexpr int32_t kFrameNameMaximumLength = 127: The maximum size for the name of a frame. An additional ‘\0’ is added at the end to make it 128 characters long.

static constexpr char const *kAutoGeneratedFrameNamePrefix = "_frame_": Auto generated frame names will start with this prefix, followed by the uid of the frame.

Previous Template Class HashMap

Next Class PoseTreeEdgeHistory

Class PoseTree

Nested Relationships

Nested Types

Class Documentation