User's Guide

UNARY

Performs several unary operations on an image

Function:

UNARY performs unary operations on either single or multi-band images. The user may choose one of six operations: SINE, COSINE, LOG, EXP, SCALE or NOT. One of four data types may be chosen for the output image: REAL*4, INTEGER*4, INTEGER*2 or BYTE. The output image is the same size as the input image.
If an output data type other than REAL*4 is requested but no scale and offset are given, the output values will be truncated as they are written to the output file. With the SCALE subcommand, if no scale and offset are given, the scale and offset values will be calculated automatically to prevent this truncation.

Parameters:

Subcommand -SIN:

Calculates the SINE of the image pixel values. The output values are defined as follows:

OUTPUT(i) = SCOFF(1)*[ sin(SCALFACT*INPUT(i) + OFFSET)] + SCOFF(2)

(NOTE: The input values are assumed to be in radians.)

IN
Input image. IN can contain BYTE, INTEGER*2, INTEGER*4, or REAL*4 data. The pixel values in IN are assumed to be in radians.

OUT
Output image. The output image that contains the modified image. The data type of OUT is determined by ODTYPE.

SCOFF(1.0,0.0)
Scale and Offset. SCOFF is a 2-dimensional variable which holds scale and offset values. After the selected UNARY function has been computed for an input pixel, the specified scale and offset values are applied as follows:
OUTPUT(i) = ( SCOFF(1) * INPUT(i) ) + SCOFF(2)
where INPUT(i) is the modified input pixel value.

ODTYPE(R*4)
Output data type. The data type of the output image.
  = SAME:  Same as input 
  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)
UNARY does all computations with floating-point values and will not perform automatic scaling of results. For this reason, it is recommended that a scaling factor and offset be specified whenever ODTYPE takes on a value other than R*4 to prevent truncation of output.
SCALFACT(1.0)
Scale factor. SCALFACT is used to scale the input image prior to applying the unary operator. When used in conjunction with OFFSET, the output image will be computed as follows: If <OP> is either the SINE or COSINE operator, then:
OUTPUT(i) = SCOFF(1)*[<OP> (SCALFACT*INPUT(i) + OFFSET)] + SCOFF(2)

OFFSET(0.0)
Offset value. OFFSET is used to offset the input image(s) prior to applying the unary operator (either SINE or COSINE). When used in conjunction with SCALFACT, the output image will be computed as follows:
If <OP> is either the SINE or COSINE operator then:
OUTPUT(i) = SCOFF(1)*[<OP> (SCALFACT*INPUT(i) + OFFSET)] + SCOFF(2)

Subcommand -COS:

Calculates the COSINE of the image pixel values. The output values are defined as follows:

OUTPUT(i) = SCOFF(1)*[ cos(SCALFACT*INPUT(i) + OFFSET)] + SCOFF(2)

(NOTE: The input values are assumed to be in radians.)

IN
Input image. IN can contain BYTE, INTEGER*2, INTEGER*4, or REAL*4 data. The pixel values in IN are assumed to be in radians.

OUT
Output image. The output image that contains the modified image. The data type of OUT is determined by ODTYPE.

SCOFF(1.0,0.0)
Scale and Offset. SCOFF is a 2-dimensional variable which holds scale and offset values. After the selected UNARY function has been computed for an input pixel, the specified scale and offset values are applied as follows:
OUTPUT(i) = ( SCOFF(1) * INPUT(i) ) + SCOFF(2)
where INPUT(i) is the modified input pixel value.

ODTYPE(R*4)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)
UNARY does all computations with floating-point values and will not perform automatic scaling of results. For this reason, it is recommended that a scaling factor and offset be specified whenever ODTYPE takes on a value other than R*4 to prevent truncation of output.
SCALFACT(1.0)
Scale factor. SCALFACT is used to scale the input image prior to applying the unary operator. When used in conjunction with OFFSET, the output image will be computed as follows: If <OP> is either the SINE or COSINE operator, then:
OUTPUT(i) = SCOFF(1)*[<OP> (SCALFACT*INPUT(i) + OFFSET)] + SCOFF(2)

OFFSET(0.0)
Offset value. OFFSET is used to offset the input image(s) prior to applying the unary operator (either SINE or COSINE). When used in conjunction with SCALFACT, the output image will be computed as follows:
If <OP> is either the SINE or COSINE operator then:
OUTPUT(i) = SCOFF(1)*[<OP> (SCALFACT*INPUT(i) + OFFSET)] + SCOFF(2)

Subcommand -LOG:

Calculates the specified LOGARITHM of the image pixel values. The output values are defined as follows:

OUTPUT(i) = SCOFF(1)*[ log(INPUT(i))/ log(BASE)] + SCOFF(2)

IN
Input image. IN can contain BYTE, INTEGER*2, INTEGER*4, or REAL*4 data.

OUT
Output image. The output image that contains the modified image. The data type of OUT is determined by ODTYPE.

SCOFF(1.0,0.0)
Scale and Offset. SCOFF is a 2-dimensional variable which holds scale and offset values. After the selected UNARY function has been computed for an input pixel, the specified scale and offset values are applied as follows:
OUTPUT(i) = ( SCOFF(1) * INPUT(i) ) + SCOFF(2)
where INPUT(i) is the modified input pixel value.

ODTYPE(R*4)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)
UNARY does all computations with floating-point values and will not perform automatic scaling of results. For this reason, it is recommended that a scaling factor and offset be specified whenever ODTYPE takes on a value other than R*4 to prevent truncation of output.
BASE(10.0)
Base value. BASE is a real number used as follows.
OUTPUT(i) = SCOFF(1)*[ log(INPUT(i))/ log(BASE)] + SCOFF(2)

Subcommand -EXP:

Calculates the specified EXPONENTIAL of image pixel values. The output image may be defined as follows:

OUTPUT(i) = SCOFF(1)*[BASE**(EXPSF*INPUT(i))] + SCOFF(2)

IN
Input image. IN can contain BYTE, INTEGER*2, INTEGER*4, or REAL*4 data.

OUT
Output image. The output image that contains the modified image. The data type of OUT is determined by ODTYPE.

SCOFF(1.0,0.0)
Scale and Offset. SCOFF is a 2-dimensional variable which holds scale and offset values. After the selected UNARY function has been computed for an input pixel, the specified scale and offset values are applied as follows:
OUTPUT(i) = ( SCOFF(1) * INPUT(i) ) + SCOFF(2)
where INPUT(i) is the modified input pixel value.

ODTYPE(R*4)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)
UNARY does all computations with floating-point values and will not perform automatic scaling of results. For this reason, it is recommended that a scaling factor and offset be specified whenever ODTYPE takes on a value other than R*4 to prevent truncation of output.
BASE(10.0)
Base value. BASE is a real number used as follows.
OUTPUT(i) = SCOFF(1)*[BASE**(EXPSF*INPUT(i))] + SCOFF(2)

EXPSF(1.0)
Exponent scale factor. EXPSF is a Real number used to scale the input image prior to applying the exponentiation. EXPSF is used as follows:
OUTPUT(i) = SCOFF(1)*[BASE**(EXPSF*INPUT(i))] + SCOFF(2)
See User Note #3.

Subcommand -SCA:

Performs a linear scaling of the image pixel values. By default, the scale and offset will be automatically calculated if converting from a higher (REAL*4) to lower (BYTE) data type using the ODTYPE parameter. The output values are defined as follows:

OUTPUT(i) = ( SCOFF(1) * INPUT(i) ) + SCOFF(2)

IN
Input image. IN can contain BYTE, INTEGER*2, INTEGER*4, or REAL*4 data.

OUT
Output image. The output image that contains the modified image. The data type of OUT is determined by ODTYPE.

SCOFF(--)
Sale and offset. SCOFF is a 2-dimensional variable which holds scale and offset values. By default, the scale and offset will be calculated according to the minimum and maximum allowed pixel values of the requested output image type, and the minimum and maximum pixel values of the input image. The user may override the automatic scaling by specifying a scale and offset. The calculated scale and offset values are then applied as follows:
OUTPUT(i) = ( SCOFF(1) * INPUT(i) ) + SCOFF(2)
where INPUT(i) is the modified input pixel value.

ODTYPE(R*4)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)
UNARY does all computations with floating-point values. By default, UNARY will perform automatic scaling of results whenever converting from a higher (REAL*4) to lower (BYTE) data type. The user may override the automatic scaling by specifying scale and offset.

Subcommand -NOT:

Performs a logical bitwise complement of an input image.

NOT determines the logical bitwise complement of each input image pixel to produce the output image as follows:

OUT(i,j) = .NOT. INPUT

In the case of BYTE images, input pixel values mapped from 0 to 255 are reverse mapped and output values are from 255 to 0.

IN
Input image. IN can contain BYTE, INTEGER*2, INTEGER*4, or REAL*4 data.

OUT
Output image. The output image that contains the modified image. The data type of OUT is determined by ODTYPE.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)
UNARY does all computations with floating-point values and will not perform automatic scaling of results. For this reason, it is recommended that a scaling factor and offset be specified whenever ODTYPE takes on a value other than R*4 to prevent truncation of output.

Examples:

LAS> unary-log in="group.in(1,1,20,20:2-4)" out=group.out base=2.0 scoff=(0.5,4.7) odtype=i*2
A window of 20 by 20 of bands 2 through 4 of image GROUP.IN will be processed. The resulting pixels are then transformed with the base 2 logarithm. Once the logarithm is applied, the output pixels are multiplied by 0.5, then increased by 4.7. When the scaling is completed, the pixels are written to the output file group, GROUP.OUT. GROUP.OUT contains INTEGER*2 pixels.
LAS> unary-sin in=file.in out=file.out odtype=byte scalfact=2.5 offset=7.5
FILE.IN is multiplied by 2.5 and an offset of 7.5 is added before transformation by SIN. FILE.OUT is a BYTE image with the same size as FILE.IN. Since the requested output data type is BYTE and the sine of any number falls between 1 and -1 inclusive, FILE.OUT will contain pixel values of zero or one only.
LAS> unary-sca in="file.in(1,1,50,50)" out=file.out scoff=(3.0,5.0)
The 50 x 50 window of FILE.IN undergoes a linear transformation with a scale of 3.0 and an offset of 5.0. The output image, FILE.OUT, is a REAL*4 image with 50 lines and pixels.
LAS> unary-exp in="group.in(1,1,20,20)" out=group.out expsf=0.8 scoff=(0.5,30.0)
The files in GROUP.IN are transformed exponentially and the output is scaled by 0.5, with an offset of 30.0. EXPSF scales the input image by 0.8 prior to applying the exponential operator, and SCOFF scales the output data after EXP is completed.
LAS> unary-not in="group.in(:4 2 3)" out=group.out
Bands 4, 2 and 3 of the input image GROUP.IN are logically complemented and output as the three-band image group.out.

Description/Algorithm:

UNARY processes the input image one band at a time. All operations are performed in REAL*4. If an output data type other than REAL*4 is requested, UNARY converts that data type while writing to the output, with some truncation of data possibly taking place. SCOFF may be used to scale the output image prior to writing it out to prevent this truncation. If SCOFF is left at its default, some truncation of data may result. With the SCALE subcommand, if SCOFF is left as its default, the scale and offset will be calculated based on the minimum and maximum allowable pixel values of the output data type and the minimum and maximum pixel values of the input image.
The following algorithms describe the computation of the output image where i is the number of the input and output pixel.
SIN: OUTPUT(i) = SCOFF(1) * sin(SCALFACT * INPUT(i)+OFFSET) + SCOFF(2)

COS: OUTPUT(i) = SCOFF(1) * cos(SCALFACT * INPUT(i)+OFFSET) + SCOFF(2)
 
LOG: OUTPUT(i) = SCOFF(1) * log(INPUT(i))/log(BASE) + SCOFF(2)

EXP: OUTPUT(i) = SCOFF(1) * (BASE ** EXPSF * (INPUT(i)) + SCOFF(2)

SCA: OUTPUT(i) = (SCOFF(1) * INPUT(i)) + SCOFF(2)

NOT: OUTPUT(i,j) =  NOT.(INPUT(i,j)

Nonfatal Error Messages:

[unary-runopt] Some pixels for band have not been exponentiated to prevent overflow
Only EXPSF and SCOFF applied to these pixels. Decrease EXPSF for better results.
[unary-scoff] SCALE and OFFSET setting will result floatingpoint overflow
Adjust the SCALE and OFFSET values for better results.

Fatal Error Message:

[unary-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 that was encountered.
[unary-pixel] Pixel values less than or equal to 0.0 found in band <N>, log function aborted
Use the program UNARY-SCA to transform the original image to eliminate all pixel values less than or equal to 0. For example, if the largest negative number in the input image is -10, use UNARY-SCA with SCOFF=(1.0,11) to create a new image that can be transformed by UNARY-LOG.

User Notes:

Input values are considered to be in radians for sine and cosine operations.
If an output data type is requested other than REAL*4, but no scale and offset are given, the output values may be truncated before they are written to the output image.
EXPSF is used to scale input intensities. To avoid floating overflow errors, the following constraint has been defined:
```
      1n(0.29E-38) < EXPSF*INPUT(i)*1n(BASE) < 1n(1.7E38)

    which is

      -88.74 < EXPSF*INPUT(i)*1n(BASE) < 88.03
```
SCOFF is used to perform an optional linear transformation after the selected function has been completed.