line_block_ifc.h

JPEG2000 EBCOT算法源码

       of the image samples and subband samples (i.e. 2^R, where R is the
       STD_NOMINAL_RANGE_BITS value) and then dividing by the L2-norm (root
       sum of filter taps) of the synthesis waveform associated with the
       relevant band.  The synthesis waveform is computed internally by
       appropriately convolving and upsampling the synthesis filters on the
       path from the subband samples back to the original image.  This leads
       to a theoretically optimal solution in terms of MSE under high-rate
       quantization assumptions, provided either the transform is orthogonal
       or the quantization errors are uncorrelated.  If the relevant
       component's flag integer contains FILTER_INFO__IDEAL_QUANT, the L2-norm
       of the synthesis waveform is taken to be equal to 2^L where L is the
       number of levels in the decomposition tree between the original image
       and the relevant subband, regardless of the actual filter tap values.
       If the flag integer contains FILTER_INFO__RADIX_QUANT, the quantization
       step size is rounded down to the nearest power of 2 once the
       above steps have been computed.
           `max_bitplanes' plays an important role in ensuring compatibility
       between bit-streams produced by implementations which use different
       IMPLEMENTATION_PRECISION values and hence different precisions for
       all fixed point sample representations.  During compression, the
       initial value of the variable pointed to by `max_bitplanes' should
       be set to 0.  The argument is used only to return the maximum number of
       bit-planes which can be supported by the implementation, which should
       be written into the bit-stream by the caller.  In fact, the value is
       simply set to IMPLEMENTATION_PRECISION-2 for the moment, since this
       allows a sign bit and an additional least significant bit for
       signalling between the quantization and coding stages, as explained
       in the comments appearing with the `encoder' and `decoder' objects.
       During decompression, `max_bitplanes' should point to a variable
       which holds the number maximum number of bitplanes, as recovered from
       the bit-stream; upon return, the value will be modified to reflect the
       maximum number which can be decoded, which is computed in exactly the
       same way as for compression.  This value need not explicitly be supplied
       to the quantization or coding objects, but they will implicitly
       recover the relevant information via the `filter_info' objects
       interface functions.
           `argc' and `argv' play the same role as the arguments passed
       to the `main' function of any "C" program.  They are provided so that
       the initialization function can look for additional special switches
       which customize its behaviour.  If special switches are used here they
       should, as a matter of convention, have the prefix, "-F", which
       identifies them as belonging to the `filter_info' object.  Moreover,
       the relevant entries in the `argv' array (including those representing
       argument parameters) should be reset to point to an empty character
       string, i.e. ""; this ensures that command-line typos can efficiently
       be caught on behalf of the user.  An example use for these command
       line arguments might be the specification of visual weights for the
       different subbands, which could modify the WMSE contributions returned
       by `filter_info__get_quant_info'.  Information of this type might not
       be included in the bit-stream, since it does not directly affect
       quantization step sizes. */

typedef void (*filter_info__print_usage__func)
  (filter_info_ref self, FILE *dest);
    /* This prototype defines the form of the `print_usage' interface function
       associated with the `filter_info' object, whose definition appears
       below.  If one or more special command-line arguments are recognized
       by the `filter_info__initialize' function, this function
       is responsible for printing a banner line introducing the object,
       which should be followed by a brief description of the command-line
       arguments which are accepted.  The usage text should be sent to the
       file stream identified by `dest'. */

typedef float *(*filter_info__get_taps__func)
  (filter_info_ref self, int flags, int component_idx, int level_idx,
   int *neg_support, int *pos_support, char **id);
    /* This prototype defines the form of the `get_taps' interface function
       associated with the `filter_info' object, whose definition appears
       below.  The function returns a pointer to an internal array of
       filter tap values.  There is no need to copy this array into local
       storage since it will persist for the lifetime of the `filter_info'
       object (i.e. until its `terminate' function is called).

       Analysis tap values appear in the opposite order to that of the
       underlying filter impulse response so that the analysis operation
       may be implemented directly as an inner product, i.e.
           c[i] = \sum_{k=-N_i}{P_i} a_i[k]x[i+k],
       where c[i] is the subband coefficient at location i, a_i[k] is the
       array of tap values for the relevant analysis filter (as returned by
       this function) and x[n] is the array of unfiltered sample values.
       We define a_i[k] to be the high-pass filter for odd indices, i
       (left and top boundaries of the image have index 0), and to be the
       low-pass filter for even indices, i.  Thus, even indexed subband
       samples, c[0], c[2], ... belong to the low-pass band, whereas high-pass
       samples, c[1], c[3], ... belong to the high-pass band.  The range of
       k values in the region of support associated with these tap values is
       given by the values of N_i and P_i.  These are returned via the
       `neg_support' and `pos_support' arguments, respectively.

       Synthesis tap values appear in the same order as the underlying filter
       impulse response so taht the synthesis operation may be implemented
       directly as a sum of synthesis waveforms,
           x[k] = \sum_i c[i] s_i[k-i]
       where the waveform, s_i[k], is zero outside the range -N_i <= k <= P_i.
       Again, odd values of i correspond to high-pass filters and even values
       of the index, i, correspond to low-pass filters and the N_i+P_i+1 tap
       values appear in order in the array returned by this function.  The
       values of N_i and P_i are again returned via the `neg_support' and
       `pos_support' arguments, respectively.

       In floating point implementations (i.e. when the quantizer and
       dequantizer floating point interface functions are to be used), these
       tap values should be applied as is without any further normalization.
       They have already been normalized in order to maintain a nominal dynamic
       range of -2^(R-1) to 2^(R-1) for all subband samples and intermediate
       results, where R is the STD_NOMINAL_RANGE_BITS value.  However, for
       fixed point implementations, one should pay careful attention to the
       definition of the `quantizer__push_line_fixed' and
       `dequantizer__pull_line_fixed' functions.  These functions expect
       additional normalization factors to be incorporated into the subband
       sample values in order to ensure that quantization step sizes are
       exact powers of 2.  It is the responsibility of the analysis and
       syntheis stages to absorb any discrepancy between these power-of-two
       step sizes and the actual step sizes into the filter coefficients so
       as to minimize numerical errors.  These factors are close to 1 and
       they may be determined via appropriate calls to the
       `filter_info__get_quant_info' function.  Moreover, the factors will
       be exactly equal to 1 if FILTER_INFO__RADIX_QUANT was included in the
       `flags' argument supplied to `filter_info__initialize'.

       The remaining arguments have the following interpretation:
           `self' holds a reference (pointer) to the relevant `filter_info'
       object (structure), so that private state information can be accessed.
           `flags' identifies the particular type of filter whose coefficients
       are being requested.  The relevant flags which may be set are
       defined by the FILTER__HIGH, FILTER__VERT and FILTER__SYNTH macros.
       If FILTER__HIGH is present, high-pass filter information will be
       returned; otherwise, the information is for the low-pass filters.  If
       FILTER__VERT is present, the information for the vertical filters is
       returned; otherwise, the information is for the horizontal filters.
       If FILTER__SYNTH is present, the information returned corresponds to
       the synthesis filters; otherwise, it corresponds to the analysis
       filters.
           `component_idx' is used to identify the component (usually
       colour component) whose decomposition is being identified here.  This
       is supplied for future compatibility, since currently the `filter_info'
       object has no way to include different filter sets for different
       components.
           `level_idx' identifies the particular level within the wavelet
       transform for which filter tap values are being requested.  A value
       of 0 will cause the function to return filters for generating the
       lowest resolution bands from the next higher resolution LL band.  A
       value of 1 will retrieve filters for generating the second lowest
       resolution bands from the next higher resolution LL band and so
       forth.
           `id' is used to return a pointer to the `id' character string
       which was originally passed to `filter_info__initialize'.  The
       argument may be NULL if this information is required.  The information
       is useful primarily for supporting built-in filters for more
       efficient implementations of the analysis or synthesis operations.
       In particular, the analysis or synthesis stages might use this argument
       to check for the built-in Daubechies 9/7 filter set which is assigned
       to the character string, "0".  It is important to realize that all
       built-in filters must be normalized so that the analysis low-pass
       filter has a DC gain of unity and the analysis high-pass filter has
       a Nyquist gain of unity. */

typedef void (*filter_info__get_quant_info__func)
  (filter_info_ref self, int component_idx, int level_idx, int band_idx,
   float *step_size, int *nearest_exponent, float *step_wmse, int *extra_lsb);
    /* This prototype defines the form of the `get_quant_info' interface
       function associated with the `filter_info' object, whose definition
       appears below.  The function returns quantization information for any
       given subband, via the last four arguments, which point to variables
       into which the relevant information will be written.  A NULL argument
       may be supplied for any of these arguments if the relevant information
       is not required.
           `component_idx' identifies the component (usually colour component)
       to which the relevant subband belongs.  A value of 0 identifies the
       first component (usually luminance).
           `level_idx' identifies the resolution level within the wavelet
       decomposition for which information is being requested.  A value of
       0 identifies the lowest resolution subbands.  Larger values identify
       successively higher resolution levels.
           `band_idx' identifies the particular subband for which information
       is being requested.  With the Mallat decomposition, this argument must
       be one of LL_BAND, LH_BAND, HL_BAND or HH_BAND, where the exact
       interpretations of these macros appears above with their definitions.
       The LL_BAND value is legal only at level 0 for obvious reasons.  With
       the Spacl decomposition, the `band_idx' argument may take on one of
       16 different values whose 4-bit identifier may be written as B1+4*B2,
       where B1 is the primary subband identifier and B2 identifies the type
       of decomposition which is applied to the primary subband to arrive at
       the actual subband.  Both B1 and B2 must be one of LL_BAND, LH_BAND,
       HL_BAND and HH_BAND.
           `step_size' is used to return the value of the quantization step
       size which is to be used in the relevant band.
           `nearest_exponent' is used to return an integer approximation to
       the base-2 logarithm of the value returned via the `step_size'
       argument.  Specifically, the largest integer, s, is returned such that
       2^s is less than or equal to the step size.  The quantizer and
       dequantizer should use 2^s as though it were the actual step size when
       working with fixed point data (i.e. when the analysis or synthesis
       stage invokes one of the fixed point push or pull functions).  This
       means that the analysis and synthesis stages are responsible for
       incorporating the discrepancy between the actual step size and this
       approximate step size into the filter tap values which are used.  In
       floating point implementations, the `nearest_exponent' value can and
       should be ignored.  Note that the integer returned via
       `nearest_exponent' may be positive or negative.
           `step_wmse' is used to return the contribution to overall
       Weighted Mean Squared Error (WMSE) in the reconstructed image, which
       may be expected from an error of exactly one step size in the
       sample values of the relevant band.  This information is very important