1.1.1.0 image.subimage

NRAO Home > CASA > CASA Toolkit Reference Manual

image.subimage - Function

1.1.1 Create a (sub)image from a region of the image

Description

This function copies all or part of the image to another on-the-fly Image tool. Both float and complex valued images are supported.

If outfile is given, the subimage is written to the specified disk file. If outfile is unset, the returned Image tool actually references the input image file (i.e. that associated with the Image tool to which you are applying this function). So if you deleted the input image disk file, it would render this tool useless. When you destroy this tool (with the done function) the reference connection is broken.

Sometimes it is useful to drop axes of length one (degenerate axes). Use the dropdeg argument if you want to do this. Further control is provided via the keepaxes parameter. If dropdeg=True, you may specify a list of degenerate axes to keep in the keep axes parameter. This allows you to drop only a subset of degenerate axes. This parameter is ignored if dropdeg=False. If dropdeg=True, all degenerate axes are dropped if keepaxes is set to an empty list (this is the default behavior). Nondegenerate axes are implicitly kept, even if they are included in the keepaxes list.

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. Use function maskhandler if you need to copy other masks too.

If the mask has fewer dimensions than the image and if the shape of the dimensions the mask and image have in common are the same, the mask will automatically have the missing dimensions added so it conforms to the image.

If stretch is true and if the number of mask dimensions is less than or equal to the number of image dimensions and some axes in the mask are degenerate while the corresponding axes in the image are not, the mask will be stetched in the degenerate dimensions. For example, if the input image has shape [100, 200, 10] and the input mask has shape [100, 200, 1] and stretch is true, the mask will be stretched along the third dimension to shape [100, 200, 10]. However if the mask is shape [100, 200, 2], stretching is not possible and an error will result.

Arguments


Inputs
outfile	Output image file name. Default is unset.
	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
dropdeg	Drop degenerate axes
	allowed:	bool
	Default:	false
overwrite	Overwrite (unprompted) pre-existing output file?
	allowed:	bool
	Default:	false
list	List informative messages to the logger
	allowed:	bool
	Default:	true
stretch	Stretch the mask if necessary and possible?
	allowed:	bool
	Default:	false
wantreturn	Return an image analysis tool attached to the created subimage
	allowed:	bool
	Default:	true
keepaxes	If dropdeg=True, these are the degenerate axes to keep. Nondegenerate axes are implicitly always kept.
	allowed:	intArray
	Default:

Returns
image

Example

"""
#
print "\t----\t subimage Ex 1 \t----"
ia.maketestimage(’myfile’,overwrite=true)
im2 = ia.subimage() # a complete copy
r1 = rg.box([10,10],[30,40],[5,5]) # A strided pixel box region
im3 = ia.subimage(outfile=’/tmp/foo’, region=r1, overwrite=true)
# Explicitly named subimage
im2.done()
im3.done()
ia.close()
#
"""

# As an example of the usage of the keepaxes parameter, consider an image
# that has axes RA, Dec, Stokes, and Freq. The Stokes and Freq axes are both
# degenerate while the RA and Dec axes are not, and it is desired to make a
# subimage in which the Stokes axis is discarded. The following command will
# accomplish that.
ia.open("my.im")
subim = ia.subimage(outfile="discarded_stokes.im", dropdeg=True, keepaxes=[3])
ia.done()
subim.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