MatchGrade

The image sequence you want the Source clip to match.

When Task is set to Match Graded Source, this should be a graded version of the Source footage.

When Task is set to Match Different Clip, this should be a different clip rather than a version of the Source footage.

Choose whether you want to match the Source input with a graded version of the same clip or a different clip:

• Match Graded Source - Match the Source clip with a graded version of the same clip (connected to the Target input). This allows you to extract and export a baked-in grade applied to the original clip.

In this mode, MatchGrade expects the same frames in both its inputs.

• Match Different Clip - Match the colors of one clip (Source) with those of another (Target). This allows you to create a grade to reproduce the look of the Target clip in the Source clip.

In this mode, MatchGrade expects different frames in the Source and Target inputs.

Set the type of analysis to perform:

• Analyze Reference Frames - Calculate a single, global grade from selected reference frames that cover the characteristic colors in the sequence and apply that grade to every frame of the Source sequence. You can use the controls under Ref Frames to choose the reference frames.

• Auto-analyze Per Frame - Calculate a local grade frame-by-frame, so that the color transform updates according to the current frame.

NOTE:  This control is only available when Task is set to Match Graded Source.

Set whether to use a mask channel to limit the grade to certain areas of the image:

• None - Do not use a mask. The grade is applied to the entire image.

• Alpha - Use the alpha channel as a mask. The grade is limited to the non-black areas of the alpha channel.

• Inverted Alpha - Invert the alpha channel and use that as a mask. The grade is limited to the non-white areas of the alpha channel.

Using a mask can be useful if you only want to match certain elements between shots or balance the color content when Task is set to Match Different Clip.

NOTE:  When Task is set to Match Graded Source, only the alpha from the Source input is used.
When Task is set to Match Different Clip, the alpha from both inputs is used.

When enabled, the computed grade is only applied to the areas of the source controlled by the Mask.

When disabled, the grade is applied to the whole image instead, allowing you to compute the grade from a selected region and apply it to the whole image without having to export the LUT.

NOTE:  This control is only displayed when the Mask control is set to anything other than None.

Select what to display in the Viewer:

• Matched - View the color matched result.

• Source - View the Source input. This can be useful when setting reference frames for the Source input.

• Target - View the Target input. This can be useful when setting reference frames for the Target input.

Click this to add a Transform node and a Reformat node upstream of the MatchGrade node to automatically align the target with the source clip.

You can use Align Target to Source if the clips are not aligned in time and space, such as when the target clip has been reformatted.

NOTE:  This control is only available when Task is set to Match Graded Source.

When enabled, clicking Align Target to Source generates a rectangular crop for the target input.

You can use Crop Target if the target contains a region that isn't present in the source, for example a black border.

NOTE:  This control is only available when Task is set to Match Graded Source.

Ref Frames - These controls are only available when Analysis is set to Analyze Reference Frames.

Displays the Source input frames that you have set as reference frames. These should be frames that cover the characteristic colors in the Source sequence.

When Task is set to Match Graded Source, the same frames are also used as reference frames from the Target input.

Set the current Source input frame as a reference frame.

Remove the current Source input frame from the reference frames.

Displays the Target input frames that you have set as reference frames. These should be frames that cover similar content as the Source reference frames (for example, the same amount of grass, skin, and so on).

NOTE:  You do not need to use the same number of Source and Target reference frames or set the same frames as reference frames for both.

NOTE:  This control is only available when Task is set to Match Different Clip.

Set the current Target input frame as a reference frame.

NOTE:  This control is only available when Task is set to Match Different Clip.

Remove the current Target input frame from the reference frames.

NOTE:  This control is only available when Task is set to Match Different Clip.

Analysis

Set the transformation used to grade the Source input:

• 3D LUT - Calculate the grade as a 3D look-up table (LUT). If necessary, you can use the Export controls to write this to a .csp format and then click Create OCIOFileTransform to create an OCIOFileTransform node that applies the grade.

• CDL - Calculate the grade as a color decision list (CDL). If necessary, you can click Create OCIOCDLTransform to create an OCIOCDLTransform node that applies the grade.

NOTE:  The CDL transform is limited and cannot model all types of color transformation. In most cases, selecting 3D LUT gives the best results.

NOTE:  This control is only available when you have set at least one reference frame.

Specify a 1D shaper LUT to use for the analysis:

• Auto Detect - Automatically detect the best pre-LUT to use.

• Linear - Use a linear pre-LUT.

• Logarithmic - Use a logarithmic pre-LUT.

Set the resolution of the LUT in which MatchGrade stores the color transformation.

A value of 16 speeds up processing. A value of 64 can improve the results, but also increases processing time.

If two very similar colors in the Source image are very different in the Target, try setting this to 64, which is the maximum value.

Set the colorspace to use:

• RGB

• YUV

• LAB

The correct setting to use depends on the nature of the transformation. Try each option to see which works best with your footage.

NOTE:  This control is only available when Task is set to Match Different Clip.

The number of refinement passes. Higher values can produce a better color match, but also take longer to process.

NOTE:  This control is only available when Task is set to Match Different Clip.

Click this to calculate the grade.

NOTE:  This control is only available when you have set at least one reference frame.

The slope value of the CDL transform. If you're not happy with the value MatchGrade calculates automatically, you can use this to fine-tune the results.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

Lock the slope value to prevent MatchGrade from recalculating it when Recalculate CDL is pressed.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

The offset value of the CDL transform. If you're not happy with the value MatchGrade calculates automatically, you can use this to fine-tune the results.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

Lock the offset value to prevent MatchGrade from recalculating it when Recalculate CDL is pressed.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

The power value of the CDL transform. If you're not happy with the value MatchGrade calculates automatically, you can use this to fine-tune the results.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

Lock the power value to prevent MatchGrade from recalculating it when Recalculate CDL is pressed.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

The saturation value of the CDL transform. If you're not happy with the value MatchGrade calculates automatically, you can use this to fine-tune the results.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

Lock the saturation value to prevent MatchGrade from recalculating it when Recalculate CDL is pressed.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

Displays the error for the CDL transform. The smaller the value, the better the results.

This value cannot be edited.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

Click this to recalculate the CDL transform that best fits the 3D LUT. CDL Output values that have lock enabled are not recalculated.

This allows you to manually set some values and automatically estimate others. For example, you can adjust and lock slope and offset and then click this button to automatically recalculate power and saturation.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

Export

The file path and name of the 3D LUT file to export. The file extension is .csp.

NOTE:  This control is only available when Transform is set to 3D LUT and you have clicked Analyze Reference Frames.

Click this to export the 3D LUT to the .csp file specified in the LUT output file field.

NOTE:  This control is only available when Transform is set to 3D LUT and you have clicked Analyze Reference Frames.

Click this to create an OCIOFileTransform node that you can use elsewhere in the script to apply the same grade.

NOTE:  This control is only available when Transform is set to 3D LUT and you have clicked Analyze Reference Frames.

Click this to create an OCIOCDLTransform node that you can use elsewhere in the script to apply the same grade.

NOTE:  This control is only available when Transform is set to CDL and you have clicked Analyze Reference Frames.

These functions run prior to starting rendering in execute(). If they throw an exception, the render aborts.

These functions run prior to starting rendering of each individual frame. If they throw an exception, the render aborts.

These functions run after each frame is finished rendering. They are not called if the render aborts. If they throw an exception, the render aborts.

These functions run after rendering of all frames is finished. If they throw an error, the render aborts.