# 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.site (https://usefulweb.site/). Part of [Lumina](https://lumina.usefulweb.site/) (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.site/ (interactive tool at https://luminacompositor.usefulweb.site/tool)
- JSON API: POST https://luminacompositor.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://luminacompositor.usefulweb.site/api/v1/tool)
- OpenAPI: https://luminacompositor.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://luminacompositor.usefulweb.site/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
- videoFormat (select): Video output (clips only) - Only used when the main input is a clip. WebM VP9 keeps transparency in browsers and most editors; ProRes 4444 (.mov) is the editing format for Final Cut, Premiere, DaVinci Resolve and After Effects.

## 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 and the graph runs per frame (nodes that do not depend on the clip are evaluated once). Output: H.264 MP4 with the original audio as AAC (opaque: transparent parts are composited on black), WebM VP9 with an alpha channel (libvpx-vp9, yuva420p, no alternate reference frames; audio as Opus) or Apple ProRes 4444 with 16-bit alpha in a QuickTime MOV (prores_ks, yuva444p10le; audio as 16-bit PCM). The server checks that its ffmpeg has the encoder before it starts.