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:

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

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. See ”help par.region” for details. Default is to use the full image.

allowed:

any

Default:

mask

Mask to use. See help par.mask for more details. 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? See help par.stretch.

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()  
#  
"""  
 

__________________________________________________________________


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

Copyright 2016 Associated Universities Inc., Washington, D.C.

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


Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search