Fmtconv

Revision as of 19:42, 13 May 2022

Description

fmtconv is a format-conversion plug-in for the VapourSynth and AviSynth+ video processing engines. It does:

• Resizing.
• Bitdepth conversion with dithering.
• Colorspace conversion (matrix, transfer characteristics and chromatic adaptation).

It supports:

• Pixel data types: 8-–12-, 14- and 16-bit integer, 32-bit float.
• Colorspaces: RGB, Y, YUV in 4:4:4, 4:2:2, 4:2:0, 4:1:1 and YCgCo with the same chroma subsampling factors.
• Progressive and interlaced content.

Fmtconv is focussed primarily on quality and exactness rather than execution speed. This does not mean it is slow or unoptimized, but fmtconv is clearly not on par with the fastest equivalent 8-bit filters.

See doc/fmtconv.html for more information.

Requirements

• AviSynth+ 3.7.0 x86/x64
• Supported color formats: all planar formats (8/10/12/14/16/32-bit, YUV/RGB with or without alpha).

Information, Syntax and Parameters for fmtc_bitdepth

Bitdepth conversion with optional dithering.

Dithering is performed when meeting at least one of these conditions:

• Reducing the bitdepth of integer data, or converting from float to integer.
• Doing a full-range ↔ TV-range conversion between integer formats, because the resulting values haven’t an exact representation.

Video compression seems to retrain better pure ordered (Bayer) dithering. Therefore this is the recommended method to avoid color banding in 8 bit signals, unless you encode at high bitrates. If you don’t care about video compression, error diffusion, void and cluster and quasirandom sequence methods give the most accurate results. To avoid discontinuities between purely flat areas and dithered areas (also called noise modulation), you can add a bit of noise, ideally in triangular distribution.

The internal noise generator is deterministic and will give the same result each run.

The internal processing is done in floating point as soon as the input is floating point or a range conversion is detected.

The _ColorRange frame property is set if at least one of the fulls or fulld parameter has been explicitely defined.

fmtc_bitdepth (clip c, int "bits", bool "flt", string "planes", bool "fulls", bool "fulld", int "dmode", float "ampo",float "ampn",bool "dyn", bool "staticnoise", int "cpuopt", int "patsize", bool "tpdfo", bool "tpdfn",bool "corplane")

clip   =

Input clip.

int  bits = -1

Destination bitdepth. A negative value means that the parameter is left undefined.

bool  flt = undefined

Set it to 1 to convert to float, and to 0 for integer data. As long as only 32-bit floating point data is supported, you don’t need to specify the bitdepth for a float conversion.

string  planes = "all"

A list of planes to process. The content of an unprocessed plane should be considered as garbage.

This is a string made of concatenated substrings for each plane, in any order. The planes are identified by their index, as well as the following aliases:

• "0", "y", "r" Y or red
• "1", "u", "g" U or green
• "2", "v", "b" V or blue
• "3", "a" Alpha channel
• "all" All the planes

bool  fulls = (depends)

bool  fulld = fulls

Indicates if the clip is full-range (True) or TV-range (False). fulls is for input, fulld for output. Reference black and white have different values depending on the range. In 8 bits, pixel values scale from 0 to 255 in full range, and 16 to 235 in TV-range (16 to 240 for the YUV chroma planes). This value has no meaning for float data.

The default value depends on the colorspace. For example, full-range is assumed for RGB and YCoCg colorspaces. Others are assumed TV-range. These parameters are mainly intended to guide conversions between integer and floating-point data. They can also be used for range conversions. Pixel values are not clipped during a conversion between two TV-range formats.

Alpha planes are always processed as full-range.

int  dmode = 3

Dithering mode, when applicable.

• 0: Ordered dithering (Bayer matrix).
• 1: No dither, round to the closest value.
• 2: Round, may be a bit faster but possibly less accurate.
• 3: Sierra-2-4A error diffusion, aka “Filter Lite”. Quick and excellent quality, similar to Floyd-Steinberg.
• 4: Stucki error diffusion. Preserves delicate edges better but distorts gradients.
• 5: Atkinson error diffusion. Generates distinct patterns but keeps clean the flat areas (noise modulation).
• 6: Classic Floyd-Steinberg error diffusion, modified for serpentine scan (avoids worm artefacts).
• 7: Ostromoukhov error diffusion. Slow, available only for integer input at the moment. Avoids usual F-S artefacts.
• 8: Void and cluster halftone dithering. This is a way to generate blue-noise dither and has a much better visual aspect than ordered dithering.
• 9: Dither using quasirandom sequences. Good intermediated between Void and cluster and error diffusion algorithms.

When using error-diffusion dithering on interlaced content, you should separate the fields first before converting them.

float  ampo = 1.0

The ordered dither peak-to-peak amplitude, depends on the target bitdepth. ≥ 0. On error diffusion algorithms, it increases the collected error amount, helping to extend the range of the dithering while preserving its natural pattern (especially Atkinson’s). This gives a better looking result than just adding noise.

float  ampn = 0.0

The noise peak-to-peak amplitude, depends on the target bitdepth. ≥ 0. Currently, the maximum value is 4. The noise is added before dithering. It reduces the SNR but a small amount may give a better, more uniform visual appearance.

bool  dyn = false

Indicates if the ordered dither pattern is dynamic (True) or static (False). If dynamic, the pattern is changed or rotated each frame.

bool  staticnoise = false

If set to true, the noise generated with ampn is static and remains the same every frame.

int  cpuopt = -1

Limits the CPU instruction set.

• −1: automatic (no limitation)
• 0: default instruction set only (depends on the compilation settings)
• 1: limit to SSE2
• 10: limit to AVX2

int  patsize = 32

Width of the pattern used in the Void and cluster algorithm.

• The only valid values are power of 2 ranging from 4 to 1024: 4, 8, 16, 32, 64, 128, 256, 512 and 1024.

bool  tpdfo = false

Set it to true to enable the triangular probability distribution function (TPDF) for halftone-based dithering algorithms. It has no effect on error diffusion methods. 0 is the standard rectangular distribution (RPDF).

Note that when triangular distribution is enabled, the maximum halftone amplitude is multiplied by 1.414 at constant ampo.

bool  tpdfn = false

Same as tpdfo, but for the additive noise part. TPDF noise looks more natural than RPDF noise, and is a crude approximation of a gaussian noise, with a bounded amplitude. Maximum noise amplitude is multiplied by 1.414 at constant ampn, so the introduced noise power is kept approximately constant.

bool  corplane = false

Set it to true to keep the dither and noise patterns correlated for all the planes. When processing a RGB picture, it helps to prevent colored noise on grey features.

Information, Syntax and Parameters for fmtc_matrix

Colorspace conversion or simple cross-plane matrix.

For Y’Cb’Cr’ and Y’Co’Cg’ colorspaces, 4:4:4 is required (no chroma subsampling). To process a subsampled colorspace, you must convert it to 4:4:4 first.

The output is not dithered, therefore you should output at a higher bitdepth than the input and dither afterward with bitdepth to avoid potential banding.

When the destination color family (R’G’B’, Y’Cb’Cr’ or Y’Co’Cg’) is not specified (via col_fam or csp), the function tries to deduce it from the matrix settings and the source color family. If it cannot be deduced, the color family remains unchanged.

Please note that this function doesn’t do conversions based on the color primaries. The R’G’B’ data are always relative to their specified standard. For example, converting Y’Cb’Cr’ data straight from BT.2020 to BT.709 doesn’t make sense as these colorspaces are defined with different primaries. For meaningful results, convert to R’G’B’ then to linear RGB and use primaries to perform the intermediary conversion.

The _ColorRange frame property is set if the fulld parameter has been explicitely defined. If the destination colorspace is a standardized one (as deduced from the specified matrix), the _Matrix and _ColorRange properties are set, otherwise they are deleted from the frame.

If an alpha channel is present in both the source and destination colorspaces, it is copied and its bitdepth is possibly adapted to the destination format. If there is no alpha channel in the source, full opacity is assumed. If there is no alpha channel in the destination, the plane is lost.

The _ColorRange frame property is set if at least one of the fulls or fulld parameter has been explicitely defined.

fmtc_matrix (clip c, string mat, string mats, string matd, bool fulls, bool fulld, arrayf coef, string csp, string col_fam, int bits, int singleout, int cpuopt)

clip  c =

Input clip.

string  mat = -1

Predefined matrix for conversions to and from R’G’B’. The direction is deduced from the specified input and output colorspaces. Possible values are:

• "601": ITU-R BT.601 / ITU-R BT.470-2 / SMPTE 170M. For Standard Definition content.
• "709": ITU-R BT.709. For High Definition content.
• "2020": ITU-R BT.2020, non constant luminance mode. For UHDTV content.
• "2100": ITU-R BT.2100, non constant luminance mode. For UHDTV content.
• "240": SMPTE 240M
• "FCC",
• "470-525": FCC Title 47
• "YCoCg",
• "YCgCo": Y’Co’Cg’
• "YDzDx": Y’D’ZD’X, SMPTE ST 2085
• "RGB": R’G’B’. Identity, no cross-plane calculations.

bool  mats = undefined

bool  matd = undefined

Source and destinations matrices for YUV. Use both when you want to do a conversion between BT.601 and BT.709. Values are the same as mat, with the addition of:

• "LMS": Intermediate colorspace for ICTCP transforms. The LMS colorspace is conveyed on RGB planes.
• "ICtCp_PQ": ITU-R BT.2100-2 ICTCP with perceptual quantization (PQ).
• "ICtCp_HLG": ITU-R BT.2100-2 ICTCP with hybrid log-gamma transfer function (HLG).

When using one of these additional values, make sure to set the other mats or matd with "RGB" to clarify the conversion direction. ICTCP transforms from R’G’B’ require the following steps:

• Convert from R’G’B’ to linear BT.2100 RGB with transfer then possibly primaries.
• Convert from linear BT.2100 RGB to linear LMS using matrix with "LMS".
• Convert from linear LMS to L’M’S’ using transfer with "2084" or "hlg".
• Convert from L’M’S’ to ICTCP using matrix with "ICtCp_PQ" or "ICtCp_HLG", respectively.

For the inverse conversion, reverse the steps. Beware, chromatic information for pixels of the highest luminance range cannot be represented in integer ICTCP and will be clipped because of the large matrix coefficients.

bool  fulls = (depends)

bool  fulld = (depends)

Indicates if the clip is full-range (True) or TV-range (False). fulls is for input, fulld for output. Reference black and white have different values depending on the range. In 8 bits, pixel values scale from 0 to 255 in full range, and 16 to 235 in TV-range (16 to 240 for the YUV chroma planes). This value has no meaning for float data.

The default value depends on the colorspace. For example, full-range is assumed for R’G’B’ and Y’Co’Cg’ colorspaces. Others are assumed TV-range. These parameters are mainly intended to guide conversions between integer and floating-point data. They can also be used for range conversions. Pixel values are not clipped during a conversion between two TV-range formats.

arrayf  coef = (undefined)

A list of 12 coefficients for a custom matrix. The coefficients should be scaled assuming the input is floating point, even if the actual input is integer. This means luma and R’G’B’ signals range from 0 to 1, and chroma signals from −0.5 to +0.5. Coefficients are listed by rows. Each row is terminated with a fourth coefficient, the additive constant (still in floating-point range). This means the matrix is actually 4×3 and during the multiplication, the input column-vector has an implicit 1 appended to its end. For example, with an R’G’B’ input:

+- -+   +-               -+   +- -+
| Y |	| c0  c1  c2  c3  |   | R | 	Y  = R × c0 + G × c1 + B × c2  + c3 
| Cb| = | c4  c5  c6  c7  | × | G | 	Cb = R × c4 + G × c5 + B × c6  + c7 
| Cr| 	| c8  c9  c10 c11 |   | B | 	Cr = R × c8 + G × c9 + B × c10 + c11 
+- -+   +-               -+   | 1 |
                              +- -+

List can be an array of float values if supported by the scripting language, or a string containing the values printed and separated with spaces.

string  csp = (undefined)

The destination format. It cannot change the data type (integer or float) nor the chroma subsampling. If the colorspace family is set to Y, single-plane processing is enabled. The output plane is selected with singleout (0 if not specified). Only planar colorspaces are allowed.

The format is a string with the same kind of content as the result from BuildPixelType or the pixel_type parameter from BlankClip. For example: "RGBP48", "YV12", "YUV444PS"…

string  col_fam = (undefined)

Explicit specification of the destination color family, as Vapoursynth constant. Supersedes the color family from csp. You can only specify colorspace with the same number of planes as the input clip.

int  bits = (undefined)

Explicit specification of the destination bitdepth. The only allowed values are 8, 10, 12, 14, 16 and 32. However you cannot reduce the bitdepth, only keep it constant or increase it. Supersedes the bitdepth from csp.

int  singleout = -1

Enable single-plane processing. This is useful to obtain only the luma from an R’G’B’ input, for example. The parameter is the plane index, ranging from 0 to 2. A negative value specifies that all planes should be processed. If singleout is ≥ 0, it supersedes the colorspace family specified in csp.

Note: when extracting a chroma plane, results between int with TV range and float data type may slightly differ. This is because in float, a neutral chroma (0%) is converted to the exact value of a medium gray (50%). In integer, the chroma output value is mapped 1–1 to the luma channel. However in TV-range, medium gray is not located exactly at the half of the data range, it lies slightly below.

int  cpuopt = -1

Limits the CPU instruction set.

• −1: automatic (no limitation)
• 0: default instruction set only (depends on the compilation settings)
• 1: limit to SSE2
• 10: limit to AVX2

Information, Syntax and Parameters for fmtc_matrix2020cl

Colorspace conversion using the ITU-R BT.2020 constant luminance matrix.

The function converts between linear RGB and Y’Cb’Cr’ colorspaces. This conversion cannot be achieve with a classic linear matrix. The output colorspace, hence the direction of the conversion, is automatically deduced from the input colorspace.

For Y’Cb’Cr’ colorspaces, 4:4:4 is required (no chroma subsampling). To process a subsampled colorspace, you must convert it to 4:4:4 first.

The RGB colorspace is always 16 bits when using integers, or 32 bits in float. The output is not dithered, therefore you should output at a higher bitdepth than the input and dither afterward with bitdepth to avoid potential banding.

Please note that the RGB content is always assumed to be linear light. The BT.2020 gamma curve is used in both directions. When operating on floating point data, the function uses the 12-bit variant of the scaling coefficients.

The _Matrix, _ColorSpace and _Transfer frame properties are set according to the transformation. The _ColorRange property is set if the full parameter has been explicitely defined.

If an alpha channel is present in both the source and destination colorspaces, it is copied and its bitdepth is possibly adapted to the destination format. If there is no alpha channel in the source, full opacity is assumed. If there is no alpha channel in the destination, the plane is lost.

fmtc_matrix2020cl (clip c, bool full, string csp, int bits, int cpuopt)

clip  c =

Input clip.

For RGB, only 16-bit clips are supported

bool  full = false

Indicates if the Y’Cb’Cr’ clip is full-range (True) or TV-range (False). Reference black and white have different values depending on the range. In 8 bits, pixel values scale from 0 to 255 in full range, and 16 to 235 in TV-range (16 to 240 for the YUV chroma planes). This value has no meaning for float data.

string  csp = (undefined)

It must be compatible with what is logically expected as output (RGB or YUV). It cannot change the data type (integer or float) nor the chroma subsampling. If the output is integer RGB, the bitdepth must be 16. Only planar colorspaces are allowed.

The format is a string with the same kind of content as the result from BuildPixelType or the pixel_type parameter from BlankClip. For example: "RGBP48", "YV12", "YUV444PS"…

int  bits = (undefined)

Explicit specification of the destination bitdepth. The only allowed values are 8, 10, 12, 14, 16 and 32. They are restricted by the output data type and format (16 bits for integer RGB). Supersedes the bitdepth from csp.

int  cpuopt = -1

Limits the CPU instruction set.

• −1: automatic (no limitation)
• 0: default instruction set only (depends on the compilation settings)

Information, Syntax and Parameters for fmtc_primaries

Performs a gamut conversion given a set of three primary colors and a reference white to another set of primary colors and a target reference white. Illuminant conversions are done using the Bradford method.

Pixel values are left intact after the transform, they are not bound to the target gamut and could be invalid colors. However, when using 16-bit unsigned integer they are clipped to representable data values.

All colors are given in xyY colorspace, with their x and y coordinates.

You must supply the full description of the original and target gamuts, with the built-in presets or by setting individual components.

Please note that this function does not work at the same level as matrix. The latter converts between gamma-compressed RGB and YUV-like colorspaces, while primaries operates on linear RGB colorspaces exclusively, whose specifications are given by the primaries. For more details, see Poynton, A Guided Tour of Color Space, 1997.

The _Primaries frame property is set or deleted, depending on the target gamut.

fmtc_primaries (clip c, arrayf rs, arrayf gs, arrayf bs,arrayf ws, arrayf rd, arrayf gd, arrayf bd, arrayf wd, string prims, string primd, int cpuopt)

clip  c =

Input clip.

Supported colorspaces are 16- or 32-bit linear RGB. You should use the transfer function to convert between linear RGB and gamma-compressed R’G’B ’colorspaces.

array  rs = (undefined)

array  gs = (undefined)

array  bs = (undefined)

array  ws = (undefined)

Primaries for the source colorspace as red, green, blue and reference white. Each variable contains two components, x and y, in this order. The y value cannot be null.

Parameters can be arrays of two float values if supported by the scripting language, or strings containing both values printed and separated with a space.

array  rd = (undefined)

array  gd = (undefined)

array  bd = (undefined)

array  wd = (undefined)

Primaries for the target colorspace. If not specified, the value is copied from the source colorspace.

string  prims = (undefined)

string  primd = (undefined)

Primaries presets for the source and destination colorspaces. Superseded by individual r, g, b and w settings. Possible values are:

Value         |Primary       |x
--------------+--------------+
"709" or      |R             |0.640,
"1361" or     |G             |0.300,
"61966-2-1" or|B             |0.150,
"61966-2-4" or|W(65)         |0.3127,
"hdtv" or     |              |
"srgb" or     |              |
--------------+--------------+
"470m" or     |R             |0.670,
"ntsc"        |G             |0.210,
              |B             |0.140,
              |W (C)         |0.3100,
--------------+--------------+
"470m93" or   |R             |0.670,
"ntscj"       |G             |0.210,
              |B             |0.140,
              |W (9305K)     |0.2848,
--------------+--------------+
"470bg" or    |R             |0.640,
"601-625" or  |G             |0.290,
"1358-625" or |B             |0.150,
"1700-625" or |W (65)        |0.3127,
"pal" or      |              |
"secam"       |              |
--------------+--------------+
"170m" or     |R             |0.630,
"240m" or     |G             |0.310,
"601-525" or  |B             |0.155,
"1358-525" or |W (65)        |0.3127
"1700-525"    |              |
--------------+--------------+
"filmc"       |R (Wratten 25)|0.681,
              |G (Wratten 58)|0.243,
              |B (Wratten 47)|0.145,
              |W (C)         |3100
--------------+--------------+
"2020" or     |R             |0.70792,
"2100" or     |G             |0.17024,
"uhdtv"       |B             |0.13137,
              |W (65)        |0.31271
--------------+--------------+
"61966-2-2" or|R             |0.640,
"scrgb"       |G             |0.300,
              |B             |0.150,
              |W (65)        |0.31271
--------------+--------------+
"adobe98"     |R             |0.640,
              |G             |0.210,
              |B             |0.150,
              |W (65)        |0.31271
--------------+--------------+
"adobewide"   |R             |0.73469,
              |G             |0.11416,
              |B             |0.15664,
              |W (50)        |0.34567
--------------+--------------+
"apple"       |R             |0.625,
              |G             |0.280,
              |B             |0.155,
              |W (65)        |0.31271
--------------+--------------+
"photopro" or |R             |0.7347,
"romm"        |G             |0.1596,
              |B             |0.0366,
              |W (50)        |0.34567
--------------+--------------+
"ciergb"      |R             |0.7347,
              |G             |0.2738,
              |B             |0.1666,
              |W (E)         |1 / 3
--------------+--------------+
"ciexyz"      |R             |1.0,
              |G             |0.0,
              |B             |0.0,
              |W (E)         |1 / 3
--------------+--------------+
"p3dci"       |R             |0.680,
              |G             |0.265,
              |B             |0.150,
              |W             |0.314
--------------+--------------+
"p3d65"       |R             |0.680,
              |G             |0.265,
              |B             |0.150,
              |W (65)        |0.3127
--------------+--------------+
"p3d60"       |R             |0.680,
              |G             |0.265,
              |B             |0.150,
              |W (60)        |0.32168
--------------+--------------+
"3213"        |R             |0.630,
              |G             |0.295,
              |B             |0.155,
              |W (65)        |0.3127
--------------+--------------+
"aces"        |R             |0.7347,
              |G             |0.0,
              |B             |0.0001,
              |W (60)        |0.32168,
--------------+--------------+
"ap1"         |R             |0.713,
              |G             |0.165,
              |B             |0.128,
              |W (60)        |0.32168,
--------------+--------------+
"sgamut" or   |R             |0.730,
"sgamut3"     |G             |0.140,
              |B             |0.100,
              |W (65)        |0.3127
--------------+--------------+
"sgamut3cine" |R             |0.766,
              |G             |0.225,
              |B             |0.089,
              |W (65)        |0.3127
--------------+--------------+
"alexa"       |R             |0.6840,
              |G             |0.2210,
              |B             |0.0861,
              |W (65)        |0.3127
--------------+--------------+
"vgamut"      |R             |0.730,
              |G             |0.165,
              |B             |0.100,
              |W (65)        |0.3127
--------------+--------------+
"p22"         |R             |0.625,
              |G             |0.280,
              |B             |0.280,
              |D(93)         |0.28315
--------------+--------------+
"fs"          |R             |0.7347,
              |G             |0.140,
              |B             |0.100,
              |W (65)        |0.31272
--------------+--------------+
"davinci"     |R             |0.8000,
              |G             |0.1682,
              |B             |0.0790,
              |W (65)        |0.3127
--------------+--------------+
"dragon"      |R             |0.75304,
              |G             |0.29957,
              |B             |0.07964,
              |W (60)        |0.32168,
--------------+--------------+
"dragon2"     |R             |0.75304,
              |G             |0.29957,
              |B             |0.14501,
              |W (60)        |0.32168,
--------------+--------------+
"red"         |R             |0.69975,
              |G             |0.30426,
              |B             |
              |W (60)        |
--------------+--------------+
"red2"        |R             |
              |G             |
              |B             |
              |W (60)        |
--------------+--------------+
"red3"        |R             |
              |G             |
              |B             |
              |W (60)        |
--------------+--------------+
"red4"        |R             |
              |G             |
              |B             |
              |W (60)        |
--------------+--------------+
"redwide"     |R             |
              |G             |
              |B             |
              |W (65)        |

Examples

TODO

Changelog

See GitHub release page.

External Links

• GitHub - Source code repository.

Back to External Filters ←