Nodes · Masks

Crucible

Masksv1core

Overview

The matting engine, as a node. Click the subject; correct what is wrong. The correction vocabulary — Fix, Guide, Refine, Exclude — decides which control to reach for, and the tool says why when a correction has no effect.

How to

View the node and click the subject.
Wrong object → Fix. Wrong shape → Guide. Wrong softness → Refine. Should not have looked there → Exclude.
Chain a CrucibleRefine when the edge wants separate treatment.

Inputs

Input	What it takes
in	the image this node works on
shape	—
mask	limits the effect to this matte — the engine's universal mask slot, applied for every node that declares it

Outputs

Output	Type
out	Image

Parameters

Parameter	Type	Default	What it does
view	Choice	image	image passes RGB through with the matte in alpha (what you comp with); alpha shows the matte itself on black (what you judge it by). `imagealphaband`
band_opacity	Float	0.65	How strongly the `band` view paints the trimap over the plate — amber for the solve band, green for the definite inside.
band_erode	Float	0.0	Widen the solve band INTO the subject by this many pixels, on top of the adaptive width. Use it when the solved edge cuts into hair.
band_dilate	Float	0.0	Widen the solve band into the BACKGROUND by this many pixels, on top of the adaptive width. Use it when background bleeds through the edge.
role	Choice	composite	What the matte is FOR — and it is not cosmetic, it changes which stages run. composite: true float alpha, edge matting and background decontamination, for a matte going into a comp. occlusion: skips both, runs coarse and deliberately fat, for holding a mover out of a camera solve — a conservative region beats a beautiful edge there. holdout / garbage: coarse and generous, for excluding an area. `compositeocclusionholdoutgarbage`
detail	Choice	whole	Which nested subject you meant. One click is ambiguous — the person, the jacket, or the collar — so identification produces all three and this picks. If it grabbed too much, try 'part'; too little, 'whole'. Cheaper than adding a correction. `wholepartsubpart`
matte	Choice	auto	Which matter solves the band: `auto` measures the background's chroma variance per frame and picks — a uniform screen gets the keyer, a busy background the closed-form matter — and the status line says which ran and on what number. Force one to compare. `autokeyerclassical`
edges	Choice	solid	What the EDGE may be. `solid` is a silhouette: interior partials and speckle become 1, and anything softer than a one-pixel ring drops to 0 — right for a body, and it deletes hair. `soft` keeps the band matter's own fractional alpha. Measured on a hair plate, solid leaves 0.8% of pixels fractional with nothing between 0.75 and 1; soft leaves 3.0% spread across the range. Switch to soft for hair, smoke and any genuinely semi-transparent edge. `solidsoft`
floaters	Float	1.0	Drop solid islands smaller than this percentage of the subject — the specks a keyer leaves in the background. 0 keeps everything. It is a share of the subject, not a pixel count, so it means the same at any resolution, and a piece the previous frame also had is never dropped however small: temporal support is evidence. Raise it if specks survive; lower it if a genuinely detached piece (a hand behind a prop, a foot under a railing) disappears.
consistency	Float	0.6	How hard the matte holds still where nothing is moving. High stops hair crawling frame to frame; the blend is region-adaptive, so a genuinely moving edge still tracks rather than smearing. 0 is a full bypass — the right answer when the hair really is moving that fast.
garbage_shapes	Shapes	—	EXCLUDE regions — "never look here". Draw over the thing in the corner of the plate that keeps getting picked up, once, instead of re-explaining it every frame. It CONSTRAINS identification rather than being cut out of the result, so you can draw the boundary straight through your subject: the edge still solves properly up to the line and simply finds nothing past it, with no aliased slice through hair. Screen-space and held still by default (a garbage matte is usually lens-fixed); per-shape lifetime bounds it to the frames it's needed. Not the same as role=garbage, which applies to a whole matte.
retain_shapes	Shapes	—	INCLUDE regions — "always consider here". Ring a part of the subject that keeps getting dropped and it is kept, whatever identification decided. Where an Include and an Exclude overlap, Include wins, so a broad Exclude over a busy corner with the one real thing ringed inside it works. An Include says WHERE, not what the subject looks like — it won't drag identification toward its colour and take everything else that shade.
guide_shapes	Shapes	—	Edge guides: open splines saying "the half-alpha line passes through here". Drawn where the solved edge is in the wrong PLACE. They move the band's centre, never its width, and never write alpha.
guide_strength	Float	1.0	How hard the guides pull the band's centre — 1 means it. 0.5 gives "I drew it and it almost worked", which is worse than either end.
guide_falloff	Float	48.0	How far a guide's pull reaches, in pixels — what makes a local guide local: 48 px fixes the jaw and leaves the ear alone.
prompts	Text		The corrections you have made, in order — the ledger. The matte is a pure function of this list, so the same clicks always give the same matte, and removing one bad click from ten minutes ago keeps the nine good ones after it.
paint_strokes	Text		AlphaPaint strokes, the escape hatch: applied to the final alpha at Analyze. An edit on the ledger — replayable and undoable — not a bypass.
refine_strokes	Text		Refine-brush strokes: definite-foreground / definite-background statements consumed when the band is built. An input the solve honours, never an authority over alpha.
tracks	Text		The baked matte, packed run-length. Written by 🜛 Analyze; read by the node every frame. Not meant to be edited by hand.
frame_start	Float	0.0	The project frame the bake starts at — set by 🜛 Analyze.
status	Text		What the last Analyze did: the stages that ran, the matter picked per frame and why, and anything it refused.
bake_dir	Text		Where 🜛 Analyze writes the matte sequence. Empty writes beside the project.
bake_prefix	Text	crucible	The file name prefix of the baked sequence.
bake_format	Choice	exr16	`exr16` is the deliverable; `exr32` when a downstream tool needs full float; `png8-proxy` is 8-bit and WILL band on hair — it says so in its name. `exr16exr32png8-proxy`
bake_first	Float	-1.0	The first frame to bake, −1 for the project range's start.
bake_last	Float	-1.0	The last frame to bake, −1 for the project range's end.
binding	Text		Provenance: which models made this matte, written by Analyze and copied into the bake's sidecar, so a sequence on disk can still answer "what made this and may I ship it" later. Not edited by hand.
tracks_hidden	Text	[]	Track ids the object list has hidden. They stay in the bake; they just do not render.
disabled	Bool	false	Bypass: the node passes its first input through untouched (D in the graph). The knobs keep their values for when it comes back.
label	Text		A note shown under the node in the graph — what this node is FOR. Never affects the render or the cache.
hide_input	Bool	false	Draw the node without its input wire — a tidy graph for a node whose source is obvious (a Dot, a viewer tap).

Known edges

Two stages are still reference-* placeholders, so Crucible is not shippable yet — see crucible.