# sdmuhsin/dlo-segmentation architecture

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

- Interactive diagram: https://gitdiagram.com/sdmuhsin/dlo-segmentation
- Repository: https://github.com/sdmuhsin/dlo-segmentation

## Overview

This repository is a deformable-linear-object (DLO) semantic-segmentation research pipeline: it renders labelled RGB-D imagery, prepares three-class training data, trains segmentation models, and evaluates their predictions. Its documented reproduction flow runs from assets through rendering, staging and label re-encoding to training and evaluation. Separate branches cover real-photo dataset adaptation and video-data generation. The graph uses README statements and the SOURCE INDEX for relationships; many implementation details—especially rendering and inference variants—were not sampled, so those links are omitted or marked unverified.

Main entry points: [`src/dformer/models/builder.py`](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/models/builder.py) (Model builder), [`src/train_dformer_v2_dlo.py`](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/train_dformer_v2_dlo.py) (DFormer training), [`src/reencode_labels_3way.py`](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/reencode_labels_3way.py) (Three-class labels), [`src/build_p44_connpaste_dataset.py`](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/build_p44_connpaste_dataset.py) (Composite dataset assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_renderer["Synthetic renderer"]
  node_video_data["Video dataset conversion"]
  node_pcl_rgbd["Point-cloud RGB-D<br/>[pcl_to_rgbd.py]"]
  node_texture["Texture mapping<br/>[texture_mapping.py]"]
  node_stage["Dataset staging"]
  node_labels["Three-class labels"]
end

subgraph group_models["Models and training"]
  node_rgbd_train["RGB-D training<br/>[train_rgbd_seg.py]"]
  node_rgb_train["RGB training"]
  node_dformer_train["DFormer training"]
  node_train_runtime["Training runtime<br/>[train.py]"]
  node_model_builder["Model builder<br/>[builder.py]"]
  node_dformer_encoder["DFormer encoder<br/>[DFormer.py]"]
  node_dformerv2_encoder["DFormer v2 encoder<br/>[DFormerv2.py]"]
  node_decoder["Segmentation decoders<br/>[nl_head.py]"]
end

subgraph group_evaluation["Evaluation and inference"]
  node_evaluator["Three-way evaluation<br/>[eval_3way_final.py]"]
  node_inference["Segmentation inference<br/>[inference.py]"]
end

subgraph group_adaptation["Real-world adaptation"]
  node_real_dataset["Electric Wires dataset"]
  node_composites["Photo composites"]
  node_composite_dataset["Composite dataset assembly"]
  node_composite_validation["Composite validation"]
end

node_engineer(("Researcher"))
node_assets[("Input assets")]
node_camera(("Camera footage"))

node_engineer -->|"fetches"| node_assets
node_assets -->|"supplies inputs"| node_renderer
node_engineer -->|"runs"| node_renderer
node_renderer -->|"renders RGB-D labels"| node_stage
node_stage -->|"stages for training"| node_labels
node_labels -->|"provides dataset"| node_rgbd_train
node_engineer -->|"trains model"| node_rgbd_train
node_engineer -->|"evaluates checkpoint"| node_evaluator
node_labels -->|"provides evaluation data"| node_evaluator
node_dformer_train -->|"imports"| node_model_builder
node_dformer_train -->|"imports"| node_rgbd_train
node_dformer_train -->|"imports"| node_rgb_train
node_rgb_train -->|"imports"| node_real_dataset
node_video_data -->|"imports"| node_pcl_rgbd
node_video_data -->|"imports"| node_texture
node_composites -->|"builds paste set"| node_composite_dataset
node_composite_dataset -->|"validated by"| node_composite_validation
node_composite_dataset -.->|"trains on"| node_rgb_train
node_camera -.->|"supplies footage"| node_evaluator
node_inference -.->|"predicts on"| node_camera
node_train_runtime -->|"builds model"| node_model_builder
node_model_builder -->|"selects encoder"| node_dformer_encoder
node_model_builder -->|"selects encoder"| node_dformerv2_encoder
node_model_builder -->|"selects decoder"| node_decoder

click node_renderer "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/render_full_dataset.py"
click node_video_data "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/convert_to_video_dataset.py"
click node_pcl_rgbd "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/pcl_to_rgbd.py"
click node_texture "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/texture_mapping.py"
click node_stage "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/prepare_dformer_data.py"
click node_labels "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/reencode_labels_3way.py"
click node_rgbd_train "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/train_rgbd_seg.py"
click node_rgb_train "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/train_rgb_only_sota.py"
click node_dformer_train "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/train_dformer_v2_dlo.py"
click node_train_runtime "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/utils/train.py"
click node_model_builder "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/models/builder.py"
click node_dformer_encoder "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/models/encoders/DFormer.py"
click node_dformerv2_encoder "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/models/encoders/DFormerv2.py"
click node_decoder "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/models/decoders/nl_head.py"
click node_real_dataset "https://github.com/sdmuhsin/dlo-segmentation/blob/main/dataset_generation/realworld_dataset.py"
click node_composites "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/composite_connector_positives.py"
click node_composite_dataset "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/build_p44_connpaste_dataset.py"
click node_composite_validation "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/validate_p44_composites.py"
click node_evaluator "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/eval_3way_final.py"
click node_inference "https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/mmseg/apis/inference.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_renderer,node_video_data,node_pcl_rgbd,node_texture,node_stage,node_labels toneBlue
class node_rgbd_train,node_rgb_train,node_dformer_train,node_train_runtime,node_model_builder,node_dformer_encoder,node_dformerv2_encoder,node_decoder,node_assets toneAmber
class node_evaluator,node_inference toneMint
class node_real_dataset,node_composites,node_composite_dataset,node_composite_validation toneRose
class node_engineer,node_camera toneIndigo
```

## Components

### Data preparation

- [Synthetic renderer](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/render_full_dataset.py): `src/render_full_dataset.py`
- [Video dataset conversion](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/convert_to_video_dataset.py): `src/convert_to_video_dataset.py`
- [Point-cloud RGB-D](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/pcl_to_rgbd.py): `src/pcl_to_rgbd.py`
- [Texture mapping](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/texture_mapping.py): `src/texture_mapping.py`
- [Dataset staging](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/prepare_dformer_data.py): `src/prepare_dformer_data.py`
- [Three-class labels](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/reencode_labels_3way.py): `src/reencode_labels_3way.py`

### Models and training

- [RGB-D training](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/train_rgbd_seg.py): `src/train_rgbd_seg.py`
- [RGB training](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/train_rgb_only_sota.py): `src/train_rgb_only_sota.py`
- [DFormer training](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/train_dformer_v2_dlo.py): `src/train_dformer_v2_dlo.py`
- [Training runtime](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/utils/train.py): `src/dformer/utils/train.py`
- [Model builder](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/models/builder.py): `src/dformer/models/builder.py`
- [DFormer encoder](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/models/encoders/DFormer.py): `src/dformer/models/encoders/DFormer.py`
- [DFormer v2 encoder](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/models/encoders/DFormerv2.py): `src/dformer/models/encoders/DFormerv2.py`
- [Segmentation decoders](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/models/decoders/nl_head.py): `src/dformer/models/decoders/nl_head.py`

### Evaluation and inference

- [Three-way evaluation](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/eval_3way_final.py): `src/eval_3way_final.py`
- [Segmentation inference](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/dformer/mmseg/apis/inference.py): `src/dformer/mmseg/apis/inference.py`

### Real-world adaptation

- [Electric Wires dataset](https://github.com/sdmuhsin/dlo-segmentation/blob/main/dataset_generation/realworld_dataset.py): `dataset_generation/realworld_dataset.py`
- [Photo composites](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/composite_connector_positives.py): `src/composite_connector_positives.py`
- [Composite dataset assembly](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/build_p44_connpaste_dataset.py): `src/build_p44_connpaste_dataset.py`
- [Composite validation](https://github.com/sdmuhsin/dlo-segmentation/blob/main/src/validate_p44_composites.py): `src/validate_p44_composites.py`

### Other components

- **Researcher**
- **Input assets**
- **Camera footage**

## Connections

- Researcher → Input assets: fetches (evidence: `README.md`)
- Input assets → Synthetic renderer: supplies inputs (evidence: `README.md`)
- Researcher → Synthetic renderer: runs (evidence: `README.md`)
- Synthetic renderer → Dataset staging: renders RGB-D labels (evidence: `README.md`)
- Dataset staging → Three-class labels: stages for training (evidence: `README.md`)
- Three-class labels → RGB-D training: provides dataset (evidence: `README.md`)
- Researcher → RGB-D training: trains model (evidence: `README.md`)
- Researcher → Three-way evaluation: evaluates checkpoint (evidence: `README.md`)
- Three-class labels → Three-way evaluation: provides evaluation data (evidence: `README.md`)
- DFormer training → Model builder: imports (evidence: `src/train_dformer_v2_dlo.py`)
- DFormer training → RGB-D training: imports (evidence: `src/train_dformer_v2_dlo.py`)
- DFormer training → RGB training: imports (evidence: `src/train_dformer_v2_dlo.py`)
- RGB training → Electric Wires dataset: imports (evidence: `src/train_rgb_only_sota.py`)
- Video dataset conversion → Point-cloud RGB-D: imports (evidence: `src/convert_to_video_dataset.py`)
- Video dataset conversion → Texture mapping: imports (evidence: `src/convert_to_video_dataset.py`)
- Photo composites → Composite dataset assembly: builds paste set (evidence: `README.md`)
- Composite dataset assembly → Composite validation: validated by (evidence: `README.md`)
- Composite dataset assembly → RGB training: trains on
- Camera footage → Three-way evaluation: supplies footage
- Segmentation inference → Camera footage: predicts on
- Training runtime → Model builder: builds model (evidence: `src/dformer/utils/train.py`)
- Model builder → DFormer encoder: selects encoder (evidence: `src/dformer/models/builder.py`)
- Model builder → DFormer v2 encoder: selects encoder (evidence: `src/dformer/models/builder.py`)
- Model builder → Segmentation decoders: selects decoder (evidence: `src/dformer/models/builder.py`)
