DATAMANIP commands


PROGRAM NAME

karith2 - Dual Operator Pointwise Arithmetic

DESCRIPTION

karith2 performs the operation specified by the operator flag (-add, -sub, etc.) between each point in Input 1 and either the corresponding point in Input 2 or the real (and imaginary) Constant values, which ever the user specifies. The karith2 operators are: Add, Subtract, Subtract From, Multiply, Divide, Divide Into, Power, Absolute Difference, Minimum, Maximum, Modulo, Hypotenuse, atan2, and ldexp.

Data Type - Single Input 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 Type - Two Input Objects 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 - 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 - Two 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 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.

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 values used to pad the data when input files are not the same size are determined by the operation. The default pad value of (0.0, 0.0) will be used for the Add (-add), Subtract (-sub), Subtract From (-subfrom), Absolute Difference (-absdiff), Minimum (-min), Maximum (-max), Hypotenuse (-hypot), and ldexp operations. The default pad value of (1.0, 0.0) will be used for the Multiply (-mul), Divide (-div), Divide Into (-divinto), Power (-pow), Modulo (-mod) and atan2 operations.

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.

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

AT LEAST ONE OF the Group:

-real
type: double
desc: Real constant value
default: 0
bounds: no range checking
AND/OR
-imag
type: double
desc: Imaginary constant value
default: 0
bounds: no range checking

Mutually Exclusive Group; you must specify ONE of:

-add
type: flag
desc: Add: o = i1 + (i2 or val)
OR
-hypot
type: flag
desc: Hypotenuse: o = sqrt(i1*i1 + (i2*i2* or val*val))
OR
-sub
type: flag
desc: Subtract: o = i1 - (i2 or val)
OR
-atan2
type: flag
desc: atan2: o = arc tangent (i1 / (i2 or val)
OR
-subfrom
type: flag
desc: Subtract From: o = (i2 or val) - i1
OR
-mul
type: flag
desc: Multiply: o = i1 * (i2 or val)
OR
-div
type: flag
desc: Divide: o = i1 / (i2 or val)
OR
-ldexp
type: flag
desc: ldexp: i1 * 2 ** (i2 or val)
OR
-divinto
type: flag
desc: Divide Into: o = (i2 or val) / i1
OR
-pow
type: flag
desc: Power: o = i1 raised to power of (i2 or val)
OR
-absdiff
type: flag
desc: Absolute Difference: o = | i1 - (i2 or val) |
OR
-min
type: flag
desc: Minimum: Returns lower value between i1 and (i2 or val)
OR
-max
type: flag
desc: Maximum: Returns higher value between i1 and (i2 or val)
OR
-mod
type: flag
desc: Modulus: o = remainder (i1/i2)

OPTIONAL ARGUMENTS

none

EXAMPLES

SEE ALSO

DATAMANIP::kabsdiff, DATAMANIP::kadd, DATAMANIP::katan2, DATAMANIP::kcube, DATAMANIP::kdeg2rad, DATAMANIP::kdiv, DATAMANIP::kdivinto, DATAMANIP::khypot, DATAMANIP::kldexp, DATAMANIP::kmaximum, DATAMANIP::kminimum, DATAMANIP::kmod, DATAMANIP::kmul, DATAMANIP::kpow, DATAMANIP::krad2deg, DATAMANIP::ksqr, DATAMANIP::ksub, DATAMANIP::ksubfrom

RESTRICTIONS

Operations on complex data are supported only for add, subtract, subtract from, multiply, divide, divide into, and power at this time. For other operations, if the input object is complex, only the real component of the data is processed, and the output object is real.

For additional complex operators, see DATAMANIP::kcmplx, DATAMANIP::kcmplx2real, DATAMANIP::kreal2cmplx, and the associated cantata pane objects (phase, magnitude, etc).

REFERENCES

COPYRIGHT

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