How tuttc/riva-track-a works
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 Data pipeline · swin_large/dataset.py Data pipeline · inference.py Infer · model.py Detector
Components 21
Dataset boundary
Competition images and annotations shared by both model pipelines.
- Cytology data · Shared cervical cytology challenge assets: train/val/test images plus CSV annotations.
data/riva-cervical-cytology-challenge-isbi-2026 - Train CSV · Training labels and box annotations.
data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/train.csv - Val CSV · Validation labels and box annotations.
data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/val.csv - Sample CSV · Competition submission template.
data/riva-cervical-cytology-challenge-isbi-2026/annotations/annotations/sample_submission.csv - Train images · Training image folder.
data/riva-cervical-cytology-challenge-isbi-2026/images/images/train - Val images · Validation image folder.
data/riva-cervical-cytology-challenge-isbi-2026/images/images/val - Test images · 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 · Paths, hyperparameters, and paper-specific settings.
frcnn_paper/config.py - Data pipeline · Loads images/boxes and applies box augmentation plus image augmentation.
frcnn_paper/dataset.py - Detector · ResNet-50 + FPN detector with Fast R-CNN head and comparison-loss extensions.
frcnn_paper/model.py - Train · Optimization loop, epoch schedule, and learning-rate drops.
frcnn_paper/train.py - Infer · Runs test-time prediction and formats submission output.
frcnn_paper/inference.py - Run entry · Pipeline entrypoint for train, inference, or full runs.
frcnn_paper/run.py - Checkpoints · 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 · Paths and experiment settings for the Swin pipeline.
swin_large/config.py - Data pipeline · Dataset loader and preprocessing for the Swin branch.
swin_large/dataset.py - OpenMMLab patch · Environment or dependency compatibility adjustments for OpenMMLab tooling.
swin_large/fix_openmmlab.py - Detector · Swin Large-based model stack.
swin_large/model.py - Train · Training loop for the Swin branch.
swin_large/train.py - Infer · Generates predictions and submission output.
swin_large/inference.py - Run entry · Pipeline entrypoint for the Swin branch.
swin_large/run.py
Connections 31
- 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.