Clipping When clipping is enabled (-thresh 0), the values in the object are clipped within the range specified by the upper and/or lower cutoff limits. In the default mode (where neither fval nor tval are selected) data values above the upper cutoff are set equal to the upper cutoff, and values below the lower cutoff are set equal to the lower cutoff value. If the fval parameter is provided, then data values below the lower cutoff are set to fval. If the tval parameter is provided, data values greater than the upper cutoff are set to that value. 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 fval.
Thresholding If thresholding is enabled (-thresh 1), thresholding is performed using the specified lower and upper cutoff values, creating a two-level output data object. It is not necessary to specify both of the upper and lower cutoff values. If only the lower cutoff is specified, all values above it are in the threshold range. If only the upper cutoff is specified, all values below it are in the threshold range. The true value (tval) is assigned to values that are within the threshold range, and all values outside of the threshold range are set to fval.
The following four diagrams illustrate how the given operation is evaluated for different combinations of upper and lower cutoffs. The plots are example data histograms. Clipping and threshold 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 for both clipping and thresholding.
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.
Thresholding results are assigned according to the following rules.
1. When lower cutoff < upper cutoff If the data value is less than the lower cutoff, or it is greater than the upper cutoff, set the output value to fval.
Otherwise, set the output value to tval.
2. When upper cutoff < lower cutoff If the data value is less than the lower cutoff and it is greater than the upper cutoff, set output value to fval.
Otherwise, set the output value to tval.
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.
Group; you must specify AT LEAST ONE of:
ONE OF the Mutually Exclusive Group:
OR
ONE OF the Mutually Exclusive Group:
OR
kclip -thresh 1 -i image:ball -lc 128 -uc 202 -tval 12 -fval 0 -o thresh.outcauses all pixels between the values on 128 and 202 (inclusively) to have a value of 12 in the output image. All other output image pixels have the value of zero.
kclip -i full_range.viff -uc 123 -lc 17 -o restricted_range.viff
Limits the range of values in the input file full_range.viff to 17...123 and writes the result to restricted_range.viff.