DATAMANIP commands


PROGRAM NAME

ksegcmp - Compare Attributes & Data of Input 1 and Input 2

DESCRIPTION

ksegcmp compares the data and attributes between two input data objects, (i1) and (i2), and prints their differences. The data within the specified data segments is compared point by point, allowing for precise comparisons of data objects independent of file format or machine architecture.

The user can specify either that all of the data segments contained in both objects be compared, or that only specific data segments be compared. The specific polymorphic segments value (val), mask (mask), location (location), time (time), and map (map) can be called out for comparison, along with an user-specified segment name (segment).

The comparison of two segments can only be performed if the segments are of the same size and dimensionality. If the data types of the two segments differ, the user can specify that the data be compared in the higher of the two data types (cast). Additionally, a +/- comparison tolerance can be specified (t). For complex comparisons, this tolerance is applied to both the real and imaginary parts of the values.

If desired, the attributes of each segment can be compared (sat). The segment attributes such as size, dimension, and data type, are not compared by here since they would have already been compared during the data comparison. Also if desired, the object-level attributes, such as the comment, can be compared (oat). The date attribute is ignored in this comparison since it is almost always different.

The program will print the results of the comparison in ASCII either to an user-specified file (o) or, if no file is specified, to kstdout.

The program can optionally print a summary of the differences it finds between each data segment (psum). The program can also optionally print a detailed report on the specific differences found in each segment. At the very minimum, a simple one line report on whether the data objects were determined to be different or identical will be printed. If no output at all is desired, the program can told to run silently (s).

The summary printed for each compared segment reports such things as differences in size or data type, as well as the number of points that were determined to be different.

The precise report of the specific points that were found to be different between two data segments will be printed in the following format :

[POSITION]

< Input #1 Value (Input #1 Data Type)

> Input #2 Value (Input #2 Data Type)

The user may specify which components of this precise report are printed with the use of different flags. The position (pos), the value at that position in the segment from input 1 (i1val), the value at that position in the segment from input 2 (i2val), along with the data types of the values (i1type) and (i2type) can all be specified to be in the detailed report. Note that this program does not allow for the data types of either segment to be printed without their values, because that provides no information.

If desired, the exit return status of the program can be set to indicate whether the data objects were determined to be different or identical (rt). A KEXIT_SUCCESS (0) exit status is used to indicate that the objects were identical, while a KEXIT_FAILURE (1) exit status is used to indicate that they are different.

Also if desired, this routine can return the exit status to a Cantata variable for use in conditional visual programming operations (var).

The comparison is performed "intelligently" using data services, so that that the entire data set from either data object is never read into memory at one time. This allows very large data objects to be compared on machines with limited virtual memory.

REQUIRED ARGUMENTS

-i1
type: infile
desc: first input data object
-i2
type: infile
desc: second input data object

OPTIONAL ARGUMENTS

-cast
type: flag
desc: cast data to common type before comparing
-tol
type: double
desc: tolerance for data comparison
default: 0
bounds: no range checking
-sat
type: boolean
desc: compare segment level attributes
default: false
-oat
type: boolean
desc: compare object level attributes
default: false
-s
type: flag
desc: silent running - do not print to stdout
-psum
type: boolean
desc: print difference summary
default: true
-pos
type: flag
desc: print the position of differing points
-i1val
type: flag
desc: print value from first input for differing points
-i1type
type: flag
desc: print data type of first input for differing points
-i2val
type: flag
desc: print value from second input for differing points
-i2type
type: flag
desc: print data type of second input for differing points
-o
type: outfile
desc: output ASCII file for summary
default: {none}
-rt
type: boolean
desc: return results as exit status
default: true
-var
type: string
desc: return results to Cantata
default: equal

Mutually Exclusive Group; if desired, specify ONE of:

-all
type: flag
desc: compare all data segments
OR

AT LEAST ONE OF the Group:

-val
type: flag
desc: compare value segments
AND/OR
-mask
type: flag
desc: compare mask segments
AND/OR
-loc
type: flag
desc: compare location segments
AND/OR
-time
type: flag
desc: compare time segments
AND/OR
-map
type: flag
desc: compare map segments
AND/OR
-segment
type: string
desc: explicit segment name to compare
default: value

EXAMPLES

ksegcmp -i1 image:ball -i2 image:moon -val -t 220 -pos -i1val -i2val

will compare the value segment of the ball image with the value segment of the moon image with a comparison tolerance of +/- 220.0. The position and values of the eight points that are different will be printed.

SEE ALSO

kcpseg, kcptoval, kcpfromval

RESTRICTIONS

ksegcmp is not yet able to return a variable to Cantata. The segment list when all segments are compared is constructed from the first input object. If the second object contains segments which are not contained in the first object, the comparison will miss them.

REFERENCES

none

COPYRIGHT

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