UsdLayerManager/README.md

USD Layer Manager

A C++17 / Windows desktop application providing a Maya Render Layers-style USD scene editor using OpenUSD v25.05, ImGui 1.92.7 (docking branch), and OpenGL 3.3 (via GLAD). Users can open, edit, and save USD files, manage layered stage overrides, inspect and edit prim properties, and interact with 3D scenes through a Hydra viewport.

Features

• Layer Stack Management — Create, reorder, mute/unmute sublayers with full undo support
• Scene Hierarchy — Browse prim tree with per-type SVG icons; create, delete, rename prims; add/replace references
• Property Editor — Maya Channel Box-style attribute editing with type-aware drag inputs, color pickers, and undoable transforms
• 3D Viewport — Hydra rendering via UsdImagingGLEngine into an offscreen FBO; switchable render delegates; grid overlay; selection bounding boxes; camera wireframes
• Camera Control — Free orbital camera (tumble/truck/dolly) or drive from USD camera prims; auto near/far clipping; frame selection
• Transform Gizmo — Pure ImDrawList-based manipulator (translate/rotate/scale) in object or world space
• Undo/Redo — Full command history for prim creation/deletion, attribute edits, transform changes, and layer operations
• Multi-select — Rectangular selection in viewport with cross-panel syncing

Dependencies

Dependency	Version	Notes
OpenUSD	v25.05	Prebuilt; found via FindOpenUSD.cmake
Dear ImGui	v1.92.7	Docking branch; Win32 + OpenGL3 backends
GLAD	—	OpenGL 3.3 core loader
Python	3.12	Required by OpenUSD runtime (python312.dll)

Build

Prerequisites

• Visual Studio 17 2022 (MSVC v143) with C++17 support
• CMake 3.20+
• Python 3.12 installed at %LOCALAPPDATA%\Programs\Python\Python312\

Steps

cmake --preset default
cmake --build build --config Release
cmake --install build --config Release

The installed App.exe lives in install/bin/.

Presets — default (Release + tests), debug, release, no-tests.

Tests

cmake --build build --config Release
ctest --test-dir build -C Release

Architecture

src/
├── main.cpp                  — Entry point (plugin path init, app lifecycle)
├── core/                     — USD business logic (no UI dependency)
│   ├── UsdStageManager       — Stage open/create/save/close lifecycle
│   ├── LayerManager          — Layer stack introspection and mutation
│   ├── PropertyManager       — Property read/write via edit target
│   ├── CommandHistory        — Undo/redo stack for ICommand instances
│   ├── UsdSceneRenderer      — Hydra rendering + picking + overlays
│   ├── ViewportCamera        — Free / USD-camera-driven orbital camera
│   └── commands/             — ICommand subclasses for all mutable operations
├── ui/                       — ImGui panels and application shell
│   ├── Application           — App shell (owns managers/panels, docking, menus)
│   ├── ImGuiContext          — Win32+OpenGL+ImGui initialization and loop
│   ├── ViewportPanel         — 3D viewport with toolbar, picking, camera
│   ├── SceneHierarchyPanel   — Prim tree browser with context menus
│   ├── PropertyPanel         — Attribute/transform editor (channel box-style)
│   ├── LayerPanel            — Layer stack editor with modal dialogs
│   ├── TransformManipulator  — ImDrawList gizmo (move/rotate/scale)
│   └── IconManager           — SVG icon rasterization via NanoSVG
└── utils/                    — Cross-cutting utilities
    ├── Logger                — Thread-safe logging (file + console)
    ├── FileDialog            — Win32 file open/save dialogs
    ├── PathUtils             — Exe-relative path resolution
    └── GLExt                 — GLAD extension initialization

Key Design Patterns

• Command Pattern — All mutable USD operations go through ICommand → CommandHistory for undo/redo
• Panel-Manager Separation — UI panels hold pointers to core managers but contain no USD layer/prim logic
• Callback Wiring — Cross-panel communication via std::function callbacks (e.g. viewport pick → hierarchy select → property panel update)
• Render-Delegate Plugability — UsdSceneRenderer can switch Hydra render plugins at runtime
• Gizmo as 2D Overlay — TransformManipulator uses pure ImDrawList calls (no GL resources), same approach as ImGuizmo

Project Configuration

Config	Purpose
cmake/modules/FindOpenUSD.cmake	OpenUSD SDK discovery
cmake/modules/FindImgui.cmake	ImGui source integration
cmake/modules/FindGlad.cmake	GLAD loader setup
CMakePresets.json	Build presets (VS 17 2022, x64)
AGENTS.md	AI agent build/architecture guide
.kilo/	Kilo AI configuration (commands, agents, skills)
openspec/changes/	Feature proposals and implementation tracking

Development Workflow

This project uses OpenSpec for feature development:

1. Propose — Create a new change under openspec/changes/<name>/ with proposal.md, design.md, specs/, and tasks.md
2. Implement — Work through checkbox-tracked tasks in tasks.md
3. Archive — Move completed changes to openspec/archive/ when done

Use Kilo's openspec-* skills to streamline this workflow.

Runtime Requirements

• Python 3.12 — OpenUSD requires python312.dll at runtime. CMake copies it to the output directory via POST_BUILD commands.
• USD Plugin Path — The app scans <exe_dir>/usd/ for plugInfo.json and registers plugins via pxr::PlugRegistry.

Contributing

Before writing any OpenUSD API call, verify the API exists in the actual SDK:

findstr /r /s "FunctionName" third_party\OpenUSD_v25.05\include\

Always build and install before running tests:

cmake --build build --config Release
cmake --install build --config Release
ctest --test-dir build -C Release

License

See LICENSE file for details.