def test_synthesis_intermediate_steps_as_expected(self, dwt_depth,
dwt_depth_ho):
filter_params = tables.LIFTING_FILTERS[
tables.WaveletFilters.haar_with_shift]
transform_coeffs = make_symbol_coeff_arrays(dwt_depth, dwt_depth_ho)
_, intermediate_values = synthesis_transform(
filter_params,
filter_params,
dwt_depth,
dwt_depth_ho,
transform_coeffs,
)
# 2D stages have all expected values
for level in range(dwt_depth_ho + 1, dwt_depth + dwt_depth_ho + 1):
names = set(n for l, n in intermediate_values if l == level)
assert names == set([
"LL",
"LH",
"HL",
"HH",
"L''",
"L'",
"L",
"H''",
"H'",
"H",
"DC''",
"DC'",
"DC",
"Output",
])
# HO stages have all expected values
for level in range(1, dwt_depth_ho + 1):
names = set(n for l, n in intermediate_values if l == level)
assert names == set([
"L",
"H",
"DC''",
"DC'",
"DC",
"Output",
])
def test_find_synthesis_filter_bounds():
coeff_arrays = make_symbol_coeff_arrays(1, 0)
expr = (1 * coeff_arrays[0]["LL"][0, 0] + 2 * coeff_arrays[0]["LL"][1, 0] +
-4 * coeff_arrays[0]["LL"][2, 0] +
10 * coeff_arrays[1]["HH"][0, 0] +
20 * coeff_arrays[1]["HH"][1, 0] +
-40 * coeff_arrays[1]["HH"][2, 0] +
100 * LinExp.new_affine_error_symbol() + 1)
lower_bound, upper_bound = synthesis_filter_bounds(expr)
assert lower_bound == (3 * LinExp("coeff_0_LL_min") +
-4 * LinExp("coeff_0_LL_max") +
30 * LinExp("coeff_1_HH_min") +
-40 * LinExp("coeff_1_HH_max") + -100 + 1)
assert upper_bound == (-4 * LinExp("coeff_0_LL_min") +
3 * LinExp("coeff_0_LL_max") +
-40 * LinExp("coeff_1_HH_min") +
30 * LinExp("coeff_1_HH_max") + +100 + 1)
def test_evaluate_synthesis_test_pattern_output():
# In this test we simply check that the decoded values match those
# computed by the optimise_synthesis_maximising_test_pattern function
wavelet_index = WaveletFilters.haar_with_shift
wavelet_index_ho = WaveletFilters.le_gall_5_3
dwt_depth = 1
dwt_depth_ho = 0
picture_bit_width = 10
max_quantisation_index = 64
quantisation_matrix = {
0: {
"LL": 0
},
1: {
"LH": 1,
"HL": 2,
"HH": 3
},
}
h_filter_params = LIFTING_FILTERS[wavelet_index_ho]
v_filter_params = LIFTING_FILTERS[wavelet_index]
input_min, input_max = signed_integer_range(picture_bit_width)
input_array = SymbolArray(2)
analysis_transform_coeff_arrays, _ = analysis_transform(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
input_array,
)
symbolic_coeff_arrays = make_symbol_coeff_arrays(dwt_depth, dwt_depth_ho)
symbolic_output_array, symbolic_intermediate_arrays = synthesis_transform(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
symbolic_coeff_arrays,
)
pyexp_coeff_arrays = make_variable_coeff_arrays(dwt_depth, dwt_depth_ho)
_, pyexp_intermediate_arrays = synthesis_transform(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
pyexp_coeff_arrays,
)
for (level,
array_name), target_array in symbolic_intermediate_arrays.items():
for x in range(target_array.period[0]):
for y in range(target_array.period[1]):
# Create a test pattern
test_pattern = make_synthesis_maximising_pattern(
input_array,
analysis_transform_coeff_arrays,
target_array,
symbolic_output_array,
x,
y,
)
synthesis_pyexp = pyexp_intermediate_arrays[(level,
array_name)][x, y]
# Run with no-optimisation iterations but, as a side effect,
# compute the actual decoded value to compare with
test_pattern = optimise_synthesis_maximising_test_pattern(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
quantisation_matrix,
synthesis_pyexp,
test_pattern,
input_min,
input_max,
max_quantisation_index,
None,
1,
None,
0.0,
0.0,
0,
0,
)
# Find the actual values
lower_value, upper_value = evaluate_synthesis_test_pattern_output(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
quantisation_matrix,
synthesis_pyexp,
test_pattern,
input_min,
input_max,
max_quantisation_index,
)
assert upper_value[0] == test_pattern.decoded_value
assert upper_value[1] == test_pattern.quantisation_index
def static_filter_analysis(
wavelet_index,
wavelet_index_ho,
dwt_depth,
dwt_depth_ho,
num_batches=1,
batch_num=0,
):
r"""
Performs a complete static analysis of a VC-2 filter configuration,
computing theoretical upper- and lower-bounds for signal values (see
:ref:`theory-affine-arithmetic`) and heuristic test patterns (see
:ref:`theory-test-patterns`) for all intermediate and final analysis and
synthesis filter values.
Parameters
==========
wavelet_index : :py:class:`vc2_data_tables.WaveletFilters` or int
wavelet_index_ho : :py:class:`vc2_data_tables.WaveletFilters` or int
dwt_depth : int
dwt_depth_ho : int
The filter parameters.
num_batches : int
batch_num : int
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
:ref:`terminology`). The naming
conventions used are those defined by
:py:func:`vc2_bit_widths.vc2_filters.analysis_transform` and
:py:func:`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
:py:class:`~vc2_bit_widths.linexp.LinExp`\ s.
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 :py:func:`~vc2_bit_widths.helpers.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): :py:class:`~vc2_bit_widths.patterns.TestPatternSpecification`, ...}
synthesis_test_patterns: {(level, array_name, x, y): :py:class:`~vc2_bit_widths.patterns.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
:ref:`terminology`). Arrays which are just interleavings, subsamplings
or renamings of other arrays are omitted.
"""
v_filter_params = LIFTING_FILTERS[wavelet_index]
h_filter_params = LIFTING_FILTERS[wavelet_index_ho]
# Create the algebraic representation of the analysis transform
picture_array = SymbolArray(2)
analysis_coeff_arrays, intermediate_analysis_arrays = analysis_transform(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
picture_array,
)
# Count the total number of arrays for use in logging messages
num_arrays = sum(array.period[0] * array.period[1]
for array in intermediate_analysis_arrays.values()
if not array.nop)
array_num = 0
# Compute bounds/test pattern for every intermediate/output analysis value
analysis_signal_bounds = OrderedDict()
analysis_test_patterns = OrderedDict()
for (level,
array_name), target_array in intermediate_analysis_arrays.items():
# Skip arrays which are just views of other arrays
if target_array.nop:
continue
for x in range(target_array.period[0]):
for y in range(target_array.period[1]):
array_num += 1
if (array_num - 1) % num_batches != batch_num:
continue
logger.info(
"Analysing analysis filter %d of %d (level %d, %s[%d, %d])",
array_num,
num_arrays,
level,
array_name,
x,
y,
)
# Compute signal bounds
analysis_signal_bounds[(level, array_name, x,
y)] = analysis_filter_bounds(
target_array[x, y])
# Generate test pattern
analysis_test_patterns[(level, array_name, x,
y)] = make_analysis_maximising_pattern(
picture_array,
target_array,
x,
y,
)
# Create the algebraic representation of the synthesis transform
coeff_arrays = make_symbol_coeff_arrays(dwt_depth, dwt_depth_ho)
synthesis_output_array, intermediate_synthesis_arrays = synthesis_transform(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
coeff_arrays,
)
# Create a view of the analysis coefficient arrays which avoids recomputing
# already-known analysis filter phases
cached_analysis_coeff_arrays = {
level: {
orient: SymbolicPeriodicCachingArray(array, picture_array)
for orient, array in orients.items()
}
for level, orients in analysis_coeff_arrays.items()
}
# Count the total number of arrays for use in logging messages
num_arrays = sum(array.period[0] * array.period[1]
for array in intermediate_synthesis_arrays.values()
if not array.nop)
array_num = 0
# Compute bounds/test pattern for every intermediate/output analysis value
synthesis_signal_bounds = OrderedDict()
synthesis_test_patterns = OrderedDict()
for (level,
array_name), target_array in intermediate_synthesis_arrays.items():
# Skip arrays which are just views of other arrays
if target_array.nop:
continue
for x in range(target_array.period[0]):
for y in range(target_array.period[1]):
array_num += 1
if (array_num - 1) % num_batches != batch_num:
continue
logger.info(
"Analysing synthesis filter %d of %d (level %d, %s[%d, %d])",
array_num,
num_arrays,
level,
array_name,
x,
y,
)
# Compute signal bounds
synthesis_signal_bounds[(level, array_name, x,
y)] = synthesis_filter_bounds(
target_array[x, y])
# Compute test pattern
synthesis_test_patterns[(
level, array_name, x,
y)] = make_synthesis_maximising_pattern(
picture_array,
cached_analysis_coeff_arrays,
target_array,
synthesis_output_array,
x,
y,
)
# For extremely large filters, a noteworthy amount of overall
# RAM can be saved by not caching synthesis filters. These
# filters generally don't benefit much in terms of runtime from
# caching so this has essentially no impact on runtime.
for a in intermediate_synthesis_arrays.values():
a.clear_cache()
return (
analysis_signal_bounds,
synthesis_signal_bounds,
analysis_test_patterns,
synthesis_test_patterns,
)
def test_integration():
# A simple integration test which computes signal bounds for a small
# transform operation
filter_params = LIFTING_FILTERS[WaveletFilters.haar_with_shift]
dwt_depth = 1
dwt_depth_ho = 1
input_picture_array = SymbolArray(2)
analysis_coeff_arrays, analysis_intermediate_values = analysis_transform(
filter_params,
filter_params,
dwt_depth,
dwt_depth_ho,
input_picture_array,
)
input_coeff_arrays = make_symbol_coeff_arrays(dwt_depth, dwt_depth_ho)
synthesis_output, synthesis_intermediate_values = synthesis_transform(
filter_params,
filter_params,
dwt_depth,
dwt_depth_ho,
input_coeff_arrays,
)
signal_min = LinExp("signal_min")
signal_max = LinExp("signal_max")
example_range = {signal_min: -512, signal_max: 511}
# Input signal bounds should be as specified
assert analysis_filter_bounds(
analysis_intermediate_values[(2, "Input")][0, 0], ) == (signal_min,
signal_max)
# Output of final analysis filter should require a greater depth (NB: for
# the Haar transform it is the high-pass bands which gain the largest
# signal range)
analysis_output_lower, analysis_output_upper = analysis_filter_bounds(
analysis_intermediate_values[(1, "H")][0, 0], )
assert analysis_output_lower.subs(example_range) < signal_min.subs(
example_range)
assert analysis_output_upper.subs(example_range) > signal_max.subs(
example_range)
example_coeff_range = {
"coeff_{}_{}_{}".format(level, orient, minmax):
maximum_dequantised_magnitude(
int(round(value.subs(example_range).constant)))
for level, orients in analysis_coeff_arrays.items()
for orient, expr in orients.items()
for minmax, value in zip(["min", "max"], analysis_filter_bounds(expr))
}
# Signal range should shrink down by end of synthesis process but should
# still be larger than the original signal
final_output_lower, final_output_upper = synthesis_filter_bounds(
synthesis_output[0, 0])
assert final_output_upper.subs(
example_coeff_range) < analysis_output_upper.subs(example_range)
assert final_output_lower.subs(
example_coeff_range) > analysis_output_lower.subs(example_range)
assert final_output_upper.subs(example_coeff_range) > signal_max.subs(
example_range)
assert final_output_lower.subs(example_coeff_range) < signal_min.subs(
example_range)
def synthesis_input_arrays(self, dwt_depth, dwt_depth_ho):
return make_symbol_coeff_arrays(dwt_depth, dwt_depth_ho)
def test_add_missing_synthesis_values(
wavelet_index,
wavelet_index_ho,
dwt_depth,
dwt_depth_ho,
):
h_filter_params = tables.LIFTING_FILTERS[wavelet_index_ho]
v_filter_params = tables.LIFTING_FILTERS[wavelet_index]
_, intermediate_values = synthesis_transform(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
make_symbol_coeff_arrays(dwt_depth, dwt_depth_ho),
)
all_expressions = {
(level, array_name, x, y): array[x, y]
for (level, array_name), array in intermediate_values.items()
for x in range(array.period[0]) for y in range(array.period[1])
}
non_nop_expressions = {
(level, array_name, x, y): array[x, y]
for (level, array_name), array in intermediate_values.items()
for x in range(array.period[0]) for y in range(array.period[1])
if not array.nop
}
# Sanity check
assert all_expressions != non_nop_expressions
refilled_expressions_not_filled = add_missing_synthesis_values(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
non_nop_expressions,
fill_in_equivalent_phases=False,
)
refilled_expressions_filled = add_missing_synthesis_values(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
non_nop_expressions,
fill_in_equivalent_phases=True,
)
assert set(refilled_expressions_not_filled) == set(all_expressions)
assert set(refilled_expressions_filled) == set(all_expressions)
for key in all_expressions:
if refilled_expressions_not_filled[key] is not None:
# Where a phase hasn't been repeated, should have exactly the same
# value.
assert (
all_expressions[key] == refilled_expressions_not_filled[key])
assert (all_expressions[key] == refilled_expressions_filled[key])
else:
# Where a phase has been filled in, without going to a lot of
# effort, all we can do is check that the substituted phase is
# 'similar' (i.e. likely to be the same expression just with
# different coordinates)
assert (sorted(
coeff for sym, coeff in all_expressions[key]) == sorted(
coeff for sym, coeff in refilled_expressions_filled[key]))
def test_make_symbol_coeff_arrays():
coeff_arrays = make_symbol_coeff_arrays(2, 0, "foobar")
assert isinstance(coeff_arrays[1]["HL"][2, 3], LinExp)
assert coeff_arrays[1]["HL"][2, 3].symbol == (("foobar", 1, "HL"), 2, 3)
def test_aggregation_flag(tmpdir, capsys, arg, exp_phases):
# Check that aggregation of filter phases works
f = str(tmpdir.join("file.json"))
# vc2-static-filter-analysis
assert sfa(shlex.split("-w haar_with_shift -d 1 -o") + [f]) == 0
# vc2-bit-widths-table
assert bwt([f] + shlex.split("-b 10 {}".format(arg))) == 0
csv_rows = list(csv.reader(capsys.readouterr().out.splitlines()))
columns = csv_rows[0][:-5]
# Check all phase columns are present as expected
if exp_phases:
assert columns == ["type", "level", "array_name", "x", "y"]
else:
assert columns == ["type", "level", "array_name"]
# Check the rows are as expected
row_headers = [tuple(row[:-5]) for row in csv_rows[1:]]
# ...by comparing with the intermediate arrays expected for this filter...
h_filter_params = LIFTING_FILTERS[WaveletFilters.haar_with_shift]
v_filter_params = LIFTING_FILTERS[WaveletFilters.haar_with_shift]
dwt_depth = 1
dwt_depth_ho = 0
_, analysis_intermediate_arrays = analysis_transform(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
SymbolArray(2),
)
_, synthesis_intermediate_arrays = synthesis_transform(
h_filter_params,
v_filter_params,
dwt_depth,
dwt_depth_ho,
make_symbol_coeff_arrays(dwt_depth, dwt_depth_ho),
)
if exp_phases:
assert row_headers == [
(type_name, str(level), array_name, str(x), str(y))
for type_name, intermediate_arrays in [
("analysis", analysis_intermediate_arrays),
("synthesis", synthesis_intermediate_arrays),
] for (level, array_name), array in intermediate_arrays.items()
for x in range(array.period[0]) for y in range(array.period[1])
]
else:
assert row_headers == [(type_name, str(level), array_name)
for type_name, intermediate_arrays in [
("analysis", analysis_intermediate_arrays),
("synthesis",
synthesis_intermediate_arrays),
] for level, array_name in intermediate_arrays]
