vc2_bit_widths.fast_partial_analysis_transform: Wavelet analysis transform

This module contains a numpy-based implementation of a VC-2-like integer lifting wavelet analysis (encoding) transform. This implementation is approximately 100x faster than executing the equivalent VC-2 pseudocode under Python. It also optionally may be used to extract intermediate results from the codec.

This module is not indended as a general-purpose encoder implementation but rather for rapid evaluation of test patterns. Since test patterns are edge-effect free, this implementation does not implement VC-2’s edge effect handling behaviour – hence the ‘partial’ part of the module name. Output values which would have been effected by edge effects will contain nonsense values.

Note

This Python+numpy filter is still extremely slow compared to any reasonable native software implementation. However, being pure Python, it is more portable and therefore useful in this application.

Example usage

The example below demonstrates how the fast_partial_analysis_transform() function may be used to perform an analysis transform on an example picture:

>>> import numpy as np
>>> from vc2_data_tables import LIFTING_FILTERS, WaveletFilters
>>> from vc2_bit_widths.fast_partial_analysis_transform import (
...     fast_partial_analysis_transform,
... )

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

>>> # 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]

>>> # Perform the analysis transform (in place)
>>> transform_coeffs = fast_partial_analysis_transform(
...     h_filter_params,
...     v_filter_params,
...     dwt_depth,
...     dwt_depth_ho,
...     picture,
... )

API

fast_partial_analysis_transform(h_filter_params, v_filter_params, dwt_depth, dwt_depth_ho, signal, target=None)

Perform a multi-level 2D analysis transform, ignoring edge effects.

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).

dwt_depth, dwt_depth_ho: int

Transform depths for 2D and horizontal-only transforms.

signalnumpy.array

The picture to be transformed. Will be transformed in-place (in interleaved form) but de-interleaved views will also be returned.

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

target(level, array_name, tx, ty) or None

If None, the complete analysis transform will be performed. If a tuple is given, the transform will run until the specified value has been computed and this value alone will be returned.

Returns

transform_coeffs{level: {orient: numpy.array, …}, …} or intermediate_value

Subsampled views of the signal array (which will have been modified in-place).

Alternatively, if the target argument is not None, the single intermediate value requested will be returned.