vc2-bit-widths-table
¶
Compute the signal ranges and bit widths required for each part of a VC-2 analysis and synthesis filter and present the results in a CSV table.
Note
The values printed 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-bit-widths-table \
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 \
--output bit_widths.csv
$ column -t -s, bit_widths.csv | head
type level array_name lower_bound test_pattern_min test_pattern_max upper_bound bits
analysis 2 Input -512 -512 511 511 10
analysis 2 DC -1024 -1024 1022 1022 11
analysis 2 DC' -2047 -2046 2046 2047 12
analysis 2 DC'' -2047 -2046 2046 2047 12
analysis 2 L -1537 -1535 1534 1535 12
analysis 2 H -2047 -2046 2046 2047 12
analysis 2 L' -3071 -3069 3069 3071 13
analysis 2 H' -4094 -4092 4092 4094 13
analysis 2 L'' -3071 -3069 3069 3071 13
The command can also be used to display the signal ranges of optimised test
patterns produced by vc2-optimise-synthesis-test-patterns
:
$ vc2-bit-widths-table \
static_analysis.json \
optimised_patterns.json \
--output bit_widths.csv
Arguments¶
The complete set of arguments can be listed using --help
usage: vc2-bit-widths-table [-h] [--picture-bit-width PICTURE_BIT_WIDTH]
[--custom-quantisation-matrix CUSTOM_QUANTISATION_MATRIX [CUSTOM_QUANTISATION_MATRIX ...]]
[--show-all-filter-phases] [--verbose]
[--output OUTPUT]
static_filter_analysis
[optimised_synthesis_test_patterns]
Compute the signal ranges and bit widths required for each part of a VC-2
analysis and synthesis filter and present the results in a CSV table.
positional arguments:
static_filter_analysis
The static analysis JSON data produced by vc2-static-
filter-analysis.
optimised_synthesis_test_patterns
A set of optimised synthesis test patterns produced by
vc2-optimise-synthesis-test-patterns.
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. 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.
--show-all-filter-phases, -p
Show signal bounds broken down into individual filter
phases. Without this option, the bounds are shown for
all filter phases.
--verbose, -v Show more detailed status information during
execution.
--output OUTPUT, -o OUTPUT
The name of the file to write the CSV bit widths table
to. Defaults to stdout.
CSV Format¶
The generated CSV have one row per analysis and synthesis filter phase. The columns are defined as follows:
- type, level, array_name, x, y
Specifies the filter phase represented by the row (see Terminology). The ‘x’ and ‘y’ columns are omitted, and the aggregate worst-case shown for all phases unless
--show-all-filter-phases
is used.- lower_bound, upper_bound
The theoretical worst-case lower- and upper-bounds for the signal. These values may be over-estimates but are guaranteed not to be under estimates of the true worst-case.
- test_pattern_min, test_pattern_max
The minimum and maximum values produced by the test patterns when they’re passed through a real encoder and decoder. These values may not represent true worst-case signal levels, though they may often be close.
Warning
It is possible that both minimum and maximum test pattern values could have the same sign. This occurs when quantisation errors are sufficiently strong as to make worst-case encodings/decodings of the test pattern have the same sign. The true signal range would still include zero.
- bits
The final column summarises the number of bits required for a signed two’s complement representation of the values in the ranges indicated. If the test pattern and theory disagree, a range of bits is indicated. The true bit width required lies somewhere in the given range.