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. 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

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()  
 

__________________________________________________________________


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