# wenbowen123/bundletrack architecture

> Architecture diagram of the GitHub repository wenbowen123/bundletrack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wenbowen123/bundletrack
- Repository: https://github.com/wenbowen123/bundletrack

## Overview

BundleTrack tracks novel objects in RGB-D sequences without an object CAD model: a user supplies a benchmark or custom sequence and masks, feature extraction and matching feed spatiotemporal pose estimation, and the system writes pose results for evaluation. The repository also includes a separate learned feature detector service and a video-segmentation component, plus training and benchmark evaluation paths. The README documents these capabilities; source excerpts are partial, so edges reflect only documented or directly evidenced wiring.

Main entry points: [`scripts/run_nocs.py`](https://github.com/wenbowen123/bundletrack/blob/master/scripts/run_nocs.py) (NOCS Runner), [`scripts/run_ycbineoat.py`](https://github.com/wenbowen123/bundletrack/blob/master/scripts/run_ycbineoat.py) (YCB Runner), [`src/FeatureManager.cpp`](https://github.com/wenbowen123/bundletrack/blob/master/src/FeatureManager.cpp) (Feature Matching), [`src/DataLoader.cpp`](https://github.com/wenbowen123/bundletrack/blob/master/src/DataLoader.cpp) (Sequence Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Sequence Inputs"]
  node_nocs_run["NOCS Runner<br/>[run_nocs.py]"]
  node_ycb_run["YCB Runner<br/>[run_ycbineoat.py]"]
  node_rgbd["RGB-D Sequence"]
  node_masks["Segmentation Masks"]
end

subgraph group_tracking["Pose Tracking"]
  node_frame["Frame Data<br/>[Frame.cpp]"]
  node_loader["Sequence Loader<br/>[DataLoader.cpp]"]
  node_features["Feature Matching<br/>[FeatureManager.cpp]"]
  node_bundler["Pose Graph<br/>[Bundler.cpp]"]
end

subgraph group_learned["Learned Perception"]
  node_lfnet["LFNet Client<br/>[FeatureManager.cpp]"]
  node_lfserver["LFNet Server<br/>[run_server.py]"]
  node_detector["Keypoint Detector<br/>[inference.py]"]
  node_detmodel["Detector Models"]
  node_vos["Video Segmentation<br/>[main.py]"]
  node_train["Detector Training<br/>[train_lfnet.py]"]
  node_weights["Model Weights"]
end

subgraph group_results["Results and Evaluation"]
  node_output["Pose Results"]
  node_nocs_eval["NOCS Evaluation<br/>[eval_nocs.py]"]
  node_ycb_eval["YCB Evaluation<br/>[eval_ycbineoat.py]"]
  node_evaltools["Evaluation Tools<br/>[eval_tools.py]"]
end

node_user(("User"))

node_user -->|"runs sequence"| node_nocs_run
node_user -->|"runs sequence"| node_ycb_run
node_nocs_run -->|"reads frames"| node_rgbd
node_ycb_run -->|"reads frames"| node_rgbd
node_nocs_run -->|"loads masks"| node_masks
node_ycb_run -->|"loads masks"| node_masks
node_rgbd -->|"provides frames"| node_loader
node_masks -->|"provides masks"| node_loader
node_loader -->|"creates frames"| node_frame
node_frame -->|"supplies RGB-D"| node_features
node_features -->|"provides matches"| node_bundler
node_bundler -->|"writes poses"| node_output
node_features -->|"requests features"| node_lfnet
node_lfnet -->|"sends image"| node_lfserver
node_lfserver -->|"runs inference"| node_detector
node_detector -->|"uses model"| node_detmodel
node_train -->|"trains model"| node_detmodel
node_train -->|"saves weights"| node_weights
node_weights -->|"initializes"| node_detmodel
node_user -.->|"runs segmentation"| node_vos
node_output -->|"evaluates poses"| node_nocs_eval
node_output -->|"evaluates poses"| node_ycb_eval
node_nocs_eval -->|"uses metrics"| node_evaltools
node_ycb_eval -->|"uses metrics"| node_evaltools

click node_nocs_run "https://github.com/wenbowen123/bundletrack/blob/master/scripts/run_nocs.py"
click node_ycb_run "https://github.com/wenbowen123/bundletrack/blob/master/scripts/run_ycbineoat.py"
click node_frame "https://github.com/wenbowen123/bundletrack/blob/master/src/Frame.cpp"
click node_loader "https://github.com/wenbowen123/bundletrack/blob/master/src/DataLoader.cpp"
click node_features "https://github.com/wenbowen123/bundletrack/blob/master/src/FeatureManager.cpp"
click node_bundler "https://github.com/wenbowen123/bundletrack/blob/master/src/Bundler.cpp"
click node_lfnet "https://github.com/wenbowen123/bundletrack/blob/master/src/FeatureManager.cpp"
click node_lfserver "https://github.com/wenbowen123/bundletrack/blob/master/lf-net-release/run_server.py"
click node_detector "https://github.com/wenbowen123/bundletrack/blob/master/lf-net-release/inference.py"
click node_detmodel "https://github.com/wenbowen123/bundletrack/tree/master/lf-net-release/models"
click node_vos "https://github.com/wenbowen123/bundletrack/blob/master/transductive-vos.pytorch/main.py"
click node_train "https://github.com/wenbowen123/bundletrack/blob/master/lf-net-release/train_lfnet.py"
click node_nocs_eval "https://github.com/wenbowen123/bundletrack/blob/master/scripts/eval_nocs.py"
click node_ycb_eval "https://github.com/wenbowen123/bundletrack/blob/master/scripts/eval_ycbineoat.py"
click node_evaltools "https://github.com/wenbowen123/bundletrack/blob/master/lf-net-release/eval_tools.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_nocs_run,node_ycb_run,node_rgbd,node_masks,node_user toneBlue
class node_frame,node_loader,node_features,node_bundler toneAmber
class node_lfnet,node_lfserver,node_detector,node_detmodel,node_vos,node_train,node_weights toneMint
class node_output,node_nocs_eval,node_ycb_eval,node_evaltools toneRose
```

## Components

### Sequence Inputs

- [NOCS Runner](https://github.com/wenbowen123/bundletrack/blob/master/scripts/run_nocs.py): `scripts/run_nocs.py`
- [YCB Runner](https://github.com/wenbowen123/bundletrack/blob/master/scripts/run_ycbineoat.py): `scripts/run_ycbineoat.py`
- **RGB-D Sequence**
- **Segmentation Masks**

### Pose Tracking

- [Frame Data](https://github.com/wenbowen123/bundletrack/blob/master/src/Frame.cpp): `src/Frame.cpp`
- [Sequence Loader](https://github.com/wenbowen123/bundletrack/blob/master/src/DataLoader.cpp): `src/DataLoader.cpp`
- [Feature Matching](https://github.com/wenbowen123/bundletrack/blob/master/src/FeatureManager.cpp): `src/FeatureManager.cpp`
- [Pose Graph](https://github.com/wenbowen123/bundletrack/blob/master/src/Bundler.cpp): `src/Bundler.cpp`

### Learned Perception

- [LFNet Client](https://github.com/wenbowen123/bundletrack/blob/master/src/FeatureManager.cpp): `src/FeatureManager.cpp`
- [LFNet Server](https://github.com/wenbowen123/bundletrack/blob/master/lf-net-release/run_server.py): `lf-net-release/run_server.py`
- [Keypoint Detector](https://github.com/wenbowen123/bundletrack/blob/master/lf-net-release/inference.py): `lf-net-release/inference.py`
- [Detector Models](https://github.com/wenbowen123/bundletrack/tree/master/lf-net-release/models): `lf-net-release/models`
- [Video Segmentation](https://github.com/wenbowen123/bundletrack/blob/master/transductive-vos.pytorch/main.py): `transductive-vos.pytorch/main.py`
- [Detector Training](https://github.com/wenbowen123/bundletrack/blob/master/lf-net-release/train_lfnet.py): `lf-net-release/train_lfnet.py`
- **Model Weights**

### Results and Evaluation

- **Pose Results**
- [NOCS Evaluation](https://github.com/wenbowen123/bundletrack/blob/master/scripts/eval_nocs.py): `scripts/eval_nocs.py`
- [YCB Evaluation](https://github.com/wenbowen123/bundletrack/blob/master/scripts/eval_ycbineoat.py): `scripts/eval_ycbineoat.py`
- [Evaluation Tools](https://github.com/wenbowen123/bundletrack/blob/master/lf-net-release/eval_tools.py): `lf-net-release/eval_tools.py`

### Other components

- **User**

## Connections

- User → NOCS Runner: runs sequence
- User → YCB Runner: runs sequence
- NOCS Runner → RGB-D Sequence: reads frames
- YCB Runner → RGB-D Sequence: reads frames
- NOCS Runner → Segmentation Masks: loads masks
- YCB Runner → Segmentation Masks: loads masks
- RGB-D Sequence → Sequence Loader: provides frames
- Segmentation Masks → Sequence Loader: provides masks
- Sequence Loader → Frame Data: creates frames
- Frame Data → Feature Matching: supplies RGB-D
- Feature Matching → Pose Graph: provides matches
- Pose Graph → Pose Results: writes poses
- Feature Matching → LFNet Client: requests features
- LFNet Client → LFNet Server: sends image
- LFNet Server → Keypoint Detector: runs inference
- Keypoint Detector → Detector Models: uses model
- Detector Training → Detector Models: trains model
- Detector Training → Model Weights: saves weights
- Model Weights → Detector Models: initializes
- User → Video Segmentation: runs segmentation
- Pose Results → NOCS Evaluation: evaluates poses
- Pose Results → YCB Evaluation: evaluates poses
- NOCS Evaluation → Evaluation Tools: uses metrics
- YCB Evaluation → Evaluation Tools: uses metrics