Creations & Frames
OpenGPEX uses a unique "Creation" model for managing multiple open images — powered by a floating TabDock that offers a more fluid experience than traditional file tabs.
What is a Creation?
In OpenGPEX, each open image or project is called a Creation (internally a "Frame"). Think of it as:
- A single canvas with its own dimensions
- Its own layer stack (multiple layers within one creation)
- Its own undo history (independent per-creation)
- Its own viewport state (zoom, pan, rotation)
You can have multiple Creations open simultaneously and switch between them instantly.
Creation vs. Layer
| Concept | What it is | Example |
|---|---|---|
| Creation (Frame) | An independent canvas/document | "My Photo", "Logo Design" |
| Layer | A single element within a Creation | Background image, text overlay, paint strokes |
Analogy: If a Creation is a "painting", then Layers are the individual "transparent sheets" stacked to compose that painting.
The TabDock
The TabDock is the floating control panel that manages all your open Creations. It appears as a compact dock (similar to the macOS Dock) that you can position anywhere in the workspace.
Appearance
- Collapsed: Shows only the active creation's thumbnail (auto-hides when not needed)
- Expanded: Hover to reveal all open creations as thumbnails with controls
Basic Operations
| Action | How |
|---|---|
| Switch Creation | Click a thumbnail in the Dock |
| Next Creation | Alt + → |
| Previous Creation | Alt + ← |
| Close Creation | Hover a thumbnail → click the ✕ button |
| Reorder | Drag thumbnails to rearrange their order |
| Move Dock | Drag the grip handle (⋮⋮) to reposition the Dock |
| Viewport Settings | Click the gear icon in the expanded Dock |
Note: Creation switching (Alt + ← / →) cycles through trunk creations only — branches are reached from their trunk's branch menu.
Trunk & Branch (Parent–Child Creations)
One of the most powerful concepts in OpenGPEX is the Trunk/Branch hierarchy:
What is a Branch?
When you derive a new creation from an existing one (e.g., via "Create Branch" from a selection), the new creation becomes a Branch of the original Trunk.
How Branches are Created
- Create Branch: Use the Create Branch button in the Clip toolbar to extract a selected region into a new Creation as a branch of the current trunk
- AI Multi-Image Results: When AI tools (ComfyUI, etc.) return multiple images, the first becomes the trunk and additional results are attached as branches
Visual Indicators
- Branch count badge: A number badge appears on trunk thumbnails showing how many branches exist
- Branch menu: Hover over a trunk thumbnail to see all its branches in a popup
- Indentation: Optionally indent branches to show hierarchy (configurable)
- Color coding: Active trunk = orange ring; active branch of a trunk = indigo ring
Why Branches?
In traditional image editors, opening many files leads to a cluttered tab bar where unrelated images mix with derived versions — making organization difficult. The Trunk/Branch model solves this by:
- Automatic grouping: Derived images are nested under their source, keeping the Dock clean even with many open files
- Visual hierarchy: One glance at the Dock shows which images are standalone and which are related sets
- Quick navigation: Hover a trunk to instantly see and switch to any of its branches
- Context preservation: When working on a branch, you always know which original it came from
Dock Configuration
Access Viewport Settings (gear icon in the Dock) to customize:
Snap Position
The dock can snap to three positions along the bottom edge of the viewport:
BL ─────── BC ─────── BR
Default: BC (bottom-center). You can also freely drag the dock anywhere and it will remember the manual position.
Options
| Setting | Description |
|---|---|
| Show Props | Always show all thumbnails (vs. only active) |
| Indent Branches | Visually indent branches in the branch menu |
| Metrics HUD | Show/hide FPS, memory, and coordinate display |
Metrics HUD
When enabled, the Dock displays a compact heads-up display:
| Metric | Description |
|---|---|
| FPS | Real-time frames-per-second (green = 50+, amber = 30-49, red = <30) |
| Mem | JavaScript heap memory usage (Chrome only) |
| World | Mouse cursor position in world coordinates |
| Local | Mouse cursor position in local (canvas) coordinates |
This is useful for precision work and performance monitoring.
Tips
- The dock auto-expands on hover and collapses when you move away — it stays out of your way
- Each creation maintains its own undo stack, so switching between creations won't affect your undo history
- You can have dozens of creations open without performance issues (only the active one renders at full quality)
- Close creations you no longer need to free up memory
Next Steps
- Workspace Basics — Layout and navigation
- Layer Management — Working with layers within a Creation
- Selection & Clipping — Creating branches from selections
Last updated: 2026-07-30