NRAO Home > CASA > CASA Toolkit Reference Manual
##### image.hanning - Function

1.1.1 Convolve one axis of image with a Hanning kernel

Description

This application performs Hanning convolution of one axis of an image defined by

z[i] = 0.25*y[i-1] + 0.5*y[i] + 0.25*y[i+1] (equation 1)

where z[i] is the value at pixel i in the hanning smoothed image, and y[i-1], y[i], and y[i+1] are the values of the input image at pixels i-1, i, and i+1 respectively. It supports both float and complex valued images. The length of the axis along which the convolution is to occur must be at least three pixels in the selected region. Masked pixel values are set to zero prior to convolution. All nondefault pixel masks are ignored during the calculation.

The convolution is done in the image domain (i.e., not with an FFT).

If drop=False, the length of the output axis will be the same as that of the input axis. The output pixel values along the convolution axis will be related to those of the input values according to equation 1, except the first and last pixels. In that case,

z = 0.5*(y + y)

and,

z[N-1] = 0.5*(y[N-2] + y[N-1])

where N is the number of pixels along the convolution aixs. The pixel mask, ORed with the OTF mask if specified, is copied from the selected region of the input image to the output image. Thus for example, if the selected region in the input image has six planes along the convolution axis, and if the pixel values, which are all unmasked, on a slice along this axis are [1, 2, 5, 10, 17, 26], the corresponding output pixel values will be [1.5, 2.5, 5.5, 10.5, 17.5, 21.5].

If drop=True and dmethod=”copy”, the output image is the image calculated if drop=True, except that only the odd-numbered planes are kept. Furthermore, if the number of planes along the convolution axis in the selected region of the input image is even, the last odd number plane is also discarded. Thus, if the selected region has N pixels along the convolution axis in the input image, along the convolution axis the output image will have (N-1)/2 planes if N is odd, or (N-2)/2 planes if N is even. In this case, the pixel and mask values are copied directly, without further processing. Thus for example, if the selected region in the input image has six planes along the convolution axis, and if the pixel values, which are all unmasked, on a slice along this axis are [1, 2, 5, 10, 17, 26], the corresponding output pixel values will be [2.5, 10.5].

If drop=True and dmethod=”mean”, first the image described in the drop=False case is calculated. The first plane and last plane(s) of that image are then discarded as described in the drop=True, dmethod=”copy” case. Then, the ith plane of the output image is calculated by averaging the (2*i)th and (2*i + 1)th planes of the intermediate image.Thus for example, if the selected region in the input image has six planes along the convolution axis, and if the pixel values, which are all unmasked, on a slice along this axis are [1, 2, 5, 10, 17, 26], the corresponding output pixel values will be [4.0, 14.0]. Masked values are taken into consideration when forming this average, so if one of the values is masked, it is not used in the average. If at least one of the values in the input pair is not masked, the corresponding output pixel will not be masked.

The hanning smoothed image is written to disk with name outfile, if specified. If not, no image is written but the image is still accessible via the returned image analysis tool (see below).

This method always returns an image analysis tool which is attached to the hanning smoothed image. This tool should always be captured and closed after any desired manipulations have been done. Closing the tool frees up system resources (eg memory), eg,

hanning_image = ia.hanning(...)

# do things (or not) with hanning_image
...
# close the returned tool promptly upon finishing with it.

hanning_image.done()

Arguments

 Inputs outfile Output image file name. Default is unset. allowed: string Default: region Region selection. See ”help par.region” for details. Default is to use the full image. allowed: any Default: variant mask Mask to use. See help par.mask. Default is none. allowed: any Default: variant axis Zero based axis to convolve. ia.coordsys().names() gives the order of the axes in the image. Less than 0 means use the spectral axis if there is one, if not an exception is thrown. allowed: int Default: -10 drop Drop every other pixel on output? allowed: bool Default: true overwrite Overwrite (unprompted) pre-existing output file? allowed: bool Default: false async Run asynchronously? allowed: bool Default: false stretch Stretch the mask if necessary and possible? See help par.stretch. Default False allowed: bool Default: false dmethod If drop=True, method to use in plane decimation. ”c(opy)”: direct copy of every second plane, ”m(ean)”: average planes 2*i and 2*i+1 in the smoothed, non-decimated image to form plane i in the output image. allowed: string Default: copy
Returns
image

Example

ia.open("mynonsmoothed.im")
# smooth the spectral axis, say it’s axis 2 and only write every other pixel
hanning = ia.hanning(outfile="myhanningsmoothed.im", axis=2, drop=True, overwrite=True)
# done with input
ia.done()
# do something with the output image, get statistics say
stats = hanning.statistics()
# close the result image
hanning.done()

__________________________________________________________________