DATAMANIP commands


PROGRAM NAME

kinset - Inset Object 2 into Object 1

DESCRIPTION

The Inset operator, kinset, insets data from Input 2 (i2) into Input 1 (i1) at the specified position, replacing the data in Input 1. The resulting Output object (o) size will be at least the size of Input 1, and may be larger, depending on the specified position values and the size of Input 2.

If Input 2 has a mask, an "Only Inset VALID Data" (insetvalid) parameter can be set to define whether only data from Input 2 that is marked as valid by the validity mask is inset into Input 1. If this parameter is set to FALSE (-insetvalid 0), all value data and the mask from Input 2 are inset into Input 1. If the parameter is TRUE (-insetvalid 1), for each point in Input 2, the mask is checked, and only valid points are inset into Input 1. In this case, the mask from Input 2 is not propagated to the output.

The inset operation is based on implicit indexing. This means that if location or time data exist, the inset 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).

The position in Input 1 where the origin of Input 2 will be placed can be determined from the Sub-Object Position attribute that is stored in Input 2, or it can be specified explicitly by providing Width, Height, Depth, Time and Element Coordinates (w,h,d,t,e). The subobject position attribute is automatically set by programs such as the Extract operator (kextract). It is legal to specify a subset of coordinates, and let the subobject position attribute define the rest of the coordinates.

In some instances, padding is necessary to maintain the integrity of the polymorphic data model - for example when the final size of the Output object is larger than that of Input 1. The Real and Imaginary Pad Values (real, imag) define the values that will be used when padding.

If padding occurs, and the option to "Identify padded data added by this program as Valid" is selected (valid TRUE), all padded data is considered valid and, if either input object contains a validity mask, the output object will have a mask, and the mask value for the padded data will be 1. The output object will not contain a mask if neither input object has a mask. If padded data is to be identified as Invalid (valid FALSE), the padded data will be masked as invalid (0). In this case, even if neither input object has a validity mask, the output object will have one.

Map Data When either of the input objects has map data, the treatment of the maps, and how the data is represented in the output object, depends on the mapping option (mapping) specified by the user. Possible mapping options are: (0) Map Data Thru Maps and (1) Use First Map Only. If neither input object has a map, the mapping option is ignored. If there are doubts about which mapping option to use, the safest bet is to map the data thru the maps.

Map Data Thru Maps: All data will be mapped before the data objects are combined. The output object will not have a map.

Use First Map Only: In this case, the map data and color attributes of the first input object that has a map are directly transferred to the output object. Note that by selecting this mapping option, you are assuming that the value segments of both objects have valid indices into that map.

Data Type 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.

Location & Time Data 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 This program will fail if either input object lacks value data.

REQUIRED ARGUMENTS

-i1
type: infile
desc: Base input image
-i2
type: infile
desc: Second (inset) input image
-o
type: outfile
desc: Resulting output object

OPTIONAL ARGUMENTS

-insetvalid
type: boolean
desc: If Object has Mask, Only Inset VALID DataIf
default: true
-real
type: double
desc: Real constant pad level
default: 0
bounds: no range checking
-imag
type: double
desc: Imaginary constant pad level
default: 0
bounds: no range checking
-padvalid
type: boolean
desc: Identify padded data added by this program as valid or invalid in mask
default: true
-mapping
type: list
desc: Defines map treatment when some, but not all, objects have maps
default: 0 "Map Data Thru Maps "

Group; specify AT LEAST ONE of:

-attr
type: flag
desc: Insert at i2 subobject position (attribute) - w,h,d,t,e will override if specified
AND/OR
-woff
type: integer
desc: Insert region beginning at this width coordinate
default: 0
bounds: no range checking
AND/OR
-hoff
type: integer
desc: Insert region beginning at this height coordinate
default: 0
bounds: no range checking
AND/OR
-doff
type: integer
desc: Insert region beginning at this depth coordinate
default: 0
bounds: no range checking
AND/OR
-toff
type: integer
desc: Insert region beginning at this time coordinate
default: 0
bounds: no range checking
AND/OR
-eoff
type: integer
desc: Insert region beginning at this element coordinate
default: 0
bounds: no range checking

EXAMPLES

SEE ALSO

DATAMANIP::kappend
DATAMANIP::kextract

RESTRICTIONS

REFERENCES

COPYRIGHT

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