Free Trial
Buy now
Demo
About
Docs
Discord
Known Issues

ONYX Ai Matte v2.5 - Plugin Parameters

Complete reference for all parameters in the ONYX Ai Matte OFX plugin. Use this guide for AI-powered matting, object segmentation, tracking, and mask refinement workflows.

1. Pipeline Mode

The top-level control that determines how the AI segments your footage. Each mode uses a different combination of GPU models and interaction style. Switching modes may cause a brief pause while GPU models swap.

Pipeline Mode

Dropdown
Options (exact UI labels):
  • Bbox/Point Prompt (Auto Track) — Interactive points and bounding box with automatic object tracking across frames. Draw a bbox or place points on one frame, then play forward — the AI tracks the object automatically.
  • Bbox/Point Prompt (Manual Track) — Same as above but without auto-tracking. You control prompts on every frame manually. Best when auto-tracking interferes or for single-frame work.
  • Text Prompt (Auto Track) — Describe objects in text (e.g. "person", "car"). The AI detects all matching objects and tracks them across frames.
  • Mask Prompt (Auto Track) — Connect a rough mask (e.g. from Roto) to the Mask input. The AI uses it as a prompt to generate a refined segmentation mask.
  • Mask For Trimap (VitMatte Manual Track) — Connect a trimap mask to the Mask input. White = foreground, black = background, grey = uncertain region. VitMatte refines the uncertain zone for hair, fur, and fine edges.
Default:
Bbox/Point Prompt (Auto Track)
Tips:
  • Bbox/Point Prompt (Auto Track) is fastest for most workflows — draw once, track automatically.
  • Text Prompt (Auto Track) is convenient when you know the object class but don't want to draw.
  • Mask For Trimap gives maximum control for hair/fur when combined with a Roto node.
  • Switching modes preserves your prompts — they are restored when you switch back.

2. Point / Bbox Mode Workflow

Use interactive points and a bounding box to define what to segment. Points can work independently or together with bbox: the bbox gives a rough region; foreground points add "include this" and background points add "exclude this." You can animate point and bbox visibility by keyframing the Enabled parameter (0/1). In Auto mode, the AI tracks the object across frames automatically after you define it on one frame.

Tools

Delete Point and Move Point are hidden in the UI. Delete: select a point and press Del. Move: click and drag.

Enable Edit

Checkbox
Default:
On
Description:
Enables or disables interactive editing of points and bounding box. When off, viewport tools are inactive — you cannot add, move, or delete prompts.
Best for:
Temporarily locking your prompts while adjusting other parameters or scrubbing timeline.

Draw Box

Checkbox
Default:
On
Description:
Activates bounding box drawing mode. Click and drag to draw a rectangle around the object. When in Bbox mode, you can also move existing points.
Best for:
  • Quick rough selection of entire objects
  • Combining with points for complex shapes
  • Auto-tracking — draw bbox on first frame, play to track
Tips:
Bbox alone is often sufficient for simple objects. For more precision, add foreground points. See Bounding Box → Enabled to disable bbox in inference without clearing it.

Add FG Point

Checkbox
Default:
Off
Description:
Add foreground points (green). Click on the object to include that area in the mask.
Best for:
  • Including specific features or parts
  • Refining bbox selection
  • Multi-object selection: without a bbox, each FG point selects a separate object
Tips:
Foreground points say "include this". Combine with background points to exclude areas. To delete points: select them and press Del on your keyboard.

Add BG Point

Checkbox
Default:
Off
Description:
Add background points (red). Click on areas you want to exclude from the mask.
Best for:
  • Excluding similar-looking background regions
  • Fixing false positives
  • Separating overlapping objects
Tips:
Use sparingly; one or two background points often fix incorrect inclusions. To delete points: select them and press Del.

Clear All Points

Push Button
Description:
Removes all foreground and background points. Bounding box is not affected.

Clear Box

Push Button
Description:
Clears the bounding box and resets auto-tracking state. Points are not affected.

Points List

Points List

Point Picker
Capacity:
Up to 32 points
Per point:
Coord (x,y), Is Foreground (bool), Enabled (0/1)
Default:
All points disabled (0,0), Is Foreground = true
Description:
Stores all interactive points. Each point has coordinates, foreground/background type, and enabled state. Points are typically added via viewport; this list is for inspection and keyframe editing.
Tips:
You can keyframe the Enabled parameter (0/1) per point to animate prompt visibility per frame. Without a bbox, multiple FG points select separate objects (multi-object mode).

Bounding Box

Bounding Box

Point Picker (2D)
Parameters:
  • Top Left — (x, y) of top-left corner
  • Bottom Right — (x, y) of bottom-right corner
  • Center — (x, y) midpoint of the bounding box. Can be linked to a Tracker via expressions to move the entire bbox across frames while preserving its size. XYAbsolute type ensures compatibility with Nuke Tracker linking.
  • Enabled 1/0 — Enable/disable bbox in inference without clearing it
Default:
Top Left (0,0), Bottom Right (0,0), Center (0,0), Enabled = 1
Description:
Defines the bounding box around the object. When enabled, the model uses this region for segmentation. In Auto mode, the bbox is automatically updated by the tracker on each frame.
Tips:
  • The Enabled parameter (0/1) can be keyframed to turn the bbox on/off per frame.
  • In Nuke: link Center to a Tracker node via expression — the entire bbox follows the tracked position while preserving its size.
  • Without a bbox, each FG point selects a separate object (up to 32 points).
  • 8 slots (Bounding Box, Bounding Box 2…8). Slots 2–8 are hidden by default.

UI Appearance

UI Appearance

Group
Parameters:
  • Show / Hide Guides — Show or hide bbox, points, and padding overlay on screen
  • Show Point Labels — Display point numbers below each point
  • Points & Bbox Color — RGBA color for points, bbox, labels, and padding overlay
  • Points Overlay Scale — Range 0.25–3.0, display 0.5–2.0. Scale for point markers and label text size
Defaults:
Show/Hide Guides = On, Show Point Labels = On, Color = (0, 0.652, 1, 0.8), Points Overlay Scale = 1.0
Description:
Controls the visibility and appearance of interactive prompts in the viewport. The padding overlay (dashed rectangle around crop region) also uses the bbox color.

3. Text Prompt Mode Workflow

Use text to describe objects instead of drawing. Text prompts detect all matching objects in the frame. If multiple objects are detected, place ONE foreground point on the object you want to select. The point does NOT refine the mask — it only picks which detected instance to use. In Auto mode, detected objects are tracked across frames.

Text Prompt

Text Input
Visible when:
Pipeline Mode = Text Prompt (Auto Track)
Default:
Empty
Description:
Describe the object to detect in plain text. Examples: "person", "dog", "car", "red dress". The AI finds objects matching your description across the frame. Press Enter to submit.
Best for:
  • Quick detection when you know the object class
  • Batch processing — detection is automatic
  • Detecting multiple instances of the same class
Tips:
Use simple, common nouns for best results. Place a FG point on the desired instance if multiple objects are detected. Text mode is slower per frame than Point/Bbox.

Score threshold

Slider
Visible when:
Pipeline Mode = Text Prompt (Auto Track)
Range:
0.0 – 1.0
Default:
0.3
Description:
Minimum confidence score for text detections. Higher values return fewer but more confident detections. Lower values include weaker matches.
Best for:
Increase if false positives appear (wrong objects detected). Decrease if the correct object is missed.

IoU threshold

Slider
Visible when:
Pipeline Mode = Text Prompt (Auto Track)
Range:
0.0 – 1.0
Default:
0.3
Description:
IoU threshold for NMS (Non-Maximum Suppression) overlap suppression. Higher values keep more overlapping detection boxes; lower values remove more duplicates.
Best for:
Lower this if multiple overlapping detections appear for the same object. Increase if nearby objects are being incorrectly merged.

4. Pre-Processing & Encoder (Pre Processing)

Controls how the source image is prepared before AI inference. Includes colorspace handling, encoder crop, and coarse mask adjustments. The Pre Processing group in the UI also includes Show Trimap Overlay, Trimap Erode/Dilate, and Mask Output.

Input is Linear

Checkbox
Default:
On
Description:
Enable if your input footage is in linear colorspace (Nuke, ACES workflows). Disable if your input is sRGB/gamma (DaVinci Resolve, Fusion). The AI models expect sRGB input — this toggle applies the correct conversion automatically.
Tips:
Wrong setting will degrade mask quality. If masks look unexpectedly bad, check this toggle first.

Enable Crop

Checkbox
Default:
On
Description:
When enabled, the AI encoder processes only the bbox region plus padding instead of the full frame. This is faster and gives better detail within the crop. When disabled, the full frame is sent to the encoder for maximum spatial context.
Tips:
  • Keep On for most workflows — faster and better detail.
  • Turn Off if the object occupies most of the frame or if you need full-frame spatial context.
  • Toggling this during active tracking will force a tracking re-initialization (the AI needs to rebuild its spatial memory).

Show Bbox Padding

Checkbox
Default:
On
Visible when:
Enable Crop = On
Description:
Shows the crop padding region as a dashed rectangle overlay in the viewport. The dashed rectangle shows exactly what area the AI encoder receives. Color follows Points & Bbox Color.

Bbox Padding %

Slider
Range:
0 – 100%
Default:
50%
Visible when:
Enable Crop = On
Description:
Extra padding around the bounding box when cropping for inference. Also defines the search area for auto-tracking. Higher values give the AI more context around the object.
Best for:
  • 0–20%: Tight crop, fastest inference
  • 30–50%: Normal (recommended). Good balance of speed and context
  • 50–100%: Large padding for fast-moving objects or objects near frame edges

Binary Threshold

Slider
Range:
0 – 255
Default:
100
Description:
Threshold for binarizing the coarse decoder mask before trimap generation. Lower values make more dark pixels become foreground (brightens black holes in the coarse mask).
Best for:
Fixing dark holes in the coarse mask before VitMatte refinement.

Black Point

Slider
Range:
0.0 – 1.0
Default:
0
Description:
Remaps the black end of the soft mask alpha before refinement. Raising this value lifts the darks — transparent areas become semi-transparent. Use to recover detail in thin or semi-transparent regions.
Best for:
Fine-tuning mask edges; soft hair or transparent objects where pure black is too aggressive.

White Point

Slider
Range:
0.0 – 1.0
Default:
1
Description:
Remaps the white end of the soft mask alpha before refinement. Lowering this value clips the brights — semi-transparent areas become more transparent.
Tips:
Use Black Point and White Point together as a levels adjustment for the pre-refinement mask. Small adjustments (0.05–0.1) are usually enough.

Fill Holes

Checkbox
Default:
On
Description:
Removes small holes inside objects for cleaner masks using connected component analysis.
Tips:
Adjust hole size with Fill Holes Area. Disable if small interior details (e.g. gaps between fingers) get filled unintentionally.

Fill Holes Area

Slider
Range:
0 – 64 (display 0–32)
Default:
16
Description:
Maximum hole size in pixels to fill (measured at the 288×288 decoder resolution). 0 = disabled. 16–32 recommended. Higher = more aggressive hole filling.

5. Mask Output & VitMatte Refinement

Controls the mask quality level and VitMatte edge refinement. The VitMatte refiner produces high-quality soft alpha mattes with natural hair, fur, and semi-transparent edge detail.

Mask Output

Dropdown
Bbox/Point mode (3 options):
  • HQ VitMatte Refiner — AI-based edge refinement. Produces soft alpha mattes with natural edges. Best quality.
  • Binary — Hard binary mask (0 or 255). Faster, no soft edges.
  • Raw Decoder (Debug) — Raw decoder output (288×288 upscaled). Soft mask, no post-processing. For tuning decoder/crop/threshold.
Text/Mask Prompt mode (2 options):
HQ VitMatte Refiner, Binary (no Raw)
Default:
HQ VitMatte Refiner
Description:
Selects the mask output quality. HQ VitMatte Refiner runs an additional AI refinement pass on the edges; Binary skips it for faster processing.

VitMatte Trimap

The trimap defines zones fed to the VitMatte refiner. Overlay colors: cyan (255) = definite foreground (inner object), green (128, 192) = uncertain zone (erode + dilate regions where VitMatte refines edges), white (64) = contour (mask boundary edge), transparent (0) = background. Use Erode and Dilate to control the uncertain zone width. Visualize with Show Trimap Overlay.

Show Trimap Overlay

Checkbox
Default:
Off
Description:
Displays the trimap directly in the viewport as a colored overlay. Cyan = inner object (definite foreground), green = uncertain zone (erode + dilate regions refined by VitMatte), white = contour (mask boundary edge). Essential for diagnosing edge quality.
Tips:
Enable while adjusting Erode/Dilate to see the trimap update in real time. Disable when done.

Trimap Overlay Opacity

Slider
Range:
0.0 – 1.0
Default:
0.5
Description:
Controls the transparency of the trimap overlay. Lower values show the source image underneath; higher values make the trimap more opaque.

Trimap Erode

Slider
Range:
0 – 255
Default:
5
Description:
Erodes the foreground region of the trimap inward. Increasing this value pushes the uncertain zone further inside the object boundary, resulting in tighter edge processing.
Best for:
  • 0: No erosion. Foreground extends to the raw mask boundary
  • 1–3: Mild. Good for clean object boundaries
  • 4–7: Medium (recommended). Good balance
  • 8+: Aggressive. Pushes uncertain zone deep into the object
Tips:
Balance with Trimap Dilate. Use Show Trimap Overlay to preview. Higher Erode = tighter foreground definition.

Trimap Dilate

Slider
Range:
0 – 255
Default:
20
Description:
Dilates the uncertain region of the trimap outward. Increasing this value expands how far the refiner looks outside the object boundary — useful for fine detail like hair or fur.
Best for:
  • 0: No dilation. Useful for solid objects with clean edges
  • 15–25: Medium (recommended). Captures most hair/fur detail
  • 30+: Large. For very fine or flyaway hair
Tips:
Higher Dilate = more edge detail captured, but VitMatte processes a larger area. Setting Dilate to 0 can fix the top-edge pixel strip issue when the object is close to the bbox boundary.

6. Mask Consistency

Prevents the mask from switching or flickering between frames. Uses a dual-layer temporal consistency system.

Enable Consistency

Checkbox
Default:
On
Description:
Enables dual-layer temporal consistency. Layer 1 selects the mask candidate closest to the previous frame (via temporal IoU weighting). Layer 2 suppresses sudden mask regions that appear without temporal support.
Best for:
Keeping masks stable during playback. Prevents body parts or regions from "flipping" between frames.

Consistency Weight (%)

Slider
Range:
0 – 100%
Default:
50%
Description:
Weight of temporal IoU in mask candidate selection (Layer 1). Higher values = stronger preference for masks similar to the previous frame.
Best for:
50% is balanced (recommended). 100% = maximum stability but may lag behind fast motion. 0% = no temporal preference.

Suppression Threshold (%)

Slider
Range:
0 – 100%
Default:
30%
Description:
IoU threshold for Layer 2 component suppression. Mask regions with less than this overlap with the previous frame are removed as "jumps".
Best for:
30% is recommended. 0% disables Layer 2 entirely. Higher values are more aggressive — may suppress legitimate fast-moving regions.

7. Temporal Smoothing

Smooths the decoder mask across frames to reduce per-frame noise and jitter. Operates at the decoder's native 288×288 resolution before upscaling.

Enable

Checkbox
Default:
Off
Description:
Enables decoder-level temporal smoothing (EMA or Median).
Tips:
Disabled by default. Enable for sequences with noticeable per-frame mask flickering.

Method

Dropdown
Options:
  • EMA — Exponential Moving Average. Fast convergence, good for smooth motion. Blends current frame with running average.
  • Median — Temporal median filter. Removes outlier frames, good for sporadic noise.
Default:
EMA

Strength

Slider
Range:
0 – 100
Default:
61
Description:
Temporal smoothing strength. 0 = off, higher values = more smoothing (more blending with previous frames). For EMA, strength 61 corresponds to alpha ≈ 0.39.

Edge Range

Slider
Range:
0 – 100
Default:
50
Description:
Alpha-guard width for temporal smoothing. Controls which pixels receive smoothing based on their alpha value. 0 = only edge pixels, 50 = moderate range (alpha 13-242), 100 = all pixels.
Tips:
Lower values restrict smoothing to edge pixels only, preserving solid foreground/background. Higher values smooth everything including flat areas.

8. Motion Freeze

Full-resolution scene-lock that freezes alpha in areas where the source image is static between frames. Suppresses VitMatte edge jitter on backgrounds and still objects.

Enable

Checkbox
Default:
Off
Description:
Enables full-resolution motion-aware alpha freezing. Where the source image doesn't change between frames, the previous alpha is preserved. Moving areas get fresh alpha from the AI.

Freeze

Slider
Range:
0 – 100%
Default:
50%
Description:
Freeze strength for static areas. 0% = no freeze (disabled), 100% = full freeze on static pixels.

Tolerance

Slider
Range:
1 – 50
Default:
10
Description:
RGB change threshold to detect motion. Lower values are more sensitive (more pixels considered "moving"). Higher values freeze more aggressively (only large changes count as motion).
Best for:
  • 1–5: Very sensitive — only truly static pixels are frozen
  • 10: Default — good balance
  • 20–50: Aggressive freeze — only large motion unfreezes

9. Output Adjustments (Mask Post-Processing)

Display, overlay, alpha mode, levels, shrink/grow, feather, and offset. Applied after all AI processing as final post-processing on the mask.

Output Alpha Mode

Dropdown
Options:
  • Straight — Alpha stored separately; RGB channels are not premultiplied
  • Premultiplied — RGB channels multiplied by alpha
Default:
Straight
Description:
Controls how the alpha channel is composited into the output image.
Tips:
Use Straight for Nuke and After Effects. Switch to Premultiplied for DaVinci Resolve (fixes white halo artifacts).

Display Mode

Dropdown
Options:
  • Overlay — Colored mask overlay on source image
  • Matte — Black/white mask only
Default:
Overlay
Description:
Both modes write the mask to the alpha channel. Overlay adds a colored preview on the RGB; Matte shows the raw mask as greyscale.

Show Mask Overlay

Checkbox
Default:
On
Description:
Toggle visibility of the colored mask overlay in the viewport. The alpha channel is always written regardless of this toggle.

Overlay Color

Color Picker (RGBA)
Default:
(0.5, 0, 0, 0.5)
Description:
Color and opacity of the mask overlay when Display Mode = Overlay.

Output Levels

Group
Parameters:
  • Levels Black — 0.0–1.0 (default: 0.0). Values below this are clipped to fully black. Removes dark noise and thin transparent fringing.
  • Levels White — 0.0–1.0 (default: 1.0). Values above this are clipped to fully white. Removes bright noise or background contamination.
  • Levels Gamma — 0.1–2.0 (default: 1.0). Midtone shift. Below 1.0 = darker/tighter mask edge; above 1.0 = brighter/wider edge.
Description:
Output levels for the final mask, applied after VitMatte refinement. Uses a 256-entry LUT for fast evaluation.
Tips:
Start with small adjustments (Black 0.02–0.05, White 0.95–0.98). Gamma 0.8–1.2 covers most use cases.

Mask Shrink/Grow

Slider
Range:
−50 to +50 pixels
Default:
0
Description:
Expand (+) or contract (−) mask boundaries. Positive = fill gaps; negative = remove thin edges and halos.
Best for:
  • +5 to +15: When edges are slightly too tight
  • −5 to −10: Remove noise or thin halos

Edge Feather

Slider
Range:
0 – 100
Default:
0
Description:
Feather (blur) mask edges for softer compositing. Only affects the edge zone, not the interior.

Offset Mask X / Y

Slider
Range:
−100 to +100 per axis
Default:
0, 0
Description:
Offset the mask horizontally (X) and vertically (Y) on screen. Useful for compensating misalignment or creative offset effects.

Final Binary Sharp

Checkbox
Default:
Off
Description:
Final binarization pass (threshold 128) with corner smoothing via majority voting. Converts the soft alpha mask to a hard binary mask. After enabling, you can manually adjust edge softness with Edge Feather.
Best for:
When you need crisp binary edges instead of soft alpha for compositing or rotoscoping.

10. Performance & Cache

Persistent disk cache stores processed masks to survive host restarts and project reloads.

Disk Cache %

Slider
Range:
10 – 90%
Default:
30%
Description:
Percentage of free disk space allocated to the persistent mask cache. Masks are compressed with zlib (~80× reduction — typically ~100 KB per 4K frame). When the limit is reached, the oldest cached files are automatically removed (LRU eviction).
Tips:
20–50% recommended. A 500 MB cache budget holds thousands of frames. On cache hit, only lightweight post-processing runs — under 50 ms vs. 1–2 s for full inference.

Cache Folder

Directory Path
Default:
Empty (system default location)
Description:
Folder where disk mask cache files are stored. Leave empty for the default system temp location. Set to a fast SSD path for best performance, or a network drive for shared cache across workstations.

Clear Disk Cache

Push Button
Description:
Deletes all cached mask files from disk immediately. Use when cache is stale or you need to free disk space.

Cache Info

Read-only
Description:
Shows current disk cache usage: number of cached frames and total size on disk. Updates automatically.

11. Debug & Advanced

Reset, license, and internal controls.

Reset all parameters

Push Button
Description:
Resets all parameters to their default values. Use when experimenting or recovering from bad settings.

License

Group
Parameters:
  • Buy at onyxofx.com — Opens website for license purchase
  • License Key — Text field for entering license key
  • Activate License — One-time online activation, then works offline
  • Deactivate License — Transfer license to another machine
  • Copy HWID to Clipboard — Copy your Hardware ID for offline license activation
  • Status — Read-only license status
Description:
License management. One-time activation with internet; afterward works fully offline. License key is not saved in the project file for security.

Quick Reference: Which Mode for Which Task

Task Recommended Mode Key Parameters
Rotoscoping (single object) Bbox/Point Prompt (Auto Track) Bbox + FG points, Auto Track, Mask Consistency, Edge Feather
Keying (hair, fur, fine edges) Bbox/Point Prompt (Auto Track) HQ VitMatte Refiner, Trimap Erode/Dilate, Black & White Points
Quick masks Bbox/Point Prompt (Auto Track) Bbox only, Auto Track, Disk Cache 30%
Batch detection by class Text Prompt (Auto Track) Text Prompt ("person", "car"), Score threshold, point to select instance
Multi-object selection Bbox/Point Prompt (Manual Track) Multiple FG points (no bbox), each point selects a separate object
Complex shapes Bbox/Point Prompt (Manual Track) Bbox + FG + BG points, Mask Shrink/Grow, Output Levels
Existing Roto refinement Mask For Trimap Connect Roto to Mask input, Trimap Erode/Dilate
Tracker-driven bbox (Nuke) Bbox/Point Prompt (Manual Track) Link Bounding Box → Center to Tracker expression
Edge jitter / flicker fix Any Motion Freeze (static BG), Temporal Smoothing (general), Mask Consistency
Static camera, jittery edges Any Motion Freeze: Enable + Freeze 50% + Tolerance 10
DaVinci Resolve compositing Any Output Alpha Mode = Premultiplied, Input is Linear = Off
Nuke / ACES compositing Any Output Alpha Mode = Straight, Input is Linear = On

Processing Pipeline Order

Understanding the order of operations helps you adjust parameters effectively. Parameters earlier in the chain affect everything downstream.

  1. Input — Linear → sRGB conversion (if Input is Linear = On)
  2. Encoder Crop — Bbox + padding region sent to AI encoder (if Enable Crop = On)
  3. AI Decoder — Generates coarse 288×288 mask from prompts
  4. Temporal Smoothing — EMA or Median at 288×288 (if enabled)
  5. Mask Consistency — Dual-layer temporal IoU + suppression
  6. Upscale — 288×288 → crop region resolution
  7. Pre-processing — Binary Threshold, Black/White Point, Fill Holes
  8. Trimap Generation — Erode/Dilate create uncertain zone
  9. VitMatte Refinement — AI edge refinement on uncertain zone (if HQ VitMatte Refiner)
  10. ApplyPostProcessing:
    • TC Layer 2 — Component suppression
    • Motion Freeze — Freeze alpha on static regions (if enabled)
    • Final Binary Sharp — Binarization (if enabled)
    • Output Levels — Black/White/Gamma
    • Shrink/Grow — Morphological expand/contract
    • Edge Feather — Gaussian blur on edges
    • Offset — X/Y pixel shift
  11. Alpha Mode — Straight or Premultiplied output

Need Help?

Get fast help from our community and support team:

Licenses

All third-party licenses and notices included with plugin installation in the installation directory.

Full License/Terms

ONYX Ai Matte v2.5 - Known Issues

A list of known issues, root causes, and workarounds. This page is updated with each release. If you encounter an issue not listed here, please report it in our Discord community.

Known Issues

Active issues with root causes and workarounds. Updated with each release.

Issue #1 — "Image missing or corrupted" after a custom gizmo

Workaround
Symptom:
The plugin shows "Image missing or corrupted" when connected after certain custom gizmos (e.g. Vignette_Remove).
Cause:
Some gizmos do not fully support the OFX pixel request protocol, so the plugin cannot read image data.
Workaround:
Insert any standard node between the gizmo and ONYX Ai Matte — for example Dot, Grade (default settings) or NoOp. This forces the host to materialize pixels before passing them to the plugin.

Issue #2 — Text prompt field unresponsive after Nuke upgrade

Workaround
Symptom:
After upgrading Nuke (e.g. from 15 to 16) the text prompt field becomes unresponsive and does not accept input.
Cause:
The old preferences file (preferences15.nk / preferences16.nk) in the .nuke folder conflicts with the new version.
Workaround:
Delete the old preferences*.nk file from the .nuke folder and restart Nuke. Settings will reset to defaults and the text field will work normally.

Issue #3 — "Image missing or corrupted" when mask is connected to Source input

Workaround
Symptom:
When connecting a mask (e.g. Roto + ChannelMerge) directly into the Source input, the plugin shows "Image missing or corrupted".
Cause:
The mask contains pixel data only within the mask area — the rest of the frame has no data at all, and the plugin cannot process an incomplete image.
Workaround:
Add a solid color node (Constant in Nuke, Background in Fusion) set to black with the same resolution as your project. Connect it to the background input of your first compositing node. This fills empty pixels with zeros and provides the plugin with a complete frame.

Issue #4 — Top edge of mask misses 1-2 pixels with VitMatte enabled

Workaround
Symptom:
With VitMatte enabled, the top edge of the mask may miss 1-2 pixels of the object when it is close to the top edge of the bbox.
Cause:
Trimap Dilate expands the uncertain zone outward, and VitMatte cannot properly refine pixels at the crop region boundary.
Workaround:
  • Reduce the Trimap Dilate parameter (try values 0–1).
  • Draw the bbox with extra margin above the object.
  • Add an FG point on the affected area.

Issue #5 — Bbox drifts and mask misaligns with log-encoded footage

Workaround
Symptom:
Tracking becomes unstable: bbox drifts, mask misaligns with the subject, segmentation quality drops. The viewer may still look acceptable via the display transform, while the numeric input to the network is not the expected linear light the models assume.
Cause:
SAM2 and VitMatte models expect linear-light values. Log-encoded footage (Cineon, LogC, V-Log, etc.) without proper linearization delivers numerically wrong pixel values, which confuses tracking and detection.
Workaround:
Before ONYX Ai Matte, apply a correct OCIO path: convert the log source to your scene linear working space (ColorSpace/LUT per your plate documentation). Verify the Read node, the chain upstream of the plugin, and project settings — without this, tracking results are not reproducible across setups.