Llimage libtest

Introduction

Looking into STORM-746, we realized we needed an applet to quickly and reliably test JPEG2000 compression/decompression strategies. We also realized that we could use such an applet to run texture compression/decompression tests as part of the set of integration tests we're running when building the viewer.

So, instead of doing a quick independent hack, we decided to build an llimage_libtest applet that can be run as part of the test suite.

Objectives

Allow on-going test of texture compression/decompression code without having to launch the viewer
Allow consistent compression/decompression performance measurements
Allow quick test of alternative compress/decompress strategies and techniques
Allow simple j2c/jpg image conversion

Quick Spec

[DONE] Add llimage_libtest as part of the integration test suite: indra/integration_tests/llimage_libtest/llimage_libtest.cpp
[DONE] Command line only executable (no display window after decompression)
[DONE] Accept a variety of arguments on the command line
[DONE] Allow bulk processing of images using file patterns on the command line (wild cards)
[DONE] Support all image file format provided by llimage, namely: j2c (JPEG2000), jpeg, png, bmp, tga
[DONE] Read images in any format and output them back in any format
[DONE] Output compress/decompress performances
[DONE] Output image properties: size, components, histograms and other stats
[DONE] Build automatically as part of the viewer
[DONE] Runs on Mac OS X
[DONE] Runs on Windows
[DONE] Runs on Linux : see STORM-1121

Building

When building with autobuild, we made the building of this applet optional and off by default. To build it, you need to specify LLIMAGE_LIBTEST in the configure command line. For instance:

autobuild configure -c RelWithDebInfo -- -DLLIMAGE_LIBTEST:BOOL=ON

Command Line Syntax

List of Arguments

Here's the list of llimage_libtest arguments as given by the --help argument:

 -h, --help
        Print this help
 -i, --input <file1 .. file2>
        List of image files to load and convert. Patterns with wild cards can be used.
 -o, --output <file1 .. file2> OR <type>
        List of image files to create (assumes same order as for input files)
        OR 3 letters file type extension to convert each input file into.
 -load, --load_size <n>
        Portion of the input file to load, in bytes.
        If (load == 0), it will load the whole file.
        If (load == -1), it will load the size relevant to reach the requested discard level (see -d).
        Only valid for j2c images. Default is 0 (load whole file).
 -r, --region <x0, y0, x1, y1>
        Crop region applied to the input files in pixels.
        Only used for j2c images. Default is no region cropping.
 -d, --discard_level <n>
        Discard level max used on input. 0 is highest resolution. Max discard level is 5.
        This allows the input image to be clamped in resolution when loading.
        Only valid for j2c images. Default is no discard.
 -p, --precincts <n>
        Dimension of precincts in pixels. Precincts are assumed square and identical for
        all levels. Note that this option also add PLT and tile markers to the codestream, 
        and uses RPCL order. Power of 2 must be used.
        Only valid for output j2c images. Default is no precincts used.
 -b, --blocks <n>
        Dimension of coding blocks in pixels. Blocks are assumed square. Power of 2 must
        be used. Blocks must be smaller than precincts. Like precincts, this option adds
        PLT, tile markers and uses RPCL.
        Only valid for output j2c images. Default is 64.
 -l, --levels <n>
        Number of decomposition levels (aka discard levels) in the output image.
        The maximum number of levels authorized is 32.
        Only valid for output j2c images. Default is 5.
 -rev, --reversible
        Set the compression to be lossless (reversible in j2c parlance).
        Only valid for output j2c images.
 -log, --logmetrics <metric>
        Log performance data for <metric>. Results in <metric>.slp
        Note: so far, only ImageCompressionTester has been tested.
 -a, --analyzeperformance
        Create a report comparing <metric>_baseline.slp with current <metric>.slp
        Results in <metric>_report.csv
 -s, --image-stats
        Output stats for each input and output image.

Usage Examples

Get help

./llimage_libtest --help

Convert a jpg image into a j2c image

./llimage_libtest --input image.jpg --output image.j2c

Convert a jpg image into a j2c image and output image statistics

./llimage_libtest --input image.jpg --output image.j2c --image-stats

Convert all j2c images in a folder to png images in the same folder

./llimage_libtest -i path/*.j2c -o png

Load all j2c images in a folder and gather decompression perf data

./llimage_libtest --input path/*.j2c --logmetrics ImageCompressionTester

Convert a set of images to j2c

./llimage_libtest -i image1.jpg image2.jpg image3.png -o j2c

Convert all j2c and jpg images from a folder into png

./llimage_libtest -i ../../../images/*.j?? -o png

Load all j2c images in a folder, gather decompression perf data, compare with baseline and create a report

./llimage_libtest -i path/*.j2c -log ImageCompressionTester -a

Convert png to lossless j2c images with (128,128) precincts and (32,32) blocks size

./llimage_libtest -i path/*.png -o j2c --precincts 128 --blocks 32 --reversible

Load j2c images using a (512,512) subregion and discarding the highest resolution level and gather decompression perf data

./llimage_libtest -i path/*.j2c --region 0 0 512 512 --discard_level 1 -log ImageCompressionTester

Extract a half res (512,512) sub rectangle from image1 and save it in image2 using (256,256) precincts and (32,32) blocks

./llimage_libtest -i image1.j2c -r 0 0 512 512 -d 1 -o image2.j2c -p 256 -b 32

Links

STORM-987