----------------------------------------------------------------------------
 Usage Examples for the Demonstration Applications Supplied with Kakadu V6.1
----------------------------------------------------------------------------

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.  Nevertheless, the demonstration applications
are quite powerful.  Licensed versions of the Kakadu system ship with
some additional, much simpler demonstration applications for dydactic
purposes.

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
  examine 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
                 Porder:T1={0,0,2,10,10,LRCP} Porder: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.
    -- Big-endian byte order is assumed for files with the ".raw" suffix,
       whereas little-endian byte order is assumed if the file has a ".rawl"
       suffix.  Pay special attention to this, since the native byte order
       varies from platform to platform -- we don't want our files to have
       platform-dependent interpretations now, do we!
    -- 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 20 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.
 r) kdu_compress -i huge.pgm -o huge.jp2 -rate 1.5 Clayers=20 Creversible=yes
                 Clevels=8 Cprecincts={256,256},{256,256},{128,128}
                 Corder=RPCL ORGgen_plt=yes ORGtparts=R Cblk={32,32}
    -- I have used this exact command to successfully compress a very large
       geospatial image (> 500 MByte BMP file).  The entire image is compressed
       without any tiling whatsoever.  The compressed image may subsequently
       be viewed quickly and efficiently using "kdu_show", at any resolution.
       The key elements here are: 1) the generation of PLT marker segments