# bharathadolf/tinkerusd architecture

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

- Interactive diagram: https://gitdiagram.com/bharathadolf/tinkerusd
- Repository: https://github.com/bharathadolf/tinkerusd

## Overview

##### Project Type and Purpose
- TinkerUsd is a desktop C++ R&D application (Windows-only) for viewing and editing Pixar’s USD scene graphs. It combines a Qt6-based UI, Hydra OpenGL rendering, USD core logic, and embedded Python scripting.

##### Main Components
a. Presentation Layer (UI)
- Qt6 Application (mainWindow, mainMenubar)
- Advanced Docking System (ADS) integration
- Sub-modules:
- Viewport (OpenGL widget + camera controls)
- Outliner (scene hierarchy tree)
- Composition Inspector (layer stack and prim composition)
- Property Editor (MVVM tree view, value editors)
- Script Editor (Python code editor)
b. Core Logic
- USD document management (`core/usdDocument`)
- Global selection service (`core/globalSelection`)
- Utility functions (`core/utils`)
c. Rendering Engine
- Hydra OpenGL adapter (`render/usdRenderEngineGL`)
- Framebuffer object manager (`render/usdDrawTargetFBO`)
d. Python API & Scripting
- C++ → Python bindings (Boost.Python) in `pythonAPI`
- Embedded module (`pythonAPI/python`)
- Global services exposed to scripts
e. Camera System
- Dolly, pan, zoom (`camera/usdCamera`)
f. External Dependencies
- OpenUSD libraries
- Qt6 + ADS docking library
- CMake build system

##### Component Relationships
- UI ←→ Core: UI widgets invoke core services to load, inspect, and modify USD scenes.
- Core ←→ OpenUSD: `usdDocument` wraps USD Stage and Prim operations via Pixar’s API.
- UI ←→ Render: Viewport widget feeds camera transforms and USD data to the Hydra OpenGL engine.
- UI ←→ PythonAPI: Script Editor runs Python code against bound C++ services.
- PythonAPI ←→ Core: Exposed functions allow scripts to manipulate selection and document.
- Camera ←→ Viewport: Input events drive camera object, which signals viewport to redraw.

##### Architectural Patterns & Principles
- Layered architecture:
- Presentation (Qt UI)
- Application services (Core + PythonAPI)
- Data/Rendering (USD + Hydra)
- MVC/MVVM in Property Editor: model, delegate, view separation for USD attribute wrappers.
- Plugin-style extensibility: Python bindings enable runtime script customization.
- Single-entry Qt event loop coordinating all modules.

##### Final Advice
- Interactions with external subsystems (USD, Qt, ADS).
- Review against the file tree to ensure no major component (e.g., camera, pythonAPI) is omitted.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer (UI)
    subgraph "Presentation Layer (UI)"
        direction TB
        MW["Main Window"]:::ui
        MM["Main Menubar"]:::ui
        VP["Viewport\n(OpenGL Widget + Camera Controls)"]:::ui
        OL["Outliner\n(Scene Hierarchy)"]:::ui
        CI["Composition Inspector"]:::ui
        PE["Property Editor"]:::ui
        SE["Script Editor"]:::ui
    end

    %% Core & PythonAPI
    subgraph "Core & Scripting Services"
        direction TB
        USDDoc["USD Document Management"]:::core
        Sel["Global Selection Service"]:::core
        Utils["Utility Functions"]:::core
        PyBind["C++/Python Bindings"]:::core
        PyMod["Embedded Python Module"]:::core
    end

    %% Rendering & Camera
    subgraph "Rendering & Camera"
        direction TB
        RenderGL["Hydra OpenGL Adapter"]:::render
        FBO["Framebuffer Object Manager"]:::render
        Cam["Camera System\n(Dolly, Pan, Zoom)"]:::render
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        USDLib("OpenUSD Libraries"):::external
        QtLib("Qt6 + ADS Docking"):::external
        CMake("CMake Build System"):::external
    end

    %% Interactions
    MW -->|"signals/slots"| USDDoc
    MW -->|"signals/slots"| Sel
    MW -->|"signals/slots"| Utils
    MW -->|"Boost.Python binding"| PyBind
    SE -->|"executes scripts"| PyBind
    PyBind -->|"exposes services"| USDDoc
    PyBind -->|"exposes services"| Sel
    USDDoc -->|"uses USD API"| USDLib
    VP -->|"feeds camera transforms & USD data"| RenderGL
    Cam -->|"drives viewport redraw"| VP
    VP -->|"renders via"| FBO
    VP -->|"renders via"| RenderGL
    VP -->|"signals update"| MW
    OL -->|"requests scene data"| USDDoc
    CI -->|"requests composition"| USDDoc
    PE -->|"requests attributes"| USDDoc
    SE -->|"edits scripts"| PyMod
    PyMod -->|"embedded module"| PyBind
    CMake -->|"builds"| MW

    %% External arrows
    USDDoc -->|"link"| USDLib
    MW -->|"built on"| QtLib
    MW -->|"linked with"| CMake

    %% Click Events
    click MW "https://github.com/bharathadolf/tinkerusd/blob/main/source/ui/mainWindow.cpp"
    click MM "https://github.com/bharathadolf/tinkerusd/blob/main/source/ui/mainMenubar.cpp"
    click VP "https://github.com/bharathadolf/tinkerusd/blob/main/source/ui/viewportOpenGLWidget.cpp"
    click OL "https://github.com/bharathadolf/tinkerusd/blob/main/source/ui/outliner/outlinerWidget.cpp"
    click CI "https://github.com/bharathadolf/tinkerusd/blob/main/source/ui/composition/compositionInspectorWidget.cpp"
    click PE "https://github.com/bharathadolf/tinkerusd/blob/main/source/ui/propertyEditor/propertyWidget.cpp"
    click SE "https://github.com/bharathadolf/tinkerusd/blob/main/source/ui/scriptEditor/scriptEditor.cpp"
    click USDDoc "https://github.com/bharathadolf/tinkerusd/blob/main/source/core/usdDocument.cpp"
    click Sel "https://github.com/bharathadolf/tinkerusd/blob/main/source/core/globalSelection.cpp"
    click Utils "https://github.com/bharathadolf/tinkerusd/blob/main/source/core/utils.cpp"
    click RenderGL "https://github.com/bharathadolf/tinkerusd/blob/main/source/render/usdRenderEngineGL.cpp"
    click FBO "https://github.com/bharathadolf/tinkerusd/blob/main/source/render/usdDrawTargetFBO.cpp"
    click PyBind "https://github.com/bharathadolf/tinkerusd/blob/main/source/pythonAPI/api.h"
    click PyMod "https://github.com/bharathadolf/tinkerusd/blob/main/source/pythonAPI/python/module.cpp"
    click Cam "https://github.com/bharathadolf/tinkerusd/blob/main/source/camera/usdCamera.cpp"
    click CMake "https://github.com/bharathadolf/tinkerusd/blob/main/source/CMakeLists.txt"

    %% Styles
    classDef ui fill:#CCE5FF,stroke:#0044CC,stroke-width:1px;
    classDef core fill:#CCFFCC,stroke:#008800,stroke-width:1px;
    classDef render fill:#FFE0CC,stroke:#CC7700,stroke-width:1px;
    classDef external fill:#DDDDDD,stroke:#777777,stroke-width:1px;
```
