✨ RollLux

Perceptive Full-Auto Metering Lighting

Procedural presets · LuxPro direction · viewport auto exposure · live tuning · viewport overlay

English · 中文 · 日本語

---

Introduction

RollLux is a Blender 5.0+ extension that analyzes a reference photo and builds a ready-to-tune light rig — key, fill, rim, accent, and world ambient — so you can replicate cinematic, portrait, product, and stylized looks without hand-placing every light.

Select.Object.Generate.Lights.Procedural.random.strategies.and.light.distribution.mp4

Match.Lighting.to.Image.Based.on.color.distribution.mp4

Auto.Light.Adjustment.Automatically.adjusts.intensity.based.on.metering.results.mp4

Every strategy thumbnail and library reference is procedurally generated in code — shaded spheres, gradient maps, and light blobs — not hand-picked stock photos. Roll Random anytime for a fresh combo, or step through named starting points that share the same generative pipeline.

Drop in a reference, hit Generate, and refine with real-time sliders. Works with Cycles and Eevee, fully offline, zero pip installs.

Author	ACGGIT
Blender	5.0.0 or newer
Engines	Cycles · Eevee
Dependencies	None (uses Blender’s bundled NumPy)

---

✨ Features

Feature	What you get
🎯 Reference analysis	Key / fill / ambient colors, contrast, mood, color temperature
🧭 LuxPro direction	Portrait-tuned light direction (left, right, top, backlight…) with confidence
🎨 Dual-tone gel lights	Blue + red/magenta (and similar) each get their own accent SPOT
⚡ Split & hard light	Sharp terminators → SPOT key, minimal fill, auto contrast / shadow seeding
🎛️ Live tuning	Intensity, exposure, distance, rotation, saturation, shadows, highlights, contrast
📸 Auto exposure	Viewport sampling in Rendered mode; TRIM / LOG / P60 metering, EV bias, fast converge, LIGHT_RIG bake
🧩 Quick / Pro UI	Compact Quick workflow or full Pro panel with advanced AE, rig, and per-light controls
🎲 Procedural presets	Strategy thumbnails & distribution refs generated in code — random roll yields new looks every time
🗂️ Strategy picker	Named starting styles + Random · procedural shaded-sphere previews · step navigation
🖼️ Distribution library	Built-in reference images procedurally synthesized (gradients, blobs, rim, vignette…)
💡 1–8 lights	Hue-diverse k-means palette matched to light count
🔧 Per-light edit	Toggle, recolor, energy, softness, delete
🔒 Lock light colors	Keep palette when re-generating or stepping presets
🪟 Floating overlay	Pin reference in viewport (opacity, scale, corner)
📂 Open image	Load a reference image from disk
🌐 Localized UI	English / 中文 / 日本語 via Blender language preferences

📊 RollLux vs manual lighting setup

	Manual rig	RollLux
Start from reference photo	❌	✅
Auto direction + color	❌	✅
Dual gel / accent detection	❌	✅
Random roll	❌	✅
Procedural preset & ref generation	❌	✅
Live slider updates	—	✅
Viewport auto exposure	❌	✅
Fully offline	✅	✅

---

📷 Screenshots & Demo

Reference → Result Portrait split-light reference matched to a 3D head	Dual-tone gel lighting Separate key + accent colors from saturated references
N-panel workflow Strategy presets, tuning sliders, LuxPro read-out	Animated workflow Load reference → Generate → Tune

_{📁 Add your own captures to ./assets/ — filenames above are the expected paths.}

---

🚀 Quick Start

Install

1. Download rolllux-5.5.5.zip from Releases.
2. Blender → Edit → Preferences → Get Extensions → ▼ → Install from Disk…
3. Select the zip → enable RollLux.

See CHANGELOG.md for changes since 5.0.

🛠️ Build from source

cd rolllux
py dev/gen_assets_main.py   # optional: regenerate thumbnails & reference PNGs
py build.py                 # -> ../dist/rolllux-<version>.zip
py build_marketplace.py     # -> ../dist/rolllux-<version>-marketplace.zip (Extension Platform)

Basic workflow

1. 3D Viewport → N → RollLux tab.
2. Load a reference image (a procedurally generated default is applied on first open).
3. Pick a Strategy preset or tap 🔄 Random for a freshly generated style.
4. Optionally change Lighting Distribution (procedural library) or use your own photo.
5. Select your subject → Generate Lighting.
6. Tune Intensity, Contrast, Shadows, Highlights, Saturation — updates apply live.
7. Switch the 3D View to Rendered shading and enable Auto Exposure (on by default) — see Auto Exposure below.
8. Use Quick for a compact panel, or Pro for full AE and rig controls.

---

📸 Auto Exposure

RollLux 5.0 ships a viewport-based auto exposure (AE) system that reads live pixels from the 3D View and keeps your scene at a stable luminance target — without leaving Blender or rendering to disk.

How it works

1. While AE is on, RollLux samples the viewport framebuffer on a timer (requires Material or Rendered shading; Rendered is preferred).
2. A 10×10 sample grid is collected over the metering region, with optional center weighting and per-frame grid jitter to reduce moiré misreads.
3. Samples are converted to luminance and aggregated with your chosen metering mode.
4. The plugin computes the EV gap to the target and applies it either to Color Management exposure or light rig energy (via intensity × 2^EV).
5. Tap Apply (✓) to bake the current AE offset into permanent settings and turn AE off.

Tip: If the viewport is not in Rendered mode, use the panel’s Set Rendered control or switch shading manually before expecting AE to react.

Quick vs Pro UI

	Quick	Pro
AE toggle	Camera icon + EV Bias + Apply	Same in the exposure row, plus AE Mode
Advanced AE	Hidden	Full Auto Exposure box: apply target, sampling, speed, gamma, jitter, fast converge, live EV readout

Switch UI Mode at the top of the panel between Quick and Pro.

Metering modes

Mode	Best for
Average	General-purpose; mean luminance of the sample region
Median	Noisy or high-contrast scenes; resists outliers
60th Percentile (P60)	Slightly brighter than median — good for portraits
Trim Mean	Drops top/bottom 10% before averaging — robust for mixed backgrounds
Log Average	HDR-ish mixes; geometric mean in log space
Highlight	Protect highlights; meters toward the 85th percentile
Reference	Target = mean luminance of your reference image (falls back to 18% grey if unavailable)

All modes blend full-frame and center samples according to Center Weight (0–100%).

Where exposure is applied

Apply to	Behavior
Color Management	Writes scene.view_settings.exposure live; optional Parameter Correction (gamma) while AE is active. Apply bakes exposure into CM and disables AE.
Light Rig	Adjusts ae_value and scales all light energy through Intensity (× 2^EV). Manual Exposure slider is locked while active. Apply multiplies Intensity by the accumulated EV and disables AE.

Light Rig mode includes Cycles-aware safeguards: luminance must settle between steps, adaptation is rate-limited, and timing scales with render engine noise — reducing flicker when Cycles is still converging.

Sampling region presets

Preset	Description
Full Frame	Entire viewport weighted equally
Balanced	70% center weight (default)
Center	Meters only the dense center grid
Subject Frame	Camera border in camera view, or center 60% in free view
Custom	Manual Center Weight slider

In camera view without Subject Frame, the plugin can also crop to the camera frame automatically.

Controls (Pro panel)

Control	Purpose
EV Bias	Exposure compensation in stops added on top of the computed target
AE Speed	How quickly EV moves toward the target (Light Rig mode caps speed adaptively)
Parameter Correction	CM gamma tweak while AE drives Color Management
Jitter	Rotate the sample grid each frame to reduce moiré misreads
Fast Converge	Stop when remaining error or the next EV step is below 0.1 stops
Live readout	Current CM exposure or Light Rig EV while AE is running
Apply (✓)	Bake AE → CM exposure or Intensity, then turn AE off

Recommended workflows

Portrait / product (CM path)

1. Generate lighting → switch viewport to Rendered.
2. AE Apply to: Color Management · Mode: P60 or Trim Mean · Sampling: Balanced.
3. Set EV Bias if the face should sit slightly brighter or darker.
4. When happy, click Apply to bake exposure into the scene.

Iterative light tuning (Light Rig path)

1. AE Apply to: Light Rig · enable Fast Converge for quicker settling.
2. Tweak colors and rig sliders while AE keeps overall brightness stable.
3. Apply when done to fold EV into Intensity and continue manual tuning.

Match reference brightness

1. Load reference → Analyze (or Generate).
2. AE Mode: Reference — target luminance comes from the reference image analysis.
3. Use EV Bias for fine matching.

---

📖 Usage

Main panel

Control	Description
Reference image	File browser or procedural library
Strategy	Procedurally generated style presets + Random (new thumbnail each roll)
Lighting Distribution	Procedurally generated reference images + Random
Generate / Analyze / Clear	Build rig · analyze only · remove rig
Tuning sliders	Intensity, exposure, AE, distance, rotation, height, colors, tone
UI Mode	Quick compact layout or Pro with full Auto Exposure block
Auto Generate	Timer-based re-roll (interval slider)

Advanced panel

Control	Description
Mode	Portrait / Scene / Auto
Aim At / Orient By	Target & axis mapping
Light Count	1–8 lights
LuxPro	Enable direction detection
Lights list	Per-light color, energy, delete
Analysis	Sampled colors, LuxPro label, mood, Kelvin
Auto Exposure	Apply target, metering mode, sampling preset, speed, bake — see Auto Exposure

Tips for best results

• Portraits — keep the face centered; avoid blown-out backgrounds.
• Split / hard light — let RollLux seed Contrast and Shadows (unlock sliders first).
• Gel / neon — use Light Count ≥ 3 so key + accent + rim are all created.
• Direction — enable LuxPro; use Rotate to fine-tune the rig orbit.

---

🤖 MCP — AI lighting (Cursor & Codex)

Drive RollLux from chat: 「给 Suzanne 打 portrait 光」, Light the Cube with golden hour, or Apply Arcane-style lighting.

Full release only — install rolllux-*.zip from GitHub Releases. The Extension Platform build (-marketplace.zip) does not include the MCP bridge.

Cursor / Codex  ──stdio──►  rolllux_mcp  ──TCP :9886──►  Blender (RollLux panel ▶ Start MCP)

Setup

1. Blender — enable RollLux → N panel → ▶ Start MCP (port 9886).
2. Python — cd rolllux/mcp && py -m pip install -e .
3. AI client — configure once (below).

Detailed guide: mcp/README.md

Cursor

Create or edit .cursor/mcp.json in your workspace root:

{
  "mcpServers": {
    "rolllux": {
      "command": "cmd",
      "args": ["/c", "py", "-m", "rolllux_mcp"],
      "cwd": "rolllux/mcp",
      "env": {
        "PYTHONPATH": "rolllux/mcp",
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9886"
      }
    }
  }
}

If you cloned only the rolllux repo, copy .cursor/mcp.json.example and set cwd to the absolute path of rolllux/mcp.
Then Cursor Settings → MCP → enable rolllux and restart Cursor.

OpenAI Codex

Add to ~/.codex/config.toml (or trust the project and use rolllux/.codex/config.toml):

[mcp_servers.rolllux]
command = "py"
args = ["-m", "rolllux_mcp"]
cwd = "C:/path/to/your/clone/rolllux/mcp"
enabled = true
tool_timeout_sec = 180

[mcp_servers.rolllux.env]
PYTHONPATH = "."
BLENDER_HOST = "localhost"
BLENDER_PORT = "9886"

Or: codex mcp add rolllux -- py -m rolllux_mcp (then set cwd and env).
In a Codex session, run /mcp to confirm tools are listed.
Template: .codex/config.toml.example

Example prompts

Example 1 — Portrait (Cursor)

You: Check Blender, list meshes, then light Suzanne with portrait and 4 lights.

Agent calls:

check_blender()
list_scene_objects(limit=20)
light_object(object_name="Suzanne", preset="portrait", light_count=4, auto_exposure=true)

Example 2 — Reference preset (Codex)

You: Clear RollLux and relight my selection using reference golden_hour.

Agent calls:

clear_rolllux_lighting()
light_selection(reference_preset="golden_hour", preset="cinematic")

Example 3 — Stylized look (any client)

Select the target mesh in Blender, then:

You: Apply Arcane teal + amber lighting on the active object.

Agent calls:

list_scene_objects()
light_arcane(intensity=0.22, light_count=4)

Style tools (light_jinx, light_doraemon, light_cyberpunk, …) use the active object; use light_object(name=…) when you need a specific mesh by name.

Tool	Purpose
check_blender	Connection + RollLux installed
list_scene_objects	Scene mesh names
light_object	Light a named object
light_selection	Light active selection
clear_rolllux_lighting	Remove rig
light_arcane, light_jinx, …	Stylized looks (active object)

---

🗺️ Roadmap

• Viewport comparison overlay (reference vs render)
• Preset export / import from current rig
• Batch generate for shot lists
• Optional AI reference tagging (offline heuristics first)

---

🤝 Contributing

Run py test_offline.py (no Blender required). Optional: blender --background --python test_blender.py. UI or lighting changes should include screenshots.

---

📄 License

GNU General Public License v3.0 or later