Class PoseTreeManager

• Defined in File pose_tree_manager.hpp

Base Types

• public holoscan::Resource (Class Resource)

• public holoscan::DistributedAppService (Class DistributedAppService)

class PoseTreeManager : public holoscan::Resource, public holoscan::DistributedAppService

Manage a shared PoseTree instance as a FragmentService.

This resource creates and holds a holoscan::PoseTree instance, making it accessible to multiple components (like operators) within the same fragment. It simplifies the management of pose data by providing a centralized, configurable point of access.

In distributed applications, PoseTreeManager also provides automatic network synchronization of the PoseTree across fragments using UCX (Unified Communication X) when used as an DistributedAppService.

Public Types

enum class Error

Error codes used by this class.

Values:

enumerator kNotInitialized

kNotInitialized is returned when operations are performed before initialization

enumerator kServerError

kServerError is returned when server operations fail

enumerator kClientError

kClientError is returned when client operations fail

enumerator kAlreadyStarted

kAlreadyStarted is returned when trying to start a service that’s already running

enumerator kNotStarted

kNotStarted is returned when trying to stop a service that’s not running

enumerator kInternalError

kInternalError is returned for unexpected internal errors

template<typename T>
using expected = holoscan::expected<T, Error>

Expected type used by this class.

using unexpected = holoscan::unexpected<Error>

Unexpected type used by this class.

Public Functions

HOLOSCAN_RESOURCE_FORWARD_ARGS_SUPER (PoseTreeManager, holoscan::Resource) PoseTreeManager()=default

virtual std::shared_ptr<Resource> resource() const override

Return a shared pointer to this resource, part of the FragmentService interface.

Returns

A std::shared_ptr<Resource> pointing to this instance.

virtual void resource(const std::shared_ptr<Resource> &resource) override

Set the internal weak pointer to this resource, part of the FragmentService interface.

Parameters

resource – A std::shared_ptr<Resource> that must point to this instance.

virtual void initialize() override

Initialize the resource and creates the underlying PoseTree instance.

This method is called by the framework after the resource is created and its parameters have been set. It allocates and initializes the PoseTree with the configured capacity parameters.

virtual void setup(holoscan::ComponentSpec &spec) override

Define the parameters for configuring the PoseTree instance.

This method registers the following parameters:

• port: Port number for UCX server (default: 13337)

• number_frames: Maximum number of coordinate frames.

• number_edges: Maximum number of edges (direct transformations) between frames.

• history_length: Total capacity for storing historical pose data across all edges.

• default_number_edges: Default number of edges allocated per new frame.

• default_history_length: Default history capacity allocated per new edge.

• edges_chunk_size: Allocation chunk size for a frame’s edge list.

• history_chunk_size: Allocation chunk size for an edge’s history buffer.

• request_timeout_ms: Timeout for UCX requests in milliseconds.

• request_poll_sleep_us: Sleep duration between request polls in microseconds.

• worker_progress_sleep_us: Sleep duration between worker progress calls in microseconds.

• server_shutdown_timeout_ms: Timeout for server shutdown in milliseconds.

• server_shutdown_poll_sleep_ms: Sleep duration between shutdown polls in milliseconds.

Parameters

spec – The component specification to which the parameters are added.

std::shared_ptr<PoseTree> tree()

Get a shared pointer to the managed PoseTree instance.

This is the primary method for accessing the pose tree from other components.

Returns

A std::shared_ptr<PoseTree> to the underlying pose tree.

std::shared_ptr<PoseTree> tree() const

Get a shared pointer to the managed PoseTree instance from a const context.

Returns

A std::shared_ptr<PoseTree> to the underlying pose tree.

virtual void driver_start(std::string_view driver_ip) override

Start the UCX server on the driver fragment.

Called by the framework on the driver fragment to start the PoseTreeUCXServer. The server will listen on the configured port for client connections.

Note

Errors are logged but not thrown to satisfy the DistributedAppService interface

Parameters

driver_ip – The IP address of the driver (unused in current implementation)

virtual void driver_shutdown() override

Shutdown the UCX server on the driver fragment.

Called by the framework to stop the PoseTreeUCXServer and clean up resources.

Note

Errors are logged but not thrown to satisfy the DistributedAppService interface

virtual void worker_connect(std::string_view driver_ip) override

Connect a worker fragment to the driver’s UCX server.

Called by the framework on worker fragments to establish a connection to the driver’s PoseTreeUCXServer using a PoseTreeUCXClient.

Note

Errors are logged but not thrown to satisfy the DistributedAppService interface

Parameters

driver_ip – The IP address of the driver fragment

virtual void worker_disconnect() override

Disconnect a worker fragment from the driver’s UCX server.

Called by the framework to disconnect the PoseTreeUCXClient and clean up resources.

Note

Errors are logged but not thrown to satisfy the DistributedAppService interface

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.

Protected Functions

expected<void> driver_start_impl(std::string_view driver_ip)

Internal implementation of driver_start with error handling.

Parameters

driver_ip – The IP address of the driver

Returns

Success (void) or error status

expected<void> driver_shutdown_impl()

Internal implementation of driver_shutdown with error handling.

Returns

Success (void) or error status

expected<void> worker_connect_impl(std::string_view driver_ip)

Internal implementation of worker_connect with error handling.

Parameters

driver_ip – The IP address of the driver fragment

Returns

Success (void) or error status

expected<void> worker_disconnect_impl()

Internal implementation of worker_disconnect with error handling.

Returns

Success (void) or error status