1.1.1.0 image.convolve2d

NRAO Home > CASA > CASA Toolkit Reference Manual

image.convolve2d - Function

1.1.1 Convolve image by a 2D kernel

Description

This function performs Fourier-based convolution of an image file using the provided 2D kernel.

If outfile is left 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 stored in memory or on disk, depending on its size. When the user destroys the on-the-fly Image tool (with the done function) this temporary image is deleted.

The user specifies which 2 pixel axes of the image are to be convolved via the axes argument. The pixels must be square or an error will result.

The user specifies the type of convolution kernel with type (minimum match is supported); currently only ’gaussian’ is available.

The user specifies 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 pixel units can be used, 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 the user to convolve unlike axes (see one of the provided example for this use case). 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 Maximum (FWHM) of the major and minor axes of the Gaussian.

The position angle is measured North through East when a plane holding a celestial coordinate (the usual astronomical convention) is convolved. 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 is specified, with argument axes).

In the case of a Gaussian, the beam parameter offers an alternate way of describing the convolving Gaussian. If used, neither major, stfaf minor, nor pa can be specified. The beam parameter must have exactly three fields: ”major”, ”minor”, and ”pa” (or ”positionangle”). This is, not coincidentally, the record format for the output of ia.restoringbeam().

The scaling of the output image is determined by the argument scale. If this is left unset then autoscaling will be invoked.

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

If the user is 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. In the case of an image with per-plane beams, for each plane, the kernel is convolved with the appropriate beam and the result is associated with that plane in the output image.

If the user sets a value for scale, then the convolution kernel will be scaled by this value. Note that it has peak of unity before the application of this scale factor.

If the units on the original image include Jy/beam, the units on the output image will be rescaled by the ratio of the input and output beams as well as rescaling by the area of convolution kernel.

If the units on the original image include K, then only the image convolution kernel rescaling is done.

If targetres=True and type=”gaussian” and the input image has a restoring beam, this method will interpret the values of major, minor, and pa as the resolution of the final image and will calculate the parameters of the Gaussian to use in the convolution so that this target resolution is achieved.

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 can be used if there is a need to copy other masks too.

See also the other convolution functions:

convolve, hanning, and sepconvolve.

Arguments


Inputs
outfile	Output image file name. The default value is unset.
	allowed:	string
	Default:
axes	Axes to convolve. The default setting is [0,1].
	allowed:	intArray
	Default:	01
type	Type of convolution kernel to be used.
	allowed:	string
	Default:	gaussian
major	Major axis, Quantity, string, numeric (e.g. 10arcsec, 20pix, 3km, etc.). This must be specified by the user.
	allowed:	any
	Default:	variant 0deg
minor	Minor axis, Quantity, string, numeric (e.g. 10arcsec, 20pix, 3km, etc.). This must be specified by the user.
	allowed:	any
	Default:	variant 0deg
pa	Position Angle, Quantity, string, numeric (e.g. 10deg). The default value is 0deg.
	allowed:	any
	Default:	variant 0deg
scale	Scale factor. The default setting (-1) is to autoscale.
	allowed:	double
	Default:	-1
region	Region selection. Default is to use the full image.
	allowed:	any
	Default:
mask	Mask to use. The default option 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?
	allowed:	bool
	Default:	false
targetres	If True and type=”gaussian”, major, minor, and pa are interpreted as the image resolution that the user wants to achieve.
	allowed:	bool
	Default:	false
beam	Alternate way of describing a Gaussian. Must have fields ”major”, ”minor”, and ”pa” (or ”positionangle”)
	allowed:	record
	Default:

Returns
image

Example

"""
#
print "\t----\t convolve2d Ex 1 \t----"
ia.maketestimage(’xy’,overwrite=true)         # Create a simple RA/DEC test image
# Convolve axes 0 and 1 of the test image with a 20x10-arcsec, 45-degree Gaussian:
im2 = ia.convolve2d(outfile=’xy.con’, axes=[0,1], type=’gauss’,
                    major=’20arcsec’, minor=’10arcsec’, pa=’45deg’,
                    overwrite=true);
# Clean up, by destroying the im2 tool and close the image tool:
im2.done()
ia.close()
#

ia.fromarray(outfile=’xypf’, pixels=ia.makearray(0, [64, 64, 4, 64]),
             overwrite=true)         # Create a simple RA/DEC/Pol/Freq test dataset
print "!!!EXPECT WARNING REGARDING INVALID SPATIAL RESTORING BEAM!!!"
# Convolve axes 0 and 3 of the test dataset with a 20x10-pixel, 45-degree Gaussian:
im2 = ia.convolve2d(outfile=’xypf.con’, axes=[0,3], type=’gauss’,
                    major=’20pix’, minor=’10pix’, pa=’45deg’,
                    overwrite=true);
# Note that pixel units must be used in the above because axes 0 and 3 are unlike.
# Clean up, by destroying the im2 tool and close the image tool:
im2.done()
ia.close()
#
"""

__________________________________________________________________

[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