RTR

Description

Creates a new image based on the ratio of two linear combinations of image channels. The denominator is optional.

Parameters

Name	Type	Caption	Length	Value range
FILE *	String	Input file name	1 - 192
CNUM *	Integer	Input channels for ratio numerator	1 - 16	-1024 -
WNUM	Float	Weights for ratio numerator	0 - 16	Default: 1.0
NCON	Float	Constant for ratio numerator	0 - 1	Default: 0.0
CDEN	Integer	Input channels for ratio denominator	0 - 16	-1024 -
WDEN	Float	Weights for ratio denominator	0 - 16	Default: 1.0
DCON	Float	Constant for ratio denominator	0 - 1	Default: 0.0
FILO	String	Name of the output file	0 - 192
DBOC	Integer	Output raster channel	0 - 1
DATATYPE	String	Output raster type	0 - 3	8U \| 16S \| 16U \| 32R Default: 32R
SMOD *	String	Scaling Mode	4 - 4	NONE \| AUTO \| LOGS Default: NONE
MASK	Integer	Area mask	0 - 4
ZERODIV	Float	Value for division by zero	0 - 1
FTYPE	String	Output file type	0 - 4	Default: PIX
FOPTIONS	String	Output file options	0 - 192
MONITOR	String	Monitor mode	0 - 3	ON, OFF Default: ON

* Required parameter

Parameter descriptions

FILE

Specifies the name of the PCIDSK file that contains the channels to ratio.

CNUM

Specifies the input image channels that will be added together to form the ratio numerator.

Up to 16 channels can be specified; at least one must be specified. Duplicate channels are NOT allowed.

Ranges of channels or segments can be specified with negative values. For example, {1,-4,10} is internally expanded to {1,2,3,4,10}. When you are not specifying a range in this way, only 48 numbers can be specified explicitly.

WNUM

Optionally specifies the weights to be assigned to channels listed in the numerator.

The weights correspond to the input channels listed in CNUM (InputNumer) by their position in the list.

NCON

Optionally specifies a REAL constant to be added to the numerator.

CDEN

Optionally specifies the image channels (up to 16) to be added together to form the ratio denominator.

Up to 16 channels can be specified. Duplicate channels are NOT allowed.

Ranges of channels or segments can be specified with negative values. For example, {1,-4,10} is internally expanded to {1,2,3,4,10}. When you are not specifying a range in this way, only 48 numbers can be specified explicitly.

WDEN

Optionally specifies weights to be assigned to channels listed in the denominator.

The weights correspond to the input channels listed in CDEN (InputDenom) by their position in the list.

DCON

Optionally specifies a REAL constant to be added to the denominator.

FILO

The name of the output file to which to write the processed data.

If the output file does not exist, one is created based on the type specified for the FTYPE parameter and the options specified for the FOPTIONS parameter. The file will have the number of channels required and have the same geocoding information and metadata as the input file.

If the output file is an existing file, it must be in a format that can be updated. The file must also contain channels suitable for writing the results, as specified by the value of the DBOC parameter.

When you specify an existing file, you need not specify a value for the FTYPE and FOPTIONS parameters unless the values of these parameters correspond to the type and options of the file; otherwise, an error may occur.

This parameter is mandatory.

DBOC

Specifies the output channel to receive the ratioed image.

if output to the new file , this parameter is ignored.

When your output file is a new file; that is, it does not exist already, you need not specify a value for this parameter; channel in the new file will be of the bit depth specified by the value of the DATATYPE parameter.

The output channel type depends on the specified Scaling Mode (SMOD) value:

LOGS: the output channel must be 8-bit
AUTO: the output channel can be 8-bit, 16-bit signed, or 16-bit unsigned, but not 32-bit real
NONE: the output channel can be of any supported type

This parameter is optional.

DATATYPE

The data type of the output channel to create. When the output is written to existing channels, this parameter is ignored.

Supported data types are:

8U: pixels are stored as 8-bit unsigned-integer values; this is the default value
16S: pixels are stored as 16-bit signed-integer values
16U: pixels are stored as 16-bit unsigned-integer values
32R: pixels are stored as 32-bit real values

When the number of output channels is greater than one, the specified data type is used for each output channel.

This parameter is optional.

SMOD

Specifies the scaling mode.

Supported options are:

NONE: no scaling is performed (default)
AUTO: performs linear scaling
LOGS: performs logarithmic scaling

If the specified output channel (DBOC) is 32-bit real, this parameter is ignored. See Scaling in the Details section for more information.

MASK

Specifies the window or bitmap that defines the area to be processed within the input raster.

If a single value is specified, that value represents the channel number of the bitmap segment in the input file. Only the pixels under the bitmap are processed; the rest of the image remains unchanged.

If four values are specified, they define the x,y offsets and x,y dimensions of a rectangular window identifying the area to process. Xoffset, Yoffset define the upper-left starting pixel coordinates of the window. Xsize is the number of pixels that define the window width. Ysize is the number of lines that define the window height.

If no value is specified, the entire channel is processed.

ZERODIV

Specifies the value to use for the result of a denominator equal to zero.

If this parameter is not specified, this value defaults to the maximum possible value for the specified output channel.

FTYPE

The format of the output file. The format must be a GDB-recognized type.

Supported file formats include, among others:

PIX: PCIDSK format
TIF: Tagged Image File
JP2: JPEG 2000 format

The default value is PIX.

For a complete list of GDB-recognized file types, see GDB-supported file formats.

FOPTIONS

The file-creation options to apply on creating the output file. These are specific to the format of the file; in each case, the default of no options is allowed. You can specify the compression schemes, file-format subtypes, and other information.

Different options are available for each type, as described for the FTYPE parameter.

For a complete list of GDB-recognized file types, including the available options for each, see GDB-supported file formats.

MONITOR

The program progress can be monitored by printing the percentage of processing completed. A system parameter, MONITOR, controls this activity.

Available options are:

ON: Turns the monitor ON (default)
OFF: Turns the monitor OFF (recommended if running in batch or background mode)

Details

RTR calculates any pixel by pixel ratioing transformation of the following form:

 WNUM(1)*CNUM(1) + WNUM(2)*CNUM(2) + ... + WNUM(i)*CNUM(i) + NCON
 ----------------------------------------------------------------
 WDEN(1)*CDEN(1) + WDEN(2)*CDEN(2) + ... + WDEN(i)*CDEN(i) + DCON

where:

CNUM: a list of image channel numbers for the numerator
WNUM: a list of real weights for each numerator channel
NCON: a real additive constant for the numerator
CDEN: a list of image channel numbers for the denominator
WDEN: a list of real weights for each denominator channel
DCON: a real additive constant for the denominator

If weights (WNUM, WDEN) are not specified, they default to 1.0. If constants (NCON,DCON) are not specified, they default to 0. If denominator channels (CDEN) are not specified, the constant for ratio denominator defaults to 1.0.

Results of this function are saved to the specified output channel (DBOC).

The MASK parameter specifies the area within the input channel to be processed. Only the area specified under the mask is processed; the rest of the image is unchanged.

If a single value is specified, this value points to a bitmap segment that defines the area to be processed. (This is useful, for instance, for enhancing water data while leaving land data unchanged, by using a bitmap to mask all areas of water). When four values are specified, these values define the X and Y offsets and the X and Y dimensions of a rectangular window within the image to be processed.

Calculations are performed using real arithmetic. If the specified output channel is 8- or 16-bit, some loss of accuracy will occur. To help mitigate this, you can specify scaling options (SMOD).

Scaling

RTR performs ratioing transformation on 8-bit unsigned integer, 16-bit signed integer, 16-bit unsigned integer, and 32-bit real channels. These channels have the following ranges for data:

Type                               Min             Max

8-bit unsigned integer               0             255
16-bit signed integer           -32768           32767
16-bit unsigned integer              0           65535
32-bit real                     1.0E38         +1.0E38

Because the results of a ratioing transformation may be outside the range of values that the output channel can store, it is often necessary to scale the results for the output channel. You can control scaling using the SMOD (Scaling Method) parameter. This parameter provides the following scaling options:

NONE: no scaling is performed. If the resulting value is less or more than the output channel can hold, it will be set to the minimum or maximum, respectively, that the channel type can hold. This option is most commonly used if the output channel is 32-bit real.
AUTO: linear scaling is performed. This is accomplished by performing two passes on the data. The first pass is used to determine the minimum and maximum values resulting from the ratioing transformation. In the second pass, these values are used to linearly scale the results to the full range of the output channel.

Note: AUTO has no effect if the specified output channel is 32-bit real.
LOGS: logarithmic scaling is performed. This is accomplished by performing two passes on the data. The first pass is used to determine the minimum and maximum values resulting from the ratioing transformation. In the second pass, these values are used to logarithmically scale the results to the full range of the output channel.

Note: The output channel must be 8-bit data. If the output channel is 16-bit signed or unsigned integer, the function will fail.

Examples

Ratio channels one and two, and overwrite channel three with the result.

EASI>file	=	"filename"
EASI>cnum	=	1	! set up numerator
EASI>wnum	=	1
EASI>ncon	=	0
EASI>cden	=	2	! set up denominator
EASI>wden	=	1
EASI>dcon	=	0
EASI>filo    =       ""
EASI>dboc	=	3	! output channel
EASI>datatype =      ""
EASI>smod	=	"NONE"	! do not scale output
EASI>mask	=		! process entire image
EASI>zerodiv	=
EASI>FTYPE   =       ""
EASI>FOPTIONS =      ""

EASI>run RTR

Average the first four channels, and save results to channel 5.

EASI>file	=	"filename"
EASI>cnum	=	1,2,3,4	! set up numerator
EASI>wnum	=	
EASI>ncon	=	
EASI>cden	=	
EASI>wden	=	
EASI>dcon	=	4
EASI>filo    =
EASI>dboc	=	5	! output channel
EASI>datatype =
EASI>smod	=	"NONE"	! do not scale output
EASI>mask	=		! process entire image
EASI>zerodiv	=
EASI>ftype =
EASI>foptions =

EASI>run RTR

Calculate the transformed vegetative index:

                TM4 - TM3
 Square root of ---------
                TM4 + TM3

where TM3 and TM4 are Thematic Mapper bands 3 and 4 respectively. Assume TM3 and TM4 are on channels 3 and 4, that the output channel is 8, and unmentioned parameters are defaulted.

EASI>file	=	"filename"
EASI>cnum	=	3,4	! set up numerator
EASI>wnum	=	-1.1
EASI>ncon	=	
EASI>cden	=	3,4
EASI>wden	=	
EASI>dcon	=	
EASI>filo    =
EASI>dboc	=	8	! output channel
EASI>datatype =
EASI>smod	=	"NONE"	! do not scale output
EASI>mask	=		! process entire image
EASI>zerodiv	=
EASI>ftype   =
EASI>foptions =

EASI>run RTR

Use STR to calculate the square root of the output channel:

EASI>file	=	"filename"
EASI>dbic	=	8
EASI>dboc	=	8
EASI>expo	=	0.5	! (default enhancement)
EASI>dbsd = 
EASI>dbsn = 
EASI>istr = 
EASI>ostr = 
EASI>lctr = 
EASI>hctr = 
EASI>trim = 
EASI>mask = 
EASI>lasc = 

EASI>run STR


EASI>run LUT

Environments	PYTHON :: EASI :: MODELER
Quick links	Description :: Parameters :: Parameter descriptions :: Details :: Examples :: Related

RTR

Ratioing transformations

Description

Parameters

Parameter descriptions

Details

Examples