Fmtconv

From Avisynth wiki
Revision as of 01:20, 29 June 2022 by Reel.Deal (Talk | contribs)

Jump to: navigation, search
Abstract
Author cretindesalpes
Version r29
Download fmtconv-r29.zip
Category Resize
License Open source
Discussion Doom9 Forum


Contents

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 focused primarily on quality and exactness rather than execution speed. This does not mean it is slow or un-optimized, 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        |y        |Description
--------------+--------------+---------+---------+--------------
"709" or      |R             |0.640,    0.330    |ITU-R BT.709-5
"1361" or     |G             |0.300,    0.600    |ITU-R BT.1361
"61966-2-1" or|B             |0.150,    0.060    |IEC 61966-2-1 (sRGB or sYCC)
"61966-2-4" or|W(65)         |0.3127,   0.3290   |IEC 61966-2-4
"hdtv" or     |              |                   |Annex B of SMPTE RP 177 (1993)
"srgb" or     |              |                   |
--------------+--------------+---------+---------+--------------
"470m" or     |R             |0.670,    0.330    |ITU-R BT.470-6 System M (historical)
"ntsc"        |G             |0.210,    0.710    |NTSC (1953)
              |B             |0.140,    0.080    |FCC
              |W (C)         |0.3100,   0.3160   |
--------------+--------------+---------+---------+--------------
"470m93" or   |R             |0.670,    0.330    |ITU-R BT.470-6 System M — Japan (NTSC-J)
"ntscj"       |G             |0.210,    0.710    |
              |B             |0.140,    0.080    |
              |W (9305K)     |0.2848,   0.2932   |
--------------+--------------+---------+---------+--------------
"470bg" or    |R             |0.640,    0.330    |ITU-R BT.470-6 System B, G (historical)
"601-625" or  |G             |0.290,    0.600    |ITU-R BT.601-6 625
"1358-625" or |B             |0.150,    0.060    |ITU-R BT.1358 625
"1700-625" or |W (65)        |0.3127,   0.3290   |ITU-R BT.1700 625 PAL and 625 SECAM
"pal" or      |              |                   |
"secam"       |              |                   |
--------------+--------------+---------+---------+--------------
"170m" or     |R             |0.630,    0.340    |SMPTE 170M (2004)
"240m" or     |G             |0.310,    0.595    |SMPTE 240M (1999)
"601-525" or  |B             |0.155,    0.070    |ITU-R BT.601-6 525
"1358-525" or |W (65)        |0.3127,   0.3290   |ITU-R BT.1358 525
"1700-525"    |              |                   |ITU-R BT.1700 NTSC
--------------+--------------+---------+---------+--------------
"filmc"       |R (Wratten 25)|0.681,    0.319    |Generic film (colour filters using Illuminant C)
              |G (Wratten 58)|0.243,    0.692    |
              |B (Wratten 47)|0.145,    0.049    |
              |W (C)         |0.3100,   0.3160   |
--------------+--------------+---------+---------+--------------
"2020" or     |R             |0.70792,  0.29203  |ITU-R BT.2020
"2100" or     |G             |0.17024,  0.79652  |ITU-R BT.2100
"uhdtv"       |B             |0.13137,  0.04588  |
              |W (65)        |0.31271,  0.32902  |
--------------+--------------+---------+---------+--------------
"61966-2-2" or|R             |0.640,    0.330    |IEC 61966-2-4 (scRGB)
"scrgb"       |G             |0.300,    0.600    |
              |B             |0.150,    0.060    |
              |W (65)        |0.31271,  0.32902  |
--------------+--------------+---------+---------+--------------
"adobe98"     |R             |0.640,    0.330    |Adobe RGB (1998)
              |G             |0.210,    0.710    |
              |B             |0.150,    0.060    |
              |W (65)        |0.31271   0.32902  |                                                               
--------------+--------------+---------+---------+--------------
"adobewide"   |R             |0.73469,  0.26531  |Adobe Wide Gamut RGB
              |G             |0.11416,  0.82621  |
              |B             |0.15664,  0.01770  |
              |W (50)        |0.34567,  0.35850  |
--------------+--------------+---------+---------+--------------
"apple"       |R             |0.625,    0.265    |Apple RGB
              |G             |0.280,    0.826    |
              |B             |0.155,    0.018    |
              |W (65)        |0.31271   0.32902  |
--------------+--------------+---------+---------+--------------
"photopro" or |R             |0.7347,   0.2653   |PhotoPro
"romm"        |G             |0.1596,   0.8404   |ROMM
              |B             |0.0366,   0.0001   |
              |W (50)        |0.34567   0.35850  |
--------------+--------------+---------+---------+--------------
"ciergb"      |R             |0.7347,   0.2653   |CIE RGB (1931)
              |G             |0.2738,   0.7174   |
              |B             |0.1666,   0.0089   |
              |W (E)         |1 / 3,    1 / 3    |
--------------+--------------+---------+---------+--------------
"ciexyz"      |R             |1.0,      0.0      |CIE XYZ (1931)
              |G             |0.0,      1.0      |
              |B             |0.0,      0.0      |
              |W (E)         |1 / 3,    1 / 3    |
--------------+--------------+---------+---------+--------------
"p3dci"       |R             |0.680,    0.320    |SMPTE ST 2113 P3-DCI
              |G             |0.265,    0.690    |SMPTE RP 431-2
              |B             |0.150,    0.060    |
              |W             |0.314,    0.351    |
--------------+--------------+---------+---------+--------------
"p3d65"       |R             |0.680,    0.320    |SMPTE ST 2113 P3-D65
              |G             |0.265,    0.690    |SMPTE EG 432-1
              |B             |0.150,    0.060    |
              |W (65)        |0.3127,   0.3290   |
--------------+--------------+---------+---------+--------------
"p3d60"       |R             |0.680,    0.320    |ACES P3-D60
              |G             |0.265,    0.690    |
              |B             |0.150,    0.060    |
              |W (60)        |0.32168,  0.33767  |
--------------+--------------+---------+---------+--------------
"3213"        |R             |0.630,    0.340    |EBU Tech. 3213-E
              |G             |0.295,    0.605    |
              |B             |0.155,    0.077    |
              |W (65)        |0.3127,   0.3290   |
--------------+--------------+---------+---------+--------------
"aces"        |R             |0.7347,   0.2653   |ACES
              |G             |0.0,      1.0      |SMPTE ST 2065-1
              |B             |0.0001,   -0.077   |
              |W (60)        |0.32168,  0.33767  |
--------------+--------------+---------+---------+--------------
"ap1"         |R             |0.713,    0.293    |ACEScc/ACESproxy AP1
              |G             |0.165,    0.830    |
              |B             |0.128,    -0.044   |
              |W (60)        |0.32168,  0.33767  |
--------------+--------------+---------+---------+--------------
"sgamut" or   |R             |0.730,    0.280    |Sony S-Gamut
"sgamut3"     |G             |0.140,    0.855    |Sony S-Gamut3
              |B             |0.100,    -0.050   |
              |W (65)        |0.3127,   0.3290   |
--------------+--------------+---------+---------+--------------
"sgamut3cine" |R             |0.766,    0.275    |Sony S-Gamut3.Cine
              |G             |0.225,    0.800    |
              |B             |0.089,    -0.087   |
              |W (65)        |0.3127,   0.3290   |
--------------+--------------+---------+---------+--------------
"alexa"       |R             |0.6840,   0.3130   |Arri ALEXA
              |G             |0.2210,   0.8480   |
              |B             |0.0861,   -0.1020  |
              |W (65)        |0.3127,   0.3290   |
--------------+--------------+---------+---------+--------------
"vgamut"      |R             |0.730,    0.280    |Panasonic V-Gamut
              |G             |0.165,    0.840    |
              |B             |0.100,    -0.03    |
              |W (65)        |0.3127,   0.3290   |
--------------+--------------+---------+---------+--------------
"p22"         |R             |0.625,    0.340    |Sony P22
              |G             |0.280,    0.595    |
              |B             |0.280,    0.070    |
              |D(93)         |0.28315,  0.29711  |
--------------+--------------+---------+---------+--------------
"fs"          |R             |0.7347,   0.2653   |Free Scale-gamut
              |G             |0.140,    0.860    |
              |B             |0.100,    −0.02985 |
              |W (65)        |0.31272,  0.32903  |
--------------+--------------+---------+---------+--------------
"davinci"     |R             |0.8000,   0.3130   |DaVinci wide gamut
              |G             |0.1682,   0.9877   |
              |B             |0.0790,   −0.1155  |
              |W (65)        |0.3127,   0.3290   |
--------------+--------------+---------+---------+--------------
"dragon"      |R             |0.75304,  0.32783  |DRAGONcolor
              |G             |0.29957,  0.70070  |
              |B             |0.07964,  -0.05494 |
              |W (60)        |0.32168,  0.33767  |
--------------+--------------+---------+---------+--------------
"dragon2"     |R             |0.75304,  0.32783  |DRAGONcolor2
              |G             |0.29957,  0.70070  |
              |B             |0.14501,  0.05110  |
              |W (60)        |0.32168,  0.33767  |
--------------+--------------+---------+---------+--------------
"red"         |R             |0.69975,  0.32905  |REDcolor
              |G             |0.30426,  0.62364  |
              |B             |0.13491,  0.03472  |
              |W (60)        |0.32168,  0.03472  |
--------------+--------------+---------+---------+--------------
"red2"        |R             |0.87868,  0.32496  |REDcolor2
              |G             |0.30089,  0.67905  |
              |B             |0.09540,  −0.02939 |
              |W (60)        |0.32168,  0.33767  |
--------------+--------------+---------+---------+--------------
"red3"        |R             |0.70118,  0.32901  |REDcolor3
              |G             |0.30060,  0.68379  |
              |B             |0.10815,  −0.00869 |
              |W (60)        |0.32168,  0.33767  |
--------------+--------------+---------+---------+--------------
"red4"        |R             |0.70118,  0.32901  |REDcolor4
              |G             |0.30060,  0.68379  |
              |B             |0.14533,  0.05162  |
              |W (60)        |0.32168,  0.33767  |
--------------+--------------+---------+---------+--------------
"redwide"     |R             |0.780308, 0.304253 |REDWideGamutRGB
              |G             |0.121595, 1.493994 |
              |B             |0.095612, −0.084589|
              |W (65)        |0.3217,   0.3290   |
Note: the values above were inserted in the wiki manually. In case of doubt, you should check the official docs first and foremost.


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
  • 7: limit to AVX
  • 10: limit to AVX2


Information, Syntax and Parameters for fmtc_resample

Resizes the planes of a clip. This function can change the chroma subsampling.

Output is always 16-bit integer (default for integer input) or 32-bit float. Use fmtc.bitdepth to convert the result to a lower bitdepth. It is possible to select the internal precision: float, or 16-bit integers with a 32-bit accumulator for the convolution. Internal conversion from float or 32-bit integers to 16 bits is done by quick rounding (no dithering). The integer operation path is available only when input and output formats are integer too.

The function can resize interlaced content, but only if presented as separated, interleaved fields. It uses the _Field and _FieldBased frame properties to detect interlaced content and field parity, maintaining the correct chroma and luma relative positions. If this automatic detection is not desired, you can specify manually the interlaced and tff parameters. Simple intra-field deinterlacing (“bob”) can be achieved this way, by specifying scalev=2.

Excepted impulse*, array parameters allow to specify plane-specific values. When specifying less than 3 values, the last specified value will be reused for the next planes. However planes works slightly differently, check the related paragraph for details.

Arrays can be specified as values printed in a string and separated with spaces.

  • Note: field resizing is not always the best way to handle interlaced content, especially for upscales. You’ll probably have better results by using a “smart” deinterlacer (making use of temporal information and anti-aliasing), resizing the progressive content at double rate then reinterlacing. Simple field resampling is more or less equivalent to this method, using a naive bob.

Interlacing parameters are automatically detected with global clip information which can be overriden by frame properties.

The function can also be used to compute horizontal and vertical convolutions. If you do so, don’t forget to set:

  • fh or fv to −1 to make sure the clip is processed even if its size doesn’t change;
  • cnorm to false to avoid automatic kernel normalisation if your impulse is already normalised, or specify total if the normalisation factor is not the sum of the impulse;
  • and center to False to keep the desired spacing between the sampling points.

The function handles the following frame properties: 

Property         |Read condition                 |Write condition
-----------------+-------------------------------+----------------------------
_FieldBased      |Automatic interlacing detection|Interlaced content
_Field           |Interlaced content             |Interlaced content
_ChromaLocation  |(none)                         |Depends on cplace parameters
_ColorRange      |(none)                         |fulld is explicitly set


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

fmtc_resample (clip c, int w, int h, arrayf sx, arrayf sy, arrayf sw, arrayf sh, float scale, float scaleh, float scalev, string kernel, string kernelh, string kernelv, arrayf impulse, arrayf impulseh, arrayf impulsev, arrayi taps, arrayi tapsh, arrayi tapsv, arrayf a1, arrayf a2, arrayf a3, arrayf a1h, arrayf a2h, arrayf a3h, arrayf a1v, arrayf a2v, arrayf a3v, int kovrspl, arrayf fh, arrayf fv, bool cnorm, arrayf total, arrayf totalh, arrayf totalv, arrayb invks, arrayb invksh, arrayb invksv, arrayi invkstaps, arrayi invkstapsh, arrayi invkstapsv, string csp, string css, arrayf planes, int fulls, int fulld, arrayb center, string cplace, string cplaces, string cplaced, int interlaced, int interlacedd, int tff, int tffd, bool flt, int cpuopt)
clip  c =
Clip to be resized
Supports all the mentioned input formats at the top + 9-bit YUV (YUV410).
int  w = (undefined)
int  h = (undefined)
New picture width and height in pixels, > 0. If not specified, it will keep the original dimensions. The dimensions must be compatible with the destination chroma subsampling. They take precedence over the scale, scaleh and scalev parameters.


arrayf  sx = 0
arrayf  sy = 0
Coordinate of the top-left corner of the picture sub-area used as source for the resizing. They can be fractional. If negative, the picture is extended by replicating the left pixel column.
These parameters are arrays, so it’s possible to specify a different value for each plane. The last value is used for the unspecified planes. The coordinates are always related to the pixel dimensions, you don’t need to scale them with the chroma subsampling.


arrayf  sw = 0
arrayf  sh = 0
Size in pixels of the sub-area to resize. They can be fractional. If 0, the area has the same size as the source clip. If negative, they define coordinates relative to the bottom-right corner, in a Crop-like manner. These parameters are arrays like sx and sy.


float  scale = 0
float  scaleh = 0
float  scalev = 0
Use these parameters to set relative dimensions, > 0. For example scale=0.5 will halve the picture size. The computed dimensions will be compatible with the destination chroma subsampling. Zero is ignored.


string  kernel = "spline36"
Kernel used by the resizer. Possible values are:
  • "point" : Nearest neighbour interpolation. Same as PointResize.
  • "rect", "box" : Box filter.
  • "linear", "bilinear": Bilinear interpolation. Same as BilinearResize.
  • "cubic", "bicubic" : Bicubic interpolation. Same as BicubicResize. The b and c variables are mapped on a1 and a2 and are both set to 1/3 by default.
  • "lanczos" : Sinc function windowed by the central lobe of a sinc. Use taps to specify its impulse length. Same as LanczosResize.
  • "blackman" : Blackman-Harris windowed sinc. Use taps to control its length. Same as BlackmanResize.
  • "blackmanminlobe" : Another kind of Blackman windowed sinc, with a bit less ringing. Use taps for you know what.
  • "spline16" : Standard cubic spline based kernel, 4 sample points. Same as Spline16Resize.
  • "spline36" : Spline, 6 sample points. Same as Spline36Resize.
  • "spline64" : Spline, 8 sample points. Same as Spline64Resize.
  • "spline" : Generic natural cubic splines, number of sample points is twice the taps parameter, so you can use taps = 6 to get a more or less Spline144Resize equivalent.
  • "gauss", "gaussian" : Gaussian kernel. The p parameter is mapped on a1 and controls the curve width. The higher p, the sharper. It is set to 30 by default. This resizer is the same as GaussResize, but taps offers a control on the filter impulse length. For low p values (soft and blurry), it’s better to increase the number of taps to avoid truncating the gaussian curve too early and creating artifacts.
  • "sinc" : Truncated sinc function. Use taps to control its length. Same as SincResize.
  • "impulse" : Custom kernel. See the impulse parameter.


arrayf  impulse = (undefined)
arrayf  impulseh = impulse
arrayf  impulsev = impulse
Offers the possibility to create your own kernel (useful for convolutions). Add your coefficents in the array. The number of coefficients must be odd. The curve is linearly interpolated between the provided points. You can oversample the impulse by setting kovrspl to a value > 1. To activate the custom kernel, set kernel="impulse".


arrayi  taps = 4
arrayi  tapsh = taps
arrayi  tapsv = taps
Some kernels have a variable number of sample points, given by this parameter. Actually this counts half the number of lobes (or equivalent); in case of downscaling, the actual number of sample points may be greater than the specified value. Range: 1–128


arrayf  a1 = (undefined)
arrayf  a2 = (undefined)
arrayf  a3 = (undefined)


arrayf  a1h = a1
arrayf  a2h = a2
arrayf  a3h = a3


arrayf  a1v = a1
arrayf  a2v = a2
arrayf  a3v = a3
Specific parameters, depending on the selected kernel.


int  kovrspl = 1
Specifies here how many times the kernel is oversampled when you provide a custom impluse response. ≥ 1.


arrayf  fh = 1
arrayf  fv = 1
Horizontal and vertical frequency factors, also known as inverse kernel support. They are multipliers on the theoretical kernel cutoff frequency in both directions. Values below 1.0 spatially expand the kernel and blur the picture. Values over 1.0 shrink the kernel and let higher frequencies pass. The result will look sharper but more aliased. The multiplicator is applied after the kernel scaling in case of downsizing. Negative values force the processing, even if the horizontal size doesn’t change. The filter will use the absolute parameter value.


bool  cnorm = true
If set to true, the impulse sum is normalised to 1 for each pixel. This is the normal behaviour when resizing, to make sure the energy is constant for all pixels. If you use the resizer as a convolution engine, it is advised to disable the normalisation.


arrayf  total = 0
arrayf  totalh = total
arrayf  totalv = total
When cnorm is activated, these parameters specify the normalisation value for the corresponding kernel. 0 means that the normalisation value is the sum of the coefficients. The Masktools’mt_convolution function has a single parameter for this use: total = totalh × totalv. Because the convolution is computed with floating point data, there is no saturation of intermediate results, therefore the balance between totalh and totalv is not important, only their product will be taken into account. Note that because kernels are single-dimention, the “parent” total parameter here is the sum of the coefficients for each direction, not the product of totalh and totalv.


arrayb  invks = false
arrayb  invksh = invks
arrayb  invksv = invks
Set these parameter to True to activate the kernel inversion mode for the specified direction (use invks for both). Inverting the kernel allows to “undo” a previous upsizing by compensating the loss in high frequencies, giving a sharper and more accurate output than classic kernels, closer to the original. This is particularly useful for clips upscaled with a bilinear kernel. All the kernel-related parameters specify the kernel to undo. The target resolution must be as close as possible to the initial resolution. The kernel inversion is mainly intended to downsize an upscaled picture. Using it for upsizing will not restore details but will give a sligthly sharper look, at the cost of a bit of aliasing and ringing. This mode is somewhat equivalent to the debilinear plug-in but works with a different principle.


arrayi  invkstaps = 4
arrayi  invkstapsh = invkstaps
arrayi  invkstapsv = invkstaps
In kernel inversion mode (invks=True), this parameter sets the number of taps for the inverted kernel. Use it as a tradeof between softness and ringing. Range: 1–128


string  csp = (undefined)
Can only change the bitdepth and the data type (integer or float). Only 16-bit integer (xxxP16) and 32-bit float data types 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.


string  css = (undefined)
Destination chroma subsampling, for YUV (and YCoCg) colorspaces. Supersedes the chroma subsampling from csp. You can also specify the subsampling with the predefined values or with a two-digit string. The first digit for the horizontal subsampling, and the second for the vertical subsampling. Only power-of-2 numbers are allowed. For example "41" is equivalent to 4:1:1 and "22" to 4:2:0.


The predefined values are:
  • "444" or "4:4:4" 4:4:4, no chroma subsampling.
  • "422" or "4:2:2" 4:2:2, horizontal 2x chroma subsampling.
  • "420" or "4:2:0" 4:2:0, horizontal and vertical 2x chroma subsampling.
  • "411" or "4:1:1" 4:1:1, horizontal 4x chroma subsampling.


arrayf  planes = all
This array decribes how each plane should be processed. It’s similar to the y, u and v parameters in Masktools 2.
  • −65535 to +0.5 : All the pixels of the plane will be set to −x (the opposite of the specified value). The range depends on the output data type. Remember, in floating-point YUV, the chroma planes range from −0.5 to +0.5.
  • 1 : The plane will not be processed. This means that the content of the output plane is pure garbage.
  • 2 : The plane of the input clip will be copied and possibly cropped. Areas out of the input picture are left unprocessed (garbage). Range (full or TV) conversions are ignored.
  • 3 : The plane will be processed (default).
The parameter can also be specified as a string. See the planes parameter from the fmtc_bitdepth function for more details.


int  fulls = (depends)
int  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 Y’Cb’Cr’ 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.


arrayb  center = true
Like the Avisynth standard resizers, this resizer preserves the position of the picture center. Disable this parameter if you may want to resize by preserving the top-left corner position. Similarly, if you are convolving without resizing, setting it to false ensures you that the same kernel will be applied to all pixels.


arrayb  cplace = "mpeg2"
arrayb  cplaces = cplace
arrayb  cplaced = cplace
Placement of the chroma samples. cplaces specifies the source clip only, cplaced the destination clip. Can be one of these strings:
  • "MPEG1", "JPEG" "center" : 4:2:0 subsampling used in MPEG-1 and JPEG. Chroma samples are located on the center of each group of 4 pixels.
  • "MPEG2", "left" : Subsampling used in MPEG-2 4:2:x and most other formats. Chroma samples are located on the left pixel column of the group.
  • "DV" : For 4:2:0 modes, it’s like MPEG-2 but U and V channels are “co-sited” vertically: V on the top row, and U on the bottom row. For 4:1:1, chroma is located on the leftmost column.
  • "top_left", "tl" : Chroma samples are located on the top-left luma sample of each pixel group.
The chroma placement is ignored when center is set to False or kernel to "point". You’ll find below an overview of common chroma placement and subsampling combinations:

Chroma placement (image:https://raw.githubusercontent.com/EleonoreMizo/fmtconv/master/doc/colorspace-subsampling.png)

int  interlaced = 2
int  interlacedd = (interlaced)
Specifies if the clip is made of frames or fields. interlacedd overrides interlaced for output.
  • 0 : Frames are progressive content.
  • 1 : Frames are actually the separated fields of an interlaced stream. Specify tff or provide the _Field property in all the frames.
  • 2 : Automatic detection, depends on the _FieldBased frame property. If not found, the frame is considered progressive.


int  tff = 2
int  tffd = tff
When processing interlaced content, specifies the field parity. tffd overrides tff for output.
  • 0 : Bottom field first (BFF). This means all even fields are top, and all odd fields are bottom.
  • 1 : Top field first (TFF). This means all even fields are bottom, and all odd fields are top.
  • 2 : Automatic detection, depends on the _Field frame property. If not found, the frame is considered progressive.


bool  flt = false
Flag to force floating point operations. When set to False, integer operations are used, but only if both input and output formats are integer. If it’s not the case, floating point operations are silently used as fallback.


int  cpuopt = -1
Limits the CPU instruction set. −1: automatic (no limitation), 0: , 1: , .
  • -1 : automatic (no limitation).
  • 0 : default instruction set only (depends on the compilation settings).
  • 1 : limit to SSE2.
  • 10 : limit to AVX2.



Examples

TODO

Changelog

See GitHub release page.

External Links

  • GitHub - Source code repository.



Back to External Filters ←

Retrieved from "http://avisynth.nl/index.php?title=Fmtconv&oldid=12656"
Personal tools