# nvidia-omniverse/kit-extension-sample-defectsgen architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia-omniverse/kit-extension-sample-defectsgen
- Repository: https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen

## Overview

##### Project type and purpose
- This is not a standalone client-server or web app but an NVIDIA Omniverse Kit extension (“Defect Extension Sample”). It plugs into an Omniverse-based application (e.g., Omniverse Code or Create) to generate synthetic defects on 3D prims via the Replicator API.

##### File structure
- Top level:
- exts/omni.example.defects – the extension’s code, assets, docs, and config
- link_app.{bat,sh} – helper for creating a symlink named “app” pointing to an Omniverse Kit app install
- tools/packman – scripts and configs for packaging/distribution (Packman tool)
- tools/scripts – convenience scripts (e.g., link_app.py)
- Inside exts/omni.example.defects:
- config/extension.toml – extension metadata
- data/ – sample textures, thumbnails for defects
- docs/ – user docs (CHANGELOG, README)
- omni/example/defects/… – Python modules: extension.py (entry point), replicator_defect logic, UI widgets, utilities

##### README for additional insights
- The extension registers UI panels and commands in the host app
- It uses the Omniverse Replicator API to project images onto a prim and spawn replicated defects
- It requires Omniverse Code ≥ 2022.3.3
- Provides guidance on linking the extension folder into an Omniverse Kit app and packaging via Packman

##### Components
a. Main components:
- Host Application (Omniverse Kit/Code/Create)
- Extension Manager (in the host app)
- Defect Extension bundle:
– extension.toml (metadata)
– Python modules (extension.py, replicator_defect.py, widgets, style, utils)
– Data assets (textures, thumbnails)
– Documentation (docs folder)
- Omniverse Replicator API (synthetic data engine)
- USD Stage / Scene Graph (underlying 3D scene)
- Packman packaging tool & scripts (tools/packman)
- Linking Scripts (link_app.bat/sh + tools/scripts/link_app.py)
b. Relationships and interactions:
1. Host App → loads → Extension Manager → discovers → Defect Extension
2. Extension entry point (extension.py) registers UI panels and commands in host
3. User interacts with UI widgets → triggers replicator_defect logic
4. Replicator API reads image assets → writes prim vars via OgnWritePrimVars → modifies USD Stage
5. Packman scripts invoke packaging/build steps for distribution
6. link_app scripts create a symlink “app” so that the extension can be loaded locally by the host
c. Architectural patterns / design principles:
– Plugin architecture (host app + extension)
– MVC-style separation inside the extension:
- View: Widgets and style modules
- Controller: extension.py routes user commands to replicator_defect
- Model: Data assets and USD scene state
– Configuration-driven (extension.toml) and data-driven (asset folders)
d. Key technologies/frameworks:
– Python 3 for extension logic
– NVIDIA Omniverse Kit / Code / Create (C++ host with Python bindings)
– Omniverse Replicator API (Python SDK)
– USD (Universal Scene Description)
– TOML for metadata
– Packman for packaging
– Shell/batch/Powershell scripts for linking

##### Detail
- TOML file as the metadata that the Extension Manager reads to register the extension
- Both the runtime flow (loading, user actions, API calls) and the build/distribution flow (packman, linking)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Components
    OmniverseApp["Omniverse Kit App"]:::runtime
    ExtManager["Extension Manager"]:::runtime

    %% Defect Extension Bundle
    subgraph "Defect Extension"
        direction TB
        Metadata["extension.toml"]:::data
        Controller["extension.py"]:::runtime
        Model["replicator_defect.py"]:::runtime
        Utils["utils.py"]:::runtime

        subgraph "UI (View)"
            direction TB
            Widgets1["rep_widgets.py"]:::runtime
            Widgets2["widgets.py"]:::runtime
            Window["window.py"]:::runtime
            Style["style.py"]:::runtime
        end

        subgraph "Data Assets"
            direction TB
            AssetsDir["data/"]:::data
            SubAssets1["data/.thumbs/256x256"]:::data
            SubAssets2["data/scratches"]:::data
        end

        subgraph "Documentation"
            direction TB
            Doc1["README.md"]:::docs
            Doc2["CHANGELOG.md"]:::docs
            Doc3["OgnWritePrimVars.rst"]:::docs
        end
    end

    %% External Services
    ReplicatorAPI["Omniverse Replicator API"]:::runtime
    USDStage["USD Stage / Scene Graph"]:::runtime

    %% Build / Packaging Tools
    subgraph "Build & Packaging"
        direction TB
        Packman["Packman Tool & Scripts"]:::build
        LinkScripts["Link Scripts"]:::build
    end

    %% Connections
    OmniverseApp -->|"loads"| ExtManager
    ExtManager -->|"discovers & loads"| Controller
    Controller -->|"reads metadata"| Metadata
    Controller -->|"registers UI"| Widgets1
    Widgets1 -->|"invokes"| Model
    Model -->|"calls API"| ReplicatorAPI
    ReplicatorAPI -->|"updates"| USDStage
    Model -->|"reads assets"| AssetsDir
    Controller -->|"uses utils"| Utils
    Packman -->|"packages extension"| Controller
    LinkScripts -.->|"creates symlink 'app'"| OmniverseApp

    %% Click Events
    click Metadata "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/config/extension.toml"
    click Controller "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/omni/example/defects/extension.py"
    click Model "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/omni/example/defects/replicator_defect.py"
    click Widgets1 "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/omni/example/defects/rep_widgets.py"
    click Widgets2 "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/omni/example/defects/widgets.py"
    click Window "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/omni/example/defects/window.py"
    click Style "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/omni/example/defects/style.py"
    click Utils "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/omni/example/defects/utils.py"
    click AssetsDir "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/tree/main/exts/omni.example.defects/data/"
    click SubAssets1 "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/tree/main/exts/omni.example.defects/omni/example/defects/data/.thumbs/256x256"
    click SubAssets2 "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/tree/main/exts/omni.example.defects/omni/example/defects/data/scratches"
    click Doc1 "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/docs/README.md"
    click Doc2 "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/docs/CHANGELOG.md"
    click Doc3 "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/exts/omni.example.defects/omni/example/defects/docs/OgnWritePrimVars.rst"
    click Packman "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/tree/main/tools/packman/"
    click LinkScripts "https://github.com/nvidia-omniverse/kit-extension-sample-defectsgen/blob/main/link_app.bat"

    %% Styles
    classDef runtime fill:#E3F2FD,stroke:#1E88E5
    classDef build fill:#FFF3E0,stroke:#FB8C00
    classDef data fill:#E8F5E9,stroke:#43A047
    classDef docs fill:#F3E5F5,stroke:#8E24AA
```
