NRAO Home > CASA > CASA Toolkit Reference Manual
image.imageconcat - Function

1.1.1 Construct a CASA image by concatenating images


Description

This function is used to concatenate two or more input CASA images into one output image. For example, if you have two image cubes which are contiguous along one axis (say a spectral axis) and you would like to glue them together along this axis, then this function is the appropriate thing to use.

The axis parameter is used to specify which zero-based axis the images should be concatenated along. A negative value indicates that the spectral axis should be used. If a negative value is given but there is no spectral axis, an exception will be thrown. The zero-based order of the axes of an image can be determined from ia.coordsys().names().

If successful, this method will return an image analysis tool referencing the concatenated image. Even if it is not wanted, the returned tool should be captured and closed as soon as the user is finished with it to free up system resources (eg memory).

If outfile is given, the image is written to the specified disk file. If outfile is unset, the on-the-fly Image tool created by the function actually references all of the input files. So if you deleted any of the input image disk files, it would render this tool useless. When you destroy this tool (with the done function) the reference connections are broken.

The input and output images must be of the same dimensionality. Therefore, if you wish to concatenate 2-D images into a 3-D image, the 2-D images must have a third axis (of length unity) so that the output image coordinates are known along the concatenation axis.

The input images are concatenated in the order in which they are listed unless the reorder parameter is set to True. If True, the images are reordered if necessary so that the world coordinate values along the selected axis monotonically increase or decrease. The direction of the increment is determined by the first listed image. If reorder=True, the world coordinate ranges of the images along the selected axis are not permitted to overlap, and the signs of the increments for this axis in all images must be the same. If reorder=False, the coordinate system of the first listed image is used as the coordinate system for the output image. If reorder=True, the coordinate system of the first image in the list of the reordered images is used as the coordinate system of the output image. Setting reorder=True can be especially useful if the infiles are specified using a wildcard character(s).

If relax=False, the input images are checked to see that they are contiguous along the concatenation axis and an error is generated if they are not. In addition, the coordinate descriptors (e.g. reference pixel, reference value etc) for the non-concatenation axes must be the same or an error will result.

The input disk image files may be in native CASA, FITS, or Miriad formats.

The contiguous criterion and coordinate descriptor equality criteria can be relaxed by setting relax=T whereupon only warnings will be issued. Dimension and shape must still be the same though. When the concatenation axis is not contiguous (but still monotonically increasing or decreasing) and relax=T, a tabular coordinate will be used to correctly describe the axis. But be aware that it means adjacent pixels are not regularly spaced. However, functions like toworld and topixel will correctly interconvert world and pixel coordinates.

In giving the input image names, the infiles argument can be a single string if you wild card it with standard shell symbols. For example, infiles=’cena_???.*’, where the “?” represents one character and “*” any number of characters.

Otherwise, you must input a vector of strings such as infiles="cena1 cena2 cena3". An input such as infiles=’files1,file2’ will be interpreted as one string naming one file and you will get an error. The reason for this is that although the latter could be parsed to extract two file names by recognizing comma delimiters, it is not possible because an expression such as infiles=’cena.{a,b}(meaning files of name “cena.a” and “cena.b”) would confuse such parsing (you would get two files of name cena.{a and b}.

You can look at the coordinate system of the output image using the ia.summary() tool method to ensure it’s correct.

The argument tempclose is, by default, True. This means that all internal reference copies of the input images are kept closed until they are needed. Then they are opened temporarily and then closed again. This enables you to effectively concatenate as many images as you like without encountering any operating system open file number limits. However, it comes at some performance loss, because opening and closing all those files takes time. If you are concatenating a smallish number of files, you might use tempclose=F. This will leave all internal reference copies permanently open, but performance, if you don’t hit the file limit, will be better.

This method requires multiple images which are specified with the infiles parameter. Therefore calling ia.open() is not necessary, although calling imageconcat() using an already open image analysis tool will work and the state of that tool (eg the image it references) will not be changed.

Arguments





Inputs

outfile

Output image file name. Default is unset.

allowed:

string

Default:

infiles

List of input CASA image files to concatenate; wild cards accepted. Default is empty string.

allowed:

any

Default:

variant

axis

Concatenation pixel axis. Use ia.coordsys().names() to get a list of axes. A negative value means use the spectral axis if there is one, if not an exception is thrown.

allowed:

int

Default:

-1

relax

Relax constraints that axis coordinate descriptors match

allowed:

bool

Default:

false

tempclose

Keep all lattices closed until needed

allowed:

bool

Default:

true

overwrite

Overwrite (unprompted) pre-existing output file?

allowed:

bool

Default:

false

reorder

Automatically reorder the images if necessary.

allowed:

bool

Default:

false

Returns
image

Example

 
 
"""  
# Create three images to concatenate together.  
ia.fromshape(’im.1’,[10,10,10],overwrite=T)  
ia.fromshape(’im.2’,[10,10,10],overwrite=T)  
ia.fromshape(’im.3’,[10,10,10],overwrite=T)  
ia.done()  
# now concatenate.  
# The three images have the same shape along the axes not to be  
# concatenated as they must. relax=T means that the contiguity  
# constraint along the concatenated axis is not imposed (if it were  
# the call would fail because the spectral axes of the input images  
# are not contiguous).  
bigim = ia.imageconcat(outfile=’bigimage’, infiles=’im.1 im.2 im.3’,  
                       axis=2, relax=T, tempclose=F, overwrite=T)  
# be sure to call done() on the return tool to free up system resources.  
bigim.done()  
"""  
 

Example

 
 
"""  
#  
# All images whose file names begin with {\sff im.} that reside in  
# the current directory are concatenated along the spectral axis if  
# there is one. All image coordinate descriptors must match.  If any  
# input image does not have a spectral axis an error will  
# result.  Because an oufile is not specified, the returned image analysis  
# tool captured in the variable named bigim just references the input images;  
# this call does not create a persistent result image.  
bigim = ia.imageconcat(infiles="im.*",relax=T)  
bigim.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