DATAMANIP commands


PROGRAM NAME

kappend - Append (or Prepend) Input Objects to Base Object

DESCRIPTION

The Append operator (kappend) combines all input data objects (i1 to i10) into a single output object (o). The objects are combined in order from Input 1 to Input 10. If the user specifies placement as "Prepend Objects to Base Object" (-append 0), then the first input will be the last appended to the output object. The dimension flags Width (w_flag), Height (h_flag), Depth (d_flag), Time (t_flag), and Elements (e_flag), specify which dimension the objects will be stacked along. For example, stacking two images along width would produce an output with the images side by side. One and only one of the dimension flags can be true.

Value Data All input objects must have value data. The value size of each input object will be zero-padded to the maximum of all sizes, except in the stacking dimension. The output size in the stacking dimension will be the sum of that dimension across all input objects. The output object data type will be the highest data type of the input data objects.

Map Data When some or all of the input objects have 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, (1) Use First Map Only, and (2) Create a Map for Each Input. If no input objects have maps, 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. The depth, time, and elements dimensions of that map must be 1, otherwise this mapping option will fail. Note that by selecting this mapping option, you are assuming that the value segments of all objects being appended have valid indices into that map.

Create a Map for Each Input: (All input objects may have maps.) For each input object that does not have a map, one will be created for it. The the output object color attributes will be copied from the first input object that has a map. New map values will be assigned using the autocolor attribute.

The map dimension corresponding to the stacking dimension (Depth, Time, or Elements) will reflect the new size of the value data in that dimension, and the maps from each object will be appended accordingly. The maximum width and height of all maps will be propagated to the output, with zero-padding being applied where necessary. Padding in the other map dimensions may occur as well. For example, if objects with the following map and value Depth sizes are being stacked along the Depth dimension,

		obj1  DEP=3  MAP_DEP = 3
		obj2  DEP=4  MAP_DEP = 1
		obj2  DEP=2  MAP_DEP = 2
the resulting value data will have a depth of 9, so the map depth will be 9 too. In this example, the second object's map will be zero-padded to have a map depth of four.

If the objects are being combined along the width or height dimensions, this mapping option will fail.

The output object map data type will be the highest of the input object map data types.

Mask Data If any input object has mask data, then the output object will also have mask data. The mask data will be resized in the same manner as value data is resized. The mask will be padded as valid (1). The highest data type of input masks will be propagated to the output mask.

Location and Time Data In all cases, the time and location data and/or attributes of the first input object will transferred to the output object. If location or time data is propagated, data values along the stacking dimension will not be changed, and therefore, the location or time data may become invalid.

REQUIRED ARGUMENTS

-i1
type: infile
desc: Base Input data object (input 1)
-o
type: outfile
desc: Resulting output data object

OPTIONAL ARGUMENTS

-i2
type: infile
desc: input file 2
default: {none}
-i3
type: infile
desc: input file 3
default: {none}
-i4
type: infile
desc: input file 4
default: {none}
-i5
type: infile
desc: input file 5
default: {none}
-i6
type: infile
desc: input file 6
default: {none}
-i7
type: infile
desc: input file 7
default: {none}
-i8
type: infile
desc: input file 8
default: {none}
-i9
type: infile
desc: input file 9
default: {none}
-i10
type: infile
desc: input file 10
default: {none}
-append
type: boolean
desc: If True, append objects to base, otherwise prepend
default: true
-mapping
type: list
desc: Defines map treatment when some, but not all, objects have maps
default: 0 "Map Data Thru Maps "

Mutually Exclusive Group; if desired, specify ONE of:

-w
type: flag
desc: Stack objects along width dimension
OR
-h
type: flag
desc: Stack objects along height dimension
OR
-d
type: flag
desc: Stack objects along depth dimension
OR
-t
type: flag
desc: Stack objects along time dimension
OR
-e
type: flag
desc: Stack objects along elements dimension

EXAMPLES

SEE ALSO

DATAMANIP::kinset

RESTRICTIONS

REFERENCES

COPYRIGHT

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