vc2_bit_widths.patterns: Containers for test pattern data

The following datastructures are used to define test patterns.

Test pattern specification

These types define a test pattern along with information about required spacing or quantisation levels.

class TestPatternSpecification(target, pattern, pattern_translation_multiple, target_translation_multiple)

A definition of a test pattern for a VC-2 filter. This test pattern is intended to maximise the value of a particular intermediate or output value of a VC-2 filter.

Test patterns for both for analysis and synthesis filters are defined in terms of picture test patterns. For analysis filters, the picture should be fed directly to the encoder under test. For synthesis filters, the pattern must first be fed to an encoder and the transform coefficients quantised before being fed to a decoder.

Test patterns tend to be quite small (tens to low hundreds of pixels square) and so it is usually sensible to collect together many test patterns into a single picture (see vc2_bit_widths.picture_packing). To retain their functionality, test patterns must remain correctly aligned with their target filter. When relocating a test pattern, the pattern must be moved only by multiples of the values in pattern_translation_multiple. For each multiple moved, the target value effected by the pattern moves by the same multiple of target_translation_multiple.

Parameters

target(tx, ty)

The target coordinate which is maximised by this test pattern.

patternTestPattern

The input pattern to be fed into a VC-2 encoder. Only those pixels defined in this pattern need be set – all other pixels may be set to arbitrary values and have no effect.

The test pattern is specified such that the pattern is as close to the top-left corner as possible given pattern_translation_multiple, without any negative pixel coordinates. That is, 0 <= min(x) < mx and 0 <= min(y) < my.

pattern_translation_multiple(mx, my)

target_translation_multiple(tmx, tmy)

The multiples by which pattern pixel coordinates and target array coordinates may be translated when relocating the test pattern. Both the pattern and target must be translated by the same multiple of these two factors.

For example, if the pattern is translated by (2*mx, 3*my), the target must be translated by (2*tmx, 3*tmy).

class OptimisedTestPatternSpecification(target, pattern, pattern_translation_multiple, target_translation_multiple, quantisation_index, decoded_value, num_search_iterations)

A test pattern specification which has been optimised to produce more extreme signal values for a particular codec configuration.

Parameters

target(tx, ty)

patternTestPattern

pattern_translation_multiple(mx, my)

target_translation_multiple(tmx, tmy)

Same as TestPatternSpecification

quantisation_indexint

The quantisation index which, when used for all coded picture slices, produces the largest values when this pattern is decoded.

decoded_valueint

For informational purposes. The value which will be produced in the target decoder array for this input pattern.

num_search_iterationsint

For informational purposes. The number of search iterations performed to find this value.

invert_test_pattern_specification(test_pattern)

Given a TestPatternSpecification or OptimisedTestPatternSpecification, return a copy with the signal polarity inverted.

Test pattern

A description of a test pattern in terms of pixel polarities.

class TestPattern(*args)

A test pattern.

A test pattern is described by a set of pixels with a defined polarity (either -1 or +1) with all other pixels being undefined (represented as 0). Where a pixel has +ve polarity, the maximum signal value should be used in test pictures, for -ve polarities, the minimum signal value should be used.

This object stores test patterns as a numpy.array defining a rectangular region where some pixels are not undefined. This region lies at the offset defined by origin and the values within the region are defined by polarities.

TestPattern objects can be constructed from either a dictionary of the form {(x, y): polarity, ...} or from a pair of arguments, origin and polarities giving a (dy, dx) tuple and 2D np.array respectively.

property origin

The origin of the rectangular region definining the test pattern given as (dy, dx).

Warning

Numpy-style index ordering used!

property polarities

A numpy.array definining the polarities of the pixels within a rectangular region definde by origin.

as_dict()

Return a dictionary representation of the test pattern of the form {(x, y): polarity, ...}.

as_picture_and_slice(signal_min=-1, signal_max=1, dtype=<class 'numpy.int64'>)

Convert this test pattern into a picture array with its origin at (0, 0).

Not supported for test patterns with pixels at negative coordinates.

Parameters

signal_minint

signal_maxint

The values to use for pixels with negative and positive polarities, respecitvely.

dtype

The numpy.array datatype for the returned array.

Returns

picturenumpy.array

A test picture with its origin at (0, 0) containing the test pattern (with zeros in all undefined pixels).

picture_slice(slice, slice)

A numpy.array slice identifying the region of picture which contains the test pattern.

__len__()

The number of defined pixels in the test pattern.

__neg__()

Return a TestPattern with inverted polarities.