DATAMANIP commands


PROGRAM NAME

kgate - Based on Gating Input, Output Values Will Be From Input 1 or Input 2

DESCRIPTION

For each point in Input 1 (i1) and Input 2 (i2), kgate assigns to the Output (o) either the value from Input 1 or Input 2, depending on the corresponding value in the Gating Input (igate), the specified Gate Value (gval), and the gating logic (logic).

kgate can be used to gate many operations. The illustration below shows gating the addition of of two data objects. The result of the gating is that the second input is added to the first only for those pixels defined by the gate object. The data objects in the illustration are represented as 2x2 matrices. For example, Input 1 is a 2x2 data file with data values of 3, shown as


        3 3
        3 3
       Input1

To perform a gated addition, first add the objects using the Add operator (kadd). Next use the first data object as Input 1 (i1) to kgate, and the output of the addition operation as Input 2 (i2) to kgate. The third input to kgate is the gating object (igate). Using the default logic option (True) and Gate Value (0), the output will get the value of Input 2 any time that the value in the gate object is equal to the specified Gate Value (0). Otherwise, the output will get the value from Input 1.

Gated Addition Example:


                                      +------+
    3 3 ---+------------------------> |i1    |
    3 3    |    +------+              |   out| --- 3 8 
   Input1  +--> |i1    |    8 8 ----> |i2    |     8 3
                |   out|--- 8 8       |      |    Result
    5 5 ------> |i2    |         +--> |igate |
    5 5         +------+         |    +------+
   Input2         Add            |      Gate
                                 |
                          1 0 ---+
                          0 1
                      Gating Input

Gate Value The Gate Value (gval) is a constant that can be specified by the user. kgate will compare the elements of the Gate Object against this value, and will gate based on whether the values in the Gate Object are equal/unequal to the Gate Value. How the gating is applied depends on the Gating Logic (logic), described below.

Gating Logic TRUE When the Gating Logic is set to TRUE (ie. If value in Gating Input equals Gate Value, Output = Input 2), Input 1 is predominant, and is only gated when the gating condition is met. Therefore the Output will be assigned values from Input 1 unless the value in the Gating Input equals the specified Gate Value, in which case Input 1 is gated and the Output is assigned the value from Input 2.

Gating Logic FALSE When the Gating Logic is set to FALSE (ie. If value in Gating Input equals Gate Value, Output = Input 1), Input 2 is predominant, and is only gated when the gating condition is met. Therefore the Output will be assigned values from Input 2 unless the value in the Gating Input equals the specified Gate Value, in which case Input 2 is gated and the Output is assigned the value from Input 1.

Subobject Position If the Use Subobject Position option (subpos) is set to "Yes", then the subobject position of each object will be applied. This includes its use in calculating the output object size. See the "Input Objects of Different Sizes - Resizing & Padding" section below. The subobject position functionality can be disabled by setting this option to "No".

Data Type If the gate object is complex, only the real component will be used.

The data type of the output object's data is cast to the highest order data type of the input objects' data. Internally, the data is processed using one of the following: unsigned byte, long, unsigned long, double, or double complex. Data is not cast to a lower type for processing.

Map Data If any input object contains map data as well as value data, then the value data is mapped through the map before the operation is performed. The output object will contain value data with no associated map, and its data type is the highest of the input (map) data types.

Validity Mask If there is a validity mask associated with either source object, the destination object mask value will be assigned according to the same rules as apply to gating the value data.

Important: The Gating object may contain mask data or value data, but not both. If mask data is supplied in the gating object, it will be used only as gate values, and will not be propagated as a mask to the output object.

Input Objects of Different Sizes - Resizing & Padding The input objects can be of different sizes. If the sizes are different, the size of the output object's data will be the maximum of the data sizes of the input objects. When resizing, the input data are padded with a constant value that is defined internally by the operation being performed. If the input objects have map data as well as value data, the maximum data size is determined after mapping.

The subobject position for each source object that has value or mask data is used to determine the minimum common subobject position between them. This minimum position, along with the individual subobject positions, is used when calculating the final destination object size. Size and offsets are calculated so that the subobject positions of the source objects are aligned. These changes are applied before the operation is performed.

The resulting subobject position attribute of the destination object will be be the minimum common subobject position described above.

The subobject position attribute of a data object defines the coordinates at which that subobject was located in its parent data object. This attribute may be automatically set by programs such as the Extract operator (DATAMANIP::kextract), or it can be explicitly set by using the Set Data Attributes operator (DATAMANIP::ksetdattr). The subobject position coordinates can be printed using the Print File Information operator (DATAMANIP::kfileinfo).

Padding: If Input 1 and/or Input 2 are enlarged, the value and/or map data will be zero padded; masks will be padded with ones. If the gating object is enlarged, it will be padded with a value unequal to the gating value. Note that padding, not pixel replication, is performed by kgate. Therefore, if the user wants the gate to be replicated along certain dimensions, that operation must be performed before hand using the resampling operator (kresample).

Explicit Location and Time Data This routine does not interpret location or time data. Rather, it operates on the implicit data space defined by the organization of the data. Therefore, if more than one input object is supplied, and location or time data exist, the first input object will be the dominant object, and all attributes will be transferred from the first object to the output object (regardless of whether the other inputs have location or time data). Padding or truncation of explicit location data may occur if the resulting output object size is different from the size of input 1.

If the first input object does not contain location or time data, but another input object does contain it, the location or time data will not be propagated.

Failure Modes This program can only operate on input objects if all have value data (either or both can have optional map data) or if all fIonlyfP have map data.

REQUIRED ARGUMENTS

-i1
type: infile
desc: First input data object
-i2
type: infile
desc: Second input file object
-igate
type: infile
desc: Gating input data object
-o
type: outfile
desc: Resulting output data object

OPTIONAL ARGUMENTS

-logic
type: boolean
desc: Gating logic: if gate data = gval, (0) use i1, (1) use i2
default: true
-gval
type: double
desc: Value on which to gate
default: 0
bounds: no range checking
-subpos
type: boolean
desc: Use subobject position attribute
default: true

EXAMPLES

SEE ALSO

DATAMANIP::kblend

RESTRICTIONS

REFERENCES

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.