The vc2_data_tables Python module

The vc2_data_tables module defines a number of constants and tables based on values published in the SMPTE ST 2042-series of standards documents. References to the standard are shown in brackets and, unless otherwise stated, refer to SMPTE ST 2042-1:2017, the main VC-2 specification.

Enumerated indices defined by the VC-2 specification (for example the parse codes which appear in parse info blocks (10.5.2)) are defined as IntEnum types (e.g. ParseCodes) with informative names assigned to each index. These may be used interchangeably with plain integer values if required or preferred.

Tables of values (for example the table of preset frame rates in (Table 11.1)) are typically represented as dictionaries (e.g. PRESET_FRAME_RATES). In these dictionaries the key is an index (e.g. PresetFrameRates) and the value a namedtuple() (e.g. FrameRate) giving the values for that row in the table.

As an example, the snippet below looks up the frame size of the Digital Cinema 2K base video format:

>>> from vc2_data_tables import BaseVideoFormats, BASE_VIDEO_FORMAT_PARAMETERS

>>> index = BaseVideoFormats.dc2k
>>> index
<BaseVideoFormats.dc2k: 15>

>>> # The named enumerated types are optional and completely interchangeable
>>> # with normal integer values, e.g.
>>> index == 15
True

>>> # Data tables are usually looked up by index (either integers or named
>>> # values may be used)
>>> params = BASE_VIDEO_FORMAT_PARAMETERS[index]
>>> params.frame_width
2048
>>> params.frame_height
1080

(10.5) Parse Info Block

PARSE_INFO_PREFIX = int

(10.5.1) The ‘magic bytes’ used to identify the start of a parse info header.

PARSE_INFO_HEADER_BYTES = int

(10.5.1) The number of bytes in the parse_info header.

class ParseCodes(IntEnum)

(10.5.2) Valid parse_code values from (Table 10.1). Names are not normative.

(11) Picture coding mode identifiers

class PictureCodingModes(IntEnum)

(11.5) Indices defined in the text. Names are not normative.

class ColorDifferenceSamplingFormats(IntEnum)

(11.4.4) Indices from (Table 11.2)

class SourceSamplingModes(IntEnum)

(11.4.5) Indices defined in the text. Names are not normative.

(11.4.6) Preset frame rates

PRESET_FRAME_RATES = {PresetFrameRates: FrameRate, ...}

(11.4.6) Frame-rate presets from (Table 11.3). Lookup from PresetFrameRates to FrameRate tuples.

class PresetFrameRates(IntEnum)

(11.4.6) Preset framerate indices from (Table 11.1).

class FrameRate(numerator, denominator)

(11.4.6) A frame rate numerator and denominator value from (Table 11.1).

Parameters

numeratorint

denominatorint

(11.4.7) Preset pixel aspect ratios

PRESET_PIXEL_ASPECT_RATIOS = {PresetPixelAspectRatios: PixelAspectRatio, ...}

(11.4.7) Pixel aspect ratio presets from (Table 11.4). Lookup from PresetPixelAspectRatios to PixelAspectRatio

class PresetPixelAspectRatios(IntEnum)

(11.4.7) Pixel aspect ratio preset indices from (Table 11.4).

class PixelAspectRatio(numerator, denominator)

(11.4.7) Pixel aspect ratio preset indices from (Table 11.4).

(11.4.9) Signal ranges

PRESET_SIGNAL_RANGES = {PresetSignalRanges: SignalRangeParameters, ...}

(11.4.9) Signal offsets/ranges presets from (Table 11.5). Lookup from PresetSignalRanges to SignalRangeParameters.

class PresetSignalRanges(IntEnum)

(11.4.9) Signal offsets/ranges preset indices from (Table 11.5).

class SignalRangeParameters(luma_offset, luma_excursion, color_diff_offset, color_diff_excursion)

An entry in (Table 11.5).

Parameters

luma_offset

The luma value corresponding with 0.

luma_excursion

The maximum value of an offset luma value.

color_diff_offset

The color difference value corresponding with 0.

color_diff_excursion

The maximum value of an offset color difference value.

(11.4.10.2) Color Primaries

PRESET_COLOR_PRIMARIES = {PresetColorPrimaries: ColorPrimariesParameters, ...}

(11.4.10.2) Normative specification names for color primaries from (Table 11.7). Lookup from PresetColorPrimaries to ColorPrimariesParameters.

class PresetColorPrimaries(IntEnum)

(11.4.10.2) Color primaries from (Table 11.7).

class ColorPrimariesParameters(name, specification)

(11.4.10.2) A color primaries description.

Parameters

name

Informative name.

specificationstr

The name of the specification defining the primaries in use.

(11.4.10.3) Color Matrices

PRESET_COLOR_MATRICES = {PresetColorMatrices: PresetColorMatrices, ...}

(11.4.10.3) Color matrices from (Table 11.8). Lookup from PresetColorMatrices ColorMatrixParameters.

class PresetColorMatrices(IntEnum)

(11.4.10.3) Color matrices from (Table 11.8).

class ColorMatrixParameters(name, specification, color_matrix)

An entry in (Table 11.8)

Parameters

name

Informative name.

specification

Normative specification name.

color_matrix

Normative color matrix description.

(11.4.10.4) Transfer functions

PRESET_TRANSFER_FUNCTIONS = {PresetTransferFunctions: TransferFunctionParameters, ...}

(11.4.10.3) Color matrices from (Table 11.8). Lookup from PresetTransferFunctions to TransferFunctionParameters.

class PresetTransferFunctions(IntEnum)

(11.4.10.4) Transfer functions from (Table 11.9).

class TransferFunctionParameters(name, specification)

An entry in (Table 11.9)

Parameters

name

Informative name.

specification

Normative specification name.

(11.4.10.1) Colour specifications

PRESET_COLOR_SPECS = {PresetColorSpecs: ColorSpecificiation, ...}

(11.4.10.3) Color matrices from (Table 11.8). Lookup from PresetColorSpecs to ColorSpecificiation.

class PresetColorSpecs(IntEnum)

(11.4.10.1) Preset color specification collections from (Table 11.6).

class ColorSpecificiation(color_primaries_index, color_matrix_index, transfer_function_index)

An entry in (Table 11.6)

Parameters

color_primaries

A PresetColorPrimaries index.

color_matrix

A PresetColorMatrices index.

transfer_function

A PresetTransferFunctions index.

(11.3) Base Video Formats

BASE_VIDEO_FORMAT_PARAMETERS = {BaseVideoFormats: BaseVideoFormatParameters, ...}

(B) Base video format specifications from (Table B.1a, B.1b, B.1c). Lookup from BaseVideoFormats to BaseVideoFormatParameters.

class BaseVideoFormats(IntEnum)

(11.3) Base video format indices from (Table 11.1).

class BaseVideoFormatParameters(frame_width, frame_height, color_diff_format_index, source_sampling, top_field_first, frame_rate_index, pixel_aspect_ratio_index, clean_width, clean_height, left_offset, top_offset, signal_range_index, color_spec_index)

2. An entry in (Table B.1a, B.1b or B.1c)

Parameters

frame_width

frame_height

color_diff_format_index

An entry from the enum ColorDifferenceSamplingFormats. Listed as ‘color difference sampling format’ in (Table B.1).

source_sampling

An entry from the enum SourceSamplingModes. Specifies progressive or interlaced.

top_field_first

If True, the top-line of the frame is in the first field.

frame_rate_index

The frame rate, one of the indices of PRESET_FRAME_RATES.

pixel_aspect_ratio_index

The pixel aspect ratio, an entry from the enum PresetPixelAspectRatios.

clean_width

clean_height

left_offset

top_offset

The clean area of the pictures. See (11.4.8) and (E.4.2).

signal_range_index

The signal ranges, an entry from the enum PresetSignalRanges.

color_spec_index

The color specification, an entry from the enum PresetColorSpecs.

(15.4.4) Lifting filters

LIFTING_FILTERS = {WaveletFilters: LiftingFilterParameters, ...}

(15.4.4.3) Filter definitions taken from (Table 15.1 to 15.6). Lookup from WaveletFilters to LiftingFilterParameters.

class WaveletFilters(IntEnum)

(12.4.2) Wavelet filter type indices from (Table 12.1). Names are based on the informative names in the table.

See also: LIFTING_FILTERS.

class LiftingFilterParameters(filter_bit_shift, stages)

(15.4.4.3) The generic container for the details described by (Table 15.1 to 15.6).

Parameters

filter_bit_shift

Right-shift to apply after synthesis (or before analysis).

stages

A list of LiftingStage objects to be used in sequence to perform synthesis with this filter.

class LiftingStage(lift_type, S, L, D, taps)

(15.4.4.1) Definition of a lifting stage/operation in a lifting filter.

Parameters

lift_type

Specifies which lifting filtering operation is taking place. One of the indices from the LiftingFilterTypes enumeration.

S

Scale factor (right-shift applied to weighted sum)

L

Length of filter.

D

Offset of filter.

taps

An array of integers defining the filter coefficients.

class LiftingFilterTypes(IntEnum)

(15.4.4.1) Indices of lifting filter step types. Names are informative and based on an interpretation of the pseudo-code in the specification.

(C.2) Profiles

PROFILES = {Profiles: ProfileParameters, ...}

The list of supported profiles from (C.2). Lookup from Profiles to ProfileParameters.

class Profiles(IntEnum)

(C.2) VC-2 profile identifiers.

class ProfileParameters(allowed_parse_codes)

(C.2) Parameters describing a profile specification.

Parameters

allowed_parse_codes

A list of supported data units. A list of values from the ParseCodes enum.

(D) Quantisation matrices

QUANTISATION_MATRICES = {(wavelet_index, wavelet_index_ho, dwt_depth, dwt_depth_ho): quantisation_matrix, ...}

The preset quantisation matrices from (Table D.1) to (Table D.8)

The loaded matrices are stored in a nested dictionary with the following layout:

QUANTISATION_MATRICES[(wavelet_index, wavelet_index_ho, dwt_depth, dwt_depth_ho)][level][orientation]

Where:

• wavelet_index and wavelet_index_ho are WaveletFilters values

• dwt_depth and dwt_depth_ho are transform depths (integers)

• level is the transform level (integer)

• orientation is one of “L”, “H”, “LL”`, “HL”`, “LH”` or “HH”`

Warning

The values in these tables correspond to those published in SMPTE ST 2042-1:2017. Consequently, errors in the quantisation matrices for the ‘Fidelity’ filter are repeated here.

(ST 2042-2) Levels

LEVELS = {Levels: LevelParameters, ...}

The list of supported levels from (ST 2042-2:2017: 5.2). A lookup from Levels to LevelParameters.

class Levels(IntEnum)

(ST 2042-2:2017: 5.2) VC-2 level identifiers.

class LevelParameters(standard)

(ST 2042-2) Parameters describing a level.

Parameters

standardstr

Name of the standards document which defines the level.