Fmtconv

Revision as of 17:02, 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.

Examples

TODO

Changelog

See GitHub release page.

External Links

• GitHub - Source code repository.

Back to External Filters ←