# nalin0503/fyp_imagemorpher architecture

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

- Interactive diagram: https://gitdiagram.com/nalin0503/fyp_imagemorpher
- Repository: https://github.com/nalin0503/fyp_imagemorpher

## Overview

##### Project Purpose and Type
- The project is an advanced image morphing pipeline designed for creating smooth transitions between images. It combines keyframe generation using diffusion-based models (handled by the DiffMorpher submodule with LCM-LoRA acceleration) and recursive FILM-based frame interpolation.
- It supports both a command-line interface (via run_morphing.py) and a web-based UI (via app.py using Streamlit) for interactive control.
- The system is intended for research and production use (NTU Final Year Project) and leverages state-of-the-art techniques in image processing.

##### Key Components and Their Roles
a. Frontend/UI Layer:
- app.py: Provides a web interface built with Streamlit. It allows users to input images, text prompts, and morphing parameters.
b. Orchestration/Controller:
- run_morphing.py: Acts as the main controller that coordinates the overall morphing process. It triggers keyframe generation and interpolation according to user-specified parameters.
- Makefile: Automates initialization, dependency setup, and triggering of morphing tasks.
c. Core Processing Modules:
- DiffMorpher Submodule: Responsible for generating keyframes using diffusion models and integrates LCM-LoRA for accelerating diffusion. Within this submodule, main.py serves as the entry point.
- FILM.py: Implements the recursive frame interpolation algorithm that smooths transitions between keyframes.
d. Supporting Components:
- requirements.txt: Manages the Python package dependencies.
- Sample_runs folder: Contains example outputs and sample morphing results, useful for testing and verification.
- Configuration Files/Assets:
- .gitmodules file: Indicates the use of submodules (like DiffMorpher).

##### Relationships and Data Flow
- The user (through either CLI or web UI) provides the initial images and associated text prompts.
- The input is first passed to the DiffMorpher component that performs diffusion-based keyframe generation (possibly enhanced by LCM-LoRA).
- Once the keyframes are generated, they are processed by the FILM.py component to create smoothly interpolated frames.
- Final outputs (videos and intermediate frames) are saved under designated directories (sample_runs) and optionally can be previewed through the web interface.
- From “User Input” to “UI Layer (app.py)” or “Direct CLI (run_morphing.py)”
- From “Controller” to “DiffMorpher Submodule” (keyframe generation)
- From “Controller” to “FILM Module” (frame interpolation)
- From both processing modules to “Output Storage” (sample_runs)

##### Architectural Patterns and Technologies
- Modular Architecture: Separation between the frontend (Streamlit UI), controller/orchestration layer (run_morphing.py), and two core processing modules (DiffMorpher and FILM).
- Submodule Integration: The DiffMorpher is integrated as a submodule, reflecting the dependency on an external keyframe generation framework.
- Acceleration Mechanism: LCM-LoRA integration for accelerating the reverse diffusion process.
- Technologies:
- Python 3.12 as the primary language.
- CUDA and GPU acceleration for diffusion and interpolation tasks.
- Streamlit for the web-based user interface.
- External libraries from Stable Diffusion, Latent Consistency Models, and FILM for frame interpolation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    U("User/CLI"):::user

    %% Interface Layer
    subgraph "User Interface"
        UI("Web UI (app.py)"):::ui
    end

    %% Orchestration/Controller Layer
    subgraph "Orchestration/Controller"
        R("run_morphing.py"):::orchestr
        M("Makefile"):::orchestr
    end

    %% Core Processing Modules
    subgraph "Core Processing"
        D("DiffMorpher (Keyframe Generation, LCM-LoRA)"):::proc
        F("FILM (Recursive Frame Interpolation)"):::proc
    end

    %% Output Storage
    OS(("Output Storage (sample_runs)")):::store

    %% Supporting Components
    subgraph "Supporting Components"
        DEP("Dependencies (requirements.txt)"):::supp
        AS("Assets (img)"):::supp
        GIT("Submodule Config (.gitmodules)"):::supp
    end

    %% Connections
    U -->|"via Web"| UI
    U -->|"via CLI"| R
    UI --> R
    R -->|"triggers"| D
    R -->|"triggers"| F
    D -->|"feeds keyframes"| F
    D -->|"config from"| GIT
    F -->|"saves output"| OS

    %% Supporting components connection (optional)
    M --- DEP
    M --- AS

    %% Styles
    classDef user fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef orchestr fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef proc fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef store fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef supp fill:#ead1dc,stroke:#a8326b,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/nalin0503/fyp_imagemorpher/blob/main/app.py"
    click R "https://github.com/nalin0503/fyp_imagemorpher/blob/main/run_morphing.py"
    click M "https://github.com/nalin0503/fyp_imagemorpher/tree/main/Makefile"
    click D "https://github.com/nalin0503/fyp_imagemorpher/tree/main/DiffMorpher"
    click GIT "https://github.com/nalin0503/fyp_imagemorpher/blob/main/.gitmodules"
    click F "https://github.com/nalin0503/fyp_imagemorpher/blob/main/FILM.py"
    click OS "https://github.com/nalin0503/fyp_imagemorpher/tree/main/sample_runs"
    click DEP "https://github.com/nalin0503/fyp_imagemorpher/blob/main/requirements.txt"
    click AS "https://github.com/nalin0503/fyp_imagemorpher/tree/main/img"
```
