1.1.1.0 image.convolve2d

NRAO Home > CASA > CasaDocument

image.convolve2d - Function

1.1.1 Convolve image by a 2D kernel
Description

This function does Fourier-based convolution of an image file by the given 2D kernel.

If outfile is unset, the image is written to the specified disk file. If outfile is not given, the newly constructed on-the-fly Image tool is associated with a temporary image. This temporary image may be in memory or on disk, depending on its size. When you destroy the on-the-fly Image tool (with the done function) this temporary image is deleted.

You specify which 2 pixel axes of the image you wish to convolve via the axes argument.

You specify the type of convolution kernel with type (minimum match is active); currently only ’gaussian’ is available. With time others will be implemented.

You specify the parameters of the convolution kernel via the arguments major, minor, and pa. These arguments can be specified in one of three ways

Quantity - for example major=qa.quantity(1, ’arcsec’) Note that you can use pixel units, viz. major=qa.quantity(1, ’pix’), see below.
String - for example minor=’1km’ (i.e. one that the Quanta quantity function accepts).
Numeric - for example major=10. In this case, the units of major and minor are assumed to be in pixels. Using pixel units allows you to convolve unlike axes. For the position angle, units of degrees are assumed.

The interpretation of major and minor depends upon the kernel type.

Gaussian - major and minor are the Full Width at Half Maxiumum (FWHM) of the major and minor axes of the Gaussian.

The position angle is measured North through East when you convolve a plane holding a celestial coordinate (the usual astronomical convention). For other axis/coordinate combinations, a positive position angle is measured from +x to +y in the absolute pixel coordinate frame (x is the first axis that you specify with argument axes).

The scaling of the output image is determined by the argument scale. If you leave it unset, then autoscaling will be invoked.

If you are not convolving the sky, then autoscaling means that the convolution kernel will be normalized to have unit volume so as to conserve flux.

If you are convolving the sky, then there are two cases for which autoscaling is useful.

Firstly, if the input image units are Jy/pixel, then the output image will have units of Jy/beam and be appropriately scaled. In addition, the restoring beam of the output image will be the same as the convolution kernel.

Secondly,if the input image units are Jy/beam, then the output image will also have units of Jy/beam and be appropriately scaled. In addition, the restoring beam of the output image will be the convolution of the input image restoring beam and the convolution kernel.

If you do not leave scale unset, then the convolution kernel will be scaled by this value (it has peak unity before application of this scale factor).

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. Use function maskhandler if you need to copy other masks too.

See also the other convolution functions convolve, hanning, and sepconvolve.

Arguments


Inputs
outfile	Output image file name. Default is unset.
	allowed:	string
	Default:
axes	Axes to convolve. Default is [0,1].
	allowed:	intArray
	Default:	0 1
type	Type of convolution kernel
	allowed:	string
	Default:	gaussian
major	Major axis, Quantity, string, numeric. Must be specified.
	allowed:	any
	Default:	variant 0deg
minor	Minor axis, Quantity, string, numeric. Must be specified.
	allowed:	any
	Default:	variant 0deg
pa	Position Angle, Quantity, string, numeric. Default is 0deg.
	allowed:	any
	Default:	variant 0deg
scale	Scale factor. Default is autoscale.
	allowed:	double
	Default:	-1
region	Region of interest. Default is whole image.
	allowed:	any
	Default:	record
mask	OTF mask, Boolean LEL expression or mask region. Default is none.
	allowed:	any
	Default:	variant
overwrite	Overwrite (unprompted) pre-existing output file?
	allowed:	bool
	Default:	false
async	Run asynchronously?
	allowed:	bool
	Default:	false

Returns
casaimage

Example

"""
#
print "\t----\t convolve2d Ex 1 \t----"
ia.maketestimage(’xy’,overwrite=true)         # RA/DEC
im2 = ia.convolve2d(outfile=’xy.con’, axes=[0,1], type=’gauss’,
                    major=’20arcsec’, minor=’10arcsec’, pa=’45deg’,
                    overwrite=true);
im2.done()
ia.close()
#
ia.fromarray(outfile=’xypf’, pixels=ia.makearray(0, [64, 64, 4, 64]),
             overwrite=true)         # RA/DEC/Pol/Freq
print "!!!EXPECT WARNING REGARDING INVALID SPATIAL RESTORING BEAM!!!"
im2 = ia.convolve2d(outfile=’xypf.con’, axes=[0,3], type=’gauss’,
                    major=’20pix’, minor=’10pix’, pa=’45deg’,
                    overwrite=true);
im2.done()
ia.close()
#
"""

In the second example we must use pixel units because axes 0 and 3 (0-rel) are unlike.

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

Please send any comments or questions about CASA or AIPS++ to aips2-requests@nrao.edu

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