plineartransform

Performs linear transform of the gray-levels.

Synopsis

plineartransform inverse min max [-m mask] [im_in|-] [im_out|-]

Description

plineartransform expands or compresses gray-levels of the input image im_in using a linear transform of the gray-levels. The parameter inverse specifies whether the transform is positive or negative.

The effect of the positive transform is to stretch the gray-levels between the new bound [min..max].
The effect of the negative transform is to stretch the gray-levels between the new bounds [min,max] and to inverse all the gray-levels: max becomes min, min becomes max, etc.

The positive linear transform of pixel 'p' has the form:

im_out[p]=(c*(im_in[p]-smin)) + min;
c=(max-min) / (smax-smin)

where smin and smax are the minimum and the maximum values of the input image, and c is a normalization factor for stretching output values between min and max.

 im_out  ^
         |
    max  |              /-------- 
         |             /
         |            /
         |           /
         |          /
         |         /
    min  |--------/
         |
         --------------------- --> im_in
                  |     |
                smin smax

The negative linear transform of pixel 'p' has the form:

im_out[p]=(c*(smax-ims[p])) + min;
c=(max-min) / (smax-smin)

where smin and smax are the minimum and the maximum values of the input image, and c is a normalization factor for stretching normalizing output values between min and max.

 im_out  ^
         |
    max  |-------\
         |        \
         |         \
         |          \
         |           \
         |            \
    min  |             \--------
         |
         --------------------- --> im_in
                  |     |
                smin smax

For color and multispectral images, the linear transform uses the vectorial approach: the min and max values are calculed from all the bands, and then each band is stretched with the same transform.

Parameters

inverse is an integer in [0,1] that specifies whether the transform is positive (inverse=0) or negative (inverse=1).
min and max specify the new bounds of the output pixel value. They are related to the type of the input image.
Note: if min < max then min and max are set with the minimum and maximum values of the input image type; for example, 0 and 255 for Uchar images.

Inputs

im_in: an image.

Outputs

im_out: an image with the same properties as im_in.

Result

Returns SUCCESS or FAILURE in case of invalid parameter values.

Examples

Applies a positive followed by a negative transform to create image b.pan. Because negative is the inverse transform of positive transform, b.pan is (almost) equal to tangram.pan (due to rounding error) and c.pan is (almost) null:

   plineartransform 1 0 255 tangram.pan a.pan
   plineartransform 0 0 255 a.pan b.pan
   pdif a.pan b.pan c.pan

Applies a linear transform to create a.pan and uses the min and max values of the image type as new bound:

   plineartransform 0 1 -1 tangram.pan a.pan

Piecewise linear transform: the input pixels between the bounds [0, 75] are compressed in the new bound [0..20] and those between the bounds [76, 255] are expanded in the new bounds [21, 255]:

   pthreshold 0 75 tangram.pan a.pan
   plineartransform 0 0 20 a.pan a1.pan
   paddcst -75 tangram.pan a.pan
   plineartransform 0 0 235 a.pan b.pan
   paddcst 20 b.pan a2.pan
   por a1.pan a2.pan a.pan

C++ prototype

Errc PLinearTransform( const Img2duc &im_in, const Img2duc &im_out, int inverse, float min, float max );

Version française

Transformation linéaire des niveaux de gris.

Author: Régis Clouard