<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

<a id="generated-tracker-code"></a>

# Generated Tracker Code

Trackers whose live impl only moves a FlatBuffer between a plugin and the host via
`SchemaTracker` or `SchemaPusher` — *schema-based* trackers — are not hand-written. They are
declared in a TOML manifest and their C++ and Python glue is generated when you configure the build.
Adding one is a `.fbs` schema plus roughly ten lines of TOML; see
[Schema-based trackers (manifest)](../device/add_device.md#schema-based-tracker-manifest) for the authoring workflow.

This page records what is generated today, what is deliberately still hand-written, and what
would have to change to generate the rest.

<a id="how-it-works"></a>

## How it works

Three inputs drive the generator:

- [src/core/deviceio_trackers/trackers.toml](https://github.com/NVIDIA/IsaacCapture/blob/main/src/core/deviceio_trackers/trackers.toml) — one `[[tracker]]` entry per tracker,
  carrying only the values that differ from the defaults.
- [src/core/deviceio_trackers/defaults.toml](https://github.com/NVIDIA/IsaacCapture/blob/main/src/core/deviceio_trackers/defaults.toml) — the defaults, expressed with
  `%placeholder%` substitutions (`%name%`, `%name_CamelCase%`, and so on).
- [src/core/codegen](https://github.com/NVIDIA/IsaacCapture/tree/main/src/core/codegen) — `manifest.py` resolves the placeholders, `templates.py`
  derives type and file names, `templates/` holds the C++ bodies as `*.hpp.template` /
  `*.cpp.template` under `pull/` and `push/` (`@KEY@` substitution via `template_renderer.py`),
  and `generate_trackers.py` renders the output.

[cmake/GenerateTrackers.cmake](https://github.com/NVIDIA/IsaacCapture/blob/main/cmake/GenerateTrackers.cmake) runs the generator through `execute_process` at
**configure** time, not build time, because CMake needs the resulting source list before it can
define targets. Output lands in `${CMAKE_BINARY_DIR}/generated/trackers/` and is **not** checked
into git, exactly like the `flatc` output. Sources are wired through an explicit
`generated_sources.cmake` list (not by globbing that directory). Two consequences worth knowing:

- Grepping `src/` for a generated class such as `Se3Tracker` finds the manifest entry and the
  generator, not a `.cpp`. Searching, debugging, and clangd all need a configured build tree.
- The manifests, every `.py` under `src/core/codegen`, and every template under
  `templates/` are registered as `CMAKE_CONFIGURE_DEPENDS`, so editing any of them re-runs
  configure on the next build.

The generator rewrites a file only when its content changed. Configure also passes
`--prune-stale` so that after renaming or removing a tracker, orphan headers cannot remain on
the generated include path and keep satisfying a stale `#include`.

<a id="what-each-entry-produces"></a>

## What each entry produces

Per manifest entry, in `${CMAKE_BINARY_DIR}/generated/trackers/`:

```text
deviceio_base/<header>_base.hpp                    # I<Class>Impl interface
deviceio_trackers/inc/deviceio_trackers/<header>.hpp
deviceio_trackers/<header>.cpp                     # the ITracker facade
live_trackers/live_<header>_impl.{hpp,cpp}         # wraps SchemaTracker / SchemaPusher
replay_trackers/replay_<header>_impl.{hpp,cpp}
```

`header` defaults from `name` (`<name>_tracker`, or `name` when it already ends in
`_tracker`). Override it when the public `#include` stem must keep a historical path.

The shared registration points stay hand-written and `#include` a generated `.inc` fragment,
so hand-written trackers keep their own rows. The fragments under `generated/trackers/inc/` cover
the live and replay factories (includes, forward declarations, try-create thunks, dispatch rows,
factory declarations and definitions), the MCAP recording traits in
[src/core/mcap/cpp/inc/mcap/recording_traits.hpp](https://github.com/NVIDIA/IsaacCapture/blob/main/src/core/mcap/cpp/inc/mcap/recording_traits.hpp), the pybind blocks in
[src/core/deviceio_trackers/python/tracker_bindings.cpp](https://github.com/NVIDIA/IsaacCapture/blob/main/src/core/deviceio_trackers/python/tracker_bindings.cpp), and a
`_generated_tracker_exports.py` that [src/python/isaaccapture/deviceio_trackers/_\_init_\_.py](https://github.com/NVIDIA/IsaacCapture/blob/main/src/python/isaaccapture/deviceio_trackers/__init__.py)
star-imports. Because that last one is spliced into `__all__`, a new manifest entry needs no
Python edit at all.

`.pyi` stubs need no work either: [src/core/python/generate_stubs.py](https://github.com/NVIDIA/IsaacCapture/blob/main/src/core/python/generate_stubs.py) derives them from
the built module.

<a id="tracker-metadata"></a>

<a id="trackers-with-metadata"></a>

## Trackers with metadata

A device that describes itself once rather than every frame (a tactile glove’s taxel layout, for
example) declares that description as the tracker’s `metadata` table:

```toml
[[tracker]]
name = "tactile"
table = "TactileDataArray"
schema = "tactile_array"
metadata = "TactileMetadata"
```

The metadata table is the `root_type` of a schema of its own, named after the table in snake case
(`tactile_metadata.fbs`), with no Record wrapper: MCAP records the table itself. Like the data table,
it needs a hand-written `schema/python/*_bindings.h` before `get_metadata()` can return it to
Python. Only `direction = "pull"` supports `metadata`.

- **Producer.** Pushes the encoded table on `tracker_metadata_collection_id(collection_id)`
  (`<collection_id>/metadata`), tensor `TRACKER_METADATA_TENSOR_IDENTIFIER`, in samples of at most
  `TRACKER_METADATA_MAX_SIZE` bytes; see [src/core/schema/cpp/inc/schema/tracker_metadata.hpp](https://github.com/NVIDIA/IsaacCapture/blob/main/src/core/schema/cpp/inc/schema/tracker_metadata.hpp).
  It pushes when it starts and periodically after that, always the same encoded table, so a consumer
  that starts later still receives it. A C++ producer does this with a `SchemaPusher`, a Python one
  with a `TensorPushTracker`, either sized to the encoded table.
- **Live.** The first metadata received is adopted, recorded once on `<channel>_metadata`, and
  returned by `get_metadata()` for the rest of the session. `get_data()` publishes and records
  data only while the producer’s metadata is confirmed: from a sample equal to the adopted one
  until the metadata collection goes away, so a restarted producer’s data waits for its own
  metadata. A sample that differs from the adopted one, or is not a valid table, is an error the
  session update throws.
- **Replay.** Reads the recorded metadata when the session opens, and publishes data only from a
  recording that holds it.

<a id="generated-today"></a>

## Generated today

| Manifest entry              | Class                           | Notes                                                                                                   |
|-----------------------------|---------------------------------|---------------------------------------------------------------------------------------------------------|
| `joint_state`               | `JointStateTracker`             | One generic joint-space device (leader arm, exoskeleton, …)                                             |
| `se3_tracker`               | `Se3Tracker`                    | Overrides `class`; the default would give `Se3TrackerTracker`                                           |
| `soma_body_joint_rotations` | `SomaBodyJointRotationsTracker` | Keyed SOMA body rotations for up to 77 controls of the 78-joint skeleton; defined against SOMA-X v0.3.1 |
| `soma_body_joint_poses`     | `SomaBodyJointPosesTracker`     | Keyed evaluated SOMA positions and orientations for up to 77 public joints                              |
| `soma_hand_joint_rotations` | `SomaHandJointRotationsTracker` | Keyed SOMA hand rotations for up to 25 controls; defined against SOMA-X v0.3.1                          |
| `soma_hand_joint_poses`     | `SomaHandJointPosesTracker`     | Keyed evaluated SOMA positions and orientations for up to 25 joints                                     |
| `oglo_tactile`              | `OgloTactileTracker`            | MCAP channels are `oglo`/`oglo_tracked`, so `channel` is overridden                                     |
| `generic_3axis_pedal`       | `Generic3AxisPedalTracker`      | Schema lives in `pedals.fbs`, so `schema` and `channel` are overridden                                  |
| `haptic_command`            | `HapticCommandPushTracker`      | `direction = "push"`: a typed producer wrapping `SchemaPusher`                                          |
| `frame_metadata_oak`        | `FrameMetadataTrackerOak`       | Overrides `class` and `header` (file stem `frame_metadata_tracker_oak`)                                 |
| `spacemouse`                | `SpaceMouseTracker`             | Overrides `class` and `traits`; the defaults would spell `Spacemouse`                                   |
| `gamepad`                   | `GamepadTracker`                | Gamepad state pushed by the gamepad plugin (SDL3); only `python_accessor` is overridden                 |

<a id="still-hand-written"></a>

## Still hand-written

| Tracker                                           | Why it is not generated                                                                                                                                               |
|---------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `HeadTracker`, `HandTracker`, `ControllerTracker` | Real `xrLocate*` / hand-tracking calls, not schema-based FlatBuffer readers                                                                                           |
| `FullBodyTracker` (PICO vendor)                   | Native `XR_BD_body_tracking`                                                                                                                                          |
| `FullBodyTracker` (Noitom vendor)                 | Genuinely schema-based by mechanism, but a **vendor** of an existing facade — see below                                                                               |
| `MessageChannelTracker`                           | `XR_NV_opaque_data_channel` with its own connection state machine                                                                                                     |
| `HapticCommandReaderTracker`                      | Cross-process consumer: `read_all_samples` on one collection, buckets by<br/>`HapticCommand.endpoint` (left/right). Paired with generated `HapticCommandPushTracker`. |
| `TensorPushTracker`                               | Deliberately kept as the untyped `bytes` escape hatch                                                                                                                 |
| `KeyboardTracker`                                 | In-process keyboard fed by host `KeyboardProvider`s, no OpenXR extension                                                                                              |

A quick way to tell the two groups apart: only schema-based impls mention `SchemaTracker` or
`SchemaPusher`. Of the hand-written live impls that use those helpers, each is listed above.

<a id="future-work"></a>

## Future work

**Multi-endpoint reader (rejected generated shape).** We briefly generated
`HapticCommandReaderTracker` with a `multi_endpoint` template (bucket samples by
`HapticCommand.endpoint` on one push-tensor collection). That shape was removed: it made the
codegen tree branchy for a single device, and a generic multi-endpoint reader does not fit
`pull/` or `push`. The hand-written reader remains the supported approach; a future redesign
(split tensors/collections per endpoint, or a dedicated generator) is optional follow-up.

**Vendored shape (Noitom).** `LiveFullBodyTrackerNoitomImpl` reads
`SchemaTracker<FullBodyPoseRecord, FullBodyPose>`, so it is schema-based by mechanism, but it is a
second *vendor* of the hand-written `FullBodyTracker` rather than its own tracker type. Generating
it would need a shape that emits **only** a live impl and a vendor-keyed dispatch row — no facade,
base interface, recording traits, replay half, or pybind block, since it shares all of those with the
PICO vendor. Its `collection_id` and `max_flatbuffer_size` also arrive through
`TrackerVendor::params` at runtime instead of being fixed at generation time.

**Schema pybind bindings.** The field-by-field `src/core/schema/python/*_bindings.h` files are
still hand-written. They are derivable from the `.bfbs` reflection data `flatc` already emits
(`--bfbs-gen-embed --reflect-names --reflect-types`), so this is a viable follow-up, but it is a
separate generator with its own risks.

**Manifest \`\`python_accessor\`\` (pybind method name).** Generated `pull` trackers use
`fragments/pybind_pull.template`, which binds whatever string `python_accessor` holds (default
`get_data`; `oglo_tactile` and `generic_3axis_pedal` override with device-specific names).
`direction = "push"` uses `push` via defaults. Future work: remove the manifest key and
hard-code `get_data` on readers (or maybe `pull`, paired with `push` on producers).
Maybe rename the C++ facade to match if we pick `pull`, so Python and C++ stay aligned without
per-tracker overrides.

If a prospective shape makes the templates hard to follow, leaving that tracker hand-written is the
correct outcome — the generator exists to remove mechanical duplication, not to model every device.
