Scaling, colorspace conversion, and dithering library

[Stephen R. Savage]

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.

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