1.1.1.0 image.collapse

NRAO Home > CASA > CASA Toolkit Reference Manual

image.collapse - Function

1.1.1 Collapse an image along a specified axis, computing a specified aggregate function of pixels along that axis.

Description

This method collapses an image along a specified axis or set of axes of length N pixels to a single pixel on each specified axis. Both float valued and complex valued images are supported. It computes a user-specified aggregate function for pixel values along the specified axes, and places those values in the single remaining plane of those axes in the output image. The method returns an image analysis tool containing the newly-created collapsed image. Valid choices of aggregate functions are: ’flux’ (see below for constraitns), ’max’, ’mean’, ’median’, ’min’, ’rms’, ’stdev’, ’sum’ and ’variance’. Minimal unique matching is supported for the function parameter (e.g. function = ’r’ will compute the rms of the pixel values, ’med’ will compute the median, etc.).

If one specifies function=’flux’, the following constraints must be true:

1. The image must have a direction coordinate, 2. The image must have at least one beam, 3. The specified axes must be exactly the direction coordinate axes, 4. Only one of the non-directional axes may be non-degenerate, 5. The iamge brightness unit must be conformant with x*yJy/beam, where x is an optional unit (such as km/s for moments images) and y is an optional SI prefix.

Axes may be specified as a single integer or an array of integers indicating the zero-based axes along which to collapse the image. Axes may also be specified as a single or array of strings which minimally and uniquely match (ignoring case) world axis names in the image (e.g. ’dec’ for collapsing along the declination axis or [’ri’, ’d’] for collapsing along both the right ascension and declination axes).

If outfile is not specified (or contains only whitespace characters), no image is written but the collapsed image is still accessible via the image analysis tool this method always returns (which references the collapsed image). If the returned object is not wanted, it should still be captured and destroyed via its done() method. If this is not done, there is no guarantee as to when the Python garbage collector will delete it. If the returned object is wanted, it should still be deleted as soon as possible for the same reasons, e.g.

collapsed_image = ia.collapse(...)

# do things (or not) with the collapsed_image and when finished working with the object, do

collapsed_image.done()

The reference pixel of the collapsed axis is set to 0 and its reference value is set to the mean of the the first and last values of that axis in the specified region of the input image. The reference value is the world coordinate value of the reference pixel. For instance, if an axis to be collapsed were to be the frequency axis, in the collapsed image, the reference value would be the mean value of the frequency range spanned, and would be stored in pixel 0.

If the input image has per plane beams, the beam at the origin of the subimage determined by the selected region is arbitrarily made the global beam of the output image. In general, the user should understand the pitfalls of collapsing images with multiple beams (i.e. that employing an aggregate function on pixels with varying beam sizes more often than not leads to ill-defined results). Convolution to a common beam is not performed automatically as part of the preprocessing before the actual rebinning occurs. In such cases, therefore, the user should probably first convolve the input image with a common restoring beam so that each plane has the same resolution, and/or use imsmooth to smooth the data to have the same beam.

Arguments


Inputs
function	Aggregate function to apply. This can be set one of flux, max, mean, median, min, rms, stdev, sum, variance. Must be specified.
	allowed:	string
	Default:
axes	Zero-based axis number (specified as a list or integer) along which to collapse the specified image. Default value is 0.
	allowed:	any
	Default:	variant 0
outfile	Output image file name. If left blank (the default), no image is written but a new image tool referencing the collapsed image is returned.
	allowed:	string
	Default:
region	Region selection. See ”help par.region” for details. Default is to use the full image.
	allowed:	any
	Default:	variant
box	Rectangular region to select in direction plane. See ”help par.box” for details. Default is to use the entire direction plane.
	allowed:	string
	Default:
chans	Channels to use. See ”help par.chans” for details. Channels must be contiguous. Default is to use all channels.
	allowed:	string
	Default:
stokes	Stokes planes to use. See ”help par.stokes” for details. Planes specified must be contiguous. Default is to use all Stokes planes.
	allowed:	string
	Default:
mask	Mask to use. See help par.mask for more details. Default setting is none.
	allowed:	string
	Default:
overwrite	Overwrite (unprompted) pre-existing output file? Ignored if ”outfile” is left blank.
	allowed:	bool
	Default:	false
stretch	Stretch the mask if necessary and possible? See help par.stretch. Default value is False.
	allowed:	bool
	Default:	false

Returns
image

Example

"""
# myimage.im is a 512x512x128x4 (ra,dec,freq,stokes) image
ia.open("myimage.im")
# collapse a subimage of it along its spectral axis avoiding the 8 edge
# channels at each end of the band, computing the mean value of the pixels
# resulting image is 256x256x1x4 in size.
collapsed = ia.collapse(outfile="collapse_spec_mean.im", function="mean", axes=2, box="127,127,383,383", chans="8~119")
# manipulate collapsed
collapsed.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