Generating static wavelet filter analyses

Note

This section does not apply to most codecs. You can skip this section if your codec only uses combinations of wavelet transforms and depths for which a default quantisation matrix is defined in annex (D) (even if you don’t use the default quantisation matrix).

The generation of certain test cases requires a mathematical analysis of the wavelet filter used by the codec under test. The VC-2 conformance software is supplied with analyses for all wavelet filter configurations for which a default quantisation matrix is defined in annex (D). If your codec uses a wavelet and depth combination for which no default quantisation matrix is defined, a suitable analysis must be produced to enable tests to be generated for this codec. The steps below walk through the process of using the vc2-static-filter-analysis tool to produce the required analyses.

Step 1: Generating static analyses

Static analyses must be created for every wavelet transform used by your codec (including those with a default quantisation matrix).

The vc2-static-filter-analysis command (provided by the vc2_bit_widths package) is used to generate a mathematical analysis of arbitrary VC-2 filter configurations.

For example, to analyse a filter which:

  • Uses the Haar (with shift) filter (wavelet index 4) vertically

  • Uses the Le Gall (5, 3) filter (wavelet index 1) horizontally

  • With a 2 level 2D transform depth

  • And 1 level horizontal-only transform depth

The following command is used:

$ vc2-static-filter-analysis \
    --wavelet-index 4 \
    --wavelet-index-ho 1 \
    --dwt-depth 2 \
    --dwt-depth-ho 1 \
    --output filter_analysis.json

This command will compute the static analysis and write them to filter_analysis.json.

For modest transform depths, this process should take a few seconds. For larger transforms, this command can take several minutes or even hours to execute so the --verbose option can be added to track progress. For extremely large filters, see the vc2_bit_widths package’s user guide for further guidance.

Step 2: Bundling static analyses

Once static analyses have been produced for all required wavelets, these must be combined into an analysis bundle file as follows:

$ vc2-bundle create bundle.zip \
      --static-filter-analysis path/to/analyses/*.json

Step 3: Run test case generation

Finally, to use the generated filter analyses during test case generation, the VC2_BIT_WIDTHS_BUNDLE environment variale must be set to the location of the bundle file generated in step 2. For example:

$ export VC2_BIT_WIDTHS_BUNDLE="path/to/bundle.zip"
$ vc2-test-case-generator path/to/codec_features.csv