# eric-yyjau/pytorch-superpoint architecture

> Architecture diagram of the GitHub repository eric-yyjau/pytorch-superpoint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eric-yyjau/pytorch-superpoint
- Repository: https://github.com/eric-yyjau/pytorch-superpoint

## Overview

##### Project Type and Purpose
- This repository is a research‐oriented PyTorch implementation of the SuperPoint keypoint detector+descriptor network.
- It provides a full deep learning pipeline: synthetic data generation → MagicPoint detector training → homography‐adaptation label export → joint SuperPoint training → descriptor/keypoint export and evaluation.

##### File Structure Analysis
- Top‐level scripts:
- train4.py, Train_model_*.py, Val_model_*.py – wrappers to start specific training/validation jobs
- export.py, export_classical.py – pipelines to generate pseudo‐ground‐truth and classical‐detector outputs
- evaluation.py – computes metrics (repeatability, matching score, homography estimation)
- run_export.sh – batch export+evaluate for HPatches
- Directories:
- configs/ – YAML files defining tasks, dataset roots, model hyperparameters
- datasets/ – Dataset reader classes (Coco, Kitti, Tum, Synthetic), splitting files, raw KITTI data
- models/ – PyTorch model definitions (SuperPointNet, SubpixelNet, U-Net blocks, classical detectors)
- utils/ – Helpers (augmentation, homographies, losses, logging)
- evaluations/ – High‐level evaluation routines for detectors and descriptors
- logs/ – Checkpoints, config.yml, predictions for each experiment
- notebooks/ – Interactive exploration and visualization
- pretrained/ – Downloaded SuperPoint v1 weights
- test/ – Unit tests / small example scripts

##### README Insights
- Details a 5‐stage pipeline:
2. Export homography‐adapted labels on COCO/KITTI/TUM
3. Train SuperPoint on pseudo‐labels
4. Export+evaluate on HPatches
5. Export+evaluate SIFT baseline
- Dependencies: PyTorch, torchvision, YAML configs, CUDA
- External datasets: MS-COCO, KITTI raw, HPatches

##### Main Components & Interactions
a. Components (group into functional layers):
1. Configuration Manager (configs/*.yaml + settings.py)
2. Data Layer
- Synthetic Data Generator (datasets/synthetic_shapes.py)
- Dataset Loaders (datasets/Coco.py, Kitti_inh.py, Tum.py)
- Data Augmenters (utils/photometric_augmentation.py, dataset utils)
3. Model Layer
- MagicPoint Detector (models/SuperPointNet*.py, classical_detectors_descriptors.py)
- Subpixel Refinement Net (models/SubpixelNet.py)
- Joint Descriptor Head (models/model_wrap.py)
4. Training & Export Pipelines
- train4.py → calls a Trainer class (uses models, datasets, utils) → logs checkpoints
- export.py → loads checkpoint → runs homography adaptation → writes .npz pseudo‐labels
5. Evaluation Layer
- evaluation.py + evaluations/*.py compute metrics on .npz outputs
6. Visualization & Notebooks (tensorboard via utils/logging.py, notebooks/*.ipynb)
7. Storage & Artifacts
- Dataset files (raw/augmented)
- Checkpoints & logs (logs/*)
- Exported labels & predictions (logs/*/predictions/*.npz)
- Pretrained weights (pretrained/)

b. Relationships & Data Flow
1. Configuration YAML → Pipeline Launcher (train4.py / export.py)
2. Pipeline → Data Layer → Model Layer (forward/backward in training or inference)
3. Model Layer → Checkpoint Writer → logs/<experiment>/checkpoints
4. Export Pipeline → loads checkpoint → applies homography adaptation → writes labels/predictions
5. Evaluation Pipeline → reads predictions → computes metrics → outputs plots/text

c. Architectural Patterns & Principles
- Modular design: each stage (train, export, eval) separated into its own script
- Clear separation of concerns: configs manage hyperparams, datasets isolate I/O, models define networks, utils abstract common code
- Pipeline orchestration: command‐line entry points that glue together config + modules

d. Key Technologies & Frameworks
- PyTorch for model definition and training
- YAML for configuration
- NumPy/.npz for label storage
- TensorBoard for logging
- Jupyter notebooks for interactive analysis

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration Layer
    subgraph "Configuration"
        config["Configuration Manager\n(YAML + settings.py)"]:::pipeline
    end

    %% Data Ingestion & Augmentation Layer
    subgraph "Data Ingestion & Augmentation"
        extCOCO["MS-COCO"]:::external
        extKITTI["KITTI Raw"]:::external
        extTUM["TUM Raw"]:::external

        synthShape["Synthetic Data Generator"]:::data
        cocoLoader["COCO Loader"]:::data
        kittiLoader["KITTI Loader"]:::data
        tumLoader["TUM Loader"]:::data

        photAug["Photometric Augmentation"]:::data
        homoUtil["Homography Utilities"]:::data
    end

    %% Model Layer
    subgraph "Model Training & Inference"
        magicPoint["MagicPoint Detector\n(SuperPointNet)"]:::model
        classicalDD["Classical Detectors\n& Descriptors"]:::model
        subpixel["Subpixel Refinement Net"]:::model
        descriptorHead["Joint Descriptor Head\n(Model Wrapper)"]:::model
    end

    %% Pipelines Layer
    subgraph "Pipelines"
        train["Training Pipeline\n(train4.py + wrappers)"]:::pipeline
        exportDL["Export Pipeline\n(export.py)"]:::pipeline
        exportClass["Classical Export\n(export_classical.py)"]:::pipeline
        runExport["Batch Export Script\n(run_export.sh)"]:::pipeline
        evalMain["Evaluation Pipeline\n(evaluation.py)"]:::pipeline
    end

    %% Storage & Artifacts Layer
    subgraph "Storage & Artifacts"
        checkpoints["Checkpoints\n(.pth)"]:::storage
        pseudoLabels["Pseudo-labels\n(.npz)"]:::storage
        logs["Logs & TensorBoard"]:::storage
        pretrained["Pretrained Weights\n(.pth)"]:::storage
    end

    %% Visualization Layer
    subgraph "Visualization & Notebooks"
        notebooks["Notebooks & Visualizations"]:::viz
    end

    %% Data Flow
    config --> train
    config --> exportDL
    config --> evalMain

    train --> synthShape
    train --> cocoLoader
    train --> kittiLoader
    train --> tumLoader

    synthShape --> photAug
    cocoLoader --> photAug
    kittiLoader --> photAug
    tumLoader --> photAug

    photAug --> magicPoint
    homoUtil --> exportDL

    magicPoint --> subpixel
    subpixel --> descriptorHead

    train --> magicPoint
    train --> subpixel
    train --> descriptorHead

    train --> checkpoints

    exportDL --> checkpoints
    exportDL --> pseudoLabels

    exportClass --> pseudoLabels
    runExport --> exportDL
    runExport --> exportClass

    pseudoLabels --> evalMain
    evalMain --> logs

    logs --> notebooks
    pretrained --> magicPoint

    extCOCO --> cocoLoader
    extKITTI --> kittiLoader
    extTUM --> tumLoader

    %% Click Events
    click config "https://github.com/eric-yyjau/pytorch-superpoint/tree/master/configs/"
    click config "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/settings.py"
    click synthShape "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/datasets/synthetic_shapes.py"
    click cocoLoader "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/datasets/Coco.py"
    click kittiLoader "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/datasets/Kitti_inh.py"
    click tumLoader "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/datasets/Tum.py"
    click photAug "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/utils/photometric_augmentation.py"
    click homoUtil "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/utils/homographies.py"
    click magicPoint "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/models/SuperPointNet.py"
    click classicalDD "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/models/classical_detectors_descriptors.py"
    click subpixel "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/models/SubpixelNet.py"
    click descriptorHead "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/models/model_wrap.py"
    click train "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/train4.py"
    click exportDL "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/export.py"
    click exportClass "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/export_classical.py"
    click runExport "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/run_export.sh"
    click evalMain "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/evaluation.py"
    click logs "https://github.com/eric-yyjau/pytorch-superpoint/tree/master/logs/"
    click pretrained "https://github.com/eric-yyjau/pytorch-superpoint/blob/master/pretrained/superpoint_v1.pth"

    %% Styles
    classDef data fill:#bbdefb,stroke:#1e88e5,color:#000
    classDef model fill:#c8e6c9,stroke:#43a047,color:#000
    classDef pipeline fill:#ffe0b2,stroke:#fb8c00,color:#000
    classDef external fill:#e0e0e0,stroke:#9e9e9e,color:#000
    classDef storage fill:#d7ccc8,stroke:#6d4c41,color:#000
    classDef viz fill:#f3e5f5,stroke:#8e24aa,color:#000
```
