1.1.1.0 image.boxcar

NRAO Home > CASA > CASA Toolkit Reference Manual

image.boxcar - Function

1.1.1 Convolve one axis of image with a boxcar kernel

Description

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

z[i] = (y[i] + y[i+i] + ... + y[i+w])/w

where z[i] is the value at pixel i in the box car smoothed image, y[k] is the pixel value of the input image at pixel k, and w is a postivie integer representing the width of the boxcar in pixels. Both float and complex valued images are supported. The length of the axis along which the convolution is to occur must be at least w pixels in the selected region, unless decimation using the mean function is chosen in which case the axis length must be at least 2*w (see below). 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 (no decimation), the length of the output axis will be equal to the length of the input axis - w + 1. 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, if the specified boxcar width is 2, and if the pixel values, which are all unmasked, on a slice along this axis are [1, 2, 5, 10, 17, 26], then the corresponding output slice will be of length five and the output pixel values will be [1.5, 3.5, 7.5, 13.5, 21.5].

If drop=True and dmethod=”copy”, the output image is the image calculated if drop=True, except that only every wth plane is kept. Both the pixel and mask values of these planes are copied directly to the output image, without further processing. Thus for example, if the selected region in the input image has six planes along the convolution axis, the boxcar width is chosen to be 2, 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, 7.5, 21.5].

If drop=True and dmethod=”mean”, first the image described in the drop=False case is calculated. Then, the ith plane of the output image is calculated by averaging the i*w to the (i+1)*w-1 planes of this intermediate image. Thus, for example, if the selected region in the input image has six planes along the convolution axis, the boxcar width is chosen to be 2, and if the pixel values, which are all unmasked, on a slice along this axis are [1, 2, 5, 10, 17, 26], then the corresponding output pixel values will be [2.5, 10.5]. Any pixels at the end of the plane of the intermediate image that do not fall into a complete bin of width w are ignored. 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 intermediate image bin is not masked, the corresponding output pixel will not be masked.

The 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 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,

smoothedim = ia.boxcar(...)
# do things (or not) with smoothedim
...
# close the returned tool promptly upon finishing with it.
smoothedim.done()

Arguments


Inputs
outfile	Output image file name. Default is none.
	allowed:	string
	Default:
region	Region selection. Default is to use the full image.
	allowed:	any
	Default:	variant
mask	Mask to use. Default is none.
	allowed:	any
	Default:	variant
axis	Zero-based axis along which 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:	-1
width	Width of the boxcar in pixels.
	allowed:	int
	Default:	2
drop	Drop every nth pixel on output, where n is the width of the boxcar?
	allowed:	bool
	Default:	true
dmethod	If drop=True, method to use in plane decimation. ”copy”: direct copy of every second plane, ”m(ean)”: average planes ni through n(i+1) - 1 (inclusive) in the smoothed, non-decimated image to form plane i in the output image.
	allowed:	string
	Default:	copy
overwrite	Overwrite (unprompted) pre-existing output file?
	allowed:	bool
	Default:	false
stretch	Stretch the mask if necessary and possible? See help par.stretch. Default False
	allowed:	bool
	Default:	false

Returns
image

Example

ia.open("mynonsmoothed.im")
# smooth the spectral axis by 3 pixels, say it’s axis 2 and only
# write every other pixel
boxcar = ia.boxcar(outfile="myboxcarsmoothed.im", axis=2, drop=True,
width=3, dmethod="c" overwrite=True)
# done with input
ia.done()
# do something with the output image, get statistics say
stats = boxcar.statistics()
# close the result image
boxcar.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