Vapoursynth ColorMatrix

From wiki.selur.net
Jump to navigation Jump to search

ColorMatrix converts YUV video from one set of YUV↔RGB coefficients (the color matrix, e.g. BT.709 or BT.601) to another, directly in YUV. Use it when the target needs another matrix than the source, for example when HD material (BT.709) is turned into SD (BT.601), or when the source was encoded with a different matrix than it is flagged with.

Filtering → Vapoursynth → Color → Conversion

ColorMatrix controls in Hybrid
ColorMatrix controls in Hybrid

What it does

The picture is converted from the From matrix to the To matrix with VapourSynth's resize, so that the colors look the same after decoding with the new matrix. Format, bit depth and range stay as they are. ColorMatrix changes neither the primaries nor the transfer characteristic; it is not a tone mapper.

Settings

Control Parameter Values Hybrid default Meaning
From matrix_in_s Rec.709, FCC, Rec.601/470bg/470m, SMPTE 170m, SMPTE 240m, YCgCo, Rec.2020ncl, Rec.2020cl, Chroma ncl, Chroma cl matrix of the source Matrix the clip is converted from. While the filter is off it follows the source's matrix; change it when the source is flagged wrongly.
To matrix_s same list SMPTE 170m Matrix the clip is converted to. Disabled while Adjust by resolution is on.
Adjust by resolution – on/off on Picks To from the output resolution: Rec.601/470bg up to 720×576, Rec.709 up to 1920×1088, Rec.2020ncl above.
Transfer _Transfer BT.709, BT.470 System M, BT.470 System B/G, BT.601, SMPTE 240M, Linear, Log (100:1), Log (316.22777:1), xvYCC, sRGB, BT.2020 (10-bit), BT.2020 (12-bit), PQ, HLG BT.709 Transfer characteristic of the clip; only used (and enabled) when From or To is a 2020 or Chroma matrix, which depend on it.
Clipping – no clipping, pre clipping, post clipping, pre and post clipping pre and post clipping Limits luma to 16–235 and chroma to 16–240 (8-bit scale, scaled to the bit depth) before, after, or before and after the conversion.

Example

A BT.709 clip converted to BT.601 (470bg) for SD output, 10-bit, with the default clipping:

# ColorMatrix: adjusting color matrix from 709 to 470bg
# ColorMatrix: clipping to TV levels
clip = core.std.Limiter(clip=clip, min=[64, 64, 64], max=[940, 960, 960])
clip = core.std.RemoveFrameProps(clip=clip, props=["_Matrix"])
clip = core.resize.Bicubic(clip, matrix_in_s="709", matrix_s="470bg")
# ColorMatrix: clipping to TV levels
clip = core.std.Limiter(clip=clip, min=[64, 64, 64], max=[940, 960, 960])

How Hybrid calls it

  • ColorMatrix works on every YUV format and keeps it.
  • Nothing is written when From and To are the same matrix.
  • VapourSynth's resize ignores matrix_in_s while the clip carries a matrix frame property, so Hybrid removes that property right before the conversion; resize sets the new one.
  • For 2020 and Chroma matrices the chosen transfer is written as frame property before the conversion.
  • The resizer kernel is the one chosen as Color resizer in Hybrid's Vapoursynth settings (Bicubic by default).
  • After the filter Hybrid uses To as the clip's matrix for all following conversions.
  • Switching on HDR10ToSDR or HDR10 to SDR (DG) switches ColorMatrix off, and the other way round.
  • ColorMatrix also offers the common options (Masked, ApplyOnlyTo, Merge, OnRegion, Gimmick).

Background

VapourSynth (resize)

The core resizers convert between formats and color spaces with the zimg library. matrix_in_s/matrix_s name the coefficients (709, fcc, 470bg, 170m, 240m, ycgco, 2020ncl, 2020cl, chromancl, chromacl, ictcp). The documentation notes that the _in arguments only apply when the matching frame property is unset, and that resize does not clip: values outside the legal range can remain, which is why Hybrid clips with std.Limiter.

AviSynth

AviSynth+ converts between matrices with ConvertToYUV…/ConvertToRGB… and their matrix parameter; a direct YUV-to-YUV matrix change is done with the external ColorMatrix plugin. See Avisynth ColorMatrix.

Sources