vc2_bit_widths.json_serialisations: JSON Data File Serialisation/Deserialisation

The vc2_bit_widths.json_serialisations module provides functions for serialising and deserialising parts of the JSON files produced by the various command-line interfaces to vc2_bit_widths (see Command-line utilities reference).

Note

These functions do not serialise/deserialise JSON directly, instead they produce/accept standard Python data structures compatible with the Python json module.

Signal bounds

serialise_signal_bounds(signal_bounds)

Convert a dictionary of analysis or synthesis signal bounds expressions into a JSON-serialisable form.

See serialise_linexp() for details of the "lower_bound" and "upper_bound" fields.

For example::

>>> before = {
...     (1, "LH", 2, 3): (
...         LinExp("foo")/2 + 1,
...         LinExp("bar")/4 + 2,
...     ),
...     ...
... }
>>> serialise_signal_bounds(before)
[
    {
        "level": 1,
        "array_name": "LH",
        "phase": [2, 3],
        "lower_bound": [
            {"symbol": "foo", "numer": "1", "denom": "2"},
            {"symbol": None, "numer": "1", "denom": "1"},
        ],
        "upper_bound": [
            {"symbol": "bar", "numer": "1", "denom": "4"},
            {"symbol": None, "numer": "2", "denom": "1"},
        ],
    },
    ...
]

deserialise_signal_bounds(signal_bounds)

Inverse of serialise_signal_bounds().

serialise_linexp(exp)

Serialise a restricted subset of LinExp s into JSON form.

Restrictions:

• Only supports expressions made up of rational values (i.e. no floating point coefficients/constants.

• Symbols must all be strings (i.e. no tuples or AAError sybols)

Example::

>>> before = LinExp({
...     "a": Fraction(1, 5),
...     "b": Fraction(10, 1),
...     None: Fraction(-2, 3),
... })
>>> serialise_linexp(before)
[
    {"symbol": "a", "numer": "1", "denom": "5"},
    {"symbol": "b", "numer": "10", "denom": "1"},
    {"symbol": None, "numer": "-2", "denom": "3"},
]

Note

Numbers are encoded as strings to avoid floating point precision limitations.

deserialise_linexp(json)

Inverse of serialise_linexp().

Test patterns

serialise_test_pattern_specifications(spec_namedtuple_type, test_patterns)

Convert a dictionary of analysis or synthesis test pattern specifications into a JSON-serialisable form.

See serialise_test_pattern() for the serialisation used for the pattern data.

For example:

>>> before = {
...     (1, "LH", 2, 3): TestPatternSpecification(
...         target=(4, 5),
...         pattern=TestPattern({(x, y): polarity, ...}),
...         pattern_translation_multiple=(6, 7),
...         target_translation_multiple=(8, 9),
...     ),
...     ...
... }
>>> serialise_test_pattern_specifications(TestPatternSpecification, before)
[
    {
        "level": 1,
        "array_name": "LH",
        "phase": [2, 3],
        "target": [4, 5],
        "pattern": {...},
        "pattern_translation_multiple": [6, 7],
        "target_translation_multiple": [8, 9],
    },
    ...
]

Parameters

spec_namedtuple_typenamedtuple() class

The namedtuple used to hold the test pattern specification. One of TestPatternSpecification or OptimisedTestPatternSpecification.

test_patterns{(level, array_name, x, y): (…), …}

deserialise_test_pattern_specifications(spec_namedtuple_type, test_patterns)

Inverse of serialise_test_pattern_specifications().

serialise_test_pattern(test_pattern)

Convert a TestPattern into a compact JSON-serialisable form.

For example::

>>> before = TestPattern({
...     (4, 10): +1, (5, 10): -1, (6, 10): +1, (7, 10): -1,
...     (4, 11): -1, (5, 11): +1, (6, 11): -1, (7, 11): +1,
...     (4, 12): +1, (5, 12): -1, (6, 12): +1, (7, 12): -1,
...     (4, 13): -1, (5, 13): +1, (6, 13): -1, (7, 13): +1,
... })
>>> serialise_test_pattern(before)
{
    'dx': 4,
    'dy': 10,
    'width': 4,
    'height': 4,
    'positive': 'paU=',
    'mask': '//8=',
}

The serialised format is based on a Base64 (RFC 3548) encoded bit-packed positive/mask representation of the picture.

In a positive/mask representation, the input picture is represented as two binary arrays: ‘positive’ and ‘mask’. When an entry in the mask is 1, a 1 in the corresponding positive array means ‘+1’ and a 0 means ‘-1’. When the mask entry is 0, the corresponding entry in the positive array is ignored and a value of ‘0’ is assumed.

The positive and mask arrays are defined as having their bottom left corner at (dx, dy) and having the width and height defined. All values outside of this region are zero.

The positive and mask arrays are serialised in raster-scan order into a bit array. This bit array is packed into bytes with the first bit in each byte being the most significant.

The byte-packed bit arrays are finally Base64 (RFC 3548) encoded into the ‘positive’ and ‘mask’ fields.

deserialise_test_pattern(dictionary)

Inverse of serialise_namedtuple().

Quantisation matrices

serialise_quantisation_matrix(quantisation_matrix)

Convert a quantisation matrix into JSON-serialisable form.

For example::

>>> before = {0: {"L": 2}, 1: {"H": 0}}
>>> serialise_quantisation_matrix(before)
{"0": {"L": 2}, "1": {"H": 0}}

deserialise_quantisation_matrix(quantisation_matrix)

Inverse of serialise_quantisation_matrix().