Skip to main content
Glama
Lightning Emperor MCP Server

Lightning Emperor MCP Server

by LucidMach
README.md
# Lightning Emperor

**Composite CG behind live-action actors, from your terminal, from Blender, or by asking an AI agent.**

![plate, matte, composite](docs/img/hero.jpg)
<sub>Left to right: a rendered green-screen plate (with real green bounce light), the automatic matte, and the composite over a CG room with a cast shadow and matched grain. Reproduce it with <code>python examples/make_demo.py</code>. No footage needed.</sub>

[![ci](https://github.com/LucidMach/LightningEmperor/actions/workflows/ci.yml/badge.svg)](https://github.com/LucidMach/LightningEmperor/actions/workflows/ci.yml) ![license](https://img.shields.io/badge/license-GPL--3.0--or--later-blue) ![python](https://img.shields.io/badge/python-3.10%2B-blue)

Replacing a green or blue screen well is mostly *measuring and matching*, not clicking: the camera's lens and distance, where the light really comes from, how noisy the plate is, how far the actor is from the wall. Lightning Emperor turns those steps into tools, and ships the know-how as a skill so an AI agent can run the whole workflow and not just one step.

| | | For |
|---|---|---|
| **Python library + CLI** | numpy only, ffmpeg for video I/O | scripts and pipelines |
| **MCP server** | 13 tools, headless Blender jobs | Claude and any MCP client |
| **Blender add-on** | sidebar panel for camera, lights, practicals, renders, matte/grain/tracking | artists |
| **Agent skill** | the workflow and the lessons, as markdown | any LLM agent |

## What you get
- **Camera:** distance from a known size in the plate, cross-checked against the lens focus distance, with a warning when they disagree. (A wrong distance makes the CG the wrong size in every frame; this is the mistake the tool exists to prevent.) Lens, exposure and white balance read straight from Blackmagic RAW files.
- **Keying:** a difference key that calibrates itself to the screen, with brightness gating for dark clothing, hole filling that leaves hair gaps open, despill confined near the screen edge, edge decontamination and removal of tracking marks.
- **Tracking:** finds tracking marks, tracks them with a homography per frame (learning the marker layout as it goes), smooths the result, exports corner pins.
- **Shadows:** where an actor's shadow falls on the backdrop, from the light position and the actor-to-wall gap.
- **Grain:** measures noise from the screen itself and synthesises matching grain. On the demo plate it recovers the true noise to within 3%.
- **Compositing:** linear-light mix with shadow and grain, plus audio alignment of a trimmed export to the camera file.

## Install
```bash
pip install "git+https://github.com/LucidMach/LightningEmperor"          # library + CLI (needs ffmpeg)
pip install "lightning-emperor[mcp] @ git+https://github.com/LucidMach/LightningEmperor"   # + MCP server
```
(A PyPI release is planned.) Blender add-on (4.2+): download `lightning_emperor-<version>.zip` from [Releases](https://github.com/LucidMach/LightningEmperor/releases), then Edit > Preferences > Get Extensions > Install from Disk.
Agent skill: copy `skill/lightning-emperor/` into your agent's skills folder. MCP client setup: [docs/mcp.md](docs/mcp.md).

## Try it in two minutes
```bash
python examples/make_demo.py demo_out      # needs Blender + ffmpeg; renders, keys, measures grain, casts a shadow, composites
lightning-emperor distance --size-px 215 --focus-m 3.0
lightning-emperor key plate.mov out/ --frame 100 --screen green     # look at out/preview_on_grey.png
lightning-emperor comp plate.mov cg.png out.png --screen green --grain grain.json --shadow-offset 120,20
```
Or connect the MCP server and ask your agent: *"Key frame 100 of plate.mov, tell me if the matte is good, then composite it over cg.png."*

## How well does it work? (honestly)
On the demo plate the grain measurement recovers the true noise (0.0110, 0.0092, 0.0141 measured vs 0.011, 0.009, 0.014 true) and its softness within 5%. Reproduce with `examples/make_demo.py`; numbers in [docs/img/demo_numbers.json](docs/img/demo_numbers.json).
It has also been used on real blue-cloth footage with tracking tape, where it removes the cloth cleanly and tracks the markers frame to frame.
Known limits, so you do not find them the hard way:
- **Fine hair:** a difference key loses strands thinner than a pixel (the demo's flyaway hairs mostly vanish). Hero shots need a dedicated hair matte.
- **Dark clothing lit by bounce from the screen** can leave small grey patches near edges.
- **Over-exposed or near-clipped screens** defeat the self-calibration (a pastel hot spot reads as foreground). Expose the screen properly.
- **Tracking** needs markers in view. With none visible the backdrop can only be held or interpolated. There is no 3D camera solve.
- **Camera metadata** is Blackmagic RAW only; other cameras need focal length and focus entered by hand.
- **Shadows** are a 2D approximation, not ray-traced contact shadows.

## Development
```bash
python -m venv .venv && . .venv/bin/activate
pip install -e ".[mcp,dev]" && pytest          # 19 tests on synthetic ground truth
python scripts/build_addon.py                   # vendors the core into the add-on and builds the extension zip (needs Blender)
```
Want to help? See [docs/ROADMAP.md](docs/ROADMAP.md) for contributor-sized tasks, and [CONTRIBUTING.md](CONTRIBUTING.md).
Built with the help of Claude Code.

## Licence
GPL-3.0-or-later. See [LICENSE](LICENSE). Blender add-ons that use its Python API must be GPL-compatible, so the whole project uses one licence.