SideFX Houdini customization package
git clone https://git.lucas.co/hou-control.git
GEMINI.md (3.7K)
1 # GEMINI.md - Project Context for hou-control (hc)
2
3 ## Project Overview
4 `hou-control` (hc) is a specialized SideFX Houdini customization package. It enhances Houdini's workflow through custom Python wrapper classes, hotkey-driven navigation, UI enhancements (HC Panel), and specialized viewer states.
5
6 ### Core Technologies
7 - **Python 3.13:** The primary language for logic, running within Houdini's embedded environment.
8 - **PySide6:** Used for custom UI elements like the `SelectionDialog` (HC Panel).
9 - **VEX:** Used for geometry processing and custom SOP/COP logic in HDAs.
10 - **XML:** Defines Houdini's main menus and network view menus.
11 - **JSON:** Manages hotkey assignments (`hc_hotkeys.json`) and project settings (`hc_settings.json`).
12
13 ## Architecture & Key Components
14
15 ### Wrapper Hierarchy (`python3.13libs/hc/`)
16 The project uses a "wrapper" pattern rather than inheritance for `hou` API objects:
17 - **`HCSession`**: Central entry point. Manages desktop-wide state, visibility, and launches the HC Panel.
18 - **`HCPane`**: Wraps `hou.Pane`. Handles splitting and pane-level logic.
19 - **`HCTab` / `HCNetworkEditor` / `HCSceneViewer`**: Specialized wrappers for different Houdini pane tabs.
20
21 ### Dispatch & Commands
22 - **`HCMaps` (`hcmaps.py`)**: A central registry that maps human-readable command names to bound methods. This is used to populate the HC Panel selection dialog.
23 - **`HCWidgets.SelectionDialog`**: The UI backend for the HC Panel (Alt+Shift+D).
24
25 ### Integration Scripts
26 - **`uiready.py`**: Runs once Houdini's UI is initialized.
27 - **`nodegraphhooks.py`**: Hooks into the network editor for custom event handling.
28 - **`123.py` / `456.py`**: Houdini's startup and scene-load scripts.
29
30 ## Workflows: Building & Running
31 Since this is a runtime package, there is no traditional "build" step.
32
33 ### Applying Changes
34 To exercise code changes without restarting Houdini:
35 1. **Reload Python Logic**: Use the **"Reload HC"** command from the HC Panel or HC Menu. This clears `hc.*` from `sys.modules` and re-imports.
36 2. **Reload Hotkeys**: Use **"Reload Hotkeys"**. This re-reads `hc_hotkeys.json` and updates Houdini's internal binding table.
37 3. **Reload Colors/Keycam**: Use specific "Reload" commands for these assets.
38
39 ## Development Conventions
40
41 ### General Engineering Standards
42 - **Surgical Updates**: Prioritize minimal, precise changes that follow local patterns.
43 - **No Direct Subclassing**: Never subclass `hou.*` types. Use the established wrapper pattern.
44 - **Type Discrimination**: Use `.type()` string checks (e.g., `tab.type() == 'HCNetworkEditor'`) instead of `isinstance`.
45 - **Environment Paths**: Build file paths using `hou.getenv("HC_PATH")` to remain portable.
46
47 ### Node Graph Logic
48 - **Snapping**: Nodes should snap to grid intersections. Note that in recent versions, `node.position()` refers to the **bottom-left corner**, while the standard visual center is offset by approximately `(0.5, 0.15)` for typical nodes.
49 - **Hierarchical Movement**: Keyboard shifting (Alt+HJKL) supports hierarchy modifiers:
50 - `Ctrl`: Downstream (descendants).
51 - `Shift`: Upstream (ancestors).
52
53 ### Testing
54 - **Agent Tests**: Use the `agent_tests/` directory for investigative or verification scripts (e.g., `test_hierarchy.py`).
55 - **RPC Support**: The project supports RPyC on port `18811`, allowing external tools to execute code directly in the running Houdini session.
56
57 ## Key Files
58 - `CLAUDE.md`: Highly detailed technical documentation and architectural reference.
59 - `hc_hotkeys.json`: Source of truth for all custom keyboard shortcuts.
60 - `python3.13libs/hc/hcsession.py`: Main session logic and entry points.
61 - `python3.13libs/hc/hcnetworkeditor.py`: Node graph navigation and manipulation logic.
62 - `agent_tests/`: Persistent test suite for agent-implemented features.