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

> Manage a shared PoseTree instance as a FragmentService.

Manage a shared [PoseTree](posetree) instance as a [FragmentService](fragmentservice).

This resource creates and holds a [`holoscan::PoseTree`](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](posetree) across fragments using UCX (Unified Communication X) when used as an [DistributedAppService](distributedappservice).

```cpp showLineNumbers={false}
#include <holoscan/pose_tree_manager.hpp>
```

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

---

## Constructors

### PoseTreeManager \[#posetreemanager]

```cpp showLineNumbers={false}
holoscan::PoseTreeManager::PoseTreeManager() = default
```

---

## Methods

### resource \[#resource]

#### Mutable

```cpp showLineNumbers={false}
void holoscan::PoseTreeManager::resource(
    const std::shared_ptr<Resource> &resource
) override
```

Set the internal weak pointer to this resource, part of the [FragmentService](fragmentservice) interface.

**Parameters**

**`resource`** `const std::shared_ptr<Resource> &`

A `std::shared_ptr<`[`Resource`](resource)`>` that must point to this instance.

---

#### Const

const

```cpp showLineNumbers={false}
std::shared_ptr<Resource> holoscan::PoseTreeManager::resource() const override
```

Return a shared pointer to this resource, part of the [FragmentService](fragmentservice) interface.

**Returns:** A `std::shared_ptr<`[`Resource`](resource)`>` pointing to this instance.

### initialize \[#initialize]

```cpp showLineNumbers={false}
void holoscan::PoseTreeManager::initialize() override
```

Initialize the resource and creates the underlying [`PoseTree`](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`](posetree) with the configured capacity parameters.

### setup \[#setup]

```cpp showLineNumbers={false}
void holoscan::PoseTreeManager::setup(
    holoscan::ComponentSpec &spec
) override
```

Define the parameters for configuring the [`PoseTree`](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`** `holoscan::ComponentSpec &`

The component specification to which the parameters are added.

---

### tree \[#tree]

#### Mutable

```cpp showLineNumbers={false}
std::shared_ptr<PoseTree> holoscan::PoseTreeManager::tree()
```

Get a shared pointer to the managed [`PoseTree`](posetree) instance.

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

**Returns:** A `std::shared_ptr<`[`PoseTree`](posetree)`>` to the underlying pose tree.

#### Const

const

```cpp showLineNumbers={false}
std::shared_ptr<PoseTree> holoscan::PoseTreeManager::tree() const
```

Get a shared pointer to the managed [`PoseTree`](posetree) instance from a const context.

**Returns:** A `std::shared_ptr<`[`PoseTree`](posetree)`>` to the underlying pose tree.

### driver\_start \[#driverstart]

```cpp showLineNumbers={false}
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](posetreeucxserver). The server will listen on the configured port for client connections.

Errors are logged but not thrown to satisfy the [DistributedAppService](distributedappservice) interface

**Parameters**

**`driver_ip`** `std::string_view`

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

---

### driver\_shutdown \[#drivershutdown]

```cpp showLineNumbers={false}
void holoscan::PoseTreeManager::driver_shutdown() override
```

Shutdown the UCX server on the driver fragment.

Called by the framework to stop the [PoseTreeUCXServer](posetreeucxserver) and clean up resources.

Errors are logged but not thrown to satisfy the [DistributedAppService](distributedappservice) interface

### worker\_connect \[#workerconnect]

```cpp showLineNumbers={false}
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](posetreeucxserver) using a [PoseTreeUCXClient](posetreeucxclient).

Errors are logged but not thrown to satisfy the [DistributedAppService](distributedappservice) interface

**Parameters**

**`driver_ip`** `std::string_view`

The IP address of the driver fragment

---

### worker\_disconnect \[#workerdisconnect]

```cpp showLineNumbers={false}
void holoscan::PoseTreeManager::worker_disconnect() override
```

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

Called by the framework to disconnect the [PoseTreeUCXClient](posetreeucxclient) and clean up resources.

Errors are logged but not thrown to satisfy the [DistributedAppService](distributedappservice) interface

### resource\_type \[#resourcetype]

```cpp showLineNumbers={false}
ResourceType holoscan::PoseTreeManager::resource_type() const
```

Get the resource type.

**Returns:** The resource type.

### name \[#name]

#### Set the name of the resource (1)

```cpp showLineNumbers={false}
Resource & holoscan::PoseTreeManager::name(
    const std::string &name
) &
```

Set the name of the resource.

**Returns:** The reference to the resource.

**Parameters**

**`name`** `const std::string &`

The name of the resource.

---

#### Set the name of the resource (2)

```cpp showLineNumbers={false}
Resource && holoscan::PoseTreeManager::name(
    const std::string &name
) &&
```

Set the name of the resource.

**Returns:** The reference to the resource.

**Parameters**

**`name`** `const std::string &`

The name of the resource.

---

#### Const

const

```cpp showLineNumbers={false}
const std::string & holoscan::ComponentBase::name() const
```

Get the name of the component.

**Returns:** The name of the component.

### fragment \[#fragment]

#### Set the fragment of the resource

```cpp showLineNumbers={false}
Resource & holoscan::PoseTreeManager::fragment(
    Fragment *fragment
)
```

Set the fragment of the resource.

**Returns:** The reference to the resource.

**Parameters**

**`fragment`** `Fragment *`

The pointer to the fragment of the resource.

---

#### Get a pointer to \[Fragment]\(fragment) object

```cpp showLineNumbers={false}
Fragment * holoscan::ComponentBase::fragment()
```

Get a pointer to [Fragment](fragment) object.

**Returns:** The Pointer to [Fragment](fragment) object.

#### Const

const

```cpp showLineNumbers={false}
const Fragment * holoscan::ComponentBase::fragment() const
```

Get a const pointer to [Fragment](fragment) object.

**Returns:** The const pointer to [Fragment](fragment) object.

### spec \[#spec]

#### Set the component specification to the resource

```cpp showLineNumbers={false}
Resource & holoscan::PoseTreeManager::spec(
    const std::shared_ptr<ComponentSpec> &spec
)
```

Set the component specification to the resource.

**Returns:** The reference to the resource.

**Parameters**

**`spec`** `const std::shared_ptr<ComponentSpec> &`

The component specification.

---

#### Get the component specification of the resource

```cpp showLineNumbers={false}
ComponentSpec * holoscan::PoseTreeManager::spec()
```

Get the component specification of the resource.

**Returns:** The pointer to the component specification.

### spec\_shared \[#specshared]

```cpp showLineNumbers={false}
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 \[#toyamlnode]

```cpp showLineNumbers={false}
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 \[#setparameters]

```cpp showLineNumbers={false}
void holoscan::PoseTreeManager::set_parameters() override
```

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

### id \[#id]

```cpp showLineNumbers={false}
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 \[#addarg]

#### Add an argument to the component (1)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::add_arg(
    const Arg &arg
)
```

Add an argument to the component.

**Parameters**

**`arg`** `const Arg &`

The argument to add.

---

#### Add an argument to the component (2)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::add_arg(
    Arg &&arg
)
```

Add an argument to the component.

**Parameters**

**`arg`** `Arg &&`

The argument to add.

---

#### Add a list of arguments to the component (1)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::add_arg(
    const ArgList &arg
)
```

Add a list of arguments to the component.

**Parameters**

**`arg`** `const ArgList &`

The list of arguments to add.

---

#### Add a list of arguments to the component (2)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::add_arg(
    ArgList &&arg
)
```

Add a list of arguments to the component.

**Parameters**

**`arg`** `ArgList &&`

The list of arguments to add.

---

### args \[#args]

```cpp showLineNumbers={false}
std::vector<Arg> & holoscan::ComponentBase::args()
```

Get the list of arguments.

**Returns:** The vector of arguments.

### description \[#description]

```cpp showLineNumbers={false}
std::string holoscan::ComponentBase::description() const
```

Get a description of the component.

**Returns:** `YAML` string.

**See also:**
to\_yaml\_node()

### service \[#service]

```cpp showLineNumbers={false}
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**

**`ServiceT`** `typename`

The type of the service/resource to retrieve. Must inherit from either [Resource](resource) or [FragmentService](fragmentservice). Defaults to [DefaultFragmentService](defaultfragmentservice) if not specified.

---

**Parameters**

**`id`** `std::string_view` — default: ""

The identifier of the service/resource. If empty, retrieves by type only.

---

### get\_service\_by\_type\_info \[#getservicebytypeinfo]

```cpp showLineNumbers={false}
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**

**`service_type`** `const std::type_info &`

The type info of the service/resource to retrieve.

---

**`id`** `std::string_view` — default: ""

The identifier of the service/resource. If empty, retrieves by type only.

---

### reset\_backend\_objects \[#resetbackendobjects]

```cpp showLineNumbers={false}
virtual void holoscan::ComponentBase::reset_backend_objects()
```

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

### FragmentService \[#fragmentservice]

```cpp showLineNumbers={false}
holoscan::FragmentService::FragmentService() = default
```

Inherit constructors from base classes.

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

### driver\_start\_impl \[#driverstartimpl]

```cpp showLineNumbers={false}
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_ip`** `std::string_view`

The IP address of the driver

---

### driver\_shutdown\_impl \[#drivershutdownimpl]

```cpp showLineNumbers={false}
expected<void> holoscan::PoseTreeManager::driver_shutdown_impl()
```

Internal implementation of driver\_shutdown with error handling.

**Returns:** Success (void) or error status

### worker\_connect\_impl \[#workerconnectimpl]

```cpp showLineNumbers={false}
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**

**`driver_ip`** `std::string_view`

The IP address of the driver fragment

---

### worker\_disconnect\_impl \[#workerdisconnectimpl]

```cpp showLineNumbers={false}
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 \[#updateparamsfromargs]

#### Update parameters based on the specified arguments

```cpp showLineNumbers={false}
void holoscan::PoseTreeManager::update_params_from_args()
```

Update parameters based on the specified arguments.

#### Update parameters based on the specified arguments (with params)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::update_params_from_args(
    std::unordered_map<std::string, ParameterWrapper> &params
)
```

Update parameters based on the specified arguments.

### service\_provider \[#serviceprovider]

```cpp showLineNumbers={false}
void holoscan::ComponentBase::service_provider(
    FragmentServiceProvider *provider
)
```

Set the service provider that owns this component.

---

## Static methods

### error\_to\_str \[#errortostr]

```cpp showLineNumbers={false}
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**

**`error`** `Error`

Error code to convert.

---

### register\_converter \[#registerconverter]

```cpp showLineNumbers={false}
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](https://github.com/jbeder/yaml-cpp/wiki/Tutorial#converting-tofrom-native-data-types) for more details.

**Template parameters**

**`typeT`** `typename`

The type of the argument to register.

---

**Example**

```cpp showLineNumbers={false}
void MyOp::initialize() {
  register_converter<Vec3>();
}
```

**Example**

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

**Example**

```cpp showLineNumbers={false}
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 \[#registerargumentsetter]

```cpp showLineNumbers={false}
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**

**`typeT`** `typename`

The type of the argument to register.

---

---

## Types

### Typedefs

| Name         | Definition                       | Description                         |
| ------------ | -------------------------------- | ----------------------------------- |
| `expected`   | `holoscan::expected< T, Error >` | Expected type used by this class.   |
| `unexpected` | `holoscan::unexpected< Error >`  | Unexpected type used by this class. |

### Error

Error codes used by this class.

| Name              | Value | Description                                                                       |
| ----------------- | ----- | --------------------------------------------------------------------------------- |
| `kNotInitialized` | `= 0` | kNotInitialized is returned when operations are performed before initialization   |
| `kServerError`    | `= 1` | kServerError is returned when server operations fail                              |
| `kClientError`    | `= 2` | kClientError is returned when client operations fail                              |
| `kAlreadyStarted` | `= 3` | kAlreadyStarted is returned when trying to start a service that's already running |
| `kNotStarted`     | `= 4` | kNotStarted is returned when trying to stop a service that's not running          |
| `kInternalError`  | `= 5` | kInternalError is returned for unexpected internal errors                         |

### ResourceType

[Resource](resource) type used for the initialization of the resource.

| Name      | Value | Description      |
| --------- | ----- | ---------------- |
| `kNative` |       | Native resource. |
| `kGXF`    |       | GXF resource.    |

---

## Member variables

| Name                             | Type                                   | Description                                                   |
| -------------------------------- | -------------------------------------- | ------------------------------------------------------------- |
| `port_`                          | `Parameter< int32_t >`                 | Port number for UCX server.                                   |
| `number_frames_`                 | `Parameter< int32_t >`                 | Maximum number of coordinate frames.                          |
| `number_edges_`                  | `Parameter< int32_t >`                 | Maximum number of edges between frames.                       |
| `history_length_`                | `Parameter< int32_t >`                 | Total capacity for historical pose data.                      |
| `default_number_edges_`          | `Parameter< int32_t >`                 | Default edges allocated per new frame.                        |
| `default_history_length_`        | `Parameter< int32_t >`                 | Default history capacity per new edge.                        |
| `edges_chunk_size_`              | `Parameter< int32_t >`                 | Allocation chunk size for frame's edge list.                  |
| `history_chunk_size_`            | `Parameter< int32_t >`                 | Allocation chunk size for edge's history buffer.              |
| `request_timeout_ms_`            | `Parameter< int64_t >`                 | Timeout for UCX requests in milliseconds.                     |
| `request_poll_sleep_us_`         | `Parameter< int64_t >`                 | Sleep duration between request polls in microseconds.         |
| `worker_progress_sleep_us_`      | `Parameter< int64_t >`                 | Sleep duration between worker progress calls in microseconds. |
| `server_shutdown_timeout_ms_`    | `Parameter< int64_t >`                 | Timeout for server shutdown in milliseconds.                  |
| `server_shutdown_poll_sleep_ms_` | `Parameter< int64_t >`                 | Sleep duration between shutdown polls in milliseconds.        |
| `maximum_clients_`               | `Parameter< int64_t >`                 | Maximum number of clients.                                    |
| `pose_tree_instance_`            | `std::shared_ptr< PoseTree >`          | The managed [PoseTree](posetree) instance.                    |
| `server_`                        | `std::unique_ptr< PoseTreeUCXServer >` | UCX server (only on driver fragment).                         |
| `client_`                        | `std::unique_ptr< PoseTreeUCXClient >` | UCX client (only on worker fragments).                        |
| `resource_`                      | `std::weak_ptr< Resource >`            | Weak reference to the managed resource (self).                |
| `resource_type_`                 | `ResourceType`                         | The type of the resource.                                     |
| `is_initialized_`                | `bool`                                 | Whether the resource is initialized.                          |
| `spec_`                          | `std::shared_ptr< ComponentSpec >`     | The component specification.                                  |
| `id_`                            | `int64_t`                              | The ID of the component.                                      |
| `name_`                          | `std::string`                          | Name of the component.                                        |
| `fragment_`                      | `Fragment *`                           | Pointer to the fragment that owns this component.             |
| `args_`                          | `std::vector< Arg >`                   | List of arguments.                                            |
| `service_provider_`              | `FragmentServiceProvider *`            | Pointer to the service provider.                              |