# arunvfx/ulaavi architecture

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

- Interactive diagram: https://gitdiagram.com/arunvfx/ulaavi
- Repository: https://github.com/arunvfx/ulaavi

## Overview

##### Project Type and Purpose
- Type: A Python‑based desktop plugin/tool that integrates with The Foundry’s Nuke compositing application.
- Purpose: Provide an intuitive UI within Nuke to browse, preview, and import high‑quality stock footage (`.mov`) using FFmpeg and OpenCV.

##### Main Architectural Components
a. Host Environment & Entry Points
– Nuke Application & Plugin Loader (external)
– `main.py`, `menu.py` (register tool in Nuke’s menu, set up plugin paths)
b. UI Layer (`ui/` package)
– Widget modules (`mainUI.py`, `_categoriesTree.py`, `_preview_proxy.py`, etc.)
– Action handlers (`_actionsUI.py`)
– Preferences & settings UI (`_preferences_grp.py`, `_settingsUI.py`)
c. Data Layer (`data/` package)
– Configuration (`config.py`)
– Data models and metadata handling (`tool_data.py`, `_handler.py`)
d. Conversion Layer (`conversion/` package)
– Command definitions (`_commands.py`)
– `.mov` conversion logic (`convert_mov.py`) — wraps FFmpeg
e. Utilities (top‑level `_operations.py`, `_utilities.py`)
– Common functions (file I/O, subprocess management, logging)
f. External Dependencies
– FFmpeg (process invoked by conversion modules)
– OpenCV, NumPy, Clique (media handling)
– PySide2/PySide6 (UI framework)
– Nuke Python API (host integration)

##### Relationships & Data Flow
- User clicks “Load Stock Footage” in Nuke → `menu.py` invokes `main.py` → UI layer spawns the main panel.
- UI events (e.g., selecting a category) call `ui/_actionsUI.py` → queries `data/_handler.py` for file lists/metadata.
- When the preview is requested, the UI calls `conversion/convert_mov.py`, which uses FFmpeg (via subprocess in `_utilities.py`) to generate or fetch a `.mov` preview.
- Conversion results (file paths) feed back into the UI preview widget (`_preview_proxy.py` → `_thumbnailUI.py`).
- Upon “Import” action, UI issues commands to Nuke’s Python API to create Read nodes pointing to the selected footage.

##### Architectural Patterns & Principles
– MVC‑style separation:
· Model = `data/` packages
· View = `ui/*UI.py` modules
· Controller = `ui/_actionsUI.py`, plus command modules in `conversion/`
– Single Responsibility: Each package handles one concern (UI, data, conversion, utilities).
– External Integration Layer: Encapsulate FFmpeg calls and Nuke API interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Environment & Entry Points
    subgraph "Host Environment & Entry Points"
        Nuke["Nuke Application"]:::external
        Menu["menu.py"]:::host
        Main["main.py"]:::host
    end

    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        UIWidgets["UI Widgets"]:::ui
        UIControllers["UI Controllers"]:::ui
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Config["config.py"]:::data
        Handler["_handler.py"]:::data
        ToolData["tool_data.py"]:::data
    end

    %% Conversion Layer
    subgraph "Conversion Layer"
        direction TB
        ConvertMov["convert_mov.py"]:::conv
        Commands["_commands.py"]:::conv
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Operations["_operations.py"]:::util
        Utilities["_utilities.py"]:::util
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        FFmpeg["FFmpeg"]:::external
        OpenCV["OpenCV/NumPy/Clique"]:::external
        PySide["PySide2/PySide6"]:::external
        NukeAPI["Nuke Python API"]:::external
    end

    %% Interactions and Data Flow
    Nuke -->|"plugin loader"| Menu
    Menu -->|"initializes"| Main
    Main -->|"launch UI"| UIWidgets
    Main -->|"binds actions"| UIControllers

    UIControllers -->|"query metadata|get file list"| Handler
    Handler -->|"reads config"| Config
    Handler -->|"provides data"| ToolData
    UIControllers -->|"request preview"| ConvertMov
    ConvertMov -->|"uses subprocess"| Utilities
    ConvertMov -->|"executes operations"| Operations
    ConvertMov -->|"calls FFmpeg"| FFmpeg
    ConvertMov -->|"returns preview path"| UIWidgets

    UIWidgets -->|"render preview"| OpenCV
    UIWidgets -->|"import footage"| NukeAPI

    %% Click Events
    click Menu "https://github.com/arunvfx/ulaavi/blob/master/menu.py"
    click Main "https://github.com/arunvfx/ulaavi/blob/master/main.py"
    click UIWidgets "https://github.com/arunvfx/ulaavi/blob/master/ui/mainUI.py"
    click UIControllers "https://github.com/arunvfx/ulaavi/blob/master/ui/_actionsUI.py"
    click Handler "https://github.com/arunvfx/ulaavi/blob/master/data/_handler.py"
    click Config "https://github.com/arunvfx/ulaavi/blob/master/data/config.py"
    click ToolData "https://github.com/arunvfx/ulaavi/blob/master/data/tool_data.py"
    click ConvertMov "https://github.com/arunvfx/ulaavi/blob/master/conversion/convert_mov.py"
    click Commands "https://github.com/arunvfx/ulaavi/blob/master/conversion/_commands.py"
    click Operations "https://github.com/arunvfx/ulaavi/blob/master/_operations.py"
    click Utilities "https://github.com/arunvfx/ulaavi/blob/master/_utilities.py"

    %% Styles
    classDef host fill:#e0d4f7,stroke:#555;
    classDef ui fill:#D0E7FF,stroke:#1E70BF;
    classDef data fill:#D4FFD0,stroke:#2E8B57;
    classDef conv fill:#FFE5B4,stroke:#FF8C00;
    classDef util fill:#F0F0F0,stroke:#666;
    classDef external fill:#FFCCCC,stroke:#CC0000;
```
