vc2-test-case-generator

This application generates test cases for VC-2 encoders and decoders given a set of codec features to target.

Usage

A codec features CSV file should be created (as described in Generating test cases). This can then be processed by vc2-test-case-generator to generate test cases for the codecs supporting the specific codec features described.

Test case generation is performed as follows:

$ vc2-test-case-generator path/to/codec_features.csv

The test cases are written to a test_cases in the current working directory. The --output argument can be given to choose an alternative location. By default, if any existing test cases are present in the output directory, the test case generator will not run. The --force argument can be added to run the test case generator anyway.

If only a subset of test cases are required, the following arguments can also be used:

  • --encoder-only: Only generate test cases for encoders

  • --decoder-only: Only generate test cases for decoders

  • --codec <regexp>: Only generate test cases for codec feature sets whose names match a supplied pattern.

Parallel execution

The test case generator can take many hours to run. To speed up execution, test cases can be generated in parallel on multi-core machines. To do this the --parallel argument is added to vc2-test-case-generator. Rather than performing test case generation, this command outputs a series of newline-separated commands which can be executed in parallel to perform test case generation. These can then be executed, for example using GNU Parallel:

$ # Write test case generation commands to 'commands.txt'
$ vc2-test-case-generator path/to/codec_features.csv --parallel > commands.txt

$ # Run test case generation in parallel using GNU Parallel
$ parallel -a commands.txt

Static wavelet filter analyses

Some test cases require a precomputed mathematical analysis of the wavelet transform used.

The VC-2 conformance software includes suitable analyses for all wavelet transforms for which a default quantisation matrix is defined in the VC-2 specification. To support additional wavelet transform combinations and depths, additional analyses must be generated as described in Generating static wavelet filter analyses.

If the VC2_BIT_WIDTHS_BUNDLE environment variable is defined, the test case generator will attempt to read wavelet filter analyses from the file it specifies. This must be a filter analysis bundle file created by vc2-bundle.

Arguments

The complete set of arguments can be listed using --help

usage: vc2-test-case-generator [-h] [--version] [--verbose] [--parallel]
                               [--output OUTPUT] [--force]
                               [--encoder-only | --decoder-only]
                               [--codecs REGEX]
                               codec_configurations

Generate test inputs for VC-2 encoder and decoder implementations.

positional arguments:
  codec_configurations  CSV file containing the set of codec configurations to
                        generate test cases for.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --verbose, -v         Show additional status information during execution.
  --parallel, -p        If given, don't generate test cases but instead
                        produce a series of commands on stdout which can be
                        executed in parallel to generate the test cases.
  --output OUTPUT, -o OUTPUT
                        Directory name to write test cases to. Will be created
                        if it does not exist. Defaults to './test_cases/'.
  --force, -f           Force the test case generator to run even if the
                        output directory is not empty.
  --encoder-only, -e    If set, only generate test cases for VC-2 encoders.
  --decoder-only, -d    If set, only generate test cases for VC-2 decoders.
  --codecs REGEX, -c REGEX
                        If given, a regular expression which selects which
                        codec configurations to generate test cases for. If
                        not given, test cases will be generated for all codec
                        configurations.