DATAMANIP commands


PROGRAM NAME

klinearop - Performs linear operations (convolution/correlation)

DESCRIPTION

klinearop performs convolution and correlation operations on a data object, using a specified kernel. These are both linear operations, thus the name klinearop.

In both cases, the operation can be essentially be viewed as moving a weighting mask (the kernel) over the data, performing a multiply-accumulate operation between the mask and the data under the mask, and storing the result in the output data. The weighting mask can have a specific location defined as the "center" or "hotspot"; when moving the mask around, this location will be placed directly on top of each data point in the input data, with the result stored in the corresponding location of the output data.

It is possible that when the kernel hotspot is positioned at certain locations (around the boundary of the input data) the kernel may partially extend outside the actual data. To handle this situation, it is common to pad the data with a specified value (often zero) so that those kernel weights that lie outside the actual data are multiplied by the pad value. The other alternative is to enforce circular (periodic) boundaries on the data (this is what an FFT does implicitly). Both boundary handling techniques are available in klinearop.

The difference between correlation and convolution is that correlation uses the kernel in exactly the orientation that it is handed to klinearop, while convolution uses a version of the kernel that is reversed or flipped along each of it's axes.

klinearop also has the ability to operate only on a specified region (called a subregion) of the input object. Data points in the output object that correspond to those in the specified subregion of the input object will be replaced with the value obtained by the linear operation. All other output data points will be copied directly from the corresponding input data points. Note that the boundary handling procedures will only affect data that lies near the edge of the input data array, not the edge of the subregion, unless the subregion includes areas near the edge of the input data.

The dimensionality of the linear operation is controlled by the dimensions of the kernel. For example, using a 5x1x1x1x1 kernel on a 512x512x1x20x1 input data object will cause a 1D operation to be done independently on each of the (512*20) rows in the input data. The size of the kernel must make sense; it is not likely that a kernel that is larger than the data in some direction will produce the correct result.

The multiply-accumulate operation is done in the higher of the kernel and data data types, unless the -upcast argument is given. In this case the data is cast to either DOUBLE or DCOMPLEX before processing, and the result will also be of that type. If the -upcast argument is not used, the result will be of the same data type as the input data.

Input objects with a map attached are mapped before processing; the output will have no map.

If either the input object or the kernel has mask data, then an error is returned since klinearop doesn't know how to handle those cases at this time.

A kernel, as referred to in this man page, is a small data object that has a sampled spatial impulse response (of the linear system you are modeling) stored in the value segment. Any data object of this type can be used as kernel. For images, it is common to create a kernel by typing the kernel values into an ASCII file as a 2D array in width and height and using that file directly as the kernel (thanks to data services). Kernels can also be created using xprism or any of the data generation programs. They can also be extracted directly from an existing image. There are several commonly used kernels in the SAMPLEDATA toolbox in $SAMPLEDATA/data/kernels.

Large data set handling is not explicitly done in klinearop. The data is processed by regions where the size of a region is controlled by the kernel and data region dimensions: The processing region dimensions are of size 1 for each direction that the kernel is of size 1, and the size if the data region for all other directions. Thus for the previous example of using a 5x1x1x1x1 kernel on a 512x512x1x20x1 input data object, with the whole data object selected for convolution (or correlation), the data will be processed in 512x1x1x1x1 chunks. If the kernel were 5x1x1x5x1, then the data would be processed in chunks of 512x1x1x20x1. Processing of large data sets is thus limited to the maximum "chunk size" that can reasonable be kept in memory. For example, using a 7x7x7x7x1 kernel on a 512x512x16x256x3 data object would require a processing region of size (512*512*16*256) double floats, around 8192MB. It is clear that you would want to do something with the kernel here; possibly break it down into separable parts that can be convolved independently. Removing this restriction on large data set handling is a topic for future work.

REQUIRED ARGUMENTS

-i1
type: infile
desc: Input object
-i2
type: infile
desc: Input kernel
-o
type: outfile
desc: output object

Mutually Exclusive Group; you must specify ONE of:

ALL OF the Mutually Inclusive Group:

-l
type: flag
desc: If flag is set, handle boundaries by padding
AND
-real
type: double
desc: Real part of pad constant
default: 0
bounds: no range checking
AND
-imag
type: double
desc: Imaginary part of pad constant
default: 0
bounds: no range checking

-c
type: flag
desc: If flag is set, handle boundaries by wrapping

OPTIONAL ARGUMENTS

-corr
type: boolean
desc: Select correlation (default) or convolution
default: false
-upcast
type: flag
desc: Upcast data to double or double complex for processing
-wc
type: integer
desc: Width coordinate of kernel hotspot
default: 0
bounds: value >= 0
-hc
type: integer
desc: Height coordinate of kernel hotspot
default: 0
bounds: value >= 0
-dc
type: integer
desc: Depth coordinate of kernel hotspot
default: 0
bounds: value >= 0
-tc
type: integer
desc: Time coordinate of kernel hotspot
default: 0
bounds: value >= 0
-ec
type: integer
desc: Element coordinate of kernel hotspot
default: 0
bounds: value >= 0
-woff
type: integer
desc: Width offset for subregion
default: 0
bounds: no range checking
-hsize
type: integer
desc: Height size for subregion
default: 1
bounds: value > 0
-hoff
type: integer
desc: Height offset for subregion
default: 0
bounds: no range checking
-wsize
type: integer
desc: Width size for subregion
default: 1
bounds: value > 0
-doff
type: integer
desc: Depth offset for subregion
default: 0
bounds: no range checking
-dsize
type: integer
desc: Depth size for subregion
default: 1
bounds: value > 0
-toff
type: integer
desc: Time offset for subregion
default: 0
bounds: no range checking
-tsize
type: integer
desc: Time size for subregion
default: 1
bounds: value > 0
-eoff
type: integer
desc: Elements offset for subregion
default: 0
bounds: no range checking
-esize
type: integer
desc: Elements size for subregion
default: 1
bounds: value > 0

EXAMPLES

Convolution between input_image, and kernel_image, with offset (0,0), pad 
value 0 for the real part and 0 for the imaginary part is:

klinearop -i1 input_image -i2 kernel_image -o output_image -corr 0 -l -real 0 -imag 0

SEE ALSO

kfft(1)

RESTRICTIONS

Large data set handling can be strange; see the above discussion.

REFERENCES

1) FUNDAMENTALS OF IMAGE PROCESSING by A. K. Jain, Prentice Hall, 1989.
2) DIGITAL IMAGE PROCESSING by Rafael C. Gonzalez and Richard E. Woods, Addison Wesley, 1992.
3) DIGITAL IMAGE PROCESSING, 2nd. Ed., by William K. Pratt, Wiley, 1991.
4) MULTIDIMENSIONAL DIGITAL SIGNAL PROCESSING, by Dan E. Dudgeon and Russell M. Mersereau, Prentice Hall, 1984.
5) DISCRETE-TIME SIGNAL PROCESSING, by Alan V. Oppenheim and Ronald W. Schafer, Prentice Hall, 1989.
6) TWO-DIMENSIONAL SIGNAL AND IMAGE PROCESSING, by Jae S. Lim, Prentice Hall, 1990.

COPYRIGHT

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