vc2_bit_widths.fast_partial_analyse_quantise_synthesise: Fast single value encode, quantise and decode

This module implements a relatively efficient (for Python) implementation of an encode, quantise and decode cycle where only a single decoder output (or intermediate) value is computed.

Example usage

The example below demonstrates how the FastPartialAnalyseQuantiseSynthesise() function may be used to compute the output of a VC-2 decoder intermediate value for a given picture:

>>> import numpy as np
>>> from vc2_data_tables import (
...     LIFTING_FILTERS,
...     WaveletFilters,
...     QUANTISATION_MATRICES,
... )
>>> from vc2_bit_widths.vc2_filters import (
...     synthesis_transform,
...     make_variable_coeff_arrays,
... )
>>> from vc2_bit_widths.fast_partial_analyse_quantise_synthesise import (
...     FastPartialAnalyseQuantiseSynthesise,
... )

>>> # Codec parameters
>>> wavelet_index = WaveletFilters.le_gall_5_3
>>> wavelet_index_ho = WaveletFilters.le_gall_5_3
>>> dwt_depth = 2
>>> dwt_depth_ho = 0

>>> # Quantisation settings
>>> quantisation_indices = list(range(64))
>>> quantisation_matrix = QUANTISATION_MATRICES[(
...     wavelet_index,
...     wavelet_index_ho,
...     dwt_depth,
...     dwt_depth_ho,
... )]

>>> # A test picture
>>> width = 1024  # NB: Must be appropriate multiple for
>>> height = 512  # filter depth chosen!
>>> picture = np.random.randint(-512, 511, (height, width))

>>> h_filter_params = LIFTING_FILTERS[wavelet_index_ho]
>>> v_filter_params = LIFTING_FILTERS[wavelet_index]

>>> # Construct synthesis expression for target synthesis value
>>> level = 1
>>> array_name = "L"
>>> tx, ty = 200, 100
>>> _, intermediate_synthesis_arrays = synthesis_transform(
...     h_filter_params,
...     v_filter_params,
...     dwt_depth,
...     dwt_depth_ho,
...     make_variable_coeff_arrays(dwt_depth, dwt_depth_ho)
... )
>>> synthesis_exp = intermediate_synthesis_arrays[(level, array_name)][tx, ty]

>>> # Setup codec
>>> codec = FastPartialAnalyseQuantiseSynthesise(
...     h_filter_params,
...     v_filter_params,
...     dwt_depth,
...     dwt_depth_ho,
...     quantisation_matrix,
...     quantisation_indices,
...     synthesis_exp,
... )

>>> # Perform the analysis/quantise/synthesis transforms
>>> codec.analyse_quantise_synthesise(picture.copy())  # NB: corrupts array!

API

class FastPartialAnalyseQuantiseSynthesise(h_filter_params, v_filter_params, dwt_depth, dwt_depth_ho, quantisation_matrix, quantisation_indices, synthesis_exp)

An object which encodes a picture, quantises the transform coefficients at a range of different quantisation indices, and then decodes a single decoder output or intermediate value at each quantisation level.

For valid results to be produced by this class, both the analysis and synthesis processes must be completely edge-effect free. If this condition is not met, behaviour is undefined and may crash or produce invalid results.

Parameters

h_filter_paramsvc2_data_tables.LiftingFilterParameters

v_filter_paramsvc2_data_tables.LiftingFilterParameters

Horizontal and vertical filter synthesis (not analysis!) filter parameters (e.g. from vc2_data_tables.LIFTING_FILTERS) defining the wavelet transform types to use.

dwt_depthint

dwt_depth_hoint

Transform depths for 2D and horizontal-only transforms.

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

The VC-2 quantisation matrix to use (e.g. from vc2_data_tables.QUANTISATION_MATRICES).

quantisation_indices[qi, …]

A list of quantisation indices to use during the quantisation step.

synthesis_expPyExp

A PyExp object which describes the partial synthesis (decoding) process to be performed.

This expression will typically be an output of a vc2_bit_widths.vc2_filters.synthesis_transform() which has been fed coefficient Arguments produced by vc2_bit_widths.vc2_filters.make_variable_coeff_arrays().

This expression must only rely on transform coefficients known to be edge-effect free in the encoder’s output.

property quantisation_indices

The quantisation indices used during decoding.

analyse_quantise_synthesise(picture)

Encode, quantise (at multiple levels) and then decode the supplied picture. The decoded result at each quantisation level will be returned.

Parameters

picturenumpy.array

The picture to be encoded. Will be corrupted as a side effect of calling this method.

Width must be a multiple of 2**(dwt_depth+dwt_depth_ho) pixels and height a multiple of 2**dwt_depth pixels.

Dimensions must also be sufficient that all transform coefficients used by the synthesis_exp will be edge-effect free.

Returns

decoded_values[value, …]

The decoded value at for each quantisation index in quantisation_indices.