jp2.h

该源码是JPEG2000的c++源代码,希望对研究JPEG2000标准以及编解码的朋友们有用.

/*****************************************************************************/
// File: jp2.h [scope = APPS/COMPRESSED-IO]
// Version: Kakadu, V2.2
// Author: David Taubman
// Last Revised: 20 June, 2001
/*****************************************************************************/
// Copyright 2001, David Taubman, The University of New South Wales (UNSW)
// The copyright owner is Unisearch Ltd, Australia (commercial arm of UNSW)
// Neither this copyright statement, nor the licensing details below
// may be removed from this file or dissociated from its contents.
/*****************************************************************************/
// Licensee: Book Owner
// License number: 99999
// The Licensee has been granted a NON-COMMERCIAL license to the contents of
// this source file, said Licensee being the owner of a copy of the book,
// "JPEG2000: Image Compression Fundamentals, Standards and Practice," by
// Taubman and Marcellin (Kluwer Academic Publishers, 2001).  A brief summary
// of the license appears below.  This summary is not to be relied upon in
// preference to the full text of the license agreement, which was accepted
// upon breaking the seal of the compact disc accompanying the above-mentioned
// book.
// 1. The Licensee has the right to Non-Commercial Use of the Kakadu software,
//    Version 2.2, including distribution of one or more Applications built
//    using the software, provided such distribution is not for financial
//    return.
// 2. The Licensee has the right to personal use of the Kakadu software,
//    Version 2.2.
// 3. The Licensee has the right to distribute Reusable Code (including
//    source code and dynamically or statically linked libraries) to a Third
//    Party, provided the Third Party possesses a license to use the Kakadu
//    software, Version 2.2, and provided such distribution is not for
//    financial return.
/******************************************************************************
Description:
   Defines classes which together embody the capabilities expected of
conformant readers and writers of the JP2 file format.  The `jp2_source'
and `jp2_target' classes define objects which derive from the abstract
compressed I/O base classes `kdu_compressed_source' and
`kdu_compressed_target'. These may be used to construct `kdu_codestream'
objects for generating or decompressing the embedded JPEG2000 code-stream box.
Methods are also provided to describe, interpret and process the
code-stream image samples in a conformant manner.
******************************************************************************/

#ifndef JP2_H
#define JP2_H
#include "kdu_compressed.h"
#include "kdu_params.h"
#include "kdu_sample_processing.h"

// Defined here
class jp2_dimensions;
class jp2_palette;
class jp2_channels;
class jp2_colour;
class jp2_resolution;
class jp2_source;
class jp2_target;

// Defined elsewhere
class j2_dimensions;
class j2_palette;
class j2_channels;
class j2_colour;
class j2_resolution;
class j2_source;
class j2_target;


/*****************************************************************************/
/*                              jp2_dimensions                               */
/*****************************************************************************/

  /* Note: Objects of this class are merely interfaces to an internal
     implementation object, `j2_dimensions', which cannot be directly
     created by an application.  Creation and destruction of the internal
     object, as well as saving and reading of JP2 boxes are capabilities
     reserved for the internal machinery. Amongst other things, this
     protects the user against the possibility of losing control of
     resources when error conditions throw exceptions. */

class jp2_dimensions {
  public: // Lifecycle member functions
    jp2_dimensions()
      { state = NULL; }
    jp2_dimensions(j2_dimensions *state)
      { this->state = state; }
    bool operator!()
      { return (state == NULL); }
    bool exists()
      { return (state != NULL); }
  // --------------------------------------------------------------------------
  public: // Initialization member functions
    void init(kdu_coords size, int num_components, bool unknown_space=true);
      /* Initializes the internal dimensions object with the indicated number
         of image components.  It is illegal to call this function unless
         there is an internal object (`exists' must return true) and that
         object has not yet been initialized.  In practice, this happens only
         when setting up a `jp2_target' object to construct a JP2 file.  To
         complete the initialization, precision information must be supplied
         for each image component (see below).
            The `size' argument holds the height and width of the
         image region on the canvas.  This information is almost entirely
         useless since it cannot be mapped to image component dimensions
         without considering sub-sampling factors and the location of the
         image region on the canvas.  It may be useful in establishing
         the size of an scanned page when used in conjunction with explicit
         capture resolution information.
            The `unknown_space' argument is true if the colour space
         information accessed via the `jp2_colour' object is not known to
         be correct.  This is often the case in practice. */
    void set_precision(int component_idx, int bit_depth, bool is_signed=false);
      /* Sets the bit-depth and signed/unsigned characteristics of the
         indicated image component.  `component_idx' must be in the range 0
         through `num_components'-1.  It is necessary to supply this
         information for every image component.  Otherwise, the object
         will be judged incomplete.
            Note that the JP2 file format was really designed with unsigned
         representations in mind.  In some cases, the use of signed
         representations is illegal and in others it may create ambiguity.
         Users are strongly encouraged to adopt unsigned representations
         whenever using the JP2 file format. */
    void init(siz_params *siz, bool unknown_space=true);
      /* Completely initializes the object, based upon the information which
         will be included in the code-stream SIZ marker segment.  This is the
         best way to ensure consistency of the redundant image header box. */
  // --------------------------------------------------------------------------
  public: // Access member functions.
    kdu_coords get_size();
      /* Returns the size of the image region on the canvas.  This
         information is almost entirely useless by itself.  Moreover, it
         is redundant with the more complete and useful information embedded
         in the code-stream's SIZ marker segment.  If the size is needed,
         it should generally be obtained by invoking the more reliable and
         informative `kdu_codestream::get_dims' member function, assuming
         that a `kdu_codestream' object is constructed. */
    int get_num_components();
      /* Returns the number of code-stream image components.  Again, this
         information is best provided by the `kdu_codestream' object. */
    bool colour_space_known();
      /* Returns false if the colour space information provided by the
         `jp2_colour' object is unreliable. */
    int get_bit_depth(int component_idx);
      /* Returns the bit-depth of the indicated image component (indices
         start from 0). */
    bool get_signed(int component_idx);
      /* Indicates whether the indicated image component (indices start
         from 0) has a signed representation.  A false return value means
         that the quantities are unsigned.  Note that all quantities processed
         by the core Kakadu system are signed quantities.  To obtain
         unsigned values, an offset of half the dynamic range must be
         added to them.  In most cases, this is the appropriate action
         to take before subjecting the data to any palette mapping,
         lookup tables, colour conversion, etc.  However, if this function
         returns true, the data should be left in its signed representation
         and all of the above operations should be performed on the signed
         quantities.  For lookup table operations, this will mean that
         negative values must be clipped to 0.
            The JP2 file format was actually designed with unsigned
         representations in mind, so that some things make no sense, are
         clumsy or else are illegal unless the samples have an unsigned
         representation. */
  // --------------------------------------------------------------------------
  private: // Data
    j2_dimensions *state;
  };

/*****************************************************************************/
/*                               jp2_palette                                 */
/*****************************************************************************/

  /* Note: Objects of this class are merely interfaces to an internal
     implementation object, `j2_palette', which cannot be directly
     created by an application.  Creation and destruction of the internal
     object, as well as saving and reading of JP2 boxes are capabilities
     reserved for the internal machinery. Amongst other things, this
     protects the user against the possibility of losing control of
     resources when error conditions throw exceptions. */

class jp2_palette {
  public: // Lifecycle member functions
    jp2_palette()
      { state = NULL; }
    jp2_palette(j2_palette *state)
      { this->state = state; }
    bool operator!()
      { return (state == NULL); }
    bool exists()
      { return (state != NULL); }
  // --------------------------------------------------------------------------
  public: // Initialization member functions
    void init(int num_components, int num_entries);
      /* Initializes the internal palette object with the indicated number
         of image components and palette entries.  It is illegal to call this
         function unless there is an internal object (`exists' must return
         true) and that object has not yet been initialized.  In practice,
         this happens only when setting up a `jp2_target' object to construct
         a JP2 file.  To complete the initialization, the individual component
         lookup tables must be set up (see below). */
    void set_lut(int comp_idx, kdu_int32 *lut, int bit_depth,
                 bool is_signed=false);
      /* Sets the palette LUT for the indicated component, where `comp_idx'
         must lie in the range 0 through `num_components'-1.  The `lut' array
         must have at least `num_entries' entries and the sample values must
         lie in the range -2^{bit_depth-1} to +2^{bit_depth-1}-1, if
         `is_signed' is true, or else 0 to 2^{bit_depth}-1, if `is_signed'
         is false. */
  // --------------------------------------------------------------------------
  public: // Access member functions
    int get_num_entries();
      /* The input component samples are to be  clipped to the range
         0 through `entries'-1, where `entries' is the value returned
         by this function.  Returns 0 if no palette is being used. */
    int get_num_components();
      /* Returns the number of new image components created by the
         palette lookup table.  Note, however, that the standard does
         not require all of these components to be used.  Nor does
         it prevent any given component from being used multiple
         times.  This function returns 0 if no palette is being used. */
    int get_bit_depth(int comp_idx);
      /* Returns the bit-depth of the indicated component, where
         `comp_idx' must be in the range 0 through `num_components'-1
         and `num_components' is the value returned by
         `get_num_components'. */
    bool get_signed(int comp_idx);
      /* Returns true if the indicated component has a signed
         representation.  Otherwise, returns false.  Note that
         Palette LUT's are always converted to signed representations
         anyway, so there are not many applications which should
         need to know whether the representation is signed or
         unsigned, except when writing the de-palettized samples
         to a file which is capable of representing signed
         quantites. */
    void get_lut(int comp_idx, float lut[]);