[OctDev] imadjust recoded

[Josep i T. <jm...@pu...>]

Hello Kai and list,

Now that we have ND arrays, I began updating imadjust.m to add RGB
images and a few things more, but I ended up recoding it all. 

Behaviour has been modified as follows:
* Interface is now compatible with MATLAB docs
* RGB support has been added
* docs have been rewritten
* tests added
* now limits can be different for each plane in RGB or each color in a
colormap (using 1-by-3 arrays)

Since I've only keeped 3 lines of code, I've copyrighted it to me and
inluded a reference to old code and original copyright. If you feel this
is wrong or impolite please tell me.

If someone could check if behaviour is ok it would be great. I attach
the m-file.... I'll commit it if you agree.

The docs:
 -- Function File: J = imadjust (I)
 -- Function File: J = imadjust (I,[LOW_IN;HIGH_IN])
 -- Function File: J = imadjust (I,[LOW_IN;HIGH_IN],[LOW_OUT;HIGH_OUT])
 -- Function File: J = imadjust (..., GAMMA)
 -- Function File: NEWMAP = imadjust (MAP, ...)
 -- Function File: RGB_OUT = imadjust (RGB, ...)
     Adjust image or colormap values to a specified range

     `J=imadjust(I)' adjusts intensity image I values so that 1% of
     data on lower and higher values (2% in total) of the image is
     saturated; choosing for that the corresponding lower and higher
     bounds (using `stretchlim') and mapping them to 0 and 1. J is an
     image of the same size as I which contains mapped values.  This is
     equivalent to `imadjust(I,stretchlim(I))'.

     `J=imadjust(I,[low_in;high_in])' behaves as described but uses
     LOW_IN and HIGH_IN values instead of calculating them. It maps
     those values to 0 and 1; saturates values lower than first limit
     to 0 and values higher than second to 1; and finally maps all
     values between limits linearly to a value between 0 and 1. If `[]'
     is passes as `[low_in;high_in]' value, then `[0;1]' is taken as a
     default value.

     `J=imadjust(I,[low_in;high_in],[low_out;high_out])' behaves as
     described but maps output values between LOW_OUT and HIGH_OUT
     instead of 0 and 1. A default value `[]' can also be used for this
     parameter, which is taken as `[0;1]'.

     `J=imadjust(...,gamma)' takes, in addition of 3 parameters
     explained above, an extra parameter GAMMA, which specifies the
     shape of the mapping curve between input elements and output
     elements, which is linear (as taken if this parameter is omitted).
     If GAMMA is above 1, then function is weighted towards lower
     values, and if below 1, towards higher values.

     `newmap=imadjust(map,...)' applies a transformation to a colormap
     MAP, which output is NEWMAP. This transformation is the same as
     explained above, just using a map instead of an image.  LOW_IN,
     HIGH_IN, LOW_OUT, HIGH_OUT and GAMMA can be scalars, in which case
     the same values are applied for all three color components of a
     map; or it can be 1-by-3 vectors, to define unique mappings for
     each component.

    `RGB_out=imadjust(RGB,...)' adjust RGB image RGB (a M-by-N-by-3
     array) the same way as specified in images and colormaps.  Here
     too LOW_IN, HIGH_IN, LOW_OUT, HIGH_OUT and GAMMA can be scalars or
     1-by-3 matrices, to specify the same mapping for all planes, or
     unique mappings for each.

     The formula used to realize the mapping (if we omit saturation) is:

     `J = low_out + (high_out - low_out) .* ((I - low_in) / (high_in -
     low_in)) .^ gamma;'

     *Compatibility notes:*

        * Prior versions of imadjust allowed `[low_in; high_in]' and
          `[low_out; high_out]' to be row vectors. Compatibility with
          this behaviour has been keeped, although preferred form is
          vertical vector (since it extends nicely to 2-by-3 matrices
          for RGB images and colormaps).

       * Previous version of imadjust, if `low_in>high_in' it
          "negated" output.  Now it is negated if `low_out>high_out',
          for compatibility with MATLAB.

        * Class of I is not considered, so limit values are not
          modified depending on class of the image, just treated "as
          is". When Octave 2.1.58 is out, limits will be multiplied by
          255 for uint8 images and by 65535 for uint16 as in MATLAB.

   See also: stretchlim, brighten.



Regards,

-- 
Josep Monés i Teixidor
Clau GnuPG: gpg --recv-keys 80E85CC4