holoscan::PoseTreeManager

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.

#include <holoscan/pose_tree_manager.hpp>

Inherits from: holoscan::Resource (public), holoscan::DistributedAppService (public)

Constructors

PoseTreeManager

holoscan::PoseTreeManager::PoseTreeManager() = default

Methods

resource

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

initialize

void holoscan::PoseTreeManager::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.

setup

void holoscan::PoseTreeManager::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

tree

std::shared_ptr<PoseTree> holoscan::PoseTreeManager::tree()

driver_start

void holoscan::PoseTreeManager::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.

Parameters

driver_shutdown

void holoscan::PoseTreeManager::driver_shutdown() override

Shutdown the UCX server on the driver fragment.

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

worker_connect

void holoscan::PoseTreeManager::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.

Parameters

worker_disconnect

void holoscan::PoseTreeManager::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.

resource_type

ResourceType holoscan::PoseTreeManager::resource_type() const

Get the resource type.

Returns: The resource type.

name

Resource & holoscan::PoseTreeManager::name(
    const std::string &name
) &

fragment

Resource & holoscan::PoseTreeManager::fragment(
    Fragment *fragment
)

spec

Resource & holoscan::PoseTreeManager::spec(
    const std::shared_ptr<ComponentSpec> &spec
)

spec_shared

std::shared_ptr<ComponentSpec> holoscan::PoseTreeManager::spec_shared()

Get the shared pointer to the component spec.

Returns: The shared pointer to the component spec.

to_yaml_node

YAML::Node holoscan::PoseTreeManager::to_yaml_node() const override

Get a YAML representation of the resource.

Returns: YAML node including spec of the resource in addition to the base component properties.

set_parameters

void holoscan::PoseTreeManager::set_parameters() override

Set the parameters based on defaults (sets GXF parameters for GXF components).

id

int64_t holoscan::ComponentBase::id() const

Get the identifier of the component.

By default, the identifier is set to -1. It is set to a valid value when the component is initialized.

With the default executor (GXFExecutor), the identifier is set to the GXF component ID.

Returns: The identifier of the component.

add_arg

void holoscan::ComponentBase::add_arg(
    const Arg &arg
)

args

std::vector<Arg> & holoscan::ComponentBase::args()

Get the list of arguments.

Returns: The vector of arguments.

description

std::string holoscan::ComponentBase::description() const

Get a description of the component.

Returns: YAML string.

See also: to_yaml_node()

service

template <typename ServiceT = DefaultFragmentService>
std::shared_ptr<ServiceT> holoscan::ComponentBase::service(
    std::string_view id = ""
) const

Retrieve a registered fragment service or resource.

Retrieves a previously registered fragment service or resource by its type and optional identifier. Returns nullptr if no service/resource is found with the specified type and identifier.

Note that any changes to the service retrieval logic in this method should be synchronized with the implementation in Fragment::service() method to maintain consistency.

Returns: The shared pointer to the service/resource, or nullptr if not found or if type casting fails.

Template parameters

Parameters

get_service_by_type_info

std::shared_ptr<FragmentService> holoscan::ComponentBase::get_service_by_type_info(
    const std::type_info &service_type,
    std::string_view id = ""
) const

Retrieve a registered fragment service or resource for Python bindings.

This is a helper method for Python bindings to retrieve a service by its C++ type info.

Returns: The shared pointer to the base service, or nullptr if not found.

Parameters

reset_backend_objects

virtual void holoscan::ComponentBase::reset_backend_objects()

Reset any backend-specific objects (e.g. GXF GraphEntity).

FragmentService

holoscan::FragmentService::FragmentService() = default

Inherit constructors from base classes.

This using declaration enables construction of DistributedAppService using the constructors of FragmentService, ServiceDriverEndpoint, and ServiceWorkerEndpoint, providing flexibility in how derived classes can be initialized.

driver_start_impl

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

Internal implementation of driver_start with error handling.

Returns: Success (void) or error status

Parameters

driver_shutdown_impl

expected<void> holoscan::PoseTreeManager::driver_shutdown_impl()

Internal implementation of driver_shutdown with error handling.

Returns: Success (void) or error status

worker_connect_impl

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

Internal implementation of worker_connect with error handling.

Returns: Success (void) or error status

Parameters

worker_disconnect_impl

expected<void> holoscan::PoseTreeManager::worker_disconnect_impl()

Internal implementation of worker_disconnect with error handling.

Returns: Success (void) or error status

update_params_from_args

void holoscan::PoseTreeManager::update_params_from_args()

service_provider

void holoscan::ComponentBase::service_provider(
    FragmentServiceProvider *provider
)

Set the service provider that owns this component.

Static methods

error_to_str

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

Convert an error code to a human readable error string.

Returns: Human-readable error string.

Parameters

register_converter

template <typename typeT>
static void holoscan::ComponentBase::register_converter()

Register the argument setter for the given type.

If an operator or resource has an argument with a custom type, the argument setter must be registered using this method.

The argument setter is used to set the value of the argument from the YAML configuration.

This method can be called in the initialization phase of the operator/resource (e.g., initialize()). The example below shows how to register the argument setter for the custom type (Vec3):

It is assumed that YAML::convert<T>::encode and YAML::convert<T>::decode are implemented for the given type. You need to specialize the YAML::convert<> template class.

For example, suppose that you had a Vec3 class with the following members:

You can define the YAML::convert<Vec3> as follows in a ‘.cpp’ file:

Please refer to the yaml-cpp documentation for more details.

Template parameters

Example

void MyOp::initialize() {
  register_converter<Vec3>();
}

Example

struct Vec3 {
  // make sure you have overloaded operator==() for the comparison
  double x, y, z;
};

Example

namespace YAML {
template<>
struct convert<Vec3> {
  static Node encode(const Vec3& rhs) {
    Node node;
    node.push_back(rhs.x);
    node.push_back(rhs.y);
    node.push_back(rhs.z);
    return node;
  }
  static bool decode(const Node& node, Vec3& rhs) {
    if(!node.IsSequence() || node.size() != 3) {
      return false;
    }
    rhs.x = node[0].as<double>();
    rhs.y = node[1].as<double>();
    rhs.z = node[2].as<double>();
    return true;
  }
};
}

register_argument_setter

template <typename typeT>
void holoscan::ComponentBase::register_argument_setter()

Register the argument setter for the given type.

Please refer to the documentation of register_converter() for more details.

Template parameters

Types

Typedefs

Error

Error codes used by this class.

ResourceType

Resource type used for the initialization of the resource.

Member variables