JB_KEYER is a procedural HSV-based colour selection and matte creation
tool.
It provides a fast way to isolate colour families, sample colours
directly from the source image, refine the resulting matte and inspect
the selection using several diagnostic viewing modes.
First submitted: 30 September 2026
Author: Juan Bautista Ruano Caro
Website: https://www.enelnombredelpixel.com
Compatible Nuke versions: All
Compatibility: Mac, Windows
======================================================================
JB_KEYER v1.0.0
Colour Selection & Matte Tool for Foundry Nuke
======================================================================
Author:
Juan Bautista Ruano
2026
======================================================================
OVERVIEW
======================================================================
JB_KEYER is a procedural HSV-based colour selection and matte creation
tool designed for Foundry Nuke.
It provides a fast way to isolate colour families, sample colours
directly from the source image, refine the resulting matte and inspect
the selection using several diagnostic viewing modes.
The tool has been designed to keep the interface simple while providing
additional controls when they are actually needed.
----------------------------------------------------------------------
MAIN FEATURES
----------------------------------------------------------------------
- Direct colour sampling from the source image.
- 12 predefined colour families.
- Custom Hue sampling and adjustment.
- Hue Width and Hue Falloff controls.
- Saturation filtering.
- HDR-friendly Value range controls.
- Complementary colour selection.
- Matte refinement controls.
- Optional external Mask input.
- Interactive colour wheel preview.
- Selection overlay preview.
- Dynamic interface.
- Multiple diagnostic output modes.
======================================================================
QUICK START
======================================================================
1. Connect your image to the main input of JB_KEYER.
2. Open the JB_KEYER properties.
3. Use "Sample Colour" to pick the colour you want to isolate directly
from the Viewer.
4. JB_KEYER automatically switches to Custom mode and calculates the
corresponding Hue.
5. Adjust:
Hue Width
Hue Falloff
Min Saturation
Min Value
Max Value
Value Falloff
until the desired area is selected.
6. Use the Matte Refinement controls if additional cleanup is required.
7. Switch between the available Output modes to inspect the result.
8. Optionally connect a Roto, RotoPaint or other alpha-producing node
to the Mask input to restrict the effect to a specific area.
[ GIF PLACEHOLDER - BASIC SAMPLE COLOUR WORKFLOW ]
======================================================================
COLOUR SELECTION
======================================================================
SAMPLE COLOUR
----------------------------------------------------------------------
Use the Sample Colour eyedropper directly in the Viewer.
JB_KEYER uses the selected Viewer coordinates to sample the RGB values
from the original Source input.
This is important because diagnostic modes such as Overlay + Wheel do
not contaminate the sampled colour.
You can therefore keep the diagnostic overlay visible while continuing
to sample colours from the original image.
After sampling:
- Colour Family automatically switches to Custom.
- Custom Hue is updated using the sampled colour.
- The sample information is displayed above the colour controls.
Example:
H 82.0° | S 0.608 | V 0.057 Sample received
The H, S and V values represent:
H = Hue
S = Saturation
V = Value
[ GIF PLACEHOLDER - SAMPLE COLOUR ]
----------------------------------------------------------------------
COLOUR FAMILY
----------------------------------------------------------------------
JB_KEYER contains the following predefined colour families:
Red
Orange
Yellow
Lime
Green
Turquoise
Cyan
Azure
Blue
Violet
Magenta
Rose
Custom
Selecting Custom enables:
Custom Hue
Hue Offset
----------------------------------------------------------------------
CUSTOM HUE
----------------------------------------------------------------------
Defines the centre Hue used by the selector when Colour Family is set
to Custom.
Sampling a colour automatically updates this value.
----------------------------------------------------------------------
HUE OFFSET
----------------------------------------------------------------------
Offsets the Custom Hue without changing the sampled base colour.
This can be useful for slightly shifting the selection manually.
----------------------------------------------------------------------
HUE WIDTH
----------------------------------------------------------------------
Defines the main Hue range that is fully selected.
Higher values include a wider range of neighbouring colours.
Lower values create a more selective key.
----------------------------------------------------------------------
HUE FALLOFF
----------------------------------------------------------------------
Controls the softness outside the main Hue Width.
A lower value creates a harder transition.
A higher value creates a smoother transition between selected and
unselected hues.
[ IMAGE PLACEHOLDER - HUE WIDTH / HUE FALLOFF ]
----------------------------------------------------------------------
MIN SATURATION
----------------------------------------------------------------------
Defines the minimum Saturation required for a pixel to participate in
the colour selection.
This is useful for excluding neutral greys, whites or very desaturated
areas that may share a similar Hue.
----------------------------------------------------------------------
MIN VALUE / MAX VALUE
----------------------------------------------------------------------
Restricts the selection using the HSV Value component.
Min Value removes darker areas.
Max Value removes brighter areas.
The default range is intentionally wide so the Value filter remains
neutral until adjusted.
----------------------------------------------------------------------
VALUE FALLOFF
----------------------------------------------------------------------
Controls the softness around the Min Value and Max Value thresholds.
----------------------------------------------------------------------
COMPLEMENTARY
----------------------------------------------------------------------
Shifts the selected Hue by 180 degrees.
This provides a fast way to select the complementary colour of the
current Hue.
======================================================================
MATTE REFINEMENT
======================================================================
After the initial HSV selection has been generated, the matte can be
refined using the following controls.
----------------------------------------------------------------------
BLACK CLIP
----------------------------------------------------------------------
Adjusts the black point of the matte.
Useful for removing weak unwanted areas from the selection.
----------------------------------------------------------------------
WHITE CLIP
----------------------------------------------------------------------
Adjusts the white point of the matte.
Useful for strengthening selected areas.
----------------------------------------------------------------------
MATTE GAMMA
----------------------------------------------------------------------
Adjusts intermediate matte values without directly changing the black
and white points.
----------------------------------------------------------------------
ERODE
----------------------------------------------------------------------
Expands or contracts the resulting matte.
----------------------------------------------------------------------
SOFTEN
----------------------------------------------------------------------
Adds softness to the matte.
----------------------------------------------------------------------
INVERT MATTE
----------------------------------------------------------------------
Inverts the final matte.
[ IMAGE PLACEHOLDER - MATTE REFINEMENT ]
======================================================================
MASK INPUT
======================================================================
JB_KEYER includes an optional secondary input called:
Mask
Connect any alpha-producing node such as:
Roto
RotoPaint
Keyer
Expression
Matte
to restrict the final JB_KEYER matte.
When no Mask is connected:
JB_KEYER behaves normally.
When a Mask is connected:
the generated matte is limited by the alpha of the Mask input.
This makes it possible to isolate the colour selection to a specific
region of the image without modifying the internal colour key.
[ GIF PLACEHOLDER - MASK INPUT ]
======================================================================
OUTPUT MODES
======================================================================
JB_KEYER includes six Output modes.
----------------------------------------------------------------------
ORIGINAL
----------------------------------------------------------------------
Displays the original source image.
----------------------------------------------------------------------
MATTE
----------------------------------------------------------------------
Displays the generated matte.
----------------------------------------------------------------------
COLOR
----------------------------------------------------------------------
Displays the original source image using the generated matte as alpha.
----------------------------------------------------------------------
COLOR WHEEL
----------------------------------------------------------------------
Displays the diagnostic colour wheel.
The wheel represents the Hue selection generated by the current
JB_KEYER settings.
----------------------------------------------------------------------
INPUT + WHEEL
----------------------------------------------------------------------
Displays the original source together with the diagnostic colour wheel.
----------------------------------------------------------------------
OVERLAY + WHEEL
----------------------------------------------------------------------
Displays the selected areas as a coloured overlay together with the
diagnostic colour wheel.
When this mode is selected, two additional controls become available:
Overlay Colour
Overlay Opacity
These controls are hidden in the other Output modes to keep the
interface compact.
[ GIF PLACEHOLDER - OUTPUT MODES ]
======================================================================
RECOMMENDED WORKFLOW
======================================================================
For normal footage:
Source
|
JB_KEYER
|
Result
For footage with strong grain, compression or sensor noise, a useful
workflow is:
Source
|
Denoise
|
JB_KEYER --> generate the matte
|
Matte
Then use that matte with the original source image.
This allows the colour analysis to work on a cleaner image while
preserving the original texture and grain in the final composite.
======================================================================
DEFAULT SETTINGS
======================================================================
Hue Width: 15
Hue Falloff: 10
Min Saturation: 0.05
Min Value: 0
Max Value: 10
Value Falloff: 0.05
Complementary: Off
Black Clip: 0
White Clip: 1
Matte Gamma: 1
Erode: 0
Soften: 0
Invert Matte: Off
Default Output:
Original
======================================================================
INSTALLATION
======================================================================
JB_KEYER is distributed using the JB_TOOLS folder structure.
The package should contain:
JB_TOOLS/
|
|-- init.py
|-- menu.py
|-- README_JB_KEYER.txt
|
|-- gizmos/
| `-- JB_KEYER.gizmo
|
`-- icons/
|-- JB_TOOLS.png
`-- JB_KEYER.png
----------------------------------------------------------------------
WINDOWS INSTALLATION
----------------------------------------------------------------------
1. Close Nuke.
2. Copy the complete JB_TOOLS folder into the Nuke plugins directory
corresponding to your Nuke installation.
Example for Nuke 16.0:
C:\Program Files\Common Files\Nuke\16.0\plugins\
The final path should therefore be:
C:\Program Files\Common Files\Nuke\16.0\plugins\JB_TOOLS\
3. Start Nuke.
4. JB_KEYER should appear in:
Nodes > JB Tools > JB Keyer
No additional Python configuration is required when JB_TOOLS is
installed in this plugin directory.
[ IMAGE PLACEHOLDER - JB TOOLS MENU ]
======================================================================
INSTALLING MULTIPLE JB TOOLS
======================================================================
JB_KEYER is part of the JB_TOOLS collection.
Other JB tools, such as JB_MONITOR, may be distributed separately.
If JB_TOOLS is already installed, DO NOT create a second JB_TOOLS
folder.
Simply merge the new JB_TOOLS folder with the existing one.
For example, after installing JB_KEYER and JB_MONITOR:
JB_TOOLS/
|
|-- init.py
|-- menu.py
|
|-- gizmos/
| |-- JB_KEYER.gizmo
| `-- JB_MONITOR.gizmo
|
|-- icons/
| |-- JB_TOOLS.png
| |-- JB_KEYER.png
| `-- JB_MONITOR.png
|
`-- resources/
`-- ...
The JB Tools menu automatically checks which tools are installed.
If only JB_KEYER is installed:
JB Tools
`-- JB Keyer
If JB_KEYER and JB_MONITOR are installed:
JB Tools
|-- JB Keyer
`-- JB Monitor
======================================================================
COMPATIBILITY
======================================================================
Compatibility with all Nuke versions.
======================================================================
CREDITS
======================================================================
JB_KEYER v1.0.0
Created by:
Juan Bautista Ruano
2026
======================================================================
Comments