-------------------------------------------------------------------------------
  Usage Examples for the Demonstration Applications Supplied with Kakadu V2.2
  ---------------------------------------------------------------------------

To help you get started right away, we provide some simple examples
demonstrating the use of the Kakadu example applications.  These are
far from exhaustive and the Kakadu software framework itself is intended
to be used in building more extensive applications than these
demonstration applications.

kdu_compress
------------
  Note: you may find it very useful to examine the attributes used by
  the compressor by supplying a `-record' argument on the command
  line.  You may also find it very useful to open up a code-stream
  (optionally embedded inside a JP2 file) using "kdu_show" and to
  examiine the properties (use menu or "p" accelerator) -- note that
  some of the attributes used by the compressor cannot be preserved
  in the code-stream (e.g., visual weights), so will show up only when
  you use `-record' with the compressor.

 a) kdu_compress -i image.pgm -o out.j2c -rate 1.0
    -- irreversible compression to 1 bit/sample.
 b) kdu_compress -i image.pgm -o out.j2c -rate 1.0,0.5,0.25
    -- irreversible compression to a 3 layer code-stream (3 embedded bit-rates)
 c) kdu_compress -i image.pgm -o out.j2c Creversible=yes -rate -,1,0.5,0.25
    -- reversible (lossless) compression with a progressive lossy to
       lossless code-stream having 4 layers.  Note the use of the dash, '-',
       to specify that the final layer should include all remaining
       compressed bits, not included in previous layers.  Specifying a
       large bit-rate for one of the layers does not have exactly the
       same effect and may leave the code-stream not quite lossless.  See
       usage statement for a more detailed explanation.
 d) kdu_compress -i red.pgm,green.pgm,blue.pgm -o out.j2c -rate 0.5
    -- irreversible colour compression (with visual weights) to 0.5 bit/pixel
    -- may use image.ppm or image.bmp if you want to start with a colour image
 e) kdu_compress -i image.pgm -o out.j2c Creversible=yes Clayers=9
                -rate 1.0,0.04 Stiles={711,393} Sorigin={39,71}
                Stile_origin{17,69} Cprecincts={128,128},{64,64}
                Corder=PCRL
    -- spatially progressive code-stream with 9 embedded quality layers,
       roughly logarithmically spaced between 0.04 and 1.0 bits per pixel,
       with some interesting canvas coordinates and weird tile sizes.
 f) kdu_compress -i image.pgm -o out.j2c Corder
    -- type this sort of thing when you can't remember the format or
       description of some element of the parameter specification language.
       In this case, you get an error message with an informative description
       of the "Corder" code-stream parameter attribute.
    -- you may find out all about the code-stream specification language
       by typing "kdu_compress -usage".
 g) kdu_compress -i image.bmp -o out.j2c -rate 0.5 -rotate 90
    -- compresses monochrome or colour bottom-up BMP file with 90 degree
       rotation.  Note that file organization geometry is folded into other
       geometric transformations, which are all performed without any
       buffering of uncompressed data.
 h) kdu_compress -i image.ppm -o out.j2c Stiles={171,191}
                 Clevels:T0C1=0 Cuse_sop:T4=yes Cycc:T2=no
    -- Use only 0 levels (instead of the default 5) of DWT for the second
       component (C1) of the first tile.  Put SOP markers in front of each
       packet of the fifth tile.  Turn off colour transformation (used by
       default for compatible 3-component images) in the third tile.
    -- Command lines used to specify complex code-stream parameter
       configurations can become very long.  As an alternative, you may
       place parameters into one or more switch files and load them from
       the command line using the "-s" option.
 i) kdu_compress -i image.pgm -o out.j2c -rate 1.0,0.3,0.07 Stiles={300,200}
                 Clayers=3 Clayers:T0=2 Clayers:T1=7 Cuse_sop=yes Cuse_eph=yes
    -- Rate allocation is performed across 3 quality layers.  Since the
       first tile is assigned only 2 layers, its quality will not improve
       beyond that associated with the second global bit-rate, 0.3 bps.
       The extra 4 layers for the second tile (T1) will receive empty
       packets without any SOP markers.  EPH markers are included with all
       packets, as mandated by the standard (see corrigendum).
 j) kdu_compress -i image.pgm -o out.j2c -rate 1.0,0.5,0.1,0.03
                 Stiles={300,200} Corder=LRCP
                 Cpoc:T1={0,0,2,10,10,LRCP} Cpoc:T1={0,0,4,10,10,PCRL}
                 -record log.txt
    -- Tile 1 (the second tile) gets two tile-parts.  The first tile-part of
       tile 1 includes the first 2 layers (0.1 bits per sample) and has a
       layer progressive order (LRCP).  The second tile-part contains the
       final two quality layers and has a resolution-progressive order (RLCP).
       The first tile-part of every tile appears first, followed by the extra
       tile-part of tile 1 (interleaved tile-parts).  Interesting things happen
       when you truncate the code-stream to a bit-rate below 1.0 -- you
       should be able to guess.
    -- The log file generated using "-record" is very useful for interpreting
       the results of complex command lines.  It uses Kakadu's uniform
       parameter language to report the code-stream parameter configuration.
 k) kdu_compress -i image.pgm -o out.bits -rate 1.0 Cprecincts={128,128}
                 Cuse_sop=yes Cuse_eph=yes "Cmodes=RESTART|ERTERM"
    -- Generates a code-stream with various error resilience features
       enabled.  Use "kdu_expand -resilient" with such code-streams for the
       best results in the event of transmission error.
 l) kdu_compress -i image.raw -o out.bits Sprecision=16 Ssigned=no
                 Sdims={1024,800} Qstep=0.0001 -rate 1.0
    -- Process a raw 16-bit image.  Note that for raw images you need to
       supply all of the dimensional information: image dimensions, bit-depth
       and whether the image samples are signed 2's complement or unsigned
       values.  Note also that the irreversible processing path chooses
       a default set of quantization parameters based on a single scaling
       parameter (Qstep) -- you can specify individual subband quantization
       factors if you really know what you are doing.  The Qstep value is
       interpreted relative to the nominal range of the data which is from
       -2^{B-1} to 2^{B-1}-1 where B is the bit-depth (Sprecision).  If your
       data is represented as 16-bit words, but all the information resides
       in the least significant 10 bits of these words, the default value
       of Qstep=1/256 may not be appropriate.  In this case, the best thing
       to do would be to specify the actual number of least significant
       bits which are being used (e.g., Sprecision=10 -- it assumes that
       the data is the least significant B bits of a ceil(B/8) byte
       word).  Alternatively, you may leave the most significant bits
       empty, but you should choose a smaller value for Qstep (as suggested
       by the example).  Remember that rate control is performed
       independently of quantization step size selection, except that if
       the quantization steps are too course, not enough bits will be
       produced by the entropy coder for the rate controller to achieve
       the target.  To see how many bits are being produced in any
       given case, run the compressor without a `-rate' argument.
 m) kdu_compress -i image_y.pgm,image_cb.pgm,image_cr.pgm -o out.jp2
                 -jp2_space sYCC CRGoffset={0,0},{0.25,0.25},{0.25,0.25}
                 -rate 1,0.5,0.2
    -- Compresses a YCbCr image directly, having chrominance components
       sub-sampled by a factor of 2 in each direction.  The CRGoffset
       argument aligns the chrominance samples in the middle of each
       2x2 block of luminance samples.  You may work with any sub-sampling
       factors you like, of course, and they may be different in each
       direction and for each component.  As a general rule, the mid-point
       registration of sub-sampled chrominance components requires
       CRGoffset values of 0.5-1/(2S), where S is the relevant
       sub-sampling factor.
          Identifies the colour space as sYCC through a containing JP2
       file's colour box so that the image can be correctly rendered
       (including all appropriate interpolation, component alignment and
       colour conversion operations) by the "kdu_show" application or any
       other conforming JP2 rendering application.
 n) kdu_compress -i image.pgm -o out.jp2 Creversible=yes -rate -,1,0.5
                 -jp2_space iccLUM,2.2,0.099
    -- Embeds the compressed image within a JP2 file having an embedded
       ICC profile identifying the image as having the tone reproduction
       curve defined by the NTSC standard (gamma curve for sRGB has
       parameters gamma=2.4 and beta=0.055 instead of 2.2 and 0.099).
 o) kdu_compress -i image.ppm -o out.jp2 -rate 2,1,0.5
                 -jp2_space iccRGB,3,0.16,0.9642,0,0,0,1,0,0,0,0.8249 Cycc=yes
    -- The embedded ICC profile inserted into the JP2 file describes the
       colour channels as G(X/X0), G(Y/Y0) and G(Z/Z0) where (X0,Y0,Z0)
       are the whitepoint of the D50 profile connection space and G() is
       the standard CIELab gamma function having parameters gamma=3.0 and
       beta=0.16.  The YCC transform applied to these colour channels for
       compression is not all that radically different from the linear
       opponent transform applied to the gamma corrected colour channels
       in the CIELab colour space.  It follows that this representation
       should have properties similar to Lab at D50 and can easily be
       converted (by means of a well conditioned linear transform) into
       a true D50 Lab space.
 p) kdu_compress -i image.ppm -o out.jp2 -rate -,0.05 Clayers=30
                 Creversible=yes Rshift=12 Rlevels=5 -roi {0.3,0.1},{0.5,0.5}
    -- Compresses a colour image losslessly using the max-shift ROI method
       to ensure that a square region of is assigned much higher priority
       in the layer generation process.  The region represents one quarter of
       the total number of image pixels and starts 30% of the way down and
       10% of the way across from the left of the image.  Reconstructing the
       initial layers (you can use kdu_show, kdu_expand or kdu_transcode to
       partially reconstructing or pair down the image) leaves an extremely
       low quality in the background (everything other than the region of
       interest) but a rapidly improving quality in the foreground as more
       and more layers arrive.  The foreground becomes lossless before
       the background improves substantially -- it eventually becomes lossless
       too.
 q) kdu_compress -i image.ppm -o out.jp2 -rate -,0.5 Clayers 30 Cblk={32,32}
                 Creversible=yes Rweight=7 Rlevels=5 -roi mask.pgm,0.5
    -- Another region of interest encoding example.  In this case the region
       is found from the mask image -- the foreground corresponds to the
       mask pixels whose values exceed 50% of the dynamic range (i.e., 128).
       The mask image is automatically scaled to fit the dimensions of each
       image component (scaling and region propogation are done incrementally
       so as to minimize memory consumption).  In this case, the max-shift
       method is not used. Instead, the distortion cost function which drives
       the PCRD-opt layer formation algorithm is modulated by the region
       characteristics.  The transition from background to foreground is
       softer than in the max-shift case and may be controlled by `Rweight'.
       Region definition is poorer than with the max-shift method, but a
       number of important disadvantages are avoided.  For more on this,
       consult the "kakadu.pdf" document.

kdu_expand
----------
 a) kdu_expand -i in.j2c -o out.pgm
    -- decompress input code-stream (or first image component thereof).
 b) kdu_expand -i in.j2c -o out.pgm -rate 0.7
    -- read only the initial portion of the code-stream, corresponding to
       an overall bit-rate of 0.7 bits/sample.  It is generally preferrable
       to use the transcoder to generate a reduced rate code-stream first,
       but direct truncation works very well so long as the code-stream has
       a layer-progressive organization with only one tile (unless
       interleaved tile-parts are used).
 c) kdu_expand -i in.j2c -o out.pgm -region {0.3,0.2},{0.6,0.4} -rotate 90
    -- decompress a limited region of the original image (starts 30% down
       and 20% in from left, extends for 60% of the original height and
       40% of the original width).  Concurrently rotates decompressed
       image by 90 degrees clockwise (no extra memory or computational
       resources required for rotation).
    -- Note that the whole code-stream if often not loaded when a region
       of interest is specified, as may be determined by observing the
       reported bit-rate.  This is particularly true of code-streams with
       multiple tiles or spatially progressive packet sequencing.
 d) kdu_expand -i in.j2c -o out.pgm -fussy
    -- most careful to check for conformance with standard.  Checks for
       appearance of marker codes in the wrong places and so forth.
 e) kdu_expand -i in.j2c -o out.pgm -resilient
    -- similar to fussy, but should not fail if a problem is encountered
       (except when problem concerns main or tile headers -- these can all
       be put up front) -- recovers from and/or conceals errors to the
       best of its ability.
 f) kdu_expand -i in.j2c -o out.pgm -reduce 2
    -- discard 2 resolution levels to generate an image whose dimensions
       are each divided by 4.
 g) kdu_expand -i in.j2c -o out.pgm -record log.txt
    -- generate a log file containing all parameter attributes associated
       with the compressed code-stream.  Any or all of these may be
       supplied to "kdu_compress" (often via a switch file).
    -- note that the log file may be incomplete if you instruct
       the decompressor to decompress only a limited region of interest
       so that one or more tiles may never be parsed.
 h) kdu_expand -i in.j2c -cpu 0
    -- measure end-to-end processing time, excluding only the writing of
       the decompressed file (specifying an output file will cause the
       measurement to be excessively influenced by the I/O associated
       with file writing)
 i) kdu_expand -i in.j2c -o out.pgm -precise
    -- force the use of higher precision numerics than are probably
       required (the implementation makes its own decisions based on
       the output bit-depth).  The same argument, supplied to the compressor
       can also have some minor beneficial effect.  Use the `-precise'
       argument during compression and decompression to get reference
       compression performance figures.
 j) kdu_expand -i in.jp2 -o out.ppm
    -- decompress a colour image wrapped up inside a JP2 file.  Note that
       sub-sampled colour components will not be interpolated nor will
       any colour appearance transform be applied to the data.  However,
       palette indices will be de-palettized.  This is probably the most
       appropriate behaviour for an application which decompresses to a
       file output.  Renderers, such as "kdu_show" should do much more.

kdu_transcode
-------------
 a) kdu_transcode -i in.j2c -o out.j2c -rate 0.5
    -- reduce the bit-rate, using as much information as the quality layer
       structure provides.
 b) kdu_transcode -i in.j2c -o out.j2c -reduce 1
    -- reduce image resolution by 2 in each direction
 c) kdu_transcode -i in.j2c -o out.j2c -rotate 90
    -- rotate image in compressed domain.  Some minor distortion increase
       will usually be observed (unless the code-stream was lossless) upon
       decompression (with -rotate -90), but subsequent rotations or block
       coder mode changes will not incur any distortion build-up.
 d) kdu_transcode -i in.j2c -o out.j2c "Cmodes=ERTERM|RESTART" Cuse_eph=yes
                  Cuse_sop=yes
    -- Add error resilience information.
 e) kdu_transcode -i in.j2c -o out.j2c Cprecincts={128,128} Corder=PCRL
    -- Convert to spatially progressive organization (even if precincts
       were not originally used).
 f) kdu_transcode -i in.jp2 -o out.j2c
    -- Extracts the code-stream from inside a JP2 file.

kdu_show
--------
  "kdu_show" is an interactive application, whose usage should be
  self-explanatory.  We make a special note of the following capabilities:
  * You may open new image files at any time and may drag and drop files
    onto the application's window.
  * Files with a ".jp2" or ".jpx" suffix are opened as JP2 compatible files.
    All others are opened as raw code-stream files.
  * You may re-open a failed image file (often after setting the "mode" to
    "resilient" or "resilient+SOP assumption").
  * You may view all of the code-stream parameters and the tile structure
    using the "properties" item of the "file" menu.
       -- Note that double-clicking on any code-stream parameter attribute
          displayed in the popup window will bring up a description of
          the attribute.
  * Lots of accelerators are defined for rapid navigation.  Some of the
    ones you may want to use a lot are:
       -- w                           -> widens the display
       -- s                           -> shrinks the display
       -- arrow keys and page up/down -> rapid navigation
       -- ctrl+z                      -> zooms out
       -- z                           -> zooms in
       -- p                           -> show properties
       -- ] and [                     -> rotate clockwise and counter-clockwise
       -- 1,2,3,4,c                   -> display image component 1, 2, 3, 4 or
                                         else appropriately mapped,
                                         interpolated and colour converted
                                         colour channels (m)
       -- <,>                         -> adjust number of quality layers

