kdu_compressed.h

JPEG2000压缩解压图像源码

               1) The rate control prediction strategy relies upon the
                  assumption that the image samples will be processed
                  incrementally, with all image components processed
                  together at the same relative rate.  It is not at all
                  appropriate to process one image component completely,
                  followed by another component and so forth.  It such
                  a processing order is intended, this function should not
                  be called.
               2) The prediction strategy may inappropriately discard
                  information, thereby harming compression, if the
                  compressibility of the first part of the image which is
                  processed is very different to that of the last part of
                  the image.  Although this is rare in our experience, it
                  may be a problem with certain types of imagery, such
                  as medical images which sometimes contain empty regions
                  near boundaries.
               3) If truly lossless compression is desired, this function
                  should not be called, no matter how large the supplied
                  `max_bytes' value.  This is because terminal coding
                  passes which do not lie on the convex hull of the
                  rate-distortion curve will be summarily discarded,
                  violating the official mandate that a lossless code-stream
                  contain all compressed bits.
            For both input and output objects, the function may only be
         called prior to the point at which the first tile is opened and it
         may only be called once, if at all. */
    KDU_EXPORT void
      set_min_slope_threshold(kdu_uint16 min_slope);
      /* This function has no impact on input codestream objects.  When
         applied to an output codestream, the function has a similar effect
         to `set_max_bytes', except that it supplies a limit on the
         distortion-length slope threshold which will be used by the rate
         control algorithm.  This is most effective if the `flush' member
         function is to be called with a set of slope thresholds, instead
         of layer size specifications (see below).  If `set_max_bytes' is
         used, the slope threshold information will be incrementally
         estimated from statistics of the compressed data as it appears.  If
         `set_max_bytes' and `set_min_slope_threshold' are both used together,
         the larger (most constraining) of the two thresholds will be used
         by the block encoder to minimize its coding efforts. */
    KDU_EXPORT void
      set_resilient(bool expect_ubiquitous_sops=false);
    KDU_EXPORT void
      set_fussy();
    KDU_EXPORT void
      set_fast();
      /* These functions may be called at any time to modify the way input
         errors are treated.  The functions have no impact on codestream
         objects used for ouput.  The three modes are mutually exclusive.
            In the resilient mode, the object makes a
         serious attempt to both detect and recover from errors in the
         code-stream.  We attempt to guarantee that decompression will not
         fail, so long as the main header is uncorrupted and there is only
         one tile with one tile-part.
             By contrast, in the fussy mode, the object makes a serious attempt
         to identify compliance violation and generates an appropriate terminal
         error message if it finds one.
             By fast mode is used by default.  In this case, compliance is
         assumed so as to minimize checking, and there is no attempt to
         recover from errors.
             The resilient mode takes an optional argument indicating whether
         or not the decompressor should expect SOP markers to appear in
         front of every packet whenever the relevant flag in the Scod byte
         of the COD marker is set.  According to the JPEG2000 standard,
         SOP markers need not appear in front of every packet when this flag
         is set; however, this weakens error resilience, since we cannot
         predict when an SOP marker should appear.  If you know that the
         code-stream has been constructed to place SOP markers in front
         of every packet (or not use them at all), then set
         `expect_ubiquitous_sops' to true, thereby allowing the error
         resilient code-stream parsing algorithm to do a better job. */
    KDU_EXPORT void
      apply_input_restrictions(int first_component, int max_components,
                               int discard_levels, int max_layers,
                               kdu_dims *region_of_interest);
      /* This function may be used only with codestream objects created
         for input (i.e., for reading).  It restricts the amount of the
         code-stream which will be accessible to the user.  Since it has an
         impact on the dimensions returned by other member functions, these
         dimensions may need to be re-acquired afterwards.  The role of this
         function is closely related to that of `change_appearance'; however,
         the latter function may be applied to both input and output
         codestream objects.
            The function may be invoked multiple times to alter the region
         of interest, resolution, image components or number of quality
         layers presented to the user.  However, unless the object is set up
         for persistence (see `kdu_codestream::set_persistent'), it may not
         be called after the first tile access.  This is because non-persistent
         objects discard data which will not be used, based on these input
         restrictions and there is no way to get the discarded data back again.
         Even in the persistent case, you may not call this function while any
         tile is open.
            Zero valued arguments are always interpreted as meaning that any
         restrictions should be removed from the relevant parameter.
            The `first_component' argument identifies the index (starting from
         0) of the first component to be presented to the user.  If this is
         non-zero, any interface functions to this or any related object which
         accept component index arguments will add this `min_component' value
         to the component index in order to obtain the index of the true
         code-stream component which is being identified.  An error message
         will be generated if `min_component' is greater than or equal to
         the total number of code-stream components.
            The `max_components' argument identifies the maximum number
         of components which will appear to be present, starting from the
         component identified by the `first_component' argument.  If
         `max_components' is 0, all components will appear.
            The `discard_levels' argument indicates the number of resolution
         levels which should be discarded. Image dimensions are effectively
         divided by 2 to the power of this number. This argument affects the
         apparent dimensions and number of DWT levels in each tile-component.
         Note, however, that neither this nor any other argument has any
         effect on the list of `kdu_params' returned by
         `kdu_codestream::access_siz'.
            The `max_layers' argument identifies the maximum number of quality
         layers which will appear to be present when precincts or code-blocks
         are accessed.  A value of 0 has the interpretation that all
         layers should be retained.
            The `region_of_interest' argument, if non-NULL, provides a
         region of interest on the high resolution grid.  Any attempt to
         access tiles or other subordinate partitions which do not intersect
         with this region will result in an error.  Note that the region may
         be larger than the actual image region.  Also, the region must be
         described in terms of the original code-stream geometry.  Specifically
         any appearance transformations supplied by the `change_appearance'
         member function have no impact on the interpretation of the region.
         You may find the `map_region' member function useful in creating
         suitable regions. */
    KDU_EXPORT void
      change_appearance(bool transpose, bool vflip, bool hflip);
      /* This function alters the apparent orientation of the image, affecting
         the apparent dimensions and regions indicated by all subordinate
         objects and interfaces.  Multiple calls are permitted and the
         functionality is supported for both input and output codestream
         objects.  Except in the case of an input object marked for persistence
         (see `kdu_codestream::set_persistent'), the function may not be called
         after the first tile access.  Even in the case of a persistent input
         object, the function may not be called while any tile is open.
            Note that this function has no impact on `kdu_params' objects in
         the list returned by `kdu_codestream::access_siz', since those
         describe the actual underlying code-stream.
            The `transpose' flag causes vertical coordinates to be transposed
         with horizontal. If `vflip' is true, vertical coordinates start (at 0)
         from the bottom of the image/canvas and work upward.  If `transpose'
         and `vflip' are both true, vertical coordinates start from the right
         and work toward the left of the true underlying representation.  If
         `hflip' is true, individual image component lines (and all related
         quantities) are flipped.  If `transpose' is also true, these lines
         correspond to columns of the true underlying representation. */
  // --------------------------------------------------------------------------
  public: // Data processing/access functions
    KDU_EXPORT kdu_tile
      open_tile(kdu_coords tile_idx);
      /* Accesses a specific tile, returning an interface which can be
         used for accessing the tile's contents, including specific
         tile-components.  Note that the returned interface contains no
         state of its own, but only an embedded reference to the real state
         information, which is buried in the implementation.  When a tile is
         first opened, the internal state information may be automatically
         created from the code-stream parameters available at that time.
         These in turn may be translated automatically from markers if this
         is an input object.  Indeed, for this to happen, any amount of the
         code-stream may need to be read and buffered internally.
             For these reasons, you should be careful only to open tiles
         which you really want to read from or write to.  Instead of walking
         through tiles to find one you are interested in, use the `find_tile'
         member function.
             The supplied tile indices must lie within the region returned
         by the `get_valid_tiles' function; otherwise, an error will be
         generated.
             The object attempts to read and buffer the minimum amount of the
         code-stream in order to satisfy the request.  Although not mandatory,
         it is a good idea to close all tiles (see `j2_tile::close' once you
         are done with them). */
    KDU_EXPORT void
      flush(int layer_bytes[], int num_layer_specs,
            kdu_uint16 *thresholds=NULL);
      /* Call this function before destroying an output object.  It performs
         the PCRD-opt rate allocation and generates the actual code-stream
         data.  In the future we may provide mechanisms for incrementally
         flushing the code-stream to save memory when working with huge
         images and spatially progressive packet progressions.  For now,
         though, this function must be called once and once only, after
         everything has been compressed.
            The `layer_bytes' array contains `num_layer_specs'.  Normally,
         `num_layer_specs' should be identical to the actual number of quality
         layers.  In this case, every non-zero entry identifies the target
         maximum number of bytes for the corresponding quality layer. Note
         that the number of bytes specified in `layer_bytes[k]' identifies
         the total number of bytes occupied by layers 0 through k, including
         all headers, marker codes and marker segments.  However, see comments
         below regarding the optional `thresholds' argument.
            Zero valued entries in the `layer_bytes' array mean that the rate
         allocator should attempt to assign roughly logarithmically spaced
         bit-rates to those quality layers.  The logarithmic spacing rule is
         applied after first subtracting a minimal header offset consisting
         of the main and tile header bytes, plus 1 byte per packet (3 bytes
         if EPH markers are being used, 7 bytes if SOP marker segments are
         being used, and 9 bytes if both SOP and EPH marker segments are being
         used).  Any or all of the entries may be 0.  If the last entry is 0,
         all generated bits will be output by the time the last quality layer
         is encountered.  If the first entry is 0 and there are multiple
         layers, the function employs the following reasonable policy to
         determine suitable rate allocation targets.
               * Let Z be the number of initial layers whose size is not
                 explicitly specified (if the last layer has no assigned
                 size, it will first be assigned the number of bytes required
                 to including all compressed information in the code-stream,
                 as described above.
               * Let R be the target number of bytes for the next layer.
               * Let H_k be the minimal header cost mentioned above (main and
                 tile headers, plus 1 byte per packet, but more if SOP
                 and/or EPH markers are used) for the first k quality layers.
               * The rate allocator will try to allocate H_1+(R-H_Z)/sqrt(2^Z)
                 bytes to the first layer.  The logarithmic spacing policy
                 will then assign roughly 2 layers per octave change in the
                 bit-rate.
         Note that the above policy will work well even if the user provides
         a `layer_bytes' array with all entries set to 0; in this case it will
         assign 2 layers per octave, with the last layer containing all