# ascend-research/turtle architecture

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

- Interactive diagram: https://gitdiagram.com/ascend-research/turtle
- Repository: https://github.com/ascend-research/turtle

## Overview

##### Project Type and Purpose
- The project is a video restoration deep learning framework. It accepts degraded video inputs (after frame extraction) and outputs enhanced, restored video frames.
- Its flexible "Model Forge" design allows customization by switching layers and feed-forward configurations through YAML option files.
- The codebase builds on the BasicSR toolbox and adapts state-of-the-art architectures for various low-level video restoration tasks.

##### File Structure
- Top-level files like README, setup.py, and make_video.py are for configuration, package management, and scripts.
- The “basicsr” directory is the core component and is subdivided into:
- data: Includes modules for dataset handling, transformations, and prefetching (e.g., data_sampler.py, video_image_dataset.py, video_super_image_dataset.py).
- models: Contains model definitions and architecture implementations (e.g., turtle_arch.py, turtle_t1_arch.py, turtlesuper_t1_arch.py) along with loss functions, learning rate schedulers, and training-related files.
- loss: Provides loss calculations needed during training.
- metrics: Implements evaluation metrics (like PSNR/SSIM) to assess performance.
- utils: Utility functions such as file handling, logger, image/video utilities.
- Additional scripts (e.g., inference.py, inference_no_ground_truth.py, video_to_frames.py) support both model testing and real-world video inference examples.
- The “options” folder contains YAML configuration files, offering flexibility to select and modify the model architecture and hyperparameters.

##### Architectural Patterns & Design Principles
- The project follows a modular design, with a clear separation between data handling, modeling, training, and evaluation.
- It employs dependency injection through YAML options to enable “Model Forge” customization.
- The system can be seen as a pipeline architecture where data flows sequentially from input, through processing layers, to the output.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Acquisition & Preprocessing"
        A["Video Input"]:::data
        B["Frame Extraction"]:::data
        subgraph "Data Loader / Preprocessing"
            C["Video Image Dataset"]:::data
            D["Video Super Image Dataset"]:::data
        end
        A -->|"extracts"| B
        B -->|"loads"| C
        B -->|"loads"| D
    end

    subgraph "Training and Model Processing"
        E["Training Engine"]:::process
        subgraph "Model Architectures"
            F1["Turtle Arch"]:::process
            F2["Turtle T1 Arch"]:::process
            F3["TurtleSuper T1 Arch"]:::process
        end
        G["Loss Computation (Directory)"]:::process
        H["Loss Functions"]:::process
        I["Learning Rate Scheduler"]:::process
        C --> E
        D --> E
        E -->|"uses"| F1
        E -->|"uses"| F2
        E -->|"uses"| F3
        F1 -->|"triggers"| H
        F2 -->|"triggers"| H
        F3 -->|"triggers"| H
        H -->|"calculates"| G
        G -->|"feeds_back"| E
        E -->|"updates"| I
    end

    subgraph "Post-Processing & Evaluation"
        J["Evaluation Metrics (Directory)"]:::evaluation
        K["PSNR/SSIM Metric"]:::evaluation
        E -->|"evaluates"| J
        J -->|"details"| K
    end

    subgraph "Inference Pipeline"
        L1["Inference with GT"]:::evaluation
        L2["Inference without GT"]:::evaluation
        E -->|"infers"| L1
        E -->|"infers"| L2
    end

    M["Configuration Management"]:::config
    N["External Dependencies (PyTorch,CUDA,BasicSR)"]:::external
    M ---|"configures"| E
    M ---|"configures"| L1
    M ---|"configures"| L2
    N ---|"supports"| E
    N ---|"supports"| L1
    N ---|"supports"| L2

    click B "https://github.com/ascend-research/turtle/blob/main/video_to_frames.py"
    click C "https://github.com/ascend-research/turtle/blob/main/basicsr/data/video_image_dataset.py"
    click D "https://github.com/ascend-research/turtle/blob/main/basicsr/data/video_super_image_dataset.py"
    click E "https://github.com/ascend-research/turtle/blob/main/basicsr/train.py"
    click G "https://github.com/ascend-research/turtle/tree/main/basicsr/loss"
    click H "https://github.com/ascend-research/turtle/blob/main/basicsr/models/losses/losses.py"
    click F1 "https://github.com/ascend-research/turtle/blob/main/basicsr/models/archs/turtle_arch.py"
    click F2 "https://github.com/ascend-research/turtle/blob/main/basicsr/models/archs/turtle_t1_arch.py"
    click F3 "https://github.com/ascend-research/turtle/blob/main/basicsr/models/archs/turtlesuper_t1_arch.py"
    click I "https://github.com/ascend-research/turtle/blob/main/basicsr/models/lr_scheduler.py"
    click L1 "https://github.com/ascend-research/turtle/blob/main/basicsr/inference.py"
    click L2 "https://github.com/ascend-research/turtle/blob/main/basicsr/inference_no_ground_truth.py"
    click J "https://github.com/ascend-research/turtle/tree/main/basicsr/metrics"
    click K "https://github.com/ascend-research/turtle/blob/main/basicsr/metrics/psnr_ssim.py"
    click M "https://github.com/ascend-research/turtle/tree/main/options"

    classDef data fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef process fill:#9ec9ff,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#B2F2BB,stroke:#333,stroke-width:2px;
    classDef config fill:#E0E0E0,stroke:#333,stroke-width:2px;
    classDef external fill:#FFCCCB,stroke:#333,stroke-width:2px;
```
