.. _bpy.types.CompositorNodeKeying:

***********
Keying Node
***********

.. figure:: /images/compositing_types_matte_keying_node.png
   :align: right

   Keying Node.

The *Keying* node is a one-stop-shop for "green screen" / "blue screen" removal.
It performs both chroma keying to remove the backdrop and despill to correct color cast from the backdrop.
Additionally, you can perform common operations used to tweak the resulting matte.


Inputs
======

Image
   Standard image input.
Key Color
   The color of content to be removed. This may be a single color,
   or a reference image such as generated by
   the :doc:`Keying Screen Node </compositing/types/matte/keying_screen>`.
Garbage Matte
   An optional mask of area(s) to always *exclude* from the output.
   This is removed from the chroma key generated matte.
Core Matte
   An optional mask of area(s) to always *include* in the output.
   This is merged with the chroma key generated matte.


Properties
==========

Pre Blur
   Reduce the effects of color noise in the image by blurring only color by the given amount,
   leaving luminosity intact. This will affect matte calculation only, not the result image.

Screen Balance
   This is the balance between color channels compared with the key color.
   0.5 will average the other channels (red and blue in the case of a green screen).

   This may be tweaked in tandem with *Clip Black* and *Clip White* while
   checking the *Matte* output to create a mask with optimal separation.
Despill Factor
   Controls how much color bleed from the key color is removed from the input
   image: 0 means no despilling, 1 means all possible spilling will be removed.
   The underlying implementation is the same as adjusting the *Unspill* amount
   of the :doc:`Color Spill Node </compositing/types/matte/color_spill>`.
Despill Balance
   This controls how the color channels are compared when computing spill,
   affecting the hue and shade of the corrected colors.
   It is similar to setting the *Limiting Channel*
   in the :doc:`Color Spill Node </compositing/types/matte/color_spill>`.
Edge Kernel Radius
   Defines the radius in pixel used to detect an edge.
Edge Kernel Tolerance
   Defines threshold used to check if pixels in radius are the same as current pixel:
   if the difference between pixel colors is higher than this threshold then the point
   will be considered an edge.
Clip Black
   This sets the threshold for what becomes fully transparent in the output (black in the matte).
   It should be set as low as possible. Uneven backdrops will require this value to be increased.
   Use of the :doc:`Keying Screen Node </compositing/types/matte/keying_screen>` can help
   keep this value low. You may also use a *Garbage Matte* to exclude problematic areas.

   This value does not impact areas detected as edges to ensure edge detail is preserved.
Clip White
   This sets the threshold for what becomes fully opaque in the output (white in the matte).
   It should be set as high as possible. Colors close to green in the foreground
   may require reducing this value and/or adjusting the *Screen Balance*.
   Particularly problematic parts can fixed with a *Core Matte* instead of a low *Clip White*.

   This value does not impact areas detected as edges to ensure edge detail is preserved.
Dilate/Erode
   Enlarge (positive numbers) or shrink (negative numbers) the matte by the specified number of pixels.
   This is similar to using the :doc:`Dilate/Erode Node </compositing/types/filter/dilate_erode>` on the matte.

   This a simple way to include more or less along the edges of the matte, particularly combined with *Post Blur*.
Feather Falloff
   The rate of the falloff at the edges of the matte when feathering, to manage edge detail.
Feather Distance
   Controls how much the matte is feathered inwards (negative number) or outwards (positive number).
Post Blur
   Make the matte less sharp, for smoother transitions to the background and noise reduction.


Outputs
=======

Image
   Processed image with the *Matte* applied to the images' :term:`alpha channel`.
Matte
   Output matte to use for checking the quality of the key, or to manually apply
   using a :doc:`Set Alpha Node </compositing/types/converter/set_alpha>` or
   :doc:`Mix Node </compositing/types/color/mix>`.
Edges
   Shows what edges were detected on the matte.
   Useful for adjusting the *Edge Kernel Radius* and *Edge Kernel Tolerance*.

.. tip::

   If there are problems with the edges of the matte, it may help to start with
   adjusting the *Edge Kernel* parameters before adjusting feathering.
   Detected edges are not subject to *Clip Black* / *Clip White* thresholds
   to preserve fine edge detail. You can check edge detection by connecting
   a :doc:`Viewer Node </compositing/types/output/viewer>` to the *Edges* output.

   Sharper detected edges (smaller *Edge Kernel Radius*, like 2 / larger *Edge Kernel Tolerance*, like 0.4)
   will create a sharper matte, but may loose some detail like stray hairs.
   A sharp matte is good, but disappearing or flickering hairs are distracting.

   Fat edges (larger *Edge Kernel Radius*, like 8 / smaller *Edge Kernel Tolerance*, like 0.05)
   will capture more edge detail, but may also produce a halo around the subject.
   The halo can be adjusted with *Feather* controls along with *Dilate/Erode*.