# thalesgroup/darswin architecture

> Architecture diagram of the GitHub repository thalesgroup/darswin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thalesgroup/darswin
- Repository: https://github.com/thalesgroup/darswin

## Overview

##### Project Type and Purpose
- This repository implements a research paper’s approach for wide-angle image classification using a distortion aware extension of the Swin Transformer. In short, it’s an image classification project targeted at handling lens distortion.
- The code is primarily for training, evaluating, and experimenting with different variants (angular, polar, radial) of Swin-based architectures, as well as managing different distortion configurations.

##### File Structure and Key Components
– Top-level files like README, LICENSE, and various markdown documentation files indicate this is an open-source research implementation.
– The directories and files point to several main components:
- Configurations (configs/): Contains YAML configuration files (e.g., one_distortion_swin_small_patch2_window4_64_gp*_*.yaml) that define model parameters, distortions, and possibly training hyperparameters.
- Data Management (data/): Contains scripts to load and process datasets (e.g., Distorted_imagenet.py, apply_fisheye.py, build.py), tools to handle cache, classes, distortion parameters, and the management of the ImageNet2010 dataset.
- Models (models/): Holds different model implementations and utilities to build either the Swin Transformer or its variations (angular, polar). It also includes helper files (models/utils.py, models/build.py) which aid in constructing the transformer network.
- Training and Evaluation: Main training script (main.py), shell scripts for training (train.sh) and evaluation (eval.sh, eval_xi.sh).
- Utilities and Core Code (config.py, logger.py, lr_scheduler.py, optimizer.py, utils.py, __init__.py): The backbone utilities, configuration reading, logging, and learning rate scheduling used throughout the project.
- Additional artifacts: Pretrained/saved files like classes_custom.pkl, sampling_pt.pkl, and different image class lists.

##### Main Components and Their Interactions
a. Data Module:
– Data loading and preprocessing routines are in the data folder. These include functions to apply distortion (e.g., apply_fisheye.py) and structure the ImageNet datasets (train/val/test folders).
– Annotations and parameter files (like dist_params.pkl, classes.pkl, etc.) are used for conditioning the data pipeline.
b. Configuration Manager:
– Files in configs/ and the top-level config.py usually handle loading various model and training parameters.
– They define settings for different distortion geometries (through different YAML files) that the model training and inference stages use.
c. Model Module:
– Contains different implementations of the Swin Transformer variants (swin_transformer, swin_transformer_angular, swin_transformer_polar, and swin_mlp).
– The build scripts (models/build.py) assemble network components using the provided configuration and weights.
d. Training & Evaluation Framework:
– main.py serves as the entry point for training.
– Shell scripts (train.sh, eval.sh, eval_xi.sh) encapsulate the workflow of training and evaluating models.
– The optimizer.py, lr_scheduler.py, and logger.py modules manage optimization, dynamic learning rate adjustments, and logging respectively.
e. Supporting Utilities:
– Utility scripts and Python modules (utils.py, __init__.py, etc.) provide common helper functions for the entire codebase.

##### Architectural Patterns and Design Principles
– Modularity: The clear separation into configs, data, models, and utils indicate a modular design. Different modules work independently but interact via well-defined interfaces.
– Reproducibility and Experiment Management: With numerous configuration files and dedicated directories for model configurations, the design is geared toward easy experimentation with various distortion parameters and transformer architectures.
– Extensibility: The use of YAML configuration files and the presence of several interchangeable model variants show that the system is designed for extensions or further improvements.
– Pipeline Flow: Data flows from raw input (datasets) through the configured preprocessing modules, then into a model-building block, trained and evaluated via a controlled training/evaluation script workflow.

##### Final Recommendation to the Principal Software Engineer
– Start by sketching the high-level modules: Data, Configuration, Model, Training, and Evaluation.
– Within each module, list the key files/folders that contribute to that part of the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Input
    ExternalInput("External Data & Distortion_Params"):::external

    %% Data Module Subgraph
    subgraph "Data Module"
        DataPreprocessor("Data Preprocessor\n(data/)"):::data
    end

    %% Configuration Manager Subgraph
    subgraph "Configuration Manager"
        YAMLConfigs("YAML Configs\n(configs/)"):::config
        ConfigSettings("Config Settings\n(config.py)"):::config
    end

    %% Model Module Subgraph
    subgraph "Model Module"
        ModelBuilder("Model Builder\n(models/)"):::model
    end

    %% Training Engine Subgraph
    subgraph "Training Engine"
        TrainingController("Training Controller\n(main.py)"):::training
        TrainScript("Train Script\n(train.sh)"):::training
    end

    %% Evaluation Module Subgraph
    subgraph "Evaluation Module"
        EvalScript("Evaluation Script\n(eval.sh)"):::evaluation
        EvalXIScript("Evaluation_XI Script\n(eval_xi.sh)"):::evaluation
    end

    %% Supporting Utilities Subgraph
    subgraph "Supporting Utilities"
        Logger("Logger\n(logger.py)"):::utilities
        LRScheduler("LR Scheduler\n(lr_scheduler.py)"):::utilities
        Optimizer("Optimizer\n(optimizer.py)"):::utilities
        Helpers("Helpers\n(utils.py)"):::utilities
        Init("Init Module\n(__init__.py)"):::utilities
    end

    %% Connections
    ExternalInput -->|"Raw_Data"| DataPreprocessor
    DataPreprocessor -->|"Preprocessed_Data"| TrainingController

    YAMLConfigs -->|"Model_Config"| ModelBuilder
    ConfigSettings -->|"Training_Params"| TrainingController

    ModelBuilder -->|"Built_Model"| TrainingController
    TrainingController -->|"Trained_Model"| EvalScript
    TrainingController -->|"Trained_Model"| EvalXIScript

    Logger ---|"Logging"| TrainingController
    LRScheduler ---|"Scheduling"| TrainingController
    Optimizer ---|"Optimization"| TrainingController
    Helpers ---|"Utilities"| TrainingController

    Logger ---|"Logging"| EvalScript
    LRScheduler ---|"Scheduling"| EvalScript
    Optimizer ---|"Optimization"| EvalScript
    Helpers ---|"Utilities"| EvalScript

    %% Click Events
    click DataPreprocessor "https://github.com/thalesgroup/darswin/tree/main/data/"
    click YAMLConfigs "https://github.com/thalesgroup/darswin/tree/main/configs/"
    click ConfigSettings "https://github.com/thalesgroup/darswin/blob/main/config.py"
    click ModelBuilder "https://github.com/thalesgroup/darswin/tree/main/models/"
    click TrainingController "https://github.com/thalesgroup/darswin/blob/main/main.py"
    click TrainScript "https://github.com/thalesgroup/darswin/blob/main/train.sh"
    click EvalScript "https://github.com/thalesgroup/darswin/blob/main/eval.sh"
    click EvalXIScript "https://github.com/thalesgroup/darswin/blob/main/eval_xi.sh"
    click Logger "https://github.com/thalesgroup/darswin/blob/main/logger.py"
    click LRScheduler "https://github.com/thalesgroup/darswin/blob/main/lr_scheduler.py"
    click Optimizer "https://github.com/thalesgroup/darswin/blob/main/optimizer.py"
    click Helpers "https://github.com/thalesgroup/darswin/blob/main/utils.py"
    click Init "https://github.com/thalesgroup/darswin/blob/main/__init__.py"

    %% Styles
    classDef data fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef config fill:#98fb98,stroke:#008000,stroke-width:2px;
    classDef model fill:#ffcccb,stroke:#ff0000,stroke-width:2px;
    classDef training fill:#fdfd96,stroke:#cccc00,stroke-width:2px;
    classDef evaluation fill:#d3d3d3,stroke:#808080,stroke-width:2px;
    classDef utilities fill:#e6e6fa,stroke:#4b0082,stroke-width:2px;
    classDef external fill:#ffe4b5,stroke:#cd853f,stroke-width:2px;
```
