DATAMANIP commands


PROGRAM NAME

kextract - Extract Rectangular Region from Object

DESCRIPTION

The Extract Region operator (kextract) extracts a region of data from the source object Input (i) and places it in the destination object Output (o). The region size is specified by the Width (wsize), Height (hsize), Depth (dsize), Time (tsize), and Elements (esize) Region Size parameters. The region will be extracted starting at the point defined by the Region Origin parameters, Width (woff), Height (hoff), Depth (doff), Time (toff), and Elements (eoff). The datum at this starting point will be placed at the origin (0,0,0,0,0) in the destination object.

The output data object size for each dimension is determined first by the Region Size parameters if they are specified, and then by the Region Origin parameters in combination with the original source data size. In other words, if the size for a dimension is not selected on the graphical user interface (or explicitly specified when running kextract from the command line), all data on that dimension will be extracted, starting at the specified origin. This will ensure the following behavior. Given an input data file with dimensions (width=100, height=100, depth=10, time=1, elements = 1), and the following specified parameters:

Region Size: Width = 50, Height = 50
Region Origin: Width = 2, Height = 2, Depth = 2
the output object size will be (width=50, height=50, depth=8, time=1, elements = 1).

The extract operation is based on implicit indexing. This means that if location or time data exist, the extract operation is not done in terms an interpretation of the location/time data values, but in terms of the implicit indexing of these data (which is specified by the width, height, depth, time, elements indices of the polymorphic data model). This program can operate on any combination of value, mask, location and/or time data in the input object. Map data is unaffected by the extract operation.

If the Region Origin and/or the Region Size fall outside of the size of the input object, destination object value, location, and time data will be padded with zero, and mask data will be padded with one.

The subobject position attribute of a data object defines the coordinates at which that subobject is located in its parent data object. The "Record Region Origin" option (subpos) allows the extract operator to set the sub-object position attribute in the output object to the Region origin. If this option is set to "Yes", the subobject position of the output object will be set to (woff, hoff, doff, toff, eoff). If "Record Region Origin" is set to "No", the output subobject position is set to (0,0,0,0,0). Programs like the insert operator (kinsert) can use this attribute for automatically inserting the subregion back into the original after processing.

The subobject position attribute can also be explicitly set by using the Set Data Attributes operator (ksetdattr), and can be printed using the Print File Information operator (kfileinfo).

The destination object data types are the same as the source object data types.

REQUIRED ARGUMENTS

-i
type: infile
desc: Input object
-o
type: outfile
desc: Resulting output region

OPTIONAL ARGUMENTS

-wsize
type: integer
desc: Specifies the region width
default: 1
bounds: value > 0
-hsize
type: integer
desc: Specifies the region height
default: 1
bounds: value > 0
-dsize
type: integer
desc: Specifies the region depth
default: 1
bounds: value > 0
-tsize
type: integer
desc: Specifies the region size on time dimension
default: 1
bounds: value > 0
-esize
type: integer
desc: Specifies the region size on elements dimension
default: 1
bounds: value > 0
-woff
type: integer
desc: Specifies origin of region on width dimension
default: 0
bounds: no range checking
-hoff
type: integer
desc: Specifies origin of region on height dimension
default: 0
bounds: no range checking
-doff
type: integer
desc: Specifies origin of region on depth dimension
default: 0
bounds: no range checking
-toff
type: integer
desc: Specifies origin of region on time dimension
default: 0
bounds: no range checking
-eoff
type: integer
desc: Specifies origin of region on elements dimension
default: 0
bounds: no range checking
-subpos
type: boolean
desc: Record region origin (Subobject Position) in output
default: false

EXAMPLES

SEE ALSO

RESTRICTIONS

This program has not yet been updated to completely support the polymorphic data model.

REFERENCES

COPYRIGHT

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