vc2_conformance.codec_features: Codec feature definitions

The vc2_conformance.codec_features module defines the CodecFeatures fixeddict which is used to describe codec and video format configurations. These are used to control the test case generators (vc2_conformance.test_cases) and encoder (vc2_conformance.encoder).

fixeddict CodecFeatures

A definition of a set of coding features supported by a video codec implementation. In practice, a particular codec’s feature set may be defined by a collection of these, defining support for several picture formats.

Keys

namestr

A unique, human-readable name to identify this collection of features (e.g. "uhd_over_hd_sdi").

levelLevels

The VC-2 level. The user is responsible for choosing settings below which actually conform to this level.

profileProfiles

The VC-2 profile to use.

picture_coding_modePictureCodingModes

The picture coding mode to use.

video_parametersVideoParameters

The video format to use.

wavelet_index, wavelet_index_hoWaveletFilters

The wavelet transform to use. For symmetric transforms, both values must be equal.

dwt_depth and dwt_depth_hoint

The transform depths to use. For symmetric transforms, dwt_depth_ho must be zero.

slices_x and slices_yint

The number of picture slices, horizontally and vertically.

fragment_slice_countint

If fragmented pictures are in use, should be non-zero and contain the maximum number of slices to include in each fragment. Otherwise, should be zero.

losslessbool

If True, lossless variable-bit-rate coding will be used. If false, fixed-rate lossy coding is used.

picture_bytesint or None

When lossless is False, this gives the number of bytes per picture to use. Slices will be assigned (as close to) the same number of bytes each as possible. If lossless is True, this value should be None.

quantization_matrixNone or {level: {orient: value, …}, …}

None or a hierarchy of dictionaries as constructed by the quant_matrix pseudocode function (12.4.5.3). If None, the default quantization matrix will be used.

The read_codec_features_csv() may be used to read these structures from a CSV. This functionality is used by the vc2-test-case-generator script.

read_codec_features_csv(csvfile)

Read a set of CodecFeatures from a CSV file in the format described by Defining codec features.

Parameters

csvfileiterable

An iterable of lines from a CSV file, e.g. an open file object.

Returns

codec_feature_setsOrderedDict([(name, CodecFeatures), …])

Raises

InvalidCodecFeaturesError

Raised if the provided CSV contains invalid or incomplete data.

Note

Validation largely extends only to syntactic issues (e.g. invalid integer values, ‘picture_bytes’ being specified for lossless formats etc). It does not include validation of ‘deeper’ issues such as too-small picture_bytes values or parameters not being permitted by the specified level.

exception InvalidCodecFeaturesError

Raised by read_codec_features_csv() encounters a problem with the data presented in a codec features listing CSV file.

Finally, the following function may be used when determining level-related restrictions which apply to a set of CodecFeatures.

codec_features_to_trivial_level_constraints(codec_features)

Returns the some of the values a given CodecFeatures would assign in a level_constraints table.

Parameters

codec_featuresCodecFeatures

Returns

constrained_values{key: concrete_value, …}

A partial set of level_constraints, specifically containing the following keys:

• level

• profile

• picture_coding_mode

• wavelet_index

• dwt_depth

• slices_x

• slices_y

• slices_have_same_dimensions

• custom_quant_matrix

In addition for the low delay profile only:

• slice_bytes_numerator

• slice_bytes_denominator

In addition for the high quality profile only:

• slice_prefix_bytes

Note

In principle, more keys could be determined, however a line in the sand is required for what is considered ‘simple’ to determine and what requires re-implementing much of the codec. We draw the line at these values since all of them are straight-forward to work out.