# tuttc/riva-track-a architecture

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

- Interactive diagram: https://gitdiagram.com/tuttc/riva-track-a
- Repository: https://github.com/tuttc/riva-track-a

## Overview

1. **Repository purpose**
   - This repo is organized around a cervical cytology detection challenge dataset under `data/riva-cervical-cytology-challenge-isbi-2026`.
   - It contains two largely separate model pipelines for the same task:
     - `frcnn_paper/`: a Faster R-CNN reproduction aligned to the paper’s method.
     - `swin_large/`: an alternative Swin-Large-based pipeline, likely built on the OpenMMLab ecosystem.

2. **Shared data boundary**
   - Both pipelines appear to consume the same competition dataset layout:
     - `images/images/train`, `val`, `test`
     - `annotations/annotations/train.csv`, `val.csv`, `sample_submission.csv`
   - This is the main boundary between raw dataset assets and the model code: CSV annotations plus image folders feed the training and inference stages.

3. **Faster R-CNN pipeline (`frcnn_paper/`)**
   - This is the more explicit end-to-end implementation and is described in the top-level README.
   - Main modules:
     - `config.py`: paths, hyperparameters, and paper-specific settings.
     - `dataset.py`: image/box loading, box augmentation, image preprocessing.
     - `model.py`: builds the detector and any helper utilities.
     - `train.py`: training loop.
     - `inference.py`: prediction generation and submission formatting.
     - `run.py`: orchestrates full pipeline execution.

4. **Faster R-CNN model architecture**
   - The README indicates the core model is **ResNet-50 + FPN** with a **Fast R-CNN head**.
   - It is configured for **8 classes**, input size **1200×1200**, and SGD optimization.
   - The paper-specific comparison losses are reflected in the README’s hyperparameters:
     - temperature `τ`
     - memory bank queue `Q`
     - RoI/class comparison weights `λ_roi`, `λ_cls`
     - RoI batch size `K`

5. **Faster R-CNN data processing**
   - `dataset.py` is not just a loader; it also applies augmentation at two levels:
     - **Box augmentation**: generates synthetic positive boxes around ground truth.
     - **Image augmentation**: flips and color jitter.
   - This means the training data pipeline expands annotations before batching, which is an important architectural distinction for diagramming.

6. **Faster R-CNN training and inference flow**
   - `train.py` is responsible for the full optimization cycle, including the paper’s epoch schedule and learning-rate drops.
   - `inference.py` converts test-image predictions into a competition submission CSV.
   - `run.py` serves as the entry point with modes for:
     - train only
     - inference only
     - full pipeline

7. **Swin-Large pipeline (`swin_large/`)**
   - This directory is a second, separate model stack with its own:
     - `config.py`
     - `dataset.py`
     - `model.py`
     - `train.py`
     - `inference.py`
     - `run.py`
   - The presence of `fix_openmmlab.py` strongly suggests this branch depends on OpenMMLab tooling or model definitions and includes environment compatibility patches.

8. **Role of the Swin-Large branch**
   - Architecturally, `swin_large/` looks like an alternate detector/classifier pipeline rather than a helper library for `frcnn_paper/`.
   - It likely follows the same dataset boundary but swaps the detector backbone/stack for a Swin Large model implementation.
   - This creates a clean “multi-model repo” pattern: same dataset, separate training/inference codepaths, separate outputs.

9. **Configuration and reproducibility boundary**
   - Both pipelines isolate experiment settings into `config.py`.
   - That makes the repo diagram straightforward: runtime entrypoints call config → dataset/model construction → training/inference.
   - The repo is therefore structured for reproducible experiments, not as a single monolithic application.

10. **Outputs and artifacts**
   - The Faster R-CNN branch explicitly emits:
     - checkpoints such as `best.pth` / epoch checkpoints
     - `submission_frcnn_paper.csv`
   - The README also references a `work_dirs/` style output structure and an annotations export area for processed splits.
   - The Swin branch has its own log file (`ouput.log`) and likely produces similar checkpoints and submission outputs.

11. **Repository-level tooling**
   - Each model subproject has its own `requirements.txt`, implying isolated dependency sets.
   - `frcnn_paper/count_images.py` suggests a small utility used for dataset sanity checks or split inspection.
   - These are supporting tools, not core runtime components, but they reinforce that data validation and experiment management are part of the workflow.

12. **How to draw the architecture**
   - The clearest diagram is:
     - **Dataset assets** in `data/...`
     - branching into **two independent training/inference pipelines**
     - each pipeline has **config → dataset processing → model → train/inference → output CSV/checkpoints**
   - The shared external dependency is the same competition data; the major divergence is the detector stack:
     - Faster R-CNN with ResNet-50/FPN
     - Swin-Large/OpenMMLab-based alternative

Main entry points: [`frcnn_paper/dataset.py`](https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/dataset.py) (Data pipeline), [`swin_large/dataset.py`](https://github.com/tuttc/riva-track-a/blob/main/swin_large/dataset.py) (Data pipeline), [`frcnn_paper/inference.py`](https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/inference.py) (Infer), [`swin_large/model.py`](https://github.com/tuttc/riva-track-a/blob/main/swin_large/model.py) (Detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dataset boundary"]
  node_dataset_root[("Cytology data<br/>dataset")]
  node_train_csv["Train CSV<br/>annotations<br/>[train.csv]"]
  node_val_csv["Val CSV<br/>annotations<br/>[val.csv]"]
  node_sample_csv["Sample CSV<br/>submission-template"]
  node_train_images["Train images<br/>image-set"]
  node_val_images["Val images<br/>image-set"]
  node_test_images["Test images<br/>image-set"]
end

subgraph group_frcnn["Faster R-CNN"]
  node_frcnn_config["Config<br/>[config.py]"]
  node_frcnn_dataset["Data pipeline<br/>dataset+augment<br/>[dataset.py]"]
  node_frcnn_model{{"Detector<br/>faster-rcnn<br/>[model.py]"}}
  node_frcnn_train["Train<br/>[train.py]"]
  node_frcnn_infer["Infer<br/>prediction<br/>[inference.py]"]
  node_frcnn_run(("Run entry<br/>orchestrator<br/>[run.py]"))
  node_frcnn_output["Checkpoints<br/>artifacts"]
end

subgraph group_swin["Swin Large"]
  node_swin_config["Config<br/>[config.py]"]
  node_swin_dataset["Data pipeline<br/>dataset<br/>[dataset.py]"]
  node_swin_fix["OpenMMLab patch<br/>compatibility<br/>[fix_openmmlab.py]"]
  node_swin_model{{"Detector<br/>swin-large<br/>[model.py]"}}
  node_swin_train["Train<br/>[train.py]"]
  node_swin_infer["Infer<br/>prediction<br/>[inference.py]"]
  node_swin_run(("Run entry<br/>orchestrator<br/>[run.py]"))
end

node_dataset_root -->|"feeds"| node_frcnn_dataset
node_dataset_root -->|"feeds"| node_swin_dataset
node_train_csv -->|"labels"| node_frcnn_dataset
node_val_csv -->|"labels"| node_frcnn_dataset
node_train_images -->|"images"| node_frcnn_dataset
node_val_images -->|"images"| node_frcnn_dataset
node_test_images -->|"inputs"| node_frcnn_infer
node_sample_csv -->|"template"| node_frcnn_infer
node_frcnn_config -->|"settings"| node_frcnn_run
node_frcnn_config -->|"hyperparams"| node_frcnn_train
node_frcnn_dataset -->|"batches"| node_frcnn_model
node_frcnn_model -->|"learns"| node_frcnn_train
node_frcnn_model -->|"predicts"| node_frcnn_infer
node_frcnn_run -->|"train mode"| node_frcnn_train
node_frcnn_run -->|"infer mode"| node_frcnn_infer
node_frcnn_train -->|"writes"| node_frcnn_output
node_frcnn_infer -->|"writes"| node_frcnn_output
node_train_csv -->|"labels"| node_swin_dataset
node_val_csv -->|"labels"| node_swin_dataset
node_train_images -->|"images"| node_swin_dataset
node_val_images -->|"images"| node_swin_dataset
node_test_images -->|"inputs"| node_swin_infer
node_sample_csv -->|"template"| node_swin_infer
node_swin_config -->|"settings"| node_swin_run
node_swin_config -->|"hyperparams"| node_swin_train
node_swin_fix -->|"patches"| node_swin_model
node_swin_dataset -->|"batches"| node_swin_model
node_swin_model -->|"learns"| node_swin_train
node_swin_model -->|"predicts"| node_swin_infer
node_swin_run -->|"train mode"| node_swin_train
node_swin_run -->|"infer mode"| node_swin_infer

click node_dataset_root "https://github.com/tuttc/riva-track-a/tree/main/data/riva-cervical-cytology-challenge-isbi-2026"
click node_train_csv "https://github.com/tuttc/riva-track-a/blob/main/data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/train.csv"
click node_val_csv "https://github.com/tuttc/riva-track-a/blob/main/data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/val.csv"
click node_sample_csv "https://github.com/tuttc/riva-track-a/blob/main/data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/sample_submission.csv"
click node_train_images "https://github.com/tuttc/riva-track-a/tree/main/data/riva-cervical-cytology-challenge-isbi-2026/images/images/train"
click node_val_images "https://github.com/tuttc/riva-track-a/tree/main/data/riva-cervical-cytology-challenge-isbi-2026/images/images/val"
click node_test_images "https://github.com/tuttc/riva-track-a/tree/main/data/riva-cervical-cytology-challenge-isbi-2026/images/images/test"
click node_frcnn_config "https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/config.py"
click node_frcnn_dataset "https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/dataset.py"
click node_frcnn_model "https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/model.py"
click node_frcnn_train "https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/train.py"
click node_frcnn_infer "https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/inference.py"
click node_frcnn_run "https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/run.py"
click node_frcnn_output "https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/submission_frcnn_paper.csv"
click node_swin_config "https://github.com/tuttc/riva-track-a/blob/main/swin_large/config.py"
click node_swin_dataset "https://github.com/tuttc/riva-track-a/blob/main/swin_large/dataset.py"
click node_swin_fix "https://github.com/tuttc/riva-track-a/blob/main/swin_large/fix_openmmlab.py"
click node_swin_model "https://github.com/tuttc/riva-track-a/blob/main/swin_large/model.py"
click node_swin_train "https://github.com/tuttc/riva-track-a/blob/main/swin_large/train.py"
click node_swin_infer "https://github.com/tuttc/riva-track-a/blob/main/swin_large/inference.py"
click node_swin_run "https://github.com/tuttc/riva-track-a/blob/main/swin_large/run.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_dataset_root,node_train_csv,node_val_csv,node_sample_csv,node_train_images,node_val_images,node_test_images toneBlue
class node_frcnn_config,node_frcnn_dataset,node_frcnn_model,node_frcnn_train,node_frcnn_infer,node_frcnn_run,node_frcnn_output toneAmber
class node_swin_config,node_swin_dataset,node_swin_fix,node_swin_model,node_swin_train,node_swin_infer,node_swin_run toneMint
```

## Components

### Dataset boundary

Competition images and annotations shared by both model pipelines.

- [Cytology data](https://github.com/tuttc/riva-track-a/tree/main/data/riva-cervical-cytology-challenge-isbi-2026): dataset · Shared cervical cytology challenge assets: train/val/test images plus CSV annotations. · `data/riva-cervical-cytology-challenge-isbi-2026`
- [Train CSV](https://github.com/tuttc/riva-track-a/blob/main/data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/train.csv): annotations · Training labels and box annotations. · `data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/train.csv`
- [Val CSV](https://github.com/tuttc/riva-track-a/blob/main/data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/val.csv): annotations · Validation labels and box annotations. · `data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/val.csv`
- [Sample CSV](https://github.com/tuttc/riva-track-a/blob/main/data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/sample_submission.csv): submission-template · Competition submission template. · `data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/sample_submission.csv`
- [Train images](https://github.com/tuttc/riva-track-a/tree/main/data/riva-cervical-cytology-challenge-isbi-2026/images/images/train): image-set · Training image folder. · `data/riva-cervical-cytology-challenge-isbi-2026/images/images/train`
- [Val images](https://github.com/tuttc/riva-track-a/tree/main/data/riva-cervical-cytology-challenge-isbi-2026/images/images/val): image-set · Validation image folder. · `data/riva-cervical-cytology-challenge-isbi-2026/images/images/val`
- [Test images](https://github.com/tuttc/riva-track-a/tree/main/data/riva-cervical-cytology-challenge-isbi-2026/images/images/test): image-set · Test image folder used for inference. · `data/riva-cervical-cytology-challenge-isbi-2026/images/images/test`

### Faster R-CNN

Paper-aligned detector pipeline built around ResNet-50 + FPN.

- [Config](https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/config.py): config · Paths, hyperparameters, and paper-specific settings. · `frcnn_paper/config.py`
- [Data pipeline](https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/dataset.py): dataset+augment · Loads images/boxes and applies box augmentation plus image augmentation. · `frcnn_paper/dataset.py`
- [Detector](https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/model.py): faster-rcnn · ResNet-50 + FPN detector with Fast R-CNN head and comparison-loss extensions. · `frcnn_paper/model.py`
- [Train](https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/train.py): training · Optimization loop, epoch schedule, and learning-rate drops. · `frcnn_paper/train.py`
- [Infer](https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/inference.py): prediction · Runs test-time prediction and formats submission output. · `frcnn_paper/inference.py`
- [Run entry](https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/run.py): orchestrator · Pipeline entrypoint for train, inference, or full runs. · `frcnn_paper/run.py`
- [Checkpoints](https://github.com/tuttc/riva-track-a/blob/main/frcnn_paper/submission_frcnn_paper.csv): artifacts · Model checkpoints and submission CSV output. · `frcnn_paper/submission_frcnn_paper.csv`

### Swin Large

Alternative detector pipeline using an OpenMMLab-style Swin Large stack.

- [Config](https://github.com/tuttc/riva-track-a/blob/main/swin_large/config.py): config · Paths and experiment settings for the Swin pipeline. · `swin_large/config.py`
- [Data pipeline](https://github.com/tuttc/riva-track-a/blob/main/swin_large/dataset.py): dataset · Dataset loader and preprocessing for the Swin branch. · `swin_large/dataset.py`
- [OpenMMLab patch](https://github.com/tuttc/riva-track-a/blob/main/swin_large/fix_openmmlab.py): compatibility · Environment or dependency compatibility adjustments for OpenMMLab tooling. · `swin_large/fix_openmmlab.py`
- [Detector](https://github.com/tuttc/riva-track-a/blob/main/swin_large/model.py): swin-large · Swin Large-based model stack. · `swin_large/model.py`
- [Train](https://github.com/tuttc/riva-track-a/blob/main/swin_large/train.py): training · Training loop for the Swin branch. · `swin_large/train.py`
- [Infer](https://github.com/tuttc/riva-track-a/blob/main/swin_large/inference.py): prediction · Generates predictions and submission output. · `swin_large/inference.py`
- [Run entry](https://github.com/tuttc/riva-track-a/blob/main/swin_large/run.py): orchestrator · Pipeline entrypoint for the Swin branch. · `swin_large/run.py`

## Connections

- Cytology data → Data pipeline: feeds · Shared competition data is consumed by the Faster R-CNN pipeline.
- Cytology data → Data pipeline: feeds · Shared competition data is consumed by the Swin pipeline.
- Train CSV → Data pipeline: labels · Training annotations are loaded for the detector pipeline.
- Val CSV → Data pipeline: labels · Validation annotations are loaded for evaluation.
- Train images → Data pipeline: images · Training images are paired with CSV boxes.
- Val images → Data pipeline: images · Validation images are paired with CSV boxes.
- Test images → Infer: inputs · Test images are used for prediction generation.
- Sample CSV → Infer: template · Submission formatting follows the competition template.
- Config → Run entry: settings · Run mode and experiment parameters are configured here.
- Config → Train: hyperparams · Training settings flow into optimization.
- Data pipeline → Detector: batches · Augmented samples are fed into the detector.
- Detector → Train: learns · Training optimizes the detector weights.
- Detector → Infer: predicts · Inference uses the trained detector.
- Run entry → Train: train mode · Entrypoint dispatches to training.
- Run entry → Infer: infer mode · Entrypoint dispatches to inference.
- Train → Checkpoints: writes · Training emits checkpoints and logs.
- Infer → Checkpoints: writes · Inference emits the submission CSV.
- Train CSV → Data pipeline: labels · Training annotations are loaded for the Swin branch.
- Val CSV → Data pipeline: labels · Validation annotations are loaded for the Swin branch.
- Train images → Data pipeline: images · Training images are paired with CSV boxes.
- Val images → Data pipeline: images · Validation images are paired with CSV boxes.
- Test images → Infer: inputs · Test images are used for prediction generation.
- Sample CSV → Infer: template · Submission formatting follows the competition template.
- Config → Run entry: settings · Run mode and experiment parameters are configured here.
- Config → Train: hyperparams · Training settings flow into optimization.
- OpenMMLab patch → Detector: patches · Compatibility fixes support the OpenMMLab-based model stack.
- Data pipeline → Detector: batches · Prepared samples are fed into the detector.
- Detector → Train: learns · Training optimizes the Swin model weights.
- Detector → Infer: predicts · Inference uses the trained detector.
- Run entry → Train: train mode · Entrypoint dispatches to training.
- Run entry → Infer: infer mode · Entrypoint dispatches to inference.