vc2-optimise-synthesis-test-patterns¶
Use a stochastic search to enchance the synthesis test patterns produced by vc2-static-filter-analysis so that they produce even more extreme values.
Note
The enhanced test patterns produced by this tool are valid only for the wavelet transform, depth, picture bit width and quantisation matrix specified. See Caveats for further limitations and assumptions made by this software.
Example usage¶
$ vc2-static-filter-analysis \
--wavelet-index le_gall_5_3 \
--dwt-depth 2 \
--output static_analysis.json
$ vc2-maximum-quantisation-index \
static_analysis.json \
--picture-bit-width 10 \
--custom-quantisation-matrix \
0 LL 1 \
1 HL 2 1 LH 0 1 HH 4 \
2 HL 1 2 LH 3 2 HH 3 \
--number-of-searches 10 \
--added-corruption-rate 0.2 \
--removed-corruption-rate 0.05 \
--base-iterations 1000 \
--added-iterations-per-improvement 500 \
--output optimised_patterns.json
Arguments¶
The complete set of arguments can be listed using --help
usage: vc2-optimise-synthesis-test-patterns [-h] --picture-bit-width
PICTURE_BIT_WIDTH
[--custom-quantisation-matrix CUSTOM_QUANTISATION_MATRIX [CUSTOM_QUANTISATION_MATRIX ...]]
[--seed SEED]
[--number-of-searches NUMBER_OF_SEARCHES]
[--terminate-early TERMINATE_EARLY]
[--added-corruption-rate ADDED_CORRUPTION_RATE]
[--removed-corruption-rate REMOVED_CORRUPTION_RATE]
[--base-iterations BASE_ITERATIONS]
[--added-iterations-per-improvement ADDED_ITERATIONS_PER_IMPROVEMENT]
[--output OUTPUT] [--verbose]
static_filter_analysis
Use a stochastic search to enchance the synthesis test patterns produced by
vc2-static-filter-analysis so that they produce even more extreme values.
positional arguments:
static_filter_analysis
The static analysis JSON data produced by vc2-static-
filter-analysis.
optional arguments:
-h, --help show this help message and exit
--picture-bit-width PICTURE_BIT_WIDTH, -b PICTURE_BIT_WIDTH
The number of bits in the picture signal.
--custom-quantisation-matrix CUSTOM_QUANTISATION_MATRIX [CUSTOM_QUANTISATION_MATRIX ...], -q CUSTOM_QUANTISATION_MATRIX [CUSTOM_QUANTISATION_MATRIX ...]
Use a custom quantisation matrix for the search.
Optional except for filters without a default
quantisation matrix defined. Should be specified as a
series 3-argument tuples giving the level, orientation
and quantisation matrix value for every entry in the
quantisation matrix.
--seed SEED, -s SEED The seed for the random number generator used to
perform searches.
--number-of-searches NUMBER_OF_SEARCHES, -N NUMBER_OF_SEARCHES
The number of independent search runs to use. The
larger this option, the more likely it is that the
search will avoid local minima (default: 10).
--terminate-early TERMINATE_EARLY, -t TERMINATE_EARLY
Terminate optimisation early if this many searches
fail to find an improvement. (Default: 1).
--added-corruption-rate ADDED_CORRUPTION_RATE, -a ADDED_CORRUPTION_RATE
The proportion of pixel values to corrupt in each
search iteration. (Default: 0.05).
--removed-corruption-rate REMOVED_CORRUPTION_RATE, -r REMOVED_CORRUPTION_RATE
The proportion of pixel values to reset to their
original state in each search iteration. (Default:
0.0).
--base-iterations BASE_ITERATIONS, -i BASE_ITERATIONS
The base number of trials to run the search for. The
larger this value, the longer the search will run
without finding any improvements before terminating.
(Default: 200).
--added-iterations-per-improvement ADDED_ITERATIONS_PER_IMPROVEMENT, -I ADDED_ITERATIONS_PER_IMPROVEMENT
The number of additional search iterations to perform
when an improved test pattern is found. (Default:
200).
--output OUTPUT, -o OUTPUT
The name of the file to write the optimised test
pattern JSON file to. Defaults to stdout.
--verbose, -v Show more detailed status information during
execution.
Choosing parameters¶
The runtime and output quality of the optimisation algorithm is highly dependent on the paramters supplied. The best performing parameters for one wavelet transform may not be the best for others.
Choosing good parameters requires manual exploration and experimentation and is unfortunately out of the scope of this manual.
See optimise_synthesis_test_patterns() for
additional details.
JSON file format¶
The output is a JSON file with the following structure:
{
"wavelet_index": <int>,
"wavelet_index_ho": <int>,
"dwt_depth": <int>,
"dwt_depth_ho": <int>,
"picture_bit_width": <int>,
"quantisation_matrix": <quantisation-matrix>,
"optimised_synthesis_test_patterns": [<test-pattern-specification>, ...],
}
Quantisation matrix¶
The "quantisation_matrix" field encodes the quantisation matrix used in the
same fashion as the VC-2 pseudocode and its format should be self-explanatory.
For example, the quantisation matrix passed to the example above is encoded
as:
{
0: {"LL": 1},
1: {"HL": 2, "LH": 0, "HH": 4},
2: {"HL": 1, "LH": 3, "HH": 3},
}
Note
The
deserialise_quantisation_matrix()
Python utility function is provided for unpacking this structure.
Test patterns¶
The <test-pattern-specification> values follow the same format used by
vc2-static-filter-analysis (see
Test patterns) with some additional
fields:
<test-pattern-specification> = {
...,
"quantisation_index": <int>,
"decoded_value": <int>,
"num_search_iterations": <int>,
}
These fields give the quantisation index found to produce the most extreme value for the test pattern, the value it managed to produce and the number of search iterations taken to reach that test pattern. This information is provided for informational purposes only.
Note
The
deserialise_test_pattern_specifications()
Python utility function is provided for unpacking this structure.
Missing values¶
Only intermediate arrays are included which contain novel values. Arrays which are just renamings, interleavings and subsamplings of other arrays are omitted.