vc2_bit_widths.helpers: Helper Functions

The vc2_bit_widths.helpers module provides a set of high-level utility functions implementing the key processes involved in bit-width analysis and test picture production for VC-2 codecs. These functions are used in much the same way as the command line interfaces, so refer to Tutorial for a more general introduction.

Many of the functions in this module can take a significant amount of time to execute for very large filters. Status information is reported using Python’s built-in logging library and may be made visible using:

>>> import logging
>>> logging.basicConfig(level=logging.INFO)

Static filter analysis

static_filter_analysis(wavelet_index, wavelet_index_ho, dwt_depth, dwt_depth_ho, num_batches=1, batch_num=0)

Performs a complete static analysis of a VC-2 filter configuration, computing theoretical upper- and lower-bounds for signal values (see Computing signal bounds with Affine Arithmetic) and heuristic test patterns (see Test pattern generation) for all intermediate and final analysis and synthesis filter values.

Parameters

wavelet_indexvc2_data_tables.WaveletFilters or int

wavelet_index_hovc2_data_tables.WaveletFilters or int

dwt_depthint

dwt_depth_hoint

The filter parameters.

num_batchesint

batch_numint

Though for most filters this function runs either instantaneously or at worst in the space of a couple of hours, unusually large filters can take an extremely long time to run. For example, a 4-level Fidelity transform may take around a month to evaluate.

These arguments may be used to split this job into separate batches which may be computed separately (and in parallel) and later combined. For example, setting num_batches to 3 results in only analysing every third filter phase. The batch_num parameter should then be set to either 0, 1 or 2 to specify which third.

The skipped phases are simply omitted from the returned dictionaries. The dictionaries returned for each batch should be unified to produce the complete analysis.

Returns

analysis_signal_bounds{(level, array_name, x, y): (lower_bound_exp, upper_bound_exp), …}

synthesis_signal_bounds{(level, array_name, x, y): (lower_bound_exp, upper_bound_exp), …}

Expressions defining the upper and lower bounds for all intermediate and final analysis and synthesis filter values.

The keys of the returned dictionaries give the level, array name and filter phase for which each pair of bounds corresponds (see Terminology). The naming conventions used are those defined by vc2_bit_widths.vc2_filters.analysis_transform() and vc2_bit_widths.vc2_filters.synthesis_transform(). Arrays which are just interleavings, subsamplings or renamings of other arrays are omitted.

The lower and upper bounds are given algebraically as LinExps.

For the analysis filter bounds, the expressions are defined in terms of the variables LinExp("signal_min") and LinExp("signal_max"). These should be substituted for the minimum and maximum picture signal level to find the upper and lower bounds for a particular picture bit width.

For the synthesis filter bounds, the expressions are defined in terms of variables of the form LinExp("coeff_LEVEL_ORIENT_min") and LinExp("coeff_LEVEL_ORIENT_max") which give lower and upper bounds for the transform coefficients with the named level and orientation.

The evaluate_filter_bounds() function may be used to substitute concrete values into these expressions for a particular picture bit width.

analysis_test_patterns: {(level, array_name, x, y): TestPatternSpecification, …}

synthesis_test_patterns: {(level, array_name, x, y): TestPatternSpecification, …}

Heuristic test patterns which are designed to maximise a particular intermediate or final filter value. For a minimising test pattern, invert the polarities of the pixels.

The keys of the returned dictionaries give the level, array name and filter phase for which each set of bounds corresponds (see Terminology). Arrays which are just interleavings, subsamplings or renamings of other arrays are omitted.

Calculating bit-width requirements

evaluate_filter_bounds(wavelet_index, wavelet_index_ho, dwt_depth, dwt_depth_ho, analysis_signal_bounds, synthesis_signal_bounds, picture_bit_width)

Evaluate all analysis and synthesis filter signal bounds expressions for a given picture bit width, giving concrete signal ranges.

Parameters

wavelet_indexvc2_data_tables.WaveletFilters or int

wavelet_index_hovc2_data_tables.WaveletFilters or int

dwt_depthint

dwt_depth_hoint

The filter parameters.

analysis_signal_bounds{(level, array_name, x, y): (lower_bound_exp, upper_bound_exp), …}

synthesis_signal_bounds{(level, array_name, x, y): (lower_bound_exp, upper_bound_exp), …}

The outputs of static_filter_analysis().

picture_bit_widthint

The number of bits in the input pictures.

Returns

concrete_analysis_signal_bounds{(level, array_name, x, y): (lower_bound, upper_bound), …}

concrete_synthesis_signal_bounds{(level, array_name, x, y): (lower_bound, upper_bound), …}

The concrete, integer signal bounds for all analysis and signal filters given a picture_bit_width-bit input picture.

Includes values for all arrays and phases, even if array interleavings/subsamplings/renamings are omitted in the input arguments.

evaluate_test_pattern_outputs(wavelet_index, wavelet_index_ho, dwt_depth, dwt_depth_ho, picture_bit_width, quantisation_matrix, max_quantisation_index, analysis_test_patterns, synthesis_test_patterns)

Given a set of test patterns, compute the signal levels actually produced by them when passed through a real encoder/decoder.

Parameters

wavelet_indexvc2_data_tables.WaveletFilters or int

wavelet_index_hovc2_data_tables.WaveletFilters or int

dwt_depthint

dwt_depth_hoint

The filter parameters.

picture_bit_widthint

The number of bits in the input pictures.

quantisation_matrix{level: {orient: value, …}, …}

The quantisation matrix.

max_quantisation_indexint

The maximum quantisation index to try (e.g. as computed by quantisation_index_bound()). Each synthesis test pattern will be quantised with every quantisation index up to (and inclusing) this limit and the worst-case value for any quantisation index will be reported.

analysis_test_patterns{(level, array_name, x, y): TestPatternSpecification, …}

synthesis_test_patterns{(level, array_name, x, y): TestPatternSpecification, …}

The test patterns to assess, e.g. from static_filter_analysis() or optimise_synthesis_test_patterns().

Returns

analysis_test_pattern_outputs{(level, array_name, x, y): (lower_bound, upper_bound), …}

synthesis_test_pattern_outputs{(level, array_name, x, y): ((lower_bound, qi), (upper_bound, qi)), …}

The worst-case signal levels achieved for each of the provided test signals when using minimising and maximising versions of the test pattern respectively.

For the syntehsis test patterns, the quantisation index used to achieve the worst-case values is also reported.

Includes values for all arrays and phases, even if array interleavings/subsamplings/renamings are omitted in the input arguments.

Bounding quantisation indices

quantisation_index_bound(concrete_analysis_signal_bounds, quantisation_matrix)

Find the largest quantisation index which could usefully be used given the supplied analysis signal bounds.

Parameters

concrete_analysis_signal_bounds{(level, orient, x, y): (lower_bound, upper_bound), …}

Concrete analysis filter bounds as produced by, e.g., evaluate_filter_bounds().

quantisation_matrix{level: {orient: value, …}, …}

The quantisation matrix in use.

Returns

max_quantisation_indexint

The upper bound for the quantisation indices sensibly used by an encoder. This value will be the smallest quantisation index which will quantise all possible transform coefficients to zero.

Optimising synthesis test patterns

optimise_synthesis_test_patterns(wavelet_index, wavelet_index_ho, dwt_depth, dwt_depth_ho, quantisation_matrix, picture_bit_width, synthesis_test_patterns, max_quantisation_index, random_state, number_of_searches, terminate_early, added_corruption_rate, removed_corruption_rate, base_iterations, added_iterations_per_improvement)

Perform a greedy search based optimisation of a complete set of synthesis test patterns.

See Search algorithm & parameters for details of the optimisation process and parameters.

Parameters

wavelet_indexvc2_data_tables.WaveletFilters or int

wavelet_index_hovc2_data_tables.WaveletFilters or int

dwt_depthint

dwt_depth_hoint

The filter parameters.

quantisation_matrix{level: {orient: value, …}, …}

The quantisation matrix in use.

picture_bit_widthint

The number of bits in the input pictures.

synthesis_test_patterns{(level, array_name, x, y): TestPatternSpecification, …}

Synthesis test patterns to use as the starting point for optimisation, as produced by e.g. static_filter_analysis().

max_quantisation_indexint

The maximum quantisation index to use, e.g. computed using quantisation_index_bound().

random_statenumpy.random.RandomState

The random number generator to use for the search.

number_of_searchesint

Repeat the greedy stochastic search process this many times for each test pattern. Since searches will tend to converge on local minima, increasing this parameter will tend to produce improved results.

terminate_earlyNone or int

If an integer, stop searching if the first terminate_early searches fail to find an improvement. If None, always performs all searches.

added_corruption_ratefloat

The proportion of pixels to assign with a random value during each search attempt (0.0-1.0).

removed_corruption_ratefloat

The proportion of pixels to reset to their starting value during each search attempt (0.0-1.0).

base_iterationsint

The initial number of search iterations to perform in each attempt.

added_iterations_per_improvementint

The number of additional search iterations to perform whenever an improved picture is found.

Returns

optimised_test_patterns{(level, array_name, x, y): OptimisedTestPatternSpecification, …}

The optimised test patterns.

Note that arrays are omitted for arrays which are just interleavings of other arrays.

Generating test pictures

generate_test_pictures(picture_width, picture_height, picture_bit_width, analysis_test_patterns, synthesis_test_patterns, synthesis_test_pattern_outputs)

Generate a series of test pictures containing the supplied selection of test patterns.

Parameters

picture_widthint

picture_heightint

The dimensions of the pictures to generate.

picture_bit_widthint

The number of bits in the input pictures.

analysis_test_patterns{(level, array_name, x, y): TestPatternSpecification, …}

synthesis_test_patterns{(level, array_name, x, y): TestPatternSpecification, …}

The individual analysis and synthesis test patterns to be combined. A maximising and minimising variant of each pattern will be included in the output. See static_filter_analysis() and optimise_synthesis_test_patterns().

synthesis_test_pattern_outputs{(level, array_name, x, y): ((lower_bound, qi), (upper_bound, qi)), …}

The worst-case quantisation indicies for each synthesis test pattern, as computed by evaluate_test_pattern_outputs().

Returns

analysis_pictures[AnalysisPicture, …]

synthesis_pictures[SynthesisPicture, …]

A series of test pictures containing correctly aligned instances of each supplied test pattern.

Pictures are returned with values in the range 0 to (2**picture_bit_width)-1, as expected by a VC-2 encoder.

Each analysis picture includes a subset of the test patterns supplied (see AnalysisPicture). The analysis test pictures are intended to be passed to an analysis filter as-is.

Each synthesis test picture includes a subset of the test patterns supplied, grouped according to the quantisation index to be used. The synthesis test pictures should first be passed through a synthesis filter and then the transform coefficients quantised using the quantisation index specified (see SynthesisPicture). The quantised transform coefficients should then be passed through the synthesis filter.

class AnalysisPicture(picture, test_points)

namedtuple(). A test picture which is to be used to assess an analysis filter.

Parameters

picturenumpy.array

The test picture.

test_points[TestPoint, …]

A list of locations within the analysis filter being tested by this picture.

class SynthesisPicture(picture, quantisation_index, test_points)

namedtuple(). A test picture which is to be used to assess an synthesis filter.

Parameters

picturenumpy.array

The test picture.

quantisation_indexint

The quantisation index to use for all picture slices when encoding the test picture.

test_points[TestPoint, …]

A list of locations within the synthesis filter being tested by this picture.

class TestPoint(level, array_name, x, y, maximise, tx, ty)

namedtuple(). Definition of the location of a point in an encoder/decoder tested by a test picture.

Parameters

levelint

array_namestr

xint

yint

The encoder/decoder intermediate value array and phase tested by this test point.

maximisebool

If True, at this point the signal level is being maximised, if False it will be minimised.

txint

tyint

The coordinates (in the intermediate value array (level, array_name)) which are being maximised or minimised.