> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/holoscan/sdk-user-guide/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/holoscan/sdk-user-guide/_mcp/server. # holoscan::PoseTree > A temporal pose tree to store relative coordinate system transformations over time. 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. ```cpp showLineNumbers={false} #include ``` --- ## Methods ### init \[#init] ```cpp showLineNumbers={false} expected_t 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_t` — default: 1024 Maximum number of frames to support. --- **`number_edges`** `int32_t` — default: 16384 Maximum number of edges to support. --- **`history_length`** `int32_t` — default: 1048576 Maximum history length. --- **`default_number_edges`** `int32_t` — default: 16 Default number of edges per frame. --- **`default_history_length`** `int32_t` — default: 1024 Default history length per edge. --- **`edges_chunk_size`** `int32_t` — default: 4 Chunk size for edge allocation. --- **`history_chunk_size`** `int32_t` — default: 64 Chunk size for history allocation. --- ### deinit \[#deinit] ```cpp showLineNumbers={false} void holoscan::PoseTree::deinit() ``` Deinitialize the `PoseTree` and free all allocated resources. ### set\_multithreading\_info \[#setmultithreadinginfo] ```cpp showLineNumbers={false} expected_t 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 \[#getposetreeversion] ```cpp showLineNumbers={false} version_t holoscan::PoseTree::get_pose_tree_version() const ``` Get the current `PoseTree` version. **Returns:** Current version of the `PoseTree`. ### create\_frame\_with\_id \[#createframewithid] ```cpp showLineNumbers={false} expected_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 \[#createframe] #### Create a new frame in the \`PoseTree\` ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **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. --- #### Create a new frame in the \`PoseTree\` with a name ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Frame id on success, error on failure. **Parameters** **`name`** `std::string_view` Human-readable name for the frame. --- #### Overload 3 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::create_frame( int32_t number_edges ) ``` Create a new frame in the `PoseTree` with edge count hint. A name will be generated automatically. **Returns:** Frame id on success, error on failure. **Parameters** **`number_edges`** `int32_t` Hint for maximum number of edges this frame will have. --- #### Overload 4 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. ### find\_frame \[#findframe] ```cpp showLineNumbers={false} expected_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 \[#findorcreateframe] #### Find a frame with the given name ```cpp showLineNumbers={false} expected_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. --- #### Find a frame with the given name (with number edges) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Frame id on success, error on failure. **Parameters** **`name`** `std::string_view` Name of the frame to find or create. --- **`number_edges`** `int32_t` Hint for maximum number of edges this frame will have. --- ### create\_edges \[#createedges] #### Create an edge between two frames ```cpp showLineNumbers={false} expected_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. --- #### Overload 2 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::create_edges( frame_t lhs, frame_t rhs, int32_t maximum_length ) ``` Create an edge between two frames with maximum length hint. **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. --- **`maximum_length`** `int32_t` Hint for maximum history length. --- #### Overload 3 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::create_edges( frame_t lhs, frame_t rhs, PoseTreeEdgeHistory::AccessMethod method ) ``` Create an edge between two frames with access method. **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. --- **`method`** `PoseTreeEdgeHistory::AccessMethod` Access method for the edge history. --- #### Overload 4 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **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. --- **`maximum_length`** `int32_t` Hint for maximum history length. --- **`method`** `PoseTreeEdgeHistory::AccessMethod` Access method for the edge history. --- #### Overload 5 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::create_edges( std::string_view lhs, std::string_view rhs ) ``` Create an edge between two frames using string names. **Returns:** Version id of the change on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- #### Overload 6 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Version id of the change on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`maximum_length`** `int32_t` Hint for maximum history length. --- #### Overload 7 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Version id of the change on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`method`** `PoseTreeEdgeHistory::AccessMethod` Access method for the edge history. --- #### Overload 8 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Version id of the change on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`maximum_length`** `int32_t` Hint for maximum history length. --- **`method`** `PoseTreeEdgeHistory::AccessMethod` Access method for the edge history. --- ### delete\_frame \[#deleteframe] #### Overload 1 ```cpp showLineNumbers={false} expected_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. --- #### Overload 2 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::delete_frame( std::string_view name ) ``` Delete a frame in the `PoseTree` by name and all its relations to other frames. **Returns:** Version id of the change on success, error on failure. **Parameters** **`name`** `std::string_view` Name of the frame to delete. --- ### delete\_edge \[#deleteedge] #### Delete an edge and free the memory ```cpp showLineNumbers={false} expected_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. --- #### Delete an edge by frame names and free the memory ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::delete_edge( std::string_view lhs, std::string_view rhs ) ``` Delete an edge by frame names and free the memory. **Returns:** Version id of the change on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- ### disconnect\_frame \[#disconnectframe] #### Overload 1 ```cpp showLineNumbers={false} expected_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. --- #### Overload 2 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::disconnect_frame( std::string_view name, double time ) ``` Disconnect a frame by name from all the others starting at a given time. **Returns:** Version id of the change on success, error on failure. **Parameters** **`name`** `std::string_view` Name of the frame to disconnect. --- **`time`** `double` Time at which to start the disconnection. --- #### Deleted overload ```cpp showLineNumbers={false} template expected_t holoscan::PoseTree::disconnect_frame( Args &&... args ) = delete ``` ### disconnect\_edge \[#disconnectedge] #### Disconnect an edge starting at a given time ```cpp showLineNumbers={false} expected_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. --- #### Overload 2 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::disconnect_edge( std::string_view lhs, std::string_view rhs, double time ) ``` Disconnect an edge by frame names starting at a given time. **Returns:** Version id of the change on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`time`** `double` Time at which to start the disconnection. --- #### Deleted overload ```cpp showLineNumbers={false} template expected_t holoscan::PoseTree::disconnect_edge( Args &&... args ) = delete ``` ### get\_frame\_name \[#getframename] ```cpp showLineNumbers={false} expected_t 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 \[#getinitparameters] ```cpp showLineNumbers={false} expected_t 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 \[#getlatest] #### Const (1) ```cpp showLineNumbers={false} expected_t> 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. --- #### Const (2) ```cpp showLineNumbers={false} expected_t> holoscan::PoseTree::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. **Returns:** Pair of pose and time on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- ### get \[#get] #### Const (with time and method and version) (1) ```cpp showLineNumbers={false} expected_t 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. --- #### Const (with time and version) (1) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **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. --- **`version`** `version_t` Version of the `PoseTree` to query. --- #### Const (with time and method) (1) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **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. --- #### Const (with time) (1) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::get( frame_t lhs, frame_t rhs, double time ) const ``` Get the pose lhs\_T\_rhs between two frames at the given time. **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. --- #### Const (with version) (1) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::get( frame_t lhs, frame_t rhs, version_t version ) const ``` Get the pose lhs\_T\_rhs between two frames at a specific version. **Returns:** Pose on success, error on failure. **Parameters** **`lhs`** `frame_t` Left hand side frame. --- **`rhs`** `frame_t` Right hand side frame. --- **`version`** `version_t` Version of the `PoseTree` to query. --- #### Const (1) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::get( frame_t lhs, frame_t rhs ) const ``` Get the latest pose lhs\_T\_rhs between two frames. **Returns:** Pose on success, error on failure. **Parameters** **`lhs`** `frame_t` Left hand side frame. --- **`rhs`** `frame_t` Right hand side frame. --- #### Const (with time and method and version) (2) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Pose on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of 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. --- #### Const (with time and version) (2) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Pose on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`time`** `double` Time at which to query the pose. --- **`version`** `version_t` Version of the `PoseTree` to query. --- #### Const (with version) (2) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Pose on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`version`** `version_t` Version of the `PoseTree` to query. --- #### Const (with time and method) (2) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Pose on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`time`** `double` Time at which to query the pose. --- **`method`** `PoseTreeEdgeHistory::AccessMethod` Access method for interpolation. --- #### Const (with time) (2) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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. **Returns:** Pose on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`time`** `double` Time at which to query the pose. --- #### Const (2) ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::get( std::string_view lhs, std::string_view rhs ) const ``` Get the latest pose lhs\_T\_rhs between two frames by name. **Returns:** Pose on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- #### Deleted overloads The following overloads are deleted to prevent misuse: ```cpp showLineNumbers={false} expected_t< Pose3d > holoscan::PoseTree::get(frame_t lhs, frame_t rhs, Args &&... args) const = delete; expected_t< Pose3d > holoscan::PoseTree::get(std::string_view lhs, std::string_view rhs, Args &&... args) const = delete; ``` ### get\_pose2\_xy \[#getpose2xy] ```cpp showLineNumbers={false} template expected_t holoscan::PoseTree::get_pose2_xy( Args &&... args ) const ``` Helper function to get a [Pose2d](../typedefs/pose2d) instead of [Pose3d](../typedefs/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] #### Set the pose between two frames in the \`PoseTree\` ```cpp showLineNumbers={false} expected_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. --- #### Overload 2 ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::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`. **Returns:** Version id of the change on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`time`** `double` Time at which to set the pose. --- **`lhs_T_rhs`** `const Pose3d &` Pose transformation from lhs to rhs. --- #### Overload 3 inline ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::set( frame_t lhs, frame_t rhs, double time, const Pose2d &lhs_T_rhs ) ``` Helper function to set a [Pose2d](../typedefs/pose2d) instead of [Pose3d](../typedefs/pose3d). **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 Pose2d &` 2D pose transformation from lhs to rhs. --- #### Overload 4 inline ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::set( std::string_view lhs, std::string_view rhs, double time, const Pose2d &lhs_T_rhs ) ``` Helper function to set a [Pose2d](../typedefs/pose2d) instead of [Pose3d](../typedefs/pose3d) using frame names. **Returns:** Version id of the change on success, error on failure. **Parameters** **`lhs`** `std::string_view` Name of left hand side frame. --- **`rhs`** `std::string_view` Name of right hand side frame. --- **`time`** `double` Time at which to set the pose. --- **`lhs_T_rhs`** `const Pose2d &` 2D pose transformation from lhs to rhs. --- #### Deleted overloads The following overloads are deleted to prevent misuse: ```cpp showLineNumbers={false} expected_t< version_t > holoscan::PoseTree::set(frame_t lhs, frame_t rhs, T time, const Pose &lhs_T_rhs) = delete; expected_t< version_t > holoscan::PoseTree::set(std::string_view lhs, std::string_view rhs, T time, const Pose &lhs_T_rhs) = delete; ``` ### get\_edge\_uids \[#getedgeuids] ```cpp showLineNumbers={false} template expected_t holoscan::PoseTree::get_edge_uids( T &container ) const ``` Get list of edge UIDs. **Returns:** Success or error status. **Template parameters** **`T`** `typename` Container type that supports clear(), capacity(), size(), and push\_back(). --- **Parameters** **`container`** `T &` Container to fill with edge UIDs. --- ### get\_edge\_names \[#getedgenames] ```cpp showLineNumbers={false} template expected_t holoscan::PoseTree::get_edge_names( T &container ) const ``` Get list of edge names. **Returns:** Success or error status. **Template parameters** **`T`** `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 \[#getframeuids] ```cpp showLineNumbers={false} template expected_t holoscan::PoseTree::get_frame_uids( T &container ) const ``` Get list of frame UIDs. **Returns:** Success or error status. **Template parameters** **`T`** `typename` Container type that supports clear(), capacity(), size(), and push\_back(). --- **Parameters** **`container`** `T &` Container to fill with frame UIDs. --- ### get\_frame\_names \[#getframenames] ```cpp showLineNumbers={false} template expected_t holoscan::PoseTree::get_frame_names( T &container ) const ``` Get list of frame names. **Returns:** Success or error status. **Template parameters** **`T`** `typename` Container type that supports clear(), capacity(), size(), and push\_back(). --- **Parameters** **`container`** `T &` Container to fill with frame names. --- ### add\_create\_frame\_callback \[#addcreateframecallback] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::add_create_frame_callback( const CreateFrameCallback &callback ) ``` Register a callback function for every time a frame is created. **Returns:** Unique ID for the callback on success, error on failure. **Parameters** **`callback`** `const CreateFrameCallback &` Callback function to register. --- ### remove\_create\_frame\_callback \[#removecreateframecallback] ```cpp showLineNumbers={false} expected_t 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](component) ID of the callback to remove. --- ### add\_set\_edge\_callback \[#addsetedgecallback] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::add_set_edge_callback( const SetEdgeCallback &callback ) ``` Register a callback function for every time an edge is set. **Returns:** Unique ID for the callback on success, error on failure. **Parameters** **`callback`** `const SetEdgeCallback &` Callback function to register. --- ### remove\_set\_edge\_callback \[#removesetedgecallback] ```cpp showLineNumbers={false} expected_t 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](component) ID of the callback to remove. --- ### get\_frame\_name\_unlocked \[#getframenameunlocked] ```cpp showLineNumbers={false} expected_t 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 \[#findorcreateframeimpl] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::find_or_create_frame_impl( std::string_view name, int32_t number_edges ) ``` ### find\_frame\_impl \[#findframeimpl] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::find_frame_impl( std::string_view name ) const ``` ### create\_frame\_impl \[#createframeimpl] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::create_frame_impl( std::string_view name, int32_t number_edges, const frame_t *id ) ``` ### create\_edges\_impl \[#createedgesimpl] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::create_edges_impl( frame_t lhs, frame_t rhs, int32_t maximum_length, PoseTreeEdgeHistory::AccessMethod method ) ``` ### delete\_edge\_impl \[#deleteedgeimpl] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::delete_edge_impl( frame_t lhs, frame_t rhs, version_t version ) ``` ### update\_root \[#updateroot] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::update_root( frame_t root ) ``` ### get\_impl \[#getimpl] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::get_impl( frame_t lhs, frame_t rhs, double time, PoseTreeEdgeHistory::AccessMethod method, version_t version ) const ``` ### get\_dfs\_impl \[#getdfsimpl] ```cpp showLineNumbers={false} expected_t holoscan::PoseTree::get_dfs_impl( frame_t lhs, frame_t rhs, double time, PoseTreeEdgeHistory::AccessMethod method, version_t version ) const ``` ### get\_latest\_impl \[#getlatestimpl] ```cpp showLineNumbers={false} expected_t> holoscan::PoseTree::get_latest_impl( frame_t lhs, frame_t rhs ) const ``` --- ## Static methods ### error\_to\_str \[#errortostr] ```cpp showLineNumbers={false} 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](posetreeedgehistory) map. | | `uid_t` | `uint64_t` | Type used as a key for the [PoseTreeEdgeHistory](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](posetreeedgehistory) used by the frames. | | `histories_management_` | `FirstFitAllocator< history_t >` | Helper to `allocate` an array of [PoseTreeEdgeHistory](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 ```cpp showLineNumbers={false} 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 ```cpp showLineNumbers={false} 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. |