# ananyapselvam/mdc-net-steel-defect-captioning architecture

> Architecture diagram of the GitHub repository ananyapselvam/mdc-net-steel-defect-captioning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ananyapselvam/mdc-net-steel-defect-captioning
- Repository: https://github.com/ananyapselvam/mdc-net-steel-defect-captioning

## Overview

MDC-Net is a steel-surface defect captioning project. Its implemented workflow parses NEU-DET XML annotations into captions and image metadata, splits records by image, loads and augments samples into batches, then trains and validates an image encoder–caption decoder. The README also describes evaluation and caption generation, but the sampled runtime code shows validation loss rather than a separate evaluation or inference-generation implementation; those documented stages are therefore marked as unverified. The graph follows visible calls and README statements; unsampled modules are not assumed to connect.

Main entry points: [`src/dataloader.py`](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/dataloader.py) (Batch assembly), [`src/model.py`](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/model.py) (MDC-Net), [`src/train.py`](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/train.py) (Training and validation), [`src/trainepoch.py`](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/trainepoch.py) (Epoch training variant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_prep["Data preparation"]
  node_annotation_parser["XML caption preprocessing<br/>[preprocess_neu.py]"]
  node_annotation_csv["Annotation records"]
  node_image_split["Image-level split<br/>[split_data.py]"]
  node_split_csvs["Train/val/test records"]
end

subgraph group_input_pipeline["Input pipeline"]
  node_augmentation["Image transforms<br/>[augmentation.py]"]
  node_vocabulary["Caption vocabulary<br/>[vocabulary.py]"]
  node_dataset["NEU dataset<br/>[dataset.py]"]
  node_dataloader["Batch assembly<br/>[dataloader.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_caption_model["Caption model"]
  node_model["MDC-Net<br/>[model.py]"]
  node_encoder["Image encoder<br/>[model.py]"]
  node_decoder["Caption decoder<br/>[model.py]"]
  node_caption_generation["Defect caption generation"]
end

subgraph group_learning["Training and evaluation"]
  node_trainer["Training and validation<br/>[train.py]"]
  node_epoch_trainer["Epoch training variant<br/>[trainepoch.py]"]
  node_checkpoint["Model checkpoint"]
end

node_dataset_source[("NEU-DET data")]
node_timm["timm model library"]

node_dataset_source -->|"provides XML/images"| node_annotation_parser
node_annotation_parser -->|"writes records"| node_annotation_csv
node_annotation_csv -->|"supplies annotations"| node_image_split
node_image_split -->|"writes splits"| node_split_csvs
node_dataloader -->|"reads train/val"| node_split_csvs
node_dataset -->|"applies transforms"| node_augmentation
node_dataset -->|"numericalizes captions"| node_vocabulary
node_dataset -->|"uses settings"| node_config
node_dataloader -->|"creates datasets"| node_dataset
node_dataloader -->|"builds vocabulary"| node_vocabulary
node_dataloader -->|"sets batch options"| node_config
node_trainer -->|"loads batches"| node_dataloader
node_trainer -->|"trains and validates"| node_model
node_trainer -->|"uses settings"| node_config
node_epoch_trainer -->|"loads batches"| node_dataloader
node_epoch_trainer -->|"trains and validates"| node_model
node_epoch_trainer -->|"uses settings"| node_config
node_model -->|"runs encoder"| node_encoder
node_model -->|"runs decoder"| node_decoder
node_encoder -->|"creates backbone"| node_timm
node_trainer -->|"saves best weights"| node_checkpoint
node_epoch_trainer -->|"saves weights"| node_checkpoint
node_model -.->|"supports captioning"| node_caption_generation

click node_annotation_parser "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/preprocess_neu.py"
click node_image_split "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/split_data.py"
click node_augmentation "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/augmentation.py"
click node_vocabulary "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/vocabulary.py"
click node_dataset "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/dataset.py"
click node_dataloader "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/dataloader.py"
click node_config "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/config.py"
click node_trainer "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/train.py"
click node_epoch_trainer "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/trainepoch.py"
click node_model "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/model.py"
click node_encoder "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/model.py"
click node_decoder "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/model.py"
click node_caption_generation "https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/tree/master/src"

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_annotation_parser,node_annotation_csv,node_image_split,node_split_csvs toneBlue
class node_augmentation,node_vocabulary,node_dataset,node_dataloader,node_config,node_dataset_source toneAmber
class node_model,node_encoder,node_decoder,node_caption_generation toneMint
class node_trainer,node_epoch_trainer,node_checkpoint toneRose
class node_timm toneIndigo
```

## Components

### Data preparation

- [XML caption preprocessing](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/preprocess_neu.py): `src/preprocess_neu.py`
- **Annotation records**
- [Image-level split](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/split_data.py): `src/split_data.py`
- **Train/val/test records**

### Input pipeline

- [Image transforms](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/augmentation.py): `src/augmentation.py`
- [Caption vocabulary](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/vocabulary.py): `src/vocabulary.py`
- [NEU dataset](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/dataset.py): `src/dataset.py`
- [Batch assembly](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/dataloader.py): `src/dataloader.py`
- [Runtime settings](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/config.py): `src/config.py`

### Caption model

- [MDC-Net](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/model.py): `src/model.py`
- [Image encoder](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/model.py): `src/model.py`
- [Caption decoder](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/model.py): `src/model.py`
- [Defect caption generation](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/tree/master/src): `src`

### Training and evaluation

- [Training and validation](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/train.py): `src/train.py`
- [Epoch training variant](https://github.com/ananyapselvam/mdc-net-steel-defect-captioning/blob/master/src/trainepoch.py): `src/trainepoch.py`
- **Model checkpoint**

### Other components

- **NEU-DET data**
- **timm model library**

## Connections

- NEU-DET data → XML caption preprocessing: provides XML/images (evidence: `src/preprocess_neu.py`)
- XML caption preprocessing → Annotation records: writes records (evidence: `src/preprocess_neu.py`)
- Annotation records → Image-level split: supplies annotations (evidence: `src/split_data.py`)
- Image-level split → Train/val/test records: writes splits (evidence: `src/split_data.py`)
- Batch assembly → Train/val/test records: reads train/val (evidence: `src/dataloader.py`)
- NEU dataset → Image transforms: applies transforms (evidence: `src/dataset.py`)
- NEU dataset → Caption vocabulary: numericalizes captions (evidence: `src/dataset.py`)
- NEU dataset → Runtime settings: uses settings (evidence: `src/dataset.py`)
- Batch assembly → NEU dataset: creates datasets (evidence: `src/dataloader.py`)
- Batch assembly → Caption vocabulary: builds vocabulary (evidence: `src/dataloader.py`)
- Batch assembly → Runtime settings: sets batch options (evidence: `src/dataloader.py`)
- Training and validation → Batch assembly: loads batches (evidence: `src/train.py`)
- Training and validation → MDC-Net: trains and validates (evidence: `src/train.py`)
- Training and validation → Runtime settings: uses settings (evidence: `src/train.py`)
- Epoch training variant → Batch assembly: loads batches (evidence: `src/trainepoch.py`)
- Epoch training variant → MDC-Net: trains and validates (evidence: `src/trainepoch.py`)
- Epoch training variant → Runtime settings: uses settings (evidence: `src/trainepoch.py`)
- MDC-Net → Image encoder: runs encoder (evidence: `src/model.py`)
- MDC-Net → Caption decoder: runs decoder (evidence: `src/model.py`)
- Image encoder → timm model library: creates backbone (evidence: `src/model.py`)
- Training and validation → Model checkpoint: saves best weights (evidence: `src/train.py`)
- Epoch training variant → Model checkpoint: saves weights (evidence: `src/trainepoch.py`)
- MDC-Net → Defect caption generation: supports captioning (evidence: `README.md`)
