DATAMANIP commands


PROGRAM NAME

kcompare - Comparison Operators

DESCRIPTION

The kcompare operator compares each point in Input 1 either with the corresponding point in Input 2 or with the Constant value (real), which ever is specified by the user. If the two values satisfy the condition flag passed in,
	Equal (eq) 
	Greater Than or Equal (ge)
	Greater Than (gt) 
	Less Than of Equal (le) 
	Less Than (lt)
	Not Equal (ne)
the corresponding point in Output will be assigned the value specified by TRUE Value (tval). It the values being compared do not satisfy the condition, the corresponding point in the output object will be the FALSE Value (fval).

If a non-zero Tolerance (tol) is specified, the two values being compared can be within this range of one another and still satisfy the comparison. The tolerance feature is not implemented at this time.

Output Data Type The output data type is generally the higher data type of the input objects (or simply the type of the input object if only a single object is supplied). A difficulty arises, however, given that tval and fval are not constrained to be the same data type as the input objects and may not lie within the range of representable numbers for the output data type. This is particularly a problem if signed output values are to be used with unsigned input objects.

This problem is handled by upgrading the output data type to signed if the input objects are unsiged and the output values are signed. For KUBYTE inputs used with signed output values, the output is forced to KSHORT (this is a special case, done to provide better range than KBYTE would allow).

If the input is of type KBIT, then the output will also be KBIT only if the output values lie in the range [0..1]. If the output values lie outside that range then the output type will be KBYTE.

Map Data The comparison operations have not been written to be fully polymorphic yet. They does not check for map data, and will therefore always operate on the value data, even if a map exists. This will most likely corrupt indexing into the map.

In the case of a single input, it is recommended to use the Copy to Value (kcptoval) segment operator to temporarily move the map data into the value segment, run the operator on the data, then move it back to the map with the Copy from Value (kcpfromval) operator.

When operating with two input objects, where at least one of the objects contains map data, data should be mapped prior to running the comparison operator. The Map Data operator (kmapdata) can be used to perform the mapping operation.

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 - Two Input Objects Masking has not been implemented yet for the comparison operators. Therefore, only the mask from the first input object will be transferred to the output.

Input Objects of Different Sizes 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).

The value used to pad the data when the input files are not the same size is zero.

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 The comparison operations have not been extended to understand location and time data. Therefore, only location and time data present in the first input object will be transferred to the output.

REQUIRED ARGUMENTS

-i1
type: infile
desc: first input data object
-o
type: outfile
desc: resulting output data object

Mutually Exclusive Group; you must specify ONE of:

-i2
type: infile
desc: second input data object
default: {none}
OR
-real
type: double
desc: constant value
default: 1
bounds: value >= 0.0

Mutually Exclusive Group; you must specify ONE of:

-eq
type: flag
desc: Equal: if i1 == (i2 or val), i1 = TRUE
OR
-ne
type: flag
desc: Not Equal: if i1 != (i2 or val), i1 = TRUE
OR
-gt
type: flag
desc: Greater Than: if i1 > (i2 or val), i1 = TRUE
OR
-ge
type: flag
desc: Greater Than or Equal: if i1 >= (i2 or val), i1 = TRUE
OR
-lt
type: flag
desc: Less Than: if i1 < (i2 or val), i1 = TRUE
OR
-le
type: flag
desc: Less Than or Equal: if i1 <= (i2 or val), i1 = TRUE

OPTIONAL ARGUMENTS

-tol
type: double
desc: Tolerance
default: 0
bounds: no range checking
-tval
type: double
desc: Value assigned to output if evaluation is TRUE
default: 1
bounds: no range checking
-fval
type: double
desc: Value assigned to output if evaluation is FALSE
default: 0
bounds: no range checking

EXAMPLES

SEE ALSO

RESTRICTIONS

This routine is still under development, and has not been modified to fully support the polymorphic data model. See paragraphs above for discussions concerning the polymorphic data segments.

Tolerance is not implemented

REFERENCES

COPYRIGHT

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