usage_examples.txt

JPEG2000的C++实现代码

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