1.1.1.0 image.convolve

NRAO Home > CASA > CASA Toolkit Reference Manual

image.convolve - Function

1.1.1 Convolve image with an array or another image

Description

This function performs Fourier-based convolution of an image file by the given kernel.

If outfile is given, the image is written to the specified disk file. If outfile is left unset, the on-the-fly Image tool generated by this function is associated with a temporary image. This temporary image may be stored in memory or on disk, depending on its size. When the user destroys the generated Image tool (with the done function) this temporary image is deleted.

The kernel is provided as a multi-dimensional array or as the filename of a disk-based image file. The provided kernel can have fewer dimensions than the image being convolved. In this case, it will be padded with degenerate axes. An error will result if the kernel has more dimensions than the image. No additional scaling of the kernel is provided yet.

The scaling of the output image is determined by the argument scale. If this is left unset, then the kernel is normalized to unit sum. If scale is not left unset, then the convolution kernel will be scaled (multiplied) by this value.

Masked pixels will be assigned the value 0.0 before convolution.

The output mask is the combination (logical OR) of the default input pixel mask (if any) and the OTF mask. Any other input pixel masks will not be copied. The function maskhandler should be used if there is a need to copy other masks too.

See also the other convolution functions:

convolve2d, sepconvolve and hanning.

Arguments


Inputs
outfile	Output image file name. Default is unset.
	allowed:	string
	Default:
kernel	Convolution kernel - An array or an image filename. Must be specified by the user.
	allowed:	any
	Default:	variant
scale	Scale factor. The default behavior is to autoscale (specified with -1.0).
	allowed:	double
	Default:	-1.0
region	Region selection. See ”help par.region” for details. Default is to use the full image.
	allowed:	variant
	Default:	variant
mask	Mask to use. See help par.mask for more details. The default setting is none.
	allowed:	any
	Default:	variant
overwrite	Overwrite (unprompted) the pre-existing output file?
	allowed:	bool
	Default:	false
stretch	Stretch the mask if necessary and possible? See help par.stretch for more details.
	allowed:	bool
	Default:	false

Returns
image

Example

"""
#
print "\t----\t convolve Ex 1 \t----"
# This example presupposes the existence of an input image file, testdata, and a kernel image file, kerneldata.
# Open the input image file:
ia.open(infile=’testdata’)
# Set up a region to be operated upon (in this case, the whole image):
r1 = rg.box()
# Perform the convolution:
im2 = ia.convolve (outfile = ’convout’, overwrite = true, region = r1, kernel = ’kerneldata’)
ia.close()
im2.done()

#
print "\t----\t convolve Ex 2 \t----"
# This example uses an array as the convolution kernel, and presupposes the existence of an input image file, testdata, which we first open:
ia.open(infile=’testdata’)
# Next, create a Python array of some kind to use as a convolution kernel. For example:
from numpy import arange
kernelarray = arange(10)**3
# Set up a region to be operated upon (in this case, the whole image):
r1 = rg.box()
# Perform the convolution:
im3 = ia.convolve (outfile = ’convout2’, overwrite = true, region = r1, kernel = kernelarray)
ia.close()
im3.done()
#
"""

__________________________________________________________________

[next] [prev] [prev-tail] [front] [up]

More information about CASA may be found at the CASA web page

This code is available under the terms of the GNU General Public Lincense