# hku-mars/m-detector architecture

> Architecture diagram of the GitHub repository hku-mars/m-detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hku-mars/m-detector
- Repository: https://github.com/hku-mars/m-detector

## Overview

M-detector is a ROS LiDAR moving-point detection package. Its principal workflow consumes point clouds and odometry, applies occlusion/depth-map tests to classify points, and publishes point- and frame-oriented results. Separate tools cluster dynamic points, visualize saved predictions, and calculate IoU/recall against dataset labels. The README documents the launch-level workflow; source excerpts show filtering and publishing details, but do not establish all connections among the filter, clustering, and evaluation executables.

Main entry points: [`src/DynObjFilter.cpp`](https://github.com/hku-mars/m-detector/blob/main/src/DynObjFilter.cpp) (Occlusion filter), [`src/DynObjCluster.cpp`](https://github.com/hku-mars/m-detector/blob/main/src/DynObjCluster.cpp) (Dynamic clustering), [`src/cal_recall_multi.cpp`](https://github.com/hku-mars/m-detector/blob/main/src/cal_recall_multi.cpp) (Recall and IoU), [`src/display_prediction.cpp`](https://github.com/hku-mars/m-detector/blob/main/src/display_prediction.cpp) (Prediction viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Online detection"]
  node_filter["Occlusion filter<br/>[DynObjFilter.cpp]"]
  node_filter_state[("Depth-map state<br/>[DynObjFilter.h]")]
  node_detector_output["Detection topics<br/>[DynObjFilter.cpp]"]
  node_dataset_configs["Sensor configurations"]
end

subgraph group_cluster["Object clustering"]
  node_clusterer["Dynamic clustering<br/>[DynObjCluster.cpp]"]
  node_cluster_api["Cluster interface<br/>[DynObjCluster.h]"]
end

subgraph group_tools["Results tools"]
  node_saved_results["Saved predictions"]
  node_labels["Dataset labels"]
  node_recall["Recall and IoU"]
  node_visualizer["Prediction viewer"]
  node_visualization["ROS visualization"]
end

subgraph group_common["Shared algorithms"]
  node_voxel["Voxel clustering<br/>[voxel_cluster.h]"]
  node_dbscan["DBSCAN clustering<br/>[dbscan.h]"]
  node_bbox["Box geometry and IoU<br/>[bbox.h]"]
  node_disk["Disk neighborhood<br/>[EA_disk.h]"]
end

node_ros_inputs(("LiDAR and odometry"))

node_ros_inputs -->|"supplies streams"| node_filter
node_filter -->|"updates maps"| node_filter_state
node_filter -->|"publishes results"| node_detector_output
node_dataset_configs -.->|"configures detection"| node_filter
node_clusterer -->|"uses voxel map"| node_voxel
node_clusterer -->|"includes helper"| node_disk
node_cluster_api -.->|"declares interface"| node_clusterer
node_saved_results -->|"provides predictions"| node_recall
node_labels -->|"provides ground truth"| node_recall
node_saved_results -->|"provides predictions"| node_visualizer
node_ros_inputs -->|"provides point cloud"| node_visualizer
node_visualizer -->|"publishes views"| node_visualization
node_recall -.->|"writes metrics"| node_saved_results

click node_filter "https://github.com/hku-mars/m-detector/blob/main/src/DynObjFilter.cpp"
click node_filter_state "https://github.com/hku-mars/m-detector/blob/main/include/m-detector/DynObjFilter.h"
click node_detector_output "https://github.com/hku-mars/m-detector/blob/main/src/DynObjFilter.cpp"
click node_clusterer "https://github.com/hku-mars/m-detector/blob/main/src/DynObjCluster.cpp"
click node_cluster_api "https://github.com/hku-mars/m-detector/blob/main/include/m-detector/DynObjCluster.h"
click node_voxel "https://github.com/hku-mars/m-detector/blob/main/include/cluster_predict/voxel_cluster.h"
click node_dbscan "https://github.com/hku-mars/m-detector/blob/main/include/cluster_predict/dbscan.h"
click node_bbox "https://github.com/hku-mars/m-detector/blob/main/include/cluster_predict/bbox.h"
click node_disk "https://github.com/hku-mars/m-detector/blob/main/include/cluster_predict/EA_disk.h"
click node_recall "https://github.com/hku-mars/m-detector/blob/main/src/cal_recall_multi.cpp"
click node_visualizer "https://github.com/hku-mars/m-detector/blob/main/src/display_prediction.cpp"
click node_visualization "https://github.com/hku-mars/m-detector/blob/main/src/display_prediction.cpp"
click node_dataset_configs "https://github.com/hku-mars/m-detector/tree/main/config"

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_filter,node_filter_state,node_detector_output,node_dataset_configs toneBlue
class node_clusterer,node_cluster_api toneAmber
class node_saved_results,node_labels,node_recall,node_visualizer,node_visualization toneMint
class node_voxel,node_dbscan,node_bbox,node_disk toneRose
class node_ros_inputs toneIndigo
```

## Components

### Online detection

- [Occlusion filter](https://github.com/hku-mars/m-detector/blob/main/src/DynObjFilter.cpp): `src/DynObjFilter.cpp`
- [Depth-map state](https://github.com/hku-mars/m-detector/blob/main/include/m-detector/DynObjFilter.h): `include/m-detector/DynObjFilter.h`
- [Detection topics](https://github.com/hku-mars/m-detector/blob/main/src/DynObjFilter.cpp): `src/DynObjFilter.cpp`
- [Sensor configurations](https://github.com/hku-mars/m-detector/tree/main/config): `config`

### Object clustering

- [Dynamic clustering](https://github.com/hku-mars/m-detector/blob/main/src/DynObjCluster.cpp): `src/DynObjCluster.cpp`
- [Cluster interface](https://github.com/hku-mars/m-detector/blob/main/include/m-detector/DynObjCluster.h): `include/m-detector/DynObjCluster.h`

### Results tools

- **Saved predictions**
- **Dataset labels**
- [Recall and IoU](https://github.com/hku-mars/m-detector/blob/main/src/cal_recall_multi.cpp): `src/cal_recall_multi.cpp`
- [Prediction viewer](https://github.com/hku-mars/m-detector/blob/main/src/display_prediction.cpp): `src/display_prediction.cpp`
- [ROS visualization](https://github.com/hku-mars/m-detector/blob/main/src/display_prediction.cpp): `src/display_prediction.cpp`

### Shared algorithms

- [Voxel clustering](https://github.com/hku-mars/m-detector/blob/main/include/cluster_predict/voxel_cluster.h): `include/cluster_predict/voxel_cluster.h`
- [DBSCAN clustering](https://github.com/hku-mars/m-detector/blob/main/include/cluster_predict/dbscan.h): `include/cluster_predict/dbscan.h`
- [Box geometry and IoU](https://github.com/hku-mars/m-detector/blob/main/include/cluster_predict/bbox.h): `include/cluster_predict/bbox.h`
- [Disk neighborhood](https://github.com/hku-mars/m-detector/blob/main/include/cluster_predict/EA_disk.h): `include/cluster_predict/EA_disk.h`

### Other components

- **LiDAR and odometry**

## Connections

- LiDAR and odometry → Occlusion filter: supplies streams (evidence: `README.md`)
- Occlusion filter → Depth-map state: updates maps (evidence: `src/DynObjFilter.cpp`)
- Occlusion filter → Detection topics: publishes results (evidence: `src/DynObjFilter.cpp`)
- Sensor configurations → Occlusion filter: configures detection
- Dynamic clustering → Voxel clustering: uses voxel map (evidence: `src/DynObjCluster.cpp`)
- Dynamic clustering → Disk neighborhood: includes helper (evidence: `src/DynObjCluster.cpp`)
- Cluster interface → Dynamic clustering: declares interface
- Saved predictions → Recall and IoU: provides predictions (evidence: `src/cal_recall_multi.cpp`)
- Dataset labels → Recall and IoU: provides ground truth (evidence: `src/cal_recall_multi.cpp`)
- Saved predictions → Prediction viewer: provides predictions (evidence: `src/display_prediction.cpp`)
- LiDAR and odometry → Prediction viewer: provides point cloud (evidence: `src/display_prediction.cpp`)
- Prediction viewer → ROS visualization: publishes views (evidence: `src/display_prediction.cpp`)
- Recall and IoU → Saved predictions: writes metrics
