How thalesgroup/darswin works
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.