Skip to content
Forged/Docs/Forged ImageProducts ↗

Keying

Pull a key that survives the edge: the keyer family, in the order that works.

Part I explains keyer families; Part II specs the Forged suite. Companion: docs/corridor-key-plugin-spec.md. Condensed for the repo; the build honors the full original. Node names drop the F prefix per registry convention (FKeyerScreen → KeyerScreen); recorded here as the one adaptation.

The three separable jobs (Part I §1)

  1. Alpha estimation (how much FG per pixel), 2. Despill (remove screen

contamination from RGB — a color op independent of alpha), 3. Edge/color reconstruction at mixed pixels. Bad keys conflate them; the suite keeps them separable. Ground rules: scene-linear float, never clamp inside a keyer, HDR/negatives survive; keyer alpha is straight until Premult.

Families

  • Luma (Keyer): 4-point range bar — 0 below p1, ramp p1→p2, hold 1 p2→p3, ramp down p3→p4; sources luminance/R/G/B/saturation; invert.
  • Difference: |fg − clean| gain/shaped; garbage/hint quality.
  • Chroma/Hue: angular distance to picked screen color in chroma, with acceptance/softness and luma weighting; quick keys.
  • Keylight-class (screen difference): screen matte m = s − (bal·o1 + (1−bal)·o2) vs the picked screen color's own m_S; alpha = 1 − gain·m/m_S clipped by clip black/white; despill = subtract estimated screen contribution — falls out of the same math. Status view (black/white/ grey 3-tone) on every keyer. Inside (holdout→α1) / outside (garbage→α0) masks applied AFTER the algorithm, uniformly across the suite.
  • IBK-class: CleanScreen manufactures a per-pixel screen plate (isolate screen colors, punch out FG, iteratively erode/diffuse across holes); KeyerIBK runs screen-difference per pixel against it — wins on hair and uneven screens.
  • Primatte-class (KeyerSample): polyhedral RGB slicing, sculpt-by- scrubbing. Big UI tier, ships last of the keyers.
  • Ultimatte lesson: shadow retention + screen correction are features.
  • ML unmixing (Corridor Key): jointly predicts straight FG + linear alpha; a branch, not a replacement — see companion doc.

Supporting cast (§3)

Despill: algorithms avg/max/min of the other channels as the limit, bias (protect skin), amount, luma-preserving add-back, respill (re-add removed spill tinted by a bg input, with saturation), and a spillMatte output. Matte tools: Erode/Dilate, Despot, EdgeBlur (blur only the matte edge), matte shaping. LightWrap (bg glow over the FG edge band). EdgeExtend (push interior color under soft edges). Additive keying = Despill's spill matte re-added. KeyMix: max/min/minus matte assembly.

The professional architecture (§4) — shipped as KeyTemplate

plate → degrain → {garbage roto · CORE matte (hard, clipped, eroded) · EDGE matte (gentle, never clipped) · holdout} → assemble core∪edge ∩ garbage − holdout; despill branch judged with α=1; premult → edge extend → merge → light wrap → additive edge → regrain. The edge matte is never clipped; the core's job is to be rock solid.

Part II requirements (§6–8)

Every keyer: src + insideMask + outsideMask inputs, same conventions; view modes result/matte/status/overlay/despill; auxiliary channels (spillMatte, screenMatte) as real channels; scene-linear asserted; bbox = input bbox, α0 outside. Tests: hand-computed pixels, HDR survival, mask precedence; benchmark plates + side-by-side vs Nuke per release; 4K half-float < 8 ms/frame on reference GPU. Build order: Despill+tools+ audit framework → Luma/Chroma → KeyerScreen → CleanScreen+IBK → EdgeExtend/LightWrap/KeyMix/Template → KeyerSample → KeyerML.