# Node Compositor for Images and Short Clips

> Run a node graph — keying, grading, LUTs, masks, merges — on images or a short clip. Evaluates a Lumina compositor graph (or a preset: green-screen composite, product shot on a gradient, LUT grade, sky replacement) on your images in linear light with premultiplied alpha. Porter–Duff merges with W3C blend modes, chroma/luma/difference keys, .cube LUTs, masks and filters; returns the result and a report for every node. Short clips are processed frame by frame.

Part of usefulweb.app (https://usefulweb.app/). Part of [Lumina](https://lumina.usefulweb.app/) (ownerApp: lumina). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://luminacompositor.usefulweb.app/ (interactive tool at https://luminacompositor.usefulweb.app/tool)
- JSON API: POST https://luminacompositor.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://luminacompositor.usefulweb.app/api/v1/tool)
- OpenAPI: https://luminacompositor.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://luminacompositor.usefulweb.app/mcp - tool `lumina_compositor`

## Inputs
- image (file, required): Main image or short clip - PNG, JPEG or WebP up to 2 megapixels, or a clip (MP4, MOV, WebM) up to 10 seconds — frames are scaled to at most about 0.4 megapixels. Image input nodes with the slot "Main image" read it.
- background (file): Background image (optional) - Read by image nodes with the slot "Background image" (green-screen and sky presets use it; without it they use a gradient).
- extra (file): Extra image (optional)
- preset (select): Graph
- graph (textarea): Graph JSON (for a custom graph) - Format: lumina-compositor version 1 (schema at /static/apps/lumina/compositor.schema.json). Copy it from Lumina → Compositor.
- lut (file): .cube LUT (optional) - Used by LUT nodes without their own .cube data, and replaces the warm fade in the LUT grade preset.
- format (select): Output format
- quality (integer): JPEG/WebP quality

## Method
- Uploads are decoded to 8-bit sRGB (auto-oriented), converted to linear light with the IEC 61966-2-1 transfer function and premultiplied by alpha; every node output is one Float32 RGBA (or mask) buffer at the canvas size (0 = size of the main image). Image input nodes fit their slot image with Catmull-Rom resampling (pre-blurred when shrinking).
- The graph is validated first (unknown types, parameter ranges, missing inputs, image/mask type mismatches, cycles, exactly one Output node) and evaluated in dependency order; identical sub-graphs are evaluated once (content-hash cache).
- Merge implements the W3C Compositing and Blending formulas: Cs′ = (1 − αb)·Cs + αb·B(Cb, Cs), co = αs·Fa·Cs′ + αb·Fb·Cb with Porter–Duff fractions Fa/Fb; blend functions see un-premultiplied colour in linear light or sRGB values (your choice). Colour nodes un-premultiply first; levels, curves, HSL, ASC CDL and LUTs work on sRGB-encoded values, exposure, white balance and vignette in linear light.
- The chroma key is a balanced colour-difference keyer: α = 1 − gain·m(C)/m(K) with m = dominant channel − balanced mix of the other two, then the backing colour is un-mixed (α·F = C − (1 − α)·K) and spill limited. Text nodes are drawn with DejaVu fonts by ImageMagick on the server (system fonts in the browser).
- Clips (up to 10 s) are decoded by ffmpeg to RGBA frames, the graph runs per frame (nodes that do not depend on the clip are evaluated once), and the frames are encoded as H.264 MP4 with the original audio as AAC. Video has no alpha channel: transparent results are shown on black.