Registered User
Join Date: Nov 2009
Posts: 327
|
Scaling, colorspace conversion, and dithering library
Some folks have expressed interest in having a program library to perform the common tasks of manipulating resolution, colorspace, and depth. The "z" library (name subject to change) provides a simple interface to perform those tasks. An open source Vapoursynth plugin is provided, demonstrating the usage of the API.
Code:
NAME:
z - z.lib for VapourSynth
SYNOPSIS:
z.Format(clip clip,
int "width",
int "height",
int "format",
enum "matrix",
enum "transfer",
enum "primaries",
enum "range",
enum "chromaloc",
enum "matrix_in",
enum "transfer_in",
enum "primaries_in",
enum "range_in",
enum "chromaloc_in",
string "resample_filter",
float "filter_param_a",
float "filter_param_b",
string "resample_filter_uv",
float "filter_param_a_uv",
float "filter_param_b_uv",
string "dither_type")
z.Subresize(clip clip,
int width,
int height,
float "shift_w",
float "shift_h",
float "subwidth",
float "subheight",
string "resample_filter",
float "filter_param_a",
float "filter_param_b",
string "dither_type")
DESCRIPTION:
z.Format is a drop-in replacement for the built-in VapourSynth resize
functions. It converts a clip of known or unknown format to another clip
of known or unknown format, changing only the parameters specified by the
user. z.Subresize provides advanced resampling capabilities intended for
use by script writers.
Arguments denoted as type "enum" may be specified by numerical index
(see ITU-T H.265 Annex E.3) or by name. Enums specified by name have their
argument name suffixed with "_s".
clip: input clip
The input may be of COMPAT color family (requires VS R28).
width,
height: output image dimensions
format: output format preset id
The output may be of COMPAT color family (requires VS R28).
matrix,
transfer,
primaries: output colorspace specification
If not provided, the corresponding attribute from the input clip will
be selected, except for YCoCg and RGB color families, where the
corresponding matrix is set by default.
range: output pixel range
For integer formats, this allows selection of the legal code values.
Even when set, out of range values (BTB/WTW) may be generated. If the
input format is of a different color family, the default range is
studio/limited for YUV and full-range for RGB.
chromaloc: output chroma location
For subsampled formats, specifies the chroma location. If the input
format is 4:4:4 or RGB and the output is subsampled, the default
location is left-aligned, as per MPEG.
matrix_in,
transfer_in,
primaries_in,
range_in,
chromaloc_in: input colorspace/format specification
If the corresponding frame property is set to a value other than
unspecified, the frame property is used instead of this parameter.
Default values are set for certain color families.
resample_filter,
filter_param_a,
filter_param_b: scaling method for RGB and Y-channel
For the bicubic filter, filter_param_a/b represent the "b" and "c"
parameters. For the lanczos filter, filter_param_a represents the
number of taps.
resample_filter_uv,
resample_filter_uv_a,
resample_filter_uv_b: scaling method for UV channels
dither_type: dithering method
Dithering is used only for conversions resulting in an integer format.
shift_w,
shift_h: offset of image top-left corner
The top-left image corner is assumed to be at coordinate (0, 0) and
the first sample centered at coordinate (0.5, 0.5). An offset may be
applied to the assumed image origin to "shift" the image.
subwidth,
subheight: fractional dimensions of input image
The input image is assumed to span from its origin a distance equal to
its dimensions in pixels. An alternative image resolution may be
specified.
The following tables list values of selected colorspace enumerations and
their abbreviated names. For all possible values, see ITU-T H.265.
Matrix coefficients (ITU-T H.265 Table E.5):
rgb Identity
The identity matrix.
Typically used for GBR (often referred to as RGB);
however, may also be used for YZX (often referred to as
XYZ);
709 KR = 0.2126; KB = 0.0722
ITU-R Rec. BT.709-5
unspec Unspecified
Image characteristics are unknown or are determined by the
application.
470bg KR = 0.299; KB = 0.114
ITU-R Rec. BT.470-6 System B, G (historical)
(functionally the same as the value 6 (170m))
170m KR = 0.299; KB = 0.114
SMPTE 170M (2004)
(functionally the same as the value 5 (470bg))
ycgco YCgCo
2020ncl KR = 0.2627; KB = 0.0593
Rec. ITU-R BT.2020 non-constant luminance system
2020cl KR = 0.2627; KB = 0.0593
Rec. ITU-R BT.2020 constant luminance system
Transfer characteristics (ITU-T H.265 Table E.4):
709 V = a * Lc0.45 - ( a - 1 ) for 1 >= Lc >= b
V = 4.500 * Lc for b > Lc >= 0
Rec. ITU-R BT.709-5
(functionally the same as the values 6 (601),
14 (2020_10) and 15 (2020_12))
unspec Unspecified
Image characteristics are unknown or are determined by the
application.
601 V = a * Lc0.45 - ( a - 1 ) for 1 >= Lc >= b
V = 4.500 * Lc for b > Lc >= 0
Rec. ITU-R BT.601-6 525 or 625
(functionally the same as the values 1 (709),
14 (2020_10) and 15 (2020_12))
linear V = Lc for all values of Lc
Linear transfer characteristics
2020_10 V = a * Lc0.45 - ( a - 1 ) for 1 >= Lc >= b
V = 4.500 * Lc for b > Lc >= 0
Rec. ITU-R BT.2020
(functionally the same as the values 1 (709),
6 (601) and 15 (2020_12))
2020_12 V = a * Lc0.45 - ( a - 1 ) for 1 >= Lc >= b
V = 4.500 * Lc for b > Lc >= 0
Rec. ITU-R BT.2020
(functionally the same as the values 1 (709),
6 (601) and 14 (2020_10))
Color primaries (ITU-T H.265 Table E.3):
709 primary x y
green 0.300 0.600
blue 0.150 0.060
red 0.640 0.330
white D65 0.3127 0.3290
Rec. ITU-R BT.709-5
unspec Unspecified
Image characteristics are unknown or are determined by the
application.
170m primary x y
green 0.310 0.595
blue 0.155 0.070
red 0.630 0.340
white D65 0.3127 0.3290
SMPTE 170M (2004)
(functionally the same as the value 7 (240m))
240m primary x y
green 0.310 0.595
blue 0.155 0.070
red 0.630 0.340
white D65 0.3127 0.3290
SMPTE 240M (1999)
(functionally the same as the value 6 (170m))
2020 primary x y
green 0.170 0.797
blue 0.131 0.046
red 0.708 0.292
white D65 0.3127 0.3290
Rec. ITU-R BT.2020
Pixel range (ITU-T H.265 Eq E-4 to E-15):
limited Y = Clip1Y( Round( ( 1 << ( BitDepthY - 8 ) ) *
( 219 * E'Y + 16 ) ) )
Cb = Clip1C( Round( ( 1 << ( BitDepthC - 8 ) ) *
( 224 * E'PB + 128 ) ) )
Cr = Clip1C( Round( ( 1 << ( BitDepthC - 8 ) ) *
( 224 * E'PR + 128 ) ) )
R = Clip1Y( ( 1 << ( BitDepthY - 8 ) ) *
( 219 * E'R + 16 ) )
G = Clip1Y( ( 1 << ( BitDepthY - 8 ) ) *
( 219 * E'G + 16 ) )
B = Clip1Y( ( 1 << ( BitDepthY - 8 ) ) *
( 219 * E'B + 16 ) )
full Y = Clip1Y( Round( ( ( 1 << BitDepthY ) - 1 ) * E'Y ) )
Cb = Clip1C( Round( ( ( 1 << BitDepthC ) - 1 ) * E'PB +
( 1 << ( BitDepthC - 1 ) ) ) )
Cr = Clip1C( Round( ( ( 1 << BitDepthC ) - 1 ) * E'PR +
( 1 << ( BitDepthC - 1 ) ) ) )
R = Clip1Y( ( ( 1 << BitDepthY ) - 1 ) * E'R )
G = Clip1Y( ( ( 1 << BitDepthY ) - 1 ) * E'G )
B = Clip1Y( ( ( 1 << BitDepthY ) - 1 ) * E'B )
Chroma location (ITU-T H.265 Figure E.1):
left
center
top_left
top
bottom_left
bottom
The following scaling methods are available:
point, bilinear, bicubic, spline16, spline36, lanczos
The following dithering methods are available:
none, ordered, random, error_diffusion
Release 2.0.2: Download link
Last edited by Stephen R. Savage; 7th December 2015 at 07:55.
Reason: v2.0.2
|