# leoxie080808/ringfusion architecture

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

- Interactive diagram: https://gitdiagram.com/leoxie080808/ringfusion
- Repository: https://github.com/leoxie080808/ringfusion

## Overview

RingFusion turns a rectified wide-angle camera image and sparse TMF8829 ranges into metric depth, uncertainty, and a point cloud. The live workflow is sensor acquisition, ToF-to-camera projection, disparity anchoring and closed-form scale fitting, then optional learned refinement and ROS output. Firmware streams ToF frames; ROS bringup starts the camera, ToF driver, and perception node. Training and model export form an offline branch. The graph follows README capabilities and sampled pipeline/launch code; wiring for unsampled ROS internals is shown only where documented by launch or README.

Main entry points: [`ros2_ws/src/ringfusion_perception/ringfusion_perception/perception_node.py`](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/perception_node.py) (Perception node), [`ros2_ws/src/ringfusion_perception/ringfusion_perception/pipeline.py`](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/pipeline.py) (Fusion pipeline), [`ros2_ws/src/ringfusion_drivers/ringfusion_drivers/tof_driver_node.py`](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_drivers/ringfusion_drivers/tof_driver_node.py) (ToF driver), [`ros2_ws/src/ringfusion_bringup/launch/single_module.launch.py`](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_bringup/launch/single_module.launch.py) (ROS bringup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensing["Sensor acquisition"]
  node_firmware["ESP32 firmware<br/>[main.c]"]
  node_tof_library["TMF8829 driver<br/>[tmf8829.c]"]
  node_camera_node["Camera driver<br/>[camera_node.py]"]
  node_tof_node["ToF driver<br/>[tof_driver_node.py]"]
  node_tof_source["ToF stream parser<br/>[tof_source.py]"]
end

subgraph group_perception["ROS perception"]
  node_bringup["ROS bringup"]
  node_rectify["Image rectification<br/>[rectify.py]"]
  node_perception_node["Perception node<br/>[perception_node.py]"]
  node_pipeline["Fusion pipeline<br/>[pipeline.py]"]
  node_geometry["ToF projection<br/>[geometry.py]"]
  node_anchoring["Affine anchoring<br/>[anchoring.py]"]
  node_blend["Depth blend<br/>[blend.py]"]
  node_roi["ROI plane mask<br/>[roi.py]"]
  node_cloud["Cloud conversion<br/>[cloud_util.py]"]
end

subgraph group_models["Depth models"]
  node_backbone["Disparity backbone<br/>[backbone.py]"]
  node_residual["Residual refiner<br/>[residual.py]"]
  node_engine["TensorRT runtime<br/>[trt_util.py]"]
end

subgraph group_offline["Training and export"]
  node_training["Model training"]
  node_student_model["Student network<br/>[student.py]"]
  node_export["ONNX export<br/>[export_onnx.py]"]
  node_calibration["Camera calibration"]
end

node_camera_actor(("Wide camera"))
node_tof_actor(("TMF8829 sensor"))
node_consumer(("ROS consumers"))

node_tof_actor -->|"ranges sensor"| node_tof_library
node_firmware -->|"calls driver"| node_tof_library
node_firmware -->|"streams frames"| node_tof_node
node_tof_node -->|"reads serial"| node_tof_source
node_camera_actor -->|"captures images"| node_camera_node
node_bringup -->|"launches"| node_camera_node
node_bringup -->|"launches"| node_tof_node
node_bringup -->|"launches"| node_perception_node
node_camera_node -->|"publishes images"| node_perception_node
node_tof_node -->|"publishes ranges"| node_perception_node
node_perception_node -->|"rectifies input"| node_rectify
node_perception_node -->|"runs frame"| node_pipeline
node_pipeline -->|"infers disparity"| node_backbone
node_pipeline -->|"projects zones"| node_geometry
node_pipeline -->|"fits scale"| node_anchoring
node_pipeline -->|"blends depth"| node_blend
node_pipeline -->|"masks regions"| node_roi
node_pipeline -->|"refines depth"| node_residual
node_perception_node -->|"builds cloud"| node_cloud
node_perception_node -->|"publishes depth cloud"| node_consumer
node_training -->|"trains network"| node_student_model
node_student_model -->|"exports weights"| node_export
node_export -->|"creates ONNX"| node_engine
node_engine -->|"runs inference"| node_backbone
node_engine -->|"runs inference"| node_residual
node_calibration -.->|"supplies calibration"| node_perception_node

click node_firmware "https://github.com/leoxie080808/ringfusion/blob/main/firmware-esp/main/main.c"
click node_tof_library "https://github.com/leoxie080808/ringfusion/blob/main/firmware-esp/components/tmf8829/tmf8829.c"
click node_bringup "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_bringup/launch/single_module.launch.py"
click node_camera_node "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_drivers/ringfusion_drivers/camera_node.py"
click node_tof_node "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_drivers/ringfusion_drivers/tof_driver_node.py"
click node_tof_source "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_drivers/ringfusion_drivers/tof_source.py"
click node_rectify "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/rectify.py"
click node_perception_node "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/perception_node.py"
click node_pipeline "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/pipeline.py"
click node_geometry "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/geometry.py"
click node_anchoring "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/anchoring.py"
click node_blend "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/blend.py"
click node_roi "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/roi.py"
click node_cloud "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/cloud_util.py"
click node_backbone "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/backbone.py"
click node_residual "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/residual.py"
click node_training "https://github.com/leoxie080808/ringfusion/tree/main/training"
click node_student_model "https://github.com/leoxie080808/ringfusion/blob/main/training/models/student.py"
click node_export "https://github.com/leoxie080808/ringfusion/blob/main/tools/export_onnx.py"
click node_engine "https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/trt_util.py"
click node_calibration "https://github.com/leoxie080808/ringfusion/blob/main/tools/calibrate_camera.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_firmware,node_tof_library,node_camera_node,node_tof_node,node_tof_source toneBlue
class node_bringup,node_rectify,node_perception_node,node_pipeline,node_geometry,node_anchoring,node_blend,node_roi,node_cloud toneAmber
class node_backbone,node_residual,node_engine toneMint
class node_training,node_student_model,node_export,node_calibration toneRose
class node_camera_actor,node_tof_actor,node_consumer toneIndigo
```

## Components

### Sensor acquisition

- [ESP32 firmware](https://github.com/leoxie080808/ringfusion/blob/main/firmware-esp/main/main.c): `firmware-esp/main/main.c`
- [TMF8829 driver](https://github.com/leoxie080808/ringfusion/blob/main/firmware-esp/components/tmf8829/tmf8829.c): `firmware-esp/components/tmf8829/tmf8829.c`
- [Camera driver](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_drivers/ringfusion_drivers/camera_node.py): `ros2_ws/src/ringfusion_drivers/ringfusion_drivers/camera_node.py`
- [ToF driver](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_drivers/ringfusion_drivers/tof_driver_node.py): `ros2_ws/src/ringfusion_drivers/ringfusion_drivers/tof_driver_node.py`
- [ToF stream parser](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_drivers/ringfusion_drivers/tof_source.py): `ros2_ws/src/ringfusion_drivers/ringfusion_drivers/tof_source.py`

### ROS perception

- [ROS bringup](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_bringup/launch/single_module.launch.py): `ros2_ws/src/ringfusion_bringup/launch/single_module.launch.py`
- [Image rectification](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/rectify.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/rectify.py`
- [Perception node](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/perception_node.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/perception_node.py`
- [Fusion pipeline](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/pipeline.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/pipeline.py`
- [ToF projection](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/geometry.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/geometry.py`
- [Affine anchoring](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/anchoring.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/anchoring.py`
- [Depth blend](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/blend.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/blend.py`
- [ROI plane mask](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/roi.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/roi.py`
- [Cloud conversion](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/cloud_util.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/cloud_util.py`

### Depth models

- [Disparity backbone](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/backbone.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/backbone.py`
- [Residual refiner](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/residual.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/residual.py`
- [TensorRT runtime](https://github.com/leoxie080808/ringfusion/blob/main/ros2_ws/src/ringfusion_perception/ringfusion_perception/trt_util.py): `ros2_ws/src/ringfusion_perception/ringfusion_perception/trt_util.py`

### Training and export

- [Model training](https://github.com/leoxie080808/ringfusion/tree/main/training): `training`
- [Student network](https://github.com/leoxie080808/ringfusion/blob/main/training/models/student.py): `training/models/student.py`
- [ONNX export](https://github.com/leoxie080808/ringfusion/blob/main/tools/export_onnx.py): `tools/export_onnx.py`
- [Camera calibration](https://github.com/leoxie080808/ringfusion/blob/main/tools/calibrate_camera.py): `tools/calibrate_camera.py`

### Other components

- **Wide camera**
- **TMF8829 sensor**
- **ROS consumers**

## Connections

- TMF8829 sensor → TMF8829 driver: ranges sensor
- ESP32 firmware → TMF8829 driver: calls driver
- ESP32 firmware → ToF driver: streams frames
- ToF driver → ToF stream parser: reads serial
- Wide camera → Camera driver: captures images
- ROS bringup → Camera driver: launches
- ROS bringup → ToF driver: launches
- ROS bringup → Perception node: launches
- Camera driver → Perception node: publishes images
- ToF driver → Perception node: publishes ranges
- Perception node → Image rectification: rectifies input
- Perception node → Fusion pipeline: runs frame
- Fusion pipeline → Disparity backbone: infers disparity
- Fusion pipeline → ToF projection: projects zones
- Fusion pipeline → Affine anchoring: fits scale
- Fusion pipeline → Depth blend: blends depth
- Fusion pipeline → ROI plane mask: masks regions
- Fusion pipeline → Residual refiner: refines depth
- Perception node → Cloud conversion: builds cloud
- Perception node → ROS consumers: publishes depth cloud
- Model training → Student network: trains network
- Student network → ONNX export: exports weights
- ONNX export → TensorRT runtime: creates ONNX
- TensorRT runtime → Disparity backbone: runs inference
- TensorRT runtime → Residual refiner: runs inference
- Camera calibration → Perception node: supplies calibration