1.1.1.0 image.imageconcat

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.

If outfile is given, the image is written to the specified disk file. If outfile is unset, the on-the-lfy 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 dimension. 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. Therefore, the Coordinate System of the output image is given by that of the first input image. 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. Look ?? for more information on foreign images.

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 with summary to make sure 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.


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. Default is spectral axis if there is one.
	allowed:	int
	Default:	-10
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

The image files im1, im2, and im3 are concatenated along the third axis to form the output image file bigimage. Only warnings are issued if axis descriptors mismatch. Access to the output image is provided via the tool called bigim.

All images whose file names begin with im and terminate with any valid filename extension that reside in the current directory are concatenated along the spectral axis if there is one. The image must be contiguous along the spectral axis and all image coordinate descriptors must match. If there is no spectral axis an error will result. Because an output file name is not given, the Image tool just references the input files, it does not copy them.

image.imageconcat - Function