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
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