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. 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 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 n*i 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()  

__________________________________________________________________


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