Matte Paint Keyer

Matte Paint Keyer operator properties for Script Engine. A chroma keyer whose key is a painted 256x256x256 selection volume in RGB. Pick a paint tool and drag over the preview to mark colours as background; Grow expands the selection through colour space to cover shades you did not touch, and Blur softens the matte edge. The per-frame cost is a single byte lookup — at 256 per axis every 8-bit colour maps to exactly one voxel, so no interpolation is needed.

Property	Type	Access	Description
`ShowAdvancedOptions`	`bool`	`get/set`	Reveals the fine-tuning controls: spill balance, luminance spill recover and the garbage matte. Leave off for a straightforward key; turn on for a difficult one.
`Output`	`MattePaintKeyerOutput`	`get/set`	`MattePaintKeyerOutput` — which view the operator renders. Each name carries its own function key, so the list is the hotkey reference and there is no second place to keep in step. Garbage matte shows the active image or layer with its offsets and source transparency; it shows black when the matte is disabled or no source is available.
`PaintHelp`	`MultilineText`	`get`	Gesture reference for painting into the selection.
`EraseRadius`	`int`	`get/set`	Radius in pixels of the eraser disc. [min=1, max=64, default=32]. Erasing uses a disc rather than the single-pixel path the other two modes use: it is a corrective gesture where covering ground matters more than precision. Note it unmarks each colour it finds that colour occurs, not only under the cursor.
`HideStrokes`	`bool`	`get/set`	Hides the red dots that trace where you have painted. The dots only appear at all when this operator is selected and the global "Show handles" toggle is on; this hides them independently, for when they sit over the very edge you are trying to judge.
`StrokeData`	`string`	`get/set`	Stroke dot positions, deflate+base64 encoded. Written and read by the operator itself. Purely cosmetic — losing it costs the overlay, not the key.
`PaintMode`	`MattePaintMode`	`get/set`	`MattePaintMode` — the active paint tool, set by the button strip. While a tool is selected it owns dragging on the preview; None gives the drag back to the layer.
`PaintStroke`	`string`	`get/set`	Paints a stroke from outside the Desktop — the entry point a web or custom client uses, since there is no other way to reach the paint tools over the API.
`AddModeCommand`	`Command`	`get`	Switch to additive painting — Shift-drag adds colours to the selection.
`ExcludeModeCommand`	`Command`	`get`	Switch to subtractive painting — Shift-drag marks colours as foreground.
`EraseModeCommand`	`Command`	`get`	Switch to erasing — Shift-drag unmarks colours with a disc.
`ClearPaintCommand`	`Command`	`get`	Discard the whole selection and return the operator to a pass-through.
`PaintCommands`	`CommandGroup`	`get`	Paint buttons — add, exclude, erase and clear, as an icon strip. The first three are modes and highlight to show which is active; clear is a one-shot action.
`SelectedColoursInfo`	`string`	`get`	(read-only) How many distinct colours are currently selected, out of the 16.7 million the volume can hold. A painted screen typically covers a fraction of a percent — Grow is what turns that into a usable key.
`Grow`	`int`	`get/set`	Expands the selection through RGB space by this many steps in each direction, as a 3D maximum filter. [min=0, max=64, default=8]. This is the part of the selection — everything it reaches is keyed completely. At 256 steps per axis nothing is filled in implicitly, so a screen that ramps across shadow and highlight needs a fair amount of grow before the matte closes up.
`GrowShape`	`MattePaintGrowShape`	`get/set`	@ScriptEngine `MattePaintGrowShape` — whether Grow expands into a Box or an ellipsoid (Spherical). [default=Spherical].
`BlurRadius`	`int`	`get/set`	Radius of the soft falloff added the grown selection, in RGB steps. [min=0, max=32, default=4]. A width in colour space, not pixels — it widens the transition between keyed and kept colours, which is what gives hair and motion blur a gradient rather than a hard cut. It cannot eat into the grown region, so raising it never makes the background less transparent. Total reach is roughly Grow + Blur radius.
`ExcludeGrow`	`int`	`get/set`	Expands each excluded colour through RGB space before it is carved out of the selection. [min=0, max=64].
`SuppressionAmount`	`int`	`get/set`	Strength of spill suppression. [min=0, max=100, default=100]. 0 disables it. Works by limiting the screen channel to the strongest of the other two, so a pixel carrying more green than either red or blue has the excess removed. The screen channel is taken from the average of the painted colours, so there is nothing to configure — but it also means genuinely green foreground objects will lose saturation.
`LumaRecover`	`int`	`get/set`	Restores brightness that spill suppression removed, by adding neutral light back. [min=-200, max=200, default=0]. 0 disables it.
`EdgeRecoveryAmount`	`int`	`get/set`	Brings detail back in half-transparent areas — hair, motion blur, smoke, the edge of glass — instead of leaving them tinted by the screen behind them. [min=0, max=100, default=100]. 0 disables it. Whether it improves a shot depends on the material, so try a few settings and compare: on some footage it recovers detail that suppression alone loses, on other footage it makes the edge worse. It changes nothing where the matte is solid; the spill suppression below is what covers those pixels.
`UseSpillBalance`	`bool`	`get/set`	Redistributes the light spill suppression removed into the other two channels. [default=true].
`SpillRedBalance`	`int`	`get/set`	Share of the removed spill added to red. [min=-255, max=255, default=0]. Locked to 0 while red is the screen channel — putting the screen's own channel back would undo the suppression.
`SpillGreenBalance`	`int`	`get/set`	Share of the removed spill added to green. [min=-255, max=255, default=0]. Locked to 0 while green is the screen channel.
`SpillBlueBalance`	`int`	`get/set`	Share of the removed spill added to blue. [min=-255, max=255, default=0]. Locked to 0 while blue is the screen channel.
`CalibrateSpillBalanceCommand`	`Command`	`get`	Recompute the three balance amounts from the current screen colour and Amount. Only needed after changing Amount — a change of screen colour recalibrates on its own.
`ResetSpillBalanceCommand`	`Command`	`get`	Set the three balance amounts back to zero, leaving suppression un-compensated.
`SpillBalanceCommands`	`CommandGroup`	`get`	Spill balance buttons — calibrate and reset.
`UseGarbageMatte`	`bool`	`get/set`	Enables the image or live layer selected as the garbage matte. [default=false]. Red adds opacity, blue removes opacity, and green reduces both spill suppression and edge recovery. Yellow combines opacity restoration with colour protection, including at partially transparent edges. Partial channel values apply proportionally. Turning this off bypasses either source without clearing the settings.
`GarbageMatteSourceUrl`	`Uri`	`get/set`	Image file used when Use source layer is off, or when the selected layer has no rendered image. Use garbage matte must be enabled. Clearing the path removes the file matte without clearing the layer selection. RGB controls opacity and colour protection; the image's alpha controls its transparency in the Garbage matte view.
`GarbageMatteXOffset`	`int`	`get/set`	Horizontal offset of the file or live-layer matte, in pixels. Positive values move it right; negative values move it left. [default=0]. Areas outside the shifted matte leave the key unchanged.
`GarbageMatteYOffset`	`int`	`get/set`	Vertical offset of the file or live-layer matte, in pixels. Positive values move it down; negative values move it up. [default=0]. The same offset applies to the key and the Garbage matte view.
`GarbageMatteSourceLayer`	`LayerRenderInfo`	`get/set`	Earlier layer in the scene's render order whose rendered output supplies a live garbage matte (experimental). Choose the layer before enabling Use source layer. Use garbage matte must also be enabled.
`UseGarbageMatteSourceLayer`	`bool`	`get/set`	Enable the experimental live-layer garbage matte in place of the image file. [default=false]. Choose the source layer first. Use garbage matte must also be enabled. Turning this off returns to the configured image file. A selected layer without a rendered image also falls back to that file. If the layer is removed or moved after this layer, the source selection is cleared and this switch turns off.
`PaintData`	`string`	`get/set`	The painted selection, deflate+base64 encoded. Written and read by the operator itself; not meant to be set by hand.
`HistogramBins`	`int`	`get/set`	Bins per axis in the histogram view — the volume is NxNxN. [min=8, max=128, default=64]. Cost and cube count are cubic: 64 is 262,144 possible bins, 128 is eight times that. Raise it to separate two colour clouds that merge at low resolution; lower it when a sparse frame reads as dust rather than a shape. Unrelated to the selection volume, which is always 256 per axis because there an 8-bit colour must map to exactly one voxel.
`HistogramMinCount`	`int`	`get/set`	Bins holding fewer pixels than this are not drawn. [min=0, max=1000, default=0]. 0 shows everything, which is the honest default. Raise it to strip sensor noise and compression speckle, at the cost of also hiding genuinely rare colours — which on an edge are exactly the ones that decide whether a key looks cut out.
`HistogramMarker`	`CubeCloudMarker`	`get/set`	`CubeCloudMarker` — what each occupied bin is drawn as: Box, Sphere or Plane. [default=Box]. Planes always face the camera and are evenly lit, so each one is a flat patch of exactly the colour it stands for — the easiest to read a colour off, and the cheapest to draw. Boxes and spheres are shaded solids, which is what gives a dense cloud its sense of depth.
`HistogramColourSpace`	`CubeCloudColorSpace`	`get/set`	`CubeCloudColorSpace` — which colour space the histogram is plotted in. [default=Rgb].
`HistogramMarkerSize`	`int`	`get/set`	Marker size in colour levels on the 0–255 axis scale, or 0 to follow the bin width. [min=0, max=64, default=0].
`HistogramCubeSize`	`int`	`get/set`	Size of each marker as a percentage of one bin's width. [min=10, max=200, default=70]. Ignored when Marker size is non-zero. Below 100 leaves gaps, so the cloud reads as points and you can see through it; above 100 the cubes overlap into a solid mass, which shows extent but hides structure.
`HistogramDensityWeight`	`int`	`get/set`	How strongly a bin's pixel count drives the size of its cube. [min=0, max=100, default=50]. At 0 every occupied bin draws the same size, which is what shows the full extent of a colour cloud including single stray pixels; at 100 rare colours shrink to specks and only the dominant ones read. Drives size rather than opacity: translucent cubes would need sorting back-to-front on every camera move, which is precisely when you are least able to afford it.
`HistogramAzimuth`	`double`	`get/set`	Horizontal camera angle around the colour cube, in degrees, measured from the blue axis toward red. [default=35]. Dragging on the preview sets this.
`HistogramElevation`	`double`	`get/set`	Camera elevation above the centre of the cube, in degrees. [min=-89, max=89, default=25]. Stops just short of straight up and straight down, where the view would flip over instead of tilting past.
`HistogramDistance`	`double`	`get/set`	Camera distance from the centre of the cube, in cube widths. [min=0.5, max=20, default=4.4]. Ctrl-dragging on the preview sets this.
`HistogramFieldOfView`	`double`	`get/set`	Vertical field of view of the histogram camera, in degrees. [min=10, max=120, default=45].
`HistogramTargetX`	`double`	`get/set`	Look-at offset from the cube's centre along the red axis, in cube widths. [default=0]. Alt-dragging on the preview sets this and its two siblings together.
`HistogramTargetY`	`double`	`get/set`	Look-at offset from the cube's centre along the blue (vertical) axis. [default=0].
`HistogramTargetZ`	`double`	`get/set`	Look-at offset from the cube's centre along the green axis. [default=0].
`HistogramShowRoom`	`bool`	`get/set`	Draws the shaded room bounding RGB space, so the cloud has somewhere to sit. [default=Yes]. An open corner rather than a closed box, so it never comes between you and the cloud.
`HistogramBackgroundLevel`	`int`	`get/set`	Background brightness behind the cube, as a percentage. [min=0, max=100, default=6]. Dark on purpose: the cubes are drawn at their own RGB colour, so a bright background would wash out exactly the dark end of the cloud a keyer most needs to see.
`HistogramKeyGlow`	`int`	`get/set`	Brightness of the glow drawn over the key's soft falloff, in the histogram-with-key view. [min=0, max=100, default=50]. 0 shows only the solid grown core.
`ResetViewCommand`	`Command`	`get`	Return the histogram camera to its default three-quarter view.
`HistogramCommands`	`CommandGroup`	`get`	View buttons — currently just the camera reset.
`HistogramBinsInfo`	`string`	`get`	(read-only) How many bins hold at least one pixel, out of Bin resolution cubed — the honest measure of how much of RGB space this frame actually occupies. Says so when the count exceeds what the view can draw, because a silently truncated cloud looks like a complete one.
`HistogramTimeMs`	`string`	`get`	(read-only) Time in milliseconds of the last histogram frame — the binning pass plus the render. Diagnostic only, but unlike Solve time this one runs every frame the mode is selected.
`ScreenColourInfo`	`string`	`get`	(read-only) The screen colour the key was solved against: the mean of the pixels in the frame whose colour is in the painted set, plus which channel it puts the screen on and the per-axis grow radii that shaping produced. Weighted by occurrence rather than by distinct colour, so one noisy outlier voxel does not count as heavily as the shade a million pixels landed on.
`SolveTimeMs`	`string`	`get`	(read-only) Time in milliseconds of the last solve. Diagnostic only — the solve runs when the paint or a setting changes, never per frame.
`Minilog`	`FormattedMessage`	`get/set`	Status message about painting and solving.

Inherits from: AbstractCameraFilteredOperator, AbstractOperator, AbstractAudioMetering, NamedModel.

See also: Matte Paint Keyer in Operators — user-facing introduction, screenshots, and section summaries.