Llimage libtest

Introduction

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.

Eventually, this applet should 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

• Command line only executable (no display window after decompression)
• Accept a variety of arguments on the command line
• Allow bulk processing of images using file patterns on the command line (wild cards)
• Support all image file formats provided by llimage, namely: j2c (JPEG2000), jpeg, png, bmp, tga
• Read images in any format and output them back in any format
• Output compress/decompress performances
• Output image properties: size, components and other stats
• Build automatically as part of the viewer
• Runs on all supported platforms: Mac OS X, Windows and Linux

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

Extract a discard level 1 rendered version of the input image using only the first 4000 bytes of the file

./llimage_libtest -i image1.j2c -load 4000 -d 1 -o image2.png

Extract a discard level 2 rendered version of the input image loading only the byte range computation used in the viewer

./llimage_libtest -i image1.j2c -load -1 -d 2 -o image2.png

Links

• STORM-987