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