Shake - Keylight

Keylight (Bundled Plugin)

Function
Keylight is an Academy Award® winning keyer from Framestore/CFC based in England. It accurately models the interaction of the blue or green screen light with the foreground elements, and replaces it with light from the new background. With this approach, blue spill and green spill removal becomes an intrinsic part of the process, and provides a much more natural look with less tedious trial and error. Soft edges such as hair and out-of-focus edges are pulled quite easily with the Keylight node.

To ensure the best results, try to always pull the key on raw plates. In the Keylight parameters, there is a colourspace toggle to indicate if the plate is in log, linear, or video color space—so you should not perform a color correction on film plates when feeding the plates into Keylight.

To understand the function in context, see “Lesson Five: Using Keylight,” in the Shake 3 Tutorials book.

Parameters	Type	Defaults	Function
HoldOutMatte	image		Indicates areas of the foreground that needs to be corrected for bluespill, but should not become transparent. The 'replace colour' is used in these areas instead of the Background.
clipMode	image	0	Sets the output resolution of the node, either the foreground image (1) or the background image (0) resolution.
output	string	"composite"	Like Primatte, you have the option to do your composite with Keylight, but there are other output options as well: composite: renders the final composite. compOnBlack: renders the foreground objects over black. compOnReplace: renders the foreground objects over the Replace Colour. This is a good mode to test your composite. unpremultiplied: renders the foreground without premultiplying the matte. This is used when you want to continue to do transformations and color corrections after pulling the key. You would then apply either a MMult node or turn on preMultiply in an Over node to do the composite. status: Black pixels represent areas that will become pure background in the composite. Blue pixels represent areas that will become spill corrected foreground. Green pixels represent a blend of foreground and background pixels. Pure green is mostly foreground and dark green is mostly background.
r,g,bScreen	float	0,0,.9	The primary color of the screen color to be pulled, i.e., usually blue or green. Note that Keylight is tuned to the primary colors and won't be effective on secondary colors (cyan, magenta, yellow). If you are trying to pull these color, you might consider switching your image from RGB to CMY with the ColorSpace node, pull the key, and then switching back to RGB.
screenRange	float	0	This defines the ranges of colours that should be keyed out. The higher the number the more screen is removed. A value of zero will give you the smoothest key, a value of .3 will remove all gray levels.
r,g,bFgBias	float	.5, .5, .5	Foreground bias is used to reduce the blue spill on foreground objects. Keylight uses this colour to calculate which shades the screen colour will pass through as it interacts with the foreground elements. For example, blonde hair in front of a blue screen tends to go through a magenta stage. Setting the FG Bias to the blonde colour will make sure this magenta cast is properly neutralised. This value effects both opacity and spill suppression. Returning it to .5, .5, .5 effectively deactivates this effect. You should avoid picking strong colours for the FG Bias. Muted shades work much better. Another way of looking at this colour is as a way of preserving a foreground colour that might otherwise be neutralised. For example a pale green object in front of a greenscreen would normally become slightly transparent, with the background showing through instead of the pale green. By setting the FG Bias to the pale green, it is preserved in the composite.
shadow, midtone, highlightBalance	float	.5, shadowBalance, shadowBalance	This parameter can help you when the screen area is slightly off of a completely pure primary color, for example cyan instead of pure blue. The transparency of the foreground is measured by calculating the difference between the dominant screen colour (blue by default) and a weighted average of the other two colours (red and green). With our example of a cyan screen, there is a greater difference between the blue and the red than the blue and the green since cyan has more green than red. Setting the balance to 0 forces Keylight to ignore the second most dominant colour in the screen, which is green in our example. Setting it to 1 makes it ignore the weakest screen colour (red). There are three controls to tune the low, medium and highlight ranges.
shadow, midtone, highlightGain	float	0, shadowGain, shadowGain	Increasing the gain makes the main matte more transparent. This tends to tint the edges the opposite of the screen colour - for blue screens edges become yellow. Decreasing the gain makes the main matte more opaque.
midTonesAt	float	.5	Sets the level of the midtones used by the Balance and Gain controls. If you are working on a dark shot, for example, you may want to set the midtone level to a dark grey to make the controls differentiate between tones that would otherwise all be considered shadows.
r, g, bReplace	float	.5, .5, .5	Spill can be replaced by the Replace Colour. This happens only in the opaque areas of the holdout matte. This is useful when you have blue areas in the foreground that you want to keep blue and opaque. The Replace Color would therefore be blue.
r, g, bExposure	float	1, rExposure, rExposure	This allows you to do color correction on the foreground element. This exactly mimics Shake's Brightness node.
r, g, bGamma	float	1, rGamma, rGamma	This applies a gamma correction to the foreground element, exactly mimicking Shake's Gamma node.
saturation	float	1	This applies a saturation correction to the foreground element, exactly mimicking Shake's Saturation node.
colourspace	string	"linear"	Keylight models the interaction of the blue/green light from the screen with the foreground elements. For these calculations to work correctly, you need to specify how pixel values relate to light levels. This is the function of the colourspace menu. Therefore with Cineon plates (or other logarithmic files) you have to option to pull the key with or without a Delog operator before the key pull. log - colourspaces are designed so that a constant difference in pixel values represents a fixed brightness difference. e.g. In the Cineon 10 bit file format a difference of 90 between two pixels corresponds to one pixel being twice as bright as the other. linear - This colourspace has the brightness of a pixel proportional to its value. A pixel at 128 will be twice as bright as one at 64 for example. video - colourspace has a more complicated relationship, but approximately the brightness is proportional to the pixel value raised to the power of 2.2
useHoldOutMatte	int	1	If the third image input is used for a holdout matte, this can toggle it on and off.
bgColor	int	1	Either pulls a key on the area outside of the frame (0), or asserts the background as the background color (i.e., usually black).

Synopsis

image = Keylight( 
  image Background,
  image Foreground,
  image HoldOutMatte,
  int clipMode,
  string output,
  float rScreen,
  float gScreen,
  float bScreen,
  float screenRange,
  float rFgBias,
  float gFgBias,
  float bFgBias,
  float shadowBalance,
  float midtoneBalance,
  float highlightBalance,
  float shadowGain,
  float midtoneGain,
  float highlightGain,
  float midTonesAt,
  float rReplace,
  float gReplace,
  float bReplace,
  float rExposure,
  float gExposure,
  float bExposure,
  float rGamma,
  float gGamma,
  float bGamma,
  float saturation,
  string colourspace,
  int useHoldOutMatte,
  int bgColor,
);

Script

image = Keylight(
  Background,
  Foreground,
  HoldOutMatte,
  clipMode
  "output",
  rScreen,
  gScreen,
  bScreen,
  screenRange,
  rFgBias,
  gFgBias,
  bFgBias,
  shadowBalance,
  midtoneBalance,
  highlightBalance,
  shadowGain,
  midtoneGain,
  highlightGain,
  midTonesAt,
  rReplace,
  gReplace,
  bReplace,
  rExposure,
  gExposure,
  bExposure,
  rGamma,
  gGamma,
  bGamma,
  saturation,
  "colourspace",
  useHoldOutMatte,
  bgColor
);