DATAMANIP commands


PROGRAM NAME

knormal - Normalize Data Regions Using Minimum & Maximum of Each Region

DESCRIPTION

The Normalize Data operator (knormal) normalizes all data within each specified region so that the minimum data value in that region will be equal to the Lower Value (lval) provided by the user, and the maximum data value in the region will be equal to the Upper Value (uval). If Predetermined Data Minimum (dmin) and Maximum (dmax) values are specified, these values will be used instead of scanning the data for minimum and maximum values. This eliminates an otherwise required pass through the data before the normalization operation.

Regions are defined by the settings of the Processing Unit options, which can be either the Whole Data Set (whole), or any combination of Width (w), Height (h), Depth (d), Time (t), and Elements (e). If none of these flags are supplied, then the default will be the whole data set.

If the source object contains value data and no map, normalization is performed on the value data. Likewise, if the source object contains map data and no value data, normalization is performed on the map. If the source object has both map and value data, certain region conditions must be met for the operation to succeed.

1. The first condition is that the normalization region must be defined by at least width and height.

2. If the map depth, time, and elements dimensions are all one, the normalization region must be the entire data set.

3. If the map depth, time, or elements dimensions are greater than 1, the corresponding dimension does not have to be part of the normalization region.

Output Data Type The Output Object Data Type (type) can also be specified. If "Propagate Input Type" is selected, the output data type will be the same as the input. If a different data type is selected, data is cast to that type after the transformation is calculated. Warning - casting to an unsigned type might result in wrap-around.

All internal processing is performed in double.

Validity Mask Currently, the validity mask is only transferred from the source to the destination object. The Masked Value Presentation attribute is used, so valid values can be substituted for invalid data (to explicitly set this attribute, use the Set Data Attribute (ksetdattr) operator in the Datamanip toolbox

As a future enhancement, invalid data will not be figured into the normalization calculations.

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

Failure Modes This program fails if the input object lacks both map data and value data.

REQUIRED ARGUMENTS

-i
type: infile
desc: Input data object
-o
type: outfile
desc: resulting data object

OPTIONAL ARGUMENTS

-lval
type: double
desc: Lower normalization value
default: 0
bounds: no range checking
-uval
type: double
desc: Upper normalization value
default: 255
bounds: no range checking
-type
type: list
desc: Data type of Output
default: 0 "Propagate Input Type"

Mutually Exclusive Group; if desired, specify ONE of:

-whole
type: flag
desc: normalize whole data set at one time
OR

AT LEAST ONE OF the Group:

-w
type: flag
desc: include width in normalization unit
AND/OR
-h
type: flag
desc: include height in normalization unit
AND/OR
-d
type: flag
desc: include depth in normalization unit
AND/OR
-t
type: flag
desc: include time in normalization unit
AND/OR
-e
type: flag
desc: include elements in normalization unit

Mutually Inclusive Group; if desired, specify ALL of:

-dmin
type: double
desc: If specified, this value used as data minimum
default: 0
bounds: no range checking
AND
-dmax
type: double
desc: If specified, this value used as data maximum
default: 0
bounds: no range checking

EXAMPLES

SEE ALSO

kconvert

RESTRICTIONS

Does not support complex input data types yet.

The validity mask is simply transferred from the input object to the output object. Invalid data will be included in the normalization calculations.

REFERENCES

COPYRIGHT

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