jp2.h

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

         functions both return false if there is no embedded ICC profile.
            The `get_icc_lut' function fills in the 2^{`index_bits'} entries
         of the supplied `lut' array for the indicated colour channel.  The
         `channel_idx' must be in the range 0 to 2 (0 for monochrome spaces).
         The range of inputs to the lookup table is assumed to be 0 to
         2^{index_bits}-1.  The entries of the lookup table will generally
         be obtained by evaluating a gamma function or interpolating tone
         reproduction data obtained from the embedded ICC profile.  The
         lookup table maps decompressed image component samples (possibly
         subjected to a palette mapping and possibly interpolated) into
         the linear (with respect to scene radiant intensity) values
         associated with the Profile Connection Space (PCS).  The lookup
         table entries are guaranteed to be non-negative numbers lying in
         the range 0 to 1, inclusive.
            For non-monochrome spaces, an additional matrix mapping into
         the D50 XYZ Profile Connection Space (PCS) is generally required.
         The relevant matrix may be obtained by calling the `get_icc_matrix'
         function, which returns false if the embedded ICC profile
         describes a monochrome space.  The `matrix3x3' argument receives
         the elements of a 3x3 matrix, with the first row of the matrix
         appearing first, followed by the second and third rows.  The
         PCS values, are obtained through the matrix-vector multiplication:
         (X Y Z)' = M * (R G B)' where R, G and B are the first, second
         and third colour channels, subjected to the tone reproduction curve
         described above, and the prime notation denotes transposition.
            It is worth noting that the PCS is defined to describe colour
         appearance under a D50 illuminant (graphic arts standard), which
         is different to the D65 illuminant of sRGB (most monitors are
         configured by default to use an even more blue illuminant, typically
         D93, although this is easily changed).  For this reason, an
         illuminant correction is typically required in addition to
         primary conversion and non-linear tone reproduction mapping (gamma)
         in order to recover RGB samples in a defined colour space from the
         PCS values. */
  // --------------------------------------------------------------------------
  public: // Convenient conversion functions
    void convert_icc_to_slum(kdu_line_buf &line, int width=-1);
    void convert_icc_to_srgb(kdu_line_buf &red, kdu_line_buf &green,
                             kdu_line_buf &blue, int width=-1);
      /* Implements any colour conversions required to obtain the relevant
         standard colour space: J2_sLUM_SPACE (first function); or
         J2_sRGB_SPACE (second function).  These functions may be called
         only if the current colour space is J2_iccLUM_SPACE (first function)
         or J2_iccRGB_SPACE (second function).  The functions adjust for
         differences between the illuminant, tone mapping and/or primary
         colorant properties of the actual and the standard colour
         spaces.
            Although `kdu_line_buf' objects can represent sample values in
         four different ways, these functions require the data to have a
         16-bit normalized (fixed point) representation, with a nominal
         dynamic range of -0.5 to 0.5 (offsets will be added and later
         removed, as necessary, to create unsigned data for processing
         by tone reproduction curves.  The least significant KDU_FIX_POINT
         bits of each 16 bit integer are the fraction bits of the fixed
         point representation. The selection of this representation is
         intended to facilitate interaction with the sample data processing
         operations conducted by the objects defined in
         "kdu_sample_processing.h".
            All conversions are performed in-situ, overwriting the original
         contents of the relevant buffer.  If `width' is negative, the
         function processes all samples in the line buffers (they must all
         have the same length in this case).  Otherwise, only the first
         `width' samples of each line buffer are processed. */
  // --------------------------------------------------------------------------
  private: // Data
    j2_colour *state;
  };

/*****************************************************************************/
/*                             jp2_resolution                                */
/*****************************************************************************/

  /* Note: Objects of this class are merely interfaces to an internal
     implementation object, `j2_resolution', 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_resolution {
  public: // Lifecycle member functions
    jp2_resolution()
      { state = NULL; }
    jp2_resolution(j2_resolution *state)
      { this->state = state; }
    bool operator!()
      { return (state == NULL); }
    bool exists()
      { return (state != NULL); }
  // --------------------------------------------------------------------------
  public: // Initialization member functions
    void init(float aspect_ratio);
      /* Initializes the internal resolution object, setting the aspect
         ratio (vertical grid spacing divided by horizontal grid spacing)
         for display and capture resolutions to the indicated value.
         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. */
    void set_different_capture_aspect_ratio(float aspect_ratio);
      /* Sets the capture aspect ratio to be different to the display
         aspect ratio (as set up by `init').  This is rarely required,
         since it makes little sense for the aspect ratios to differ. */
    void set_resolution(float resolution, bool for_display=true);
      /* Sets the vertical resolution in high resolution canvas grid
         points per metre.  If `for_display' is true, this is the default
         display resolution; oherwise, it is the capture resolution.  There
         is no need to explicitly specify either of these resolutions.  If
         no resolution is specified the relevant box will not be written in
         the JP2 file, except when a non-unity aspect ratio is selected.  In
         the latter case, a default display resolution box will be created
         having a default vertical display resolution of 1 grid point per
         metre. */
  // --------------------------------------------------------------------------
  public: // Access member functions
    float get_aspect_ratio(bool for_display=true);
      /* Always returns a positive aspect ratio representing the vertical
         grid spacing divided by the horizontal grid spacing on the
         code-stream's high resolution canvas.  If `for_display' is false,
         the capture aspect ratio is returned instead of the display aspect
         ratio, although these should be identical in any reasonable use of
         the relevant JP2 boxes. */
    float get_resolution(bool for_display=true);
      /* Returns a positive value if and only if explicit resolution
         information is available.  If `for_display' is true, the return
         value identifies the default vertical display resolution
         (in canvas grid points per metre).  Otherwise, the return value is
         the vertical capture resolution (again in canvas grid points per
         metre).  In both cases, the returned values may be multiplied by the
         aspect ratio to recover horizontal resolution. */
  // --------------------------------------------------------------------------
  private: // Data
    j2_resolution *state;
  };

/*****************************************************************************/
/*                               jp2_source                                  */
/*****************************************************************************/

  /* Note: Objects of this class are merely interfaces to an internal
     implementation object, `j2_source'.  To destroy the internal object
     you must invoke the explicit `close' function. */

class jp2_source : public kdu_compressed_source {
  public: // Lifecycle functions
    jp2_source()
      { state = NULL; }
    bool operator!()
      { return (state == NULL); }
    bool exists()
      { return (state != NULL); }
    void open (char *fname);
      /* Generates an error if the file cannot be opened or is found not
         to be compatible with the JP2 format. */
    void close();
      /* Destroys the internal object and resets the state of the interface
         so that `exists' returns false.  It is safe to close an object
         which was never opened. */
  // --------------------------------------------------------------------------
  public: // JP2 specific access functions
    jp2_dimensions access_dimensions();
    jp2_palette access_palette();
    jp2_channels access_channels();
    jp2_colour access_colour();
    jp2_resolution access_resolution();
      /* These functions return objects which may be used to access the
         information carried with the JP2 file.  The information reported
         by each of these objects must be interpreted by conformant JP2
         readers.  What this means is application dependent, but a conformant
         rendering device should be prepared to perform palette translation,
         aspect ratio correction and colour conversion to an appropriate
         space.  The information provided by `access_dimensions' is redundant
         with the code-stream and most applications should ignore it, using
         the `kdu_codestream' object's capabilities to return the relevant
         quantities.  Nevertheless, the information may prove useful if
         the code-stream is not to be opened for some reason. */
  // --------------------------------------------------------------------------
  public: // Function overrides to implement compressed data I/O
    int read(kdu_byte *buf, int num_bytes);
  // --------------------------------------------------------------------------
  private: // Data
    j2_source *state;
  };

/*****************************************************************************/
/*                               jp2_target                                  */
/*****************************************************************************/

  /* Note: Objects of this class are merely interfaces to an internal
     implementation object, `j2_target'.  To destroy the internal object
     you must invoke the explicit `close' function. */

class jp2_target : public kdu_compressed_target {
  public: // Lifecycle functions
    jp2_target()
      { state = NULL; }
    bool operator!()
      { return (state == NULL); }
    bool exists()
      { return (state != NULL); }
    void open (char *fname);
      /* Generates an error if the file cannot be opened. */
    void close();
      /* Destroys the internal object and resets the state of the interface
         so that `exists' returns false.  It is safe to close an object
         which was never opened. */
  // --------------------------------------------------------------------------
  public: // Access to attributes which may need to be set.
    jp2_dimensions access_dimensions(); // You must access and initialize this
    jp2_colour access_colour();         // You must access and initialize this
    jp2_palette access_palette();       // Defaults to no palette
    jp2_channels access_channels();     // Defaults to using initial components
    jp2_resolution access_resolution(); // Defaults to 1:1 aspect ratio
      /* These functions may be used to gain access to and thence initialize
         any or all of the attributes of the JP2 file being constructed.
         Any changes must be effected prior to the first attempt to write
         code-stream data to the object.  The palette, channels and
         resolution information will be automatically assigned default
         parameters if necessary, but the `jp2_dimensions' and `jp2_colour'
         objects must be accessed and explicitly initialized, or else an
         error will be generated when the first attempt is made to write
         code-stream data. */
  // --------------------------------------------------------------------------
  public: // Function overrides to implement compressed data I/O
    bool write(kdu_byte *buf, int num_bytes);
  // --------------------------------------------------------------------------
  private: // Data
    j2_target *state;
  };

#endif // JP2_H