vc2_bit_widths.bundle: Analysis file bundling

Pre-computed filter analyses (e.g. from multiple runs of vc2-static-filter-analysis) and optimised test patterns (e.g. from runs of vc2-optimise-synthesis-test-patterns) may be packed into a ‘bundle’ file along with an index of available patterns.

The bundle file is a compressed zip file and offers significant space savings over storing the analyses uncompressed.

The provision of an index file also enables more efficient lookup of files by codec parameters than reading every file.

bundle_create_from_serialised_dicts(file_or_filename, serialised_static_filter_analyses=(), serialised_optimised_synthesis_test_patterns=())

Create a bundle file containing the supplied pre-serialised filter analyses and test patterns.

Parameters
file_or_filenamefile-like or str

The bundle to write to.

serialised_static_filter_analysesiterable

An iterable of dictionaries containing filter analyses with all entries serialised as produced by vc2-static-filter-analysis. Must be free of duplicates.

serialised_optimised_synthesis_test_patternsiterable

An iterable of dictionaries containing filter analyses with all entries serialised as expected by vc2-optimise-synthesis-test-patterns. Must be free of duplicates.

bundle_index(file_or_filename)

Get the index from a bundle file.

Parameters
file_or_filenamefile-like or str

The bundle to read.

Returns
indexdict

Returns a dictionary containing two lists under the keys “static_filter_analyses” and “optimised_synthesis_test_patterns”. Both lists contain dictionaries containing the following fields:

  • “wavelet_index” (int)

  • “wavelet_index_ho” (int)

  • “dwt_depth” (int)

  • “dwt_depth_ho” (int)

  • “filename”: The file in the bundle containing the corresponding analysis or test patterns.

The “optimised_synthesis_test_patterns” list dicts also contain the following additional entries:

  • “quantisation_matrix” ({level: {orient: value, ...}, ...})

  • “picture_bit_width” (int)

bundle_get_static_filter_analysis(file_or_filename, wavelet_index, wavelet_index_ho, dwt_depth, dwt_depth_ho)

Read a static filter analysis for a particular filter configuration from a bundle. Raises KeyError if no matching analysis is present in the bundle.

Parameters
file_or_filenamefile-like or str

The bundle to read.

wavelet_indexint
wavelet_index_hoint
dwt_depthint
dwt_depth_hoint
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), …}
analysis_test_patterns: {(level, array_name, x, y): TestPatternSpecification, …}
synthesis_test_patterns: {(level, array_name, x, y): TestPatternSpecification, …}

See vc2_bit_widths.helpers.static_filter_analysis().

bundle_get_optimised_synthesis_test_patterns(file_or_filename, wavelet_index, wavelet_index_ho, dwt_depth, dwt_depth_ho, quantisation_matrix, picture_bit_width)

Read a static filter analysis for a particular filter configuration from a bundle. Raises KeyError if no matching analysis is present in the bundle.

Parameters
file_or_filenamefile-like or str

The bundle to read.

wavelet_indexint
wavelet_index_hoint
dwt_depthint
dwt_depth_hoint
quantisation_matrix{level: {orient: value, …}, …}
picture_bit_widthint
Returns
optimised_test_patterns{(level, array_name, x, y): OptimisedTestPatternSpecification, …}

See vc2_bit_widths.helpers.optimise_synthesis_test_patterns().