User's Guide

RESCALE

Rescale an image

Function:

Rescale an image by unscaling each pixel with an input scale factor and an offset value then applying an output scale factor and offset value.

Parameters:

IN
Input image. The image to be rescaled. IN may be any data type, windowed, and/or subanded. Unsigned integer data types are not fully supported under LAS. IDTYPE must be used to specify UNSIGNED INTEGER*2 and UNSIGNED INTEGER*4 images.

OUT
Output image. The rescaled output image is the same size as the input image. The output data type is determined by ODTYPE.

ISCALE
Input scale. The scaling factor to be used to unscale the input image. ISCALE must contain a single value for all bands of IN or a separate value for each band of IN.

IOFFSET
Input offset. The offset value to be used to unscale the input image. IOFFSET must contain a single value for all bands of IN or a separate value for each band of IN.

IMASK(0,1,2,3,4,5,6,7,8,9)
Input mask values. IMASK specifies pixel vales in the input image which are mask values. When these values are encountered, they are not unscaled but are set to the value specified in OMASK. If NULL, there are no mask values in IN. See User Note 1.

IDTYPE(--)
Input data type. The data type of the input image. Unsigned integer data types are not fully supported under LAS. U*2 or U*4 must be specified for unsigned images.

  = --:    Same as input 
  = U*2:   UNSIGNED INTEGER*2
  = U*4:   UNSIGNED INTEGER*4

SHIFT(--)
Data shift. Value to be subtracted from the input pixels after they have been unscaled but before rescaling. If NULL, the data shift will be set to zero for all input bands. Otherwise, SHIFT must contain a single value for all bands of IN or a separate value for each band of IN. See User Note 2.

OSCALE(1.0)
Output scale. The scaling factor to be used to rescale the input image. OSCALE must contain a single value for all bands of IN or a separate value for each band of IN.

OOFFSET(0.0)
Output offset. The offset value to be used to rescale the input image. OOFFSET must contain a single value for all bands of IN or a separate value for each band of IN.

OMASK(0,1,2,3,4,5,6,7,8,9)
Output mask values. OMASK specifies an output value for each of the mask values in IMASK. If NULL, each mask value specified in IMASK is set to zero in the output image. If OMASK contains a single value, each mask value specified in IMASK is set to this value in the output image. If OMASK contains multiple values, it must have the same number of entries as IMASK.

ODTYPE(--)
Output data type. The data type of the output image.

  = --:    Same as input 
  = BYTE:  BYTE
  = I*2:   INTEGER*2
  = U*2:   UNSIGNED INTEGER*2
  = I*4:   INTEGER*4
  = U*4:   UNSIGNED INTEGER*4
  = R*4:   REAL*4

OMAX(--)
Output maximum. Maximum pixel values allowed in OUT. If a pixel value exceeds this value, it will be set to zero in the output image. If OMAX=NULL, the pixel values will be checked against the maximum value for the output data type. See User Note 3.

OMIN(--)
Output minimum. Minimum pixel values allowed in OUT. If a pixel value is less than this value, it will be set to zero in the output image. If OMIN=NULL, the pixel values will be checked against the minimum value for the output data type. See User Note 3.

ROUNDOPT(ROUND)
Round option. Option to round or truncate INTEGER or BYTE rescaled data before it is written to the output image.

  = ROUND:  Round the rescaled data.
  = TRUNC:  Truncate the rescaled data.

Examples:

  1. LAS> rescale in=img out=img2 iscale=0.1 ioffset=10.0 imask=-- omask=-- odtype=r*4

    All bands from IMG are unscaled with a scaling factor of 0.1 and an offset of 10.0. Since OSCALE and OOFFSET default to 1.0 and 0.0, respectively, IMG2 will be an unscaled version of IMG. Both IMASK and OMASK are set to NULL to indicate there are no mask values in the input image. Thus, all pixel values will be unscaled. IMG2 will be of type REAL*4.

  2. LAS> rescale in=img out=img2 iscale=5.602 ioffset=10.0 imask=-- shift=-160.0 omask=-- odtype=r*4

    All bands from IMG are unscaled with a scaling factor of 5.602 and an offset of 10.0. Since OSCALE and OOFFSET default to 1.0 and 0.0, respectively, IMG2 will be an unscaled version of IMG. After each pixel has been unscaled to its actual value, a shift value of -160 will be subtracted. Both IMASK and OMASK are set to NULL to indicate there are no mask values in the input image. Thus, all pixel values will be unscaled. IMG2 will be of type REAL*4.

  3. LAS> rescale in=img out=img2 iscale=1.0 ioffset=10.0 oscale=10.0 offset=10.0 odtype=r*4

    All bands of IMG are unscaled with a scaling factor of 1.0 and an offset of 10.0. The unscaled values are rescaled with a scaling factor of 10.0 and an offset of 10.0. Since IMASK and OMASK were allowed to default, pixel values of 0 through 9 in the input image are not rescaled but are placed directly in the output image. IMG2 will be of type REAL*4.

  4. LAS> rescale in=img out=img2 iscale=0.683 ioffset=133.0 oscale=1.0 ooffset=10.0 omask=0 odtype=byte

    All bands of IMG are unscaled with a scaling factor of 0.683 and an offset of 133.0. The unscaled values are rescaled with a scaling factor of 1.0 and an offset of 10.0. IMASK was allowed to default indicating pixel values in the range 0 to 9 are mask values. Since OMASK has been set to zero, all pixel values in the range 0 to 9 in the input image are set to 0 in the output image. The data type of IMG2 will be BYTE.

  5. LAS> rescale in="img(:1,3)" out=img2 iscale=(10.0,10.0) ioffset=(10.0,202.5) imask=-- oscale=(100.0,200.0) ooffset=(100.0,100.0) omask=--

    Band one from IMG is unscaled with a scale factor of 10.0 and an offset of 10.0. The unscaled values are rescaled with a scale factor of 100.0 and an offset of 100.0. Band three from image IMG is unscaled with a scale factor of 10.0 and an offset of 202.5. The unscaled values are rescaled with a scale factor of 200.0 and an offset of 100.0. Since IMASK and OMASK have been set to NULL, there are no mask values present in IMG. The output data is truncated and written to image IMG2. IMG2 is a two-band image that is the same size and data type as IMG.

Description/Algorithm:

After the input and output images are opened, the input pixels are unscaled, possibly shifted by a constant amount, and then rescaled. BYTE and INTEGER data is rounded or truncated depending on the value of ROUNDOPT. If the input pixel values are equal to one of the mask values in IMASK, the pixel is set to the corresponding value in OMASK without rescaling.

The following algorithm is used to rescale the input data:

   OUT_PIXEL = ((IN_PIXEL - IOFFSET) / ISCALE - SHIFT) * OSCALE + OOFFSET

Nonfatal Error Message:

  1. [rescale-mmflag] Not computing min/max

    LAS currently does not support unsigned data types. The minimum and maximum pixel values will not be computed. Processing continues.

Fatal Error Messages:

  1. [rescale-alloc] Error allocating memory

    An error occurred dynamically allocating memory. Contact the system administrator if the problem persists.

  2. [rescale-fatal] Fatal error encountered

    A fatal error was encountered during processing. Processing is terminated. The error message that is displayed immediately preceding this message is the specific error encountered.

  3. [rescale-masks] IMASK and OMASK do not contain same number of values

    When mapping multiple input mask values to multiple output mask values, IMASK and OMASK must contain the same number of values. Respecify OMASK. See User Note 1.

  4. [rescale-num] Invalid number of values for <xxxxx>

    <xxxxx> must have a single value for all bands or a separate value for each band of IN. Check the specified parameter and re-run.

  5. [rescale-range] <xxxxx> out of range

    One of the values specified in <xxxxx> is outside the valid range for ODTYPE. Ensure each of the values for this parameter are correct and/or specify a larger data type for ODTYPE.

User Notes:

  1. IMASK and OMASK are used to specify mask values in the input and output images, respectively. Images may contain a range of values that are reserved to indicate areas such as water, interrupted projection areas, no data, etc. In such images, the valid pixel values are scaled and offset to reserve the mask values. When these images are rescaled, these mask values should not be unscaled.

    IMASK allows the user to specify up to ten integer mask values. If a pixel value from IN equals one of these values, it will be set to the value indicated by OMASK in OUT. The following two points summarize the behavior of IMASK and OMASK:

    	1. When IMASK=NULL, there are no mask values in IN.  All
    	   pixel values are unscaled and stored in OUT.  If the
    	   user specifies a value for OMASK, it is ignored.
    
    	2. If the user specifies a mask value(s) in IMASK there
    	   are three options for OMASK.
    
    	    a. If OMASK=NULL, all mask values in IN will be set
    	       to zero in OUT.
    
    	    b. If OMASK contains a single value, all mask values
    	       in IN will be set to the specified value in OUT.
    	    
    	    c. In the third case, OMASK must contain the same
    	       number of mask values as IMASK.  If a pixel value
    	       from IN is equal to the n'th value specified in
    	       IMASK, the pixel will be set to the n'th value
    	       specified in OMASK.
    
  2. In some scaling schemes a value is added to every pixel to shift the actual data range prior to scaling. SHIFT allows the user specify such a value for each band to be rescaled. RESCALE will unscale the pixel values from IN, subtract the value of SHIFT, and rescale this result using OSCALE and OOFFSET.

  3. The values specified in OMASK are subject to the limits specified in OMAX and OMIN.

  4. The following is the equation used to rescale the input image:

        OUT_PIXEL = ((IN_PIXEL - IOFFSET) / ISCALE - SHIFT) * OSCALE + OOFFSET
    

  5. Unsigned integer data types are not fully supported under LAS. If the input data is UNSIGNED INTEGER*2 or UNSIGNED INTEGER*4 the user must set IDTYPE to U*2 or U*4, respectively.

  6. If more than 10 bands are to be rescaled, the user must supply at most one value for ISCALE, IOFFSET, SHIFT, OSCALE, OOFFSET, OMAX, and OMIN. This is due to the fact that when multiple values are specified, the user must specify one value for each of the input bands. Each of these parameters will allow at most 10 values.