🎙️ Flight Deck Announcement: "Ladies and gentlemen, please stow your random seed generators in the upright position. We have reached cruising altitude in $\mathbb{R}^{65,536}$ and the slot machine is officially out of service."

</div>

🧭 Master Navigation Index

What Is Gimbal?
Visual Showcase & Galleries
Installation
🎯 Getting Started & How to Use
🛠️ Complete Flight Instrument Catalog (Node Reference)
📋 Canonical Workflow Guides
🔬 Mathematical & Theoretical Deep Dives
📖 Project History
📚 Documentation Archives & Research Papers
🏷️ Brand Standards

What Is Gimbal?

Every diffusion artist knows the feeling: you have a vivid creative vision, but your tools offer a high-stakes slot machine. Change the seed, roll again, pray to the VAE gods, and hope something vaguely close emerges from the noise. Gimbal exists to officially decommission that loop.

Gimbal is a suite of latent-space flight instruments — 19 ComfyUI custom nodes that let you navigate the high-dimensional manifold of a diffusion model the way a pilot navigates the sky: with exact coordinates, heading, altitude, and intent. Instead of re-rolling seeds and hoping a random walk lands somewhere interesting, you plot a flight plan, hold your orientation, and land right on your target runway.

[!TIP] Co-Pilot's Log: Why spend 45 minutes re-rolling seeds like a casino regular when you can vector-steer straight to your target coordinates and still have time for a coffee break?

Core Capabilities at a Glance

🖼️ Visual Showcase & Galleries

<img src="assets/brand/gimbal_social_preview.png" alt="Gimbal Social Preview" width="800"/> <table> <tr> <td align="center"><img src="assets/brand/gimbal_02_cinematic_steering_showcase.png" width="380"/> Workflow 02: Cinematic Steering 100% vehicle silhouette lock with text-steered cyberpunk lighting.</td> <td align="center"><img src="assets/brand/gimbal_08_harmonic_orbiter_showcase.png" width="380"/> Workflow 08: Harmonic Orbiter Constant-radius closed-loop geodesic 360° tour.</td> </tr> <tr> <td align="center"><img src="assets/brand/gimbal_09_subspace_material_showcase.png" width="380"/> Workflow 09: Subspace Material Subspace channel decoupling (Concrete → Chrome → Velvet).</td> <td align="center"><img src="assets/brand/gimbal_04_semantic_slider_showcase.png" width="380"/> Workflow 04: Brand Lighting Photometric lighting transfer across luxury product categories.</td> </tr> </table>

Sample Output Comparisons

📁 Explore all 206 test renders and 3 interactive HTML HUD galleries in the Visual Asset & Gallery Index.

🚀 Installation

System Requirements

ComfyUI (any recent build)
Python: 3.10+
PyTorch: 2.0+ with CUDA (RTX 3060 / 40-series tested) or CPU
Supported Architectures: SD 1.5, SDXL 1.0 (4-channel), SD 3.5, FLUX.1 (16-channel)

Step-by-Step Installation

# 1. Navigate to your ComfyUI custom_nodes folder
cd ComfyUI/custom_nodes

# 2. Clone the repository
git clone https://github.com/form-and-noise/ComfyUI-Gimbal.git

# 3. Install requirements
pip install -r ComfyUI-Gimbal/requirements.txt

# 4. Restart ComfyUI

All nodes will appear in the ComfyUI Add Node → Gimbal/* menu, organized into 7 logical flight categories.

🎯 Getting Started & How to Use Guide

The Core Mental Model

Traditional diffusion treats latent tensors as random noise that the UNet denoises into an image. Gimbal treats the latent tensor $\mathbf{z} \in \mathbb{R}^{C \times H \times W}$ as a geometric point in a high-dimensional vector space ($D = 65,536$ dimensions).

   ┌─────────────────────────────────────────────────────────────┐
   │                    THE GIMBAL FLIGHT DECK                   │
   │                                                             │
   │   🧭 COMPASS PRO        🗺️ MANIFOLD EXPLORER   📍 GPS ANCHOR│
   │   [Vector Steering]     [2D Topology Grids]    [Save Point] │
   │          ▲                       ▲                   ▲      │
   │          └───────────────────────┼───────────────────┘      │
   │                                  │                          │
   │                    🌉 CROSS-MODAL BRIDGE                    │
   │                    [Natural Language Input]                 │
   │                                  │                          │
   │                    🛡️ LATENT STABILIZER                     │
   │                    [LAMNr Quality Filter]                   │
   └─────────────────────────────────────────────────────────────┘

Tutorial 1: Your First Concept Blend (2-Minute Quick Start)

Goal: Blend a Redwood Forest with a Mountain Summit at a precise 50% geometric midpoint without muddy colors.

┌─────────────────────────────────────────────────────────────────┐
│              CONCEPT BLENDER — WIRING DIAGRAM                    │
│                                                                   │
│  [Prompt A: "dense redwood forest"]                               │
│       └──► KSampler A (denoise=1.0) ──► latent_A ──┐             │
│                                                     ▼             │
│  [Prompt B: "rocky mountain summit"] ──► 🧭 Gimbal Compass Pro   │
│       └──► KSampler B (denoise=1.0) ──► latent_B ──┘             │
│                                           (mode: Slerp, t=0.50)   │
│                                                │                  │
│                                                ▼                  │
│                                         KSampler (final)         │
│                                         (denoise=0.90, CFG=5.5)   │
│                                                │                  │
│                                                ▼                  │
│                                           VAEDecode ──► 🖼️ Image  │
└─────────────────────────────────────────────────────────────────┘

Step-by-Step Instructions:

Create two standard text prompts: Prompt A (Redwood Forest) and Prompt B (Mountain Summit).
Wire each prompt into its own KSampler running denoise = 1.0 to generate two raw concept latents (latent_A and latent_B).
Add a 🧭 Gimbal Compass Pro node (Add Node → Gimbal/Flight Instruments → Gimbal Compass Pro).
Connect latent_A to base_latent and origin_latent. Connect latent_B to target_latent.
Set mode = "Slerp" and strength = 0.50.
Pass latent_out into a final KSampler set to denoise = 0.90, CFG = 5.5, steps = 25.
Decode with VAEDecode and save. You now have a photorealistic, crisp 50% hybrid environment.

📖 Full Workflow Guide: Workflow 01: Concept Blender

Tutorial 2: Natural Language Lighting Steering

Goal: Take an existing car or portrait and change the atmosphere to "Cyberpunk Midnight" while locking the vehicle silhouette 100%.

[Base Latent: Studio Car Render] ──┐
                                   ▼
[🌉 Cross-Modal Bridge] ──► 🧭 Compass Pro (Orthogonal_Projection, strength=1.5)
  instruction = "dark cool neon"   │
                                   ▼
                        [🛡️ Latent Stabilizer] (psi=0.88, scale_cap=8.0)
                                   │
                                   ▼
                        [KSampler: Refine] (denoise=0.55, CFG=3.8) ──► [VAEDecode]

Generate or VAE-encode your base subject into BASE_LATENT.
Add a 🌉 Gimbal Cross-Modal Bridge node. Type "dark cool neon cyberpunk cinematic" into instruction.
Connect direction_latent from the Bridge to target_latent of a 🧭 Compass Pro. Connect BASE_LATENT to base_latent.
Set Compass mode to Orthogonal_Projection and strength = 1.50.
Wire latent_out through a 🛡️ Gimbal Latent Stabilizer (truncation_psi = 0.88, scale_cap = 8.0).
Pass into a refinement KSampler with denoise = 0.55 and CFG = 3.8. The car's body panels and reflections remain identical, but all lighting and background atmosphere shift to neon cyberpunk.

📖 Full Workflow Guide: Workflow 02: Text-Steered Lighting

Tutorial 3: 2D Neighborhood Mapping (Manifold Grid)

Goal: Explore 9 variations of a concept across two independent visual axes in a single render batch.

Connect your center starting latent to center_latent of 🗺️ Gimbal Manifold Explorer.
Connect a "Warm Earthy" vector to x_vector and a "Cool Obsidian" vector to y_vector (from Cross-Modal Bridge).
Set grid_size_x = 3, grid_size_y = 3, x_strength = 1.5, y_strength = 1.5, interpolation_mode = "Slerp".
Connect the output latent_batch (9 latents) to a refinement KSampler with denoise = 0.50.
Pass decoded images to 🪡 Gimbal Grid Stitch (columns = 3) to view all 9 variations in a clean contact sheet.

📖 Full Workflow Guide: Workflow 03: Manifold Grid

Tutorial 4: Bookmarking Latents with GPS Waypoints

Goal: Extract the best image from a 9-image manifold grid, save its coordinates to disk, and reload it in a future session.

Add a 📍 Gimbal GPS Anchor node. Connect latent_batch from your Manifold Explorer.
Set select_index = 4 (picks the center cell) and save_waypoint = True.
Give it a name: waypoint_name = "golden_arch_hero_v1".
When executed, Gimbal writes output/gimbal/golden_arch_hero_v1.json with full tensor coordinates, statistics, and cryptographic SHA-256 hash.
In any future workflow or session, add a 📂 Gimbal GPS Load node, point to that JSON file, and immediately resume navigation from that exact location.

📖 Full Workflow Guide: Workflow 04: Brand-Locked Lighting

The 5 Golden Rules of Latent Flight

🛫 Pre-Flight Safety Checklist: Disregarding these rules may result in mid-air spatial collisions, deep-fried pixel turbulence, or unexpected character re-skinning.

Step-0 Noise vs. Mid-Denoise (The Early Bird Rule): Always perform concept blends (SLERP) on Step-0 Gaussian initial noise before spatial feature maps crystallize into stubborn real estate. Intercepting latents at Step 8 is like trying to redesign an airplane while it's landing—it forces grotesque boundary re-skinning (tree trunks morphing violently into rock spires).
Refinement Denoise Sweet Spot ($0.45 – 0.60$): When refining latents modified by Compass Pro or Manifold Explorer, keep denoise between $0.45$ and $0.60$. Higher denoise ($>0.70$) completely overwrites your carefully calculated flight path; lower denoise ($<0.35$) leaves behind raw, un-denoised math artifacts that look like abstract mathematical soup.
Drop CFG During Refinement ($3.5 – 4.5$) (Don't Yell at the UNet): Since Gimbal has already injected clear semantic direction into the latent tensor, high guidance ($>6.5$) will over-drive the signal and deep-fry your images with crispy black wireframe outlines.
Use Orthogonal Projection for Geometry Lock: When steering lighting or atmosphere on an existing image, always set Orthogonal_Projection mode. This decomposes the change vector perpendicular to your subject—allowing you to repaint the sky neon cyberpunk without accidentally altering the shape of your sports car.
Always Deploy Latent Stabilizer After Steering: When applying high text-steering gains, insert GimbalLatentStabilizer ($\psi = 0.88$, $\text{cap} = 8.0$) before your final KSampler. Think of it as your automatic flight stabilizer—reining in outlier noise spikes before they cause visual turbulence.

🛠️ Complete Flight Instrument Catalog (Nodes)

| Instrument Name | ComfyUI Display Name | Category | Primary Function & Mathematical Core | Documentation | | :--- | :--- | :--- | :--- | :--- | | GimbalCompass_Pro | 🧭 Gimbal Compass Pro | Flight Instruments | Vector arithmetic, $\mu$-SLERP, and orthogonal projection steering. | compass_pro.md | | GimbalManifold_Explorer | 🗺️ Gimbal Manifold Explorer | Flight Instruments | 2D $\mu$-centered orthogonal latent topography grid synthesis. | manifold_explorer.md | | GimbalCrossModalBridge | 🌉 Gimbal Cross-Modal Bridge | Conditioning | Calibrated keyword-to-subspace signature projection. | crossmodal_bridge.md | | GimbalCircularOrbit | 🔄 Gimbal Circular Orbit | Trajectory | Constant-radius closed-loop geodesic orbits ($z(\theta) = \mu + r(\cos\theta\mathbf{u} + \sin\theta\mathbf{v})$). | circular_orbit.md | | GimbalWaypointSpline | 〰️ Gimbal Waypoint Spline | Trajectory | Spherical Catmull-Rom geodesic spline multi-stop flight path. | waypoint_spline.md | | GimbalSemanticSlider | 🎚️ Gimbal Semantic Slider | Decomposition | Real-time SVD/PCA batch covariance decomposition attribute isolation. | semantic_slider.md | | GimbalGPS_Anchor | 📍 Gimbal GPS Anchor (Save) | Navigation | Extracts single latents, computes hashes, and saves JSON waypoints. | gps_anchor.md | | GimbalGPS_Load | 📂 Gimbal GPS Load | Navigation | Recalls saved cryptographic waypoint tensors and provenance metadata. | gps_load.md | | GimbalChannelSplit | 🔀 Gimbal Channel Split | Subspace | Decouples 4-ch (SDXL) or 16-ch (FLUX) into frequency sub-bands. | channel_split.md | | GimbalChannelMerge | 🔁 Gimbal Channel Merge | Subspace | Lossless concatenation and recomposition of split latent bands. | channel_merge.md | | GimbalChannelScale | ⚖️ Gimbal Channel Scale | Subspace | Independent per-channel frequency gain and amplitude control. | channel_scale.md | | GimbalLatentStabilizer | 🛡️ Gimbal Latent Stabilizer | Stabilizer | Full LAMNr pipeline: Woodbury denoise, scale cap, and $\psi$ shrinkage. | latent_stabilizer.md | | GimbalTruncation | 📉 Gimbal Truncation | Quality | Surgical variance shrinkage toward centroid ($z' = \mu + \psi(z-\mu)$). | truncation.md | | GimbalLatentMath | 🔢 Gimbal Latent Math | Primitives | Full dispatcher exposing all 13 LAMNr primitives in a single node. | latent_math.md | | GimbalDiagnostics | 📊 Gimbal Diagnostics | Telemetry | Real-time tensor readout: min, max, mean, std, L2 norm, channel variance. | diagnostics.md | | GimbalLatentTelemetry | 📡 Gimbal Latent Telemetry | Telemetry | Research-grade OOD metrics: Exact Log-Likelihood, Mahalanobis, TC. | latent_telemetry.md | | GimbalVectorAnalogy | ➕ Gimbal Vector Analogy | Arithmetic | Concept arithmetic ($A - B + C$) with orthogonal projection safeguards. | vector_analogy.md | | GimbalLikenessIsolator| 🎭 Gimbal Likeness Isolator | Conditioning | Differential LoRA probe decoupling identity tokens from scene style. | likeness_isolator.md | | GimbalGridStitch | 🪡 Gimbal Grid Stitch | Utility | Stitches multi-sample batches into composite image contact sheets. | grid_stitch.md |

📋 Canonical Workflow Guides

🔬 Mathematical & Theoretical Deep Dives

For power users, machine learning engineers, and researchers seeking the mathematical formulations underlying Gimbal:

What is Latent Space? — Intuitive guide to high-dimensional manifold topology and VAE compression.
SLERP vs. LERP: Why the Arc Matters — Mathematical derivation of midpoint variance collapse and empirical $\mu$-centered SLERP (Equation E4).
The Gaussian Annulus Theorem — Proof of why high-dimensional mass concentrates on a thin hypersphere shell in $\mathbb{R}^{65,536}$.
Channel Architecture: 4ch (SDXL) vs. 16ch (FLUX.1) — Subspace frequency band decoupling and broad-spectrum cluster mapping.
The LAMNr Framework (Equations E1–E13) — Full technical dossier covering normalizing flows, Woodbury matrix MMSE inversion, Mahalanobis OOD metrics, and Total Correlation.
Failure Case Studies & Remediations — Audited post-mortems of Step-8 SLERP collisions, CFG variance frying, analogy double-exposures, and delta-zero collapse.

📖 Project History

Creation Timeline & Development History — The evolutionary story from the original pre-alpha "Wayfinder" prototype, through the "Latent Explorer" LAMNr research era and Run 4 failure remediations, to the certified "Gimbal" node suite.

🙏 Acknowledgments & Co-Pilot Attribution

This project exists at the intersection of human architectural direction and high-dimensional synthetic collaboration. Deep gratitude is owed to the multi-agent AI flight crew who filled specialized roles across mathematical modeling, CUDA optimization, documentation drafting, and refactoring:

The AI Flight Deck

Anthropic: Claude 3.5 / 3.7 Sonnet (Architectural refactoring & core node logic)
Google DeepMind: Gemini 3.1 Pro & Gemini 3.7 Flash (Research synthesis & telemetry pipeline design)
DeepSeek: DeepSeek V3 / R1 / 4 Pro (low-rank tensor calculus)
Moonshot AI: Kimi k3 (Long-context analysis & codebase indexing)
Zhipu AI: GLM-5.2 (Mathematical derivations & logic audits)
Xiaomi: MiMo 2.5 Pro (Subspace routing & auxiliary pipeline support)
Laguna: Laguna S2 (Specialized inference tasks and workflow testing)

Foundational Grounding

Christina: For the breath, clarity, and perseverance through deep debugging sessions.
Kyle: For endless patience, belief, and foundational support behind the scenes.

📚 Research & Theoretical Foundations

Gimbal's mathematical core and latent flight dynamics are grounded in foundational research across generative models, high-dimensional geometry, and subspace decomposition:

Latent Diffusion Architectures:
- Rombach, R., Blattmann, A., Lorenz, D., Esser, P., & Ommer, B. (2022). High-Resolution Image Synthesis with Latent Diffusion Models. CVPR.
- Ho, J., Jain, A., & Abbeel, P. (2020). Denoising Diffusion Probabilistic Models. NeurIPS.
Spherical Geometry & Interpolation Dynamics:
- Shoemake, K. (1985). Animating Rotation with Quaternion Curves (SLERP). ACM SIGGRAPH.
- Blum, A., Hopcroft, J., & Kannan, R. (2020). Foundations of Data Science (Geometry of High Dimensions & Annulus Theorem). Cambridge University Press.
Subspace Decomposition & Orthogonal Steering:
- Härkönen, E., Hertzmann, A., Lehtinen, J., & Paris, S. (2020). Ganspace: Discovering Interpretable GAN Controls. NeurIPS.
- Shen, Y., Gu, J., Tang, X., & Zhou, B. (2020). Interpreting the Latent Space for Semantic Face Editing. IEEE TPAMI.
Statistical Telemetry & Manifold Regularization:
- Lee, K., Lee, K., Lee, H., & Shin, J. (2018). A Simple Unified Framework for Detecting Out-of-Distribution Samples (Mahalanobis Distance). NeurIPS.
- Brock, A., Donahue, J., & Simonyan, K. (2018). Large Scale GAN Training for High Fidelity Natural Image Synthesis (Truncation). ICLR.

</div>