DATAMANIP commands


PROGRAM NAME

kmegaclip - Clip the Range of Values in Data Object

DESCRIPTION

The MegaClip operator (kmegaclip) performs clipping on the Input data object (i), limiting the range of values in the object. Upper and lower cutoff values can be specified as either single constant values (lc, uc), or sets of values passed in as data objects (ilc, iuc). It is not necessary to specify both the Upper Cutoff and the Lower Cutoff.

All data values in the Input object that are LESS THAN the Lower Cutoff are set to the Lower Cutoff in the resulting Output object, unless the alternate "Lower Cutoff Output Value" (fval) is explicitly provided. If this value is provided, clipped data are set to that value instead of the Lower Cutoff. Likewise, data values GREATER THAN the Upper Cutoff are set to the Upper Cutoff, unless the alternate "Upper Cutoff Output Value" is explicitly provided. All other data remain the same.
Exception: Any time that both the upper and lower cutoff values are provided, and the upper cutoff is LESS THAN the lower cutoff, then data values between the two cutoffs are always set equal to the "Lower Cutoff Output Value" (fval).

The following four diagrams illustrate how the data is clipped for different combinations of upper and lower cutoffs. The plots are example data histograms. Clipping output assignment rules are given following the diagrams.

Lower Cutoff Only:


     lower cutoff result:       |<-F->|<----T---->|
                                |     | :     .   |
                                |    .:.:.  .:::  |
                                |:. .::::::.::::: |
                                |::::::::::::::::.|
                                ------|------------
                                      lower cutoff (lc)

if value < lc cutoff result = False if value >= lc cutoff result = True

Upper Cutoff Only:


        upper cutoff result:    |<----T---->|<-F->|
                                |       :   | .   |
                                |    .:.:.  .:::  |
                                |:. .::::::.::::: |
                                |::::::::::::::::.|
                                ------------|------
                                            upper cutoff (uc)

if value > uc cutoff result = False if value <= uc cutoff result = True

Upper Cutoff is Greater than Lower Cutoff: When both upper and lower cutoff values are specified, and the upper cutoff is GREATER THAN the lower cutoff, the combined cutoff result is the logical AND of the individual results.


        lower cutoff result:    |<-F->|<----T---->|
        upper cutoff result:    |<----T---->|<-F->|

combined cutoff result: |<-F->|<-T->|<-F->| | | : | . | | .:.:. .::: | |:. .::::::.::::: | |::::::::::::::::.| ------|-----|------ lc uc

if value < lc OR value > uc cutoff result = False if value >= lc AND value <= uc cutoff result = True

Upper Cutoff is Less than Lower Cutoff: When both upper and lower cutoff values are specified, but the upper cutoff is LESS THAN the lower cutoff, the combined cutoff result is the logical OR of the individual results. (Specifying the lower cutoff to be greater than the upper cutoff inverts the operation.) In this case, the false value assigned to the output will always be fval.


        upper cutoff result:    |<-T->|<----F---->|
        lower cutoff result:    |<----F---->|<-T->|

combined cutoff result: |<-T->|<-F->|<-T->| | | : | . | | .:.:. .::: | |:. .::::::.::::: | |::::::::::::::::.| ------|-----|------ uc lc

if value < lc AND value > uc cutoff result = False if value >= lc OR value <= uc cutoff result = True

Clipping results are assigned according to the following rules. ("Lower result" and "upper result" are either the clipping values or fval and tval - see discussion above.)

1. When lower cutoff < upper cutoff If the data value is less than the lower cutoff, set the output value to "lower result".

If the data value is greater than the upper cutoff, set the output value to "upper result".

Otherwise, the data value remains the same.

2. When upper cutoff < lower cutoff If the data value is less than the upper cutoff and it is greater than the lower cutoff, set output value to the "lower result".

Otherwise, the data value remains the same.

When upper and lower cutoff values are equal, the only data values that are evaluated as TRUE are those that are equal to the cutoff values.

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

Data Objects of Different Sizes If, in addition to the input data object (i), upper or lower cutoff objects (ilc, iuc) are supplied, the source objects can be of different sizes. If the sizes are different, the size of the destination object's data will be the the same as that of the input data object. When resizing the cutoff objects, the data is zero padded, or truncated to the size of the input object. Alignment between the input files will always be the upper-left hand corner, position (0,0,0,0,0).

Map Data - Single Input If the input object contains a map, then the operation is performed on the map data. If the input object does not have a map but has value data, then the operation is performed on the value data.

Map Data - Multiple Input Objects 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 - Single Input If there is a validity mask associated with the input object, the mask is transferred to the output object. To decrease processing time, the operation will still be performed on those data that have corresponding mask values equal to zero. If the data under the mask is genuinely fInotfP processable, such as NaN or infinity, the user can specify that a value be substituted in place of the original value when it is accessed. The masked data substitution attributes for a data object can be explicitly set and stored using the fISet AttributefP operator, DATAMANIP::ksetdattr.

Validity Mask - Multiple Input Objects If there is a validity mask associated with any of the input objects, the resulting output object will have a mask. The output object mask is the logical AND of the input object masks. If only one input object has a mask, then the other input object's mask is assumed to be "all valid" (mask value = 1). If a mask is resized for the operation, the mask padding value will be 1.

To decrease processing time, the operation will still be performed on data that have corresponding mask values equal to zero (invalid data). If the data under the mask is genuinely fInotfP processable, such as NaN or infinity, the user can specify that a value be substituted in place of the original value when it is accessed. The masked data substitution attributes for a data object can be explicitly set and stored using the fISet AttributefP operator, DATAMANIP::ksetdattr.

Explicit Location and Time Data - Single Input If the input object has time data or location data, it is transferred to the output object.

Explicit Location and Time Data - Two Input Objects 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 - Single Input This program fails if the input object lacks both map data and value data.

Failure Modes - Two Input Objects 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.

Executing MegaClip runs the program kclip with the -thresh option set to FALSE (-thresh 0).

REQUIRED ARGUMENTS

-i
type: infile
desc: Input file
-o
type: outfile
desc: output file

Group; you must specify AT LEAST ONE of:

ONE OF the Mutually Exclusive Group:

-lc
type: double
desc: Constant lower cutoff value
default: 64
bounds: no range checking
OR
-ilc
type: infile
desc: File containing lower cutoff values
default: {none}

ONE OF the Mutually Exclusive Group:

-uc
type: double
desc: Constant upper cutoff value
default: 128
bounds: no range checking
OR
-iuc
type: infile
desc: File containing upper cutoff values
default: {none}

OPTIONAL ARGUMENTS

-fval
type: double
desc: Output value if data is LESS THAN lower cutoff
default: 0
bounds: no range checking
-tval
type: double
desc: Output value if data is GREATER THAN upper cutoff
default: 1
bounds: no range checking

EXAMPLES

SEE ALSO

DATAMANIP::kclipabove, DATAMANIP::kclipbelow, DATAMANIP::kclipin, DATAMANIP::kclipout, DATAMANIP::kclip

RESTRICTIONS

REFERENCES

COPYRIGHT

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