# vinavfx/stockmanager-for-nuke architecture

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

- Interactive diagram: https://gitdiagram.com/vinavfx/stockmanager-for-nuke
- Repository: https://github.com/vinavfx/stockmanager-for-nuke

## Overview

##### Project Type and Purpose
- This is a Python-based Nuke plugin (“Stock Manager”) that indexes folders of video/texture files, generates lightweight JPG previews, and provides an interactive UI inside Nuke for browsing, filtering, and loading those assets.
- Key responsibilities: file‐system scanning (indexing), in-memory catalog of “stocks,” preview generation (via FFmpeg/ImageMagick), and two dockable UI panels in Nuke.

##### Main Architectural Components
A. Configuration
- env.py: holds INDEXING_DIR & ROOT_STOCKS_DIRS – drives where stocks are discovered and where thumbnails live.
B. Indexing Service
- scripts/indexing.py: command-line script that reads ROOT_STOCKS_DIRS, invokes FFmpeg/ImageMagick to produce JPGs into INDEXING_DIR, and builds an on-disk metadata cache.
C. In-Memory Model
- src/stocks.py: defines Stock objects and collection; loads metadata from the on-disk index into RAM for ultra-fast search.
D. Controller / Business Logic
- src/stock_manager.py: orchestrates initialization, event routing, and communication between model and UI panels.
- nuke_util/ & python_util/: helper modules for Nuke API calls and generic utilities.
E. View / UI
- src/player_panel.py & src/stocks_panel.py: define Qt/PySide panels embedded in Nuke’s interface—display thumbnails, filter bar, status bar, and preview grid/list.
F. External Processes
- FFmpeg & ImageMagick: invoked by the indexing script and potentially on-the-fly preview requests.

##### Component Interactions and Data Flow
1) Configuration (env.py) feeds paths into the Indexing Service.
2) Indexing Service scans file system → generates JPG thumbnails → writes metadata to INDEXING_DIR.
3) On plugin launch (via import in menu.py), Stock Manager loads metadata from INDEXING_DIR → populates In-Memory Model.
4) User opens Stocks Panel → Controller binds model to view → initial thumbnail grid rendered.
5) User filters or searches → Controller requests subset from In-Memory Model → View updates display.
6) User clicks an item → Controller calls Nuke API (via nuke_util) to load asset into the current node, optionally spawning a Player Panel for video playback.
7) If needed, Controller can invoke FFmpeg/ImageMagick on demand for custom thumbnail sizes or video scrubbing.

##### Architectural Patterns and Principles
- Plugin Architecture: loose coupling between Nuke host and Stock Manager module (import via menu.py).
- MVC-style separation:
- Model = src/stocks.py (in-memory data)
- View = Qt panels (player_panel.py, stocks_panel.py)
- Controller = stock_manager.py + util modules.
- Single Responsibility: indexing, config, UI, and business logic each live in dedicated directories/files.
- In-memory caching for performance (fast search and UI response).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Batch Indexing
    subgraph "Batch Indexing"
        Config["env.py"]:::internal
        RawStocks["ROOT_STOCKS_DIRS"]:::external
        Indexer["Indexing Service<br>(scripts/indexing.py)"]:::internal
        FFmpeg["FFmpeg"]:::external
        IMagick["ImageMagick"]:::external
        MetadataStore["Metadata Store<br>(JSON index, JPGs)"]:::data
    end

    %% Interactive UI Mode
    subgraph "Interactive UI (Inside Nuke)"
        NukeHost["Nuke Host"]:::nuke
        Controller["Controller<br>(stock_manager.py)"]:::internal
        Model["In-Memory Model<br>(stocks.py)"]:::internal
        NukeUtil["Nuke Utils"]:::internal
        PyUtil["Python Utils"]:::internal
        StocksPanel["Stocks Panel<br>(stocks_panel.py)"]:::internal
        PlayerPanel["Player Panel<br>(player_panel.py)"]:::internal
    end

    %% Data Flow - Batch Indexing
    Config -->|"provide paths"| Indexer
    RawStocks -->|"file scan"| Indexer
    Indexer -->|"generate thumbnails"| FFmpeg
    Indexer -->|"generate thumbnails"| IMagick
    Indexer -->|"write metadata"| MetadataStore

    %% Data Flow - Interactive UI
    MetadataStore -->|"load metadata"| Model
    NukeHost -->|"import plugin"| Controller
    Controller -->|"load metadata"| Model
    Model -->|"data for UI"| StocksPanel
    StocksPanel -->|"user action"| Controller
    Controller -->|"query"| Model
    Controller -->|"invoke Nuke API"| NukeUtil
    Controller -->|"invoke util"| PyUtil
    Controller -->|"spawn player"| PlayerPanel
    Controller -->|"on-demand thumbnail"| FFmpeg
    Controller -->|"on-demand thumbnail"| IMagick
    Controller -->|"load asset"| NukeHost

    %% Click Events
    click Config "https://github.com/vinavfx/stockmanager-for-nuke/blob/main/env.py"
    click Indexer "https://github.com/vinavfx/stockmanager-for-nuke/blob/main/scripts/indexing.py"
    click Model "https://github.com/vinavfx/stockmanager-for-nuke/blob/main/src/stocks.py"
    click Controller "https://github.com/vinavfx/stockmanager-for-nuke/blob/main/src/stock_manager.py"
    click NukeUtil "https://github.com/vinavfx/stockmanager-for-nuke/tree/main/nuke_util/"
    click PyUtil "https://github.com/vinavfx/stockmanager-for-nuke/tree/main/python_util/"
    click StocksPanel "https://github.com/vinavfx/stockmanager-for-nuke/blob/main/src/stocks_panel.py"
    click PlayerPanel "https://github.com/vinavfx/stockmanager-for-nuke/blob/main/src/player_panel.py"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#0366d6,color:#000;
    classDef external fill:#d9ead3,stroke:#38761d,color:#000;
    classDef nuke fill:#f9cb9c,stroke:#b45f06,color:#000;
    classDef data fill:#fff2cc,stroke:#bf9000,color:#000;
```
