1.1.1.0 image.imagecalc

NRAO Home > CASA > CASA Toolkit Reference Manual

image.imagecalc - Function

1.1.1 Perform mathematical calculations on an image or images.

Description

This method is used to evaluate a mathematical expression involving existing images. It fully supports both float and complex valued images. The syntax of the expression supplied via the pixels parameter (in what is called the Lattice Expression Language, or LEL) is explained in detail in note 223. This is a rich mathematical language with allows all manner of mathematical operations to be applied to images.

Any image files embedded in the expression may be native CASA or FITS (but not yet Miriad) images.

If successful, this method always returns an image analysis tool that references the image resulting from the calculation. This returned tool should always be captured and closed as soon as the user is done with it to free up system resources (eg, memory). The image analysis tool on which the method is called (eg the ia tool when one runs ia.imagecalc()) remains unaltered, eg it still refers to the same image it did prior to the imagecalc() call.

Values of the returned tool are evaluated ”on demand”. That is, only when a method is run on the returned tool are the necessary values computed. And in fact, the values have to be reevaluated for each operation (method call). This means that there is a small performance hit for using the returned tool rather than the image written to disk and that none of the images which were used in the expression should be deleted while the returned tool is in use because they must be accessed for calculating the expression each time an operation of the returned tool is performed. These limitations do not apply to the ouput image if one is specified with the outfile parameter; it is a genuine CASA image with numerical values. If outfile is blank, no ouput image is written (although the resulting image can still be accessed via the returned image analysis tool as described below).

Normally you should just write the image, close the returned tool, and open the results image with the default ia tool and operate on it. If you are interested in conserving disk space, you don’t need to keep the result of the calculation around for very long, and/or you are only going to do a small number of operations on the result image, should you set outfile=””.

Note that when multiple image are used in the expression, there is no garauntee about which of those images will be used to create the metadata of the output image, unless imagemd is specified. If imagemd is specified, the following rules of metadata copying will be followed:

1. The pixel data type of the image specified by imagemd and the output image must be the same. 2. The metadata copied include the coordinate system (and so of course the dimensionality of the output image must correspond to the coordinate system to be copied), the image_info record (which contains things like the beam(s)), the misc_info record (should one exist in the image specified by imagemd), and the units. 3. If the output image is a spectral image, the brightness units are set to the empty string. 4. If the ouptut image is a polarization angle image, the brightness unit is set to ”deg” and the stokes coordinate is set to have a single plane of type of Pangle.

Arguments


Inputs
outfile	Output image file name. If blank the resulting image is not written, but it can still be accessed via the returned image analysis tool.
	allowed:	string
	Default:
pixels	LEL expression. Must be specified. For example ”myimage1.im + myimage2.im”.
	allowed:	string
	Default:
overwrite	Overwrite (unprompted) pre-existing output file?
	allowed:	bool
	Default:	false
imagemd	The image from which metadata should be copied. Default means no gaurantee from which image is used.
	allowed:	string
	Default:

Returns
image

Example

"""
# Suppose aF and bF are images with single precision and we want
# to determine the result of the following expression:
# aF + min(float($\pi$, mean(bF))
#
# In this case, the images aF and bF do not need to have the same shapes and
# coordinates, because only the mean(bF) results in the mean of all pixel
# values in bF. If aF has single precision pixel values, the resulting image
# will as well. This expression first computes the scalar value of the minimum
# of $\pi$ and the mean of the pixel values of bF. That scalar is then
# added to the value of each pixel in aF. In the code below, the
# result is written to image cF which can be accessed immediately
# via the returned image analysis tool captured in the variable myim.
# If the expression is masked, that mask will be copied to the new image.

# create images of different sizes to operate on
ia.fromshape(’aF’,[10,10],overwrite=true)
ia.fromshape(’bF’,[10,20,30],overwrite=true)
# close the ia tool to free up resources
ia.done()
# at each pixel in bF, take the minimum of that pixel value and pi and add
# the resulting value to the corresponding pixel in af
# note that only the subset of pixels in bF that correspond to those in aF
# are used; the resulting image has the same size as the smaller image, aF,
# used in the input
myim = ia.imagecalc(outfile=’cF’, pixels=’aF + min(float(pi()), mean(bF))’,
overwrite=true)
# confirm the resulting image has the same size as aF, should be [10, 10]
myim.shape()
# close the myim tool to free up system resources
myim.done()
"""

Example

"""
# The following example shows the use of the two min() LEL functions. One takes a
# single argument and will return a scalar representing the minimum pixel value
# of that entire image. The other takes two arguments (either an image and a
# scalar or two images of conforming shapes) and returns an image for which
# the minimum has been calculated on a pixel by pixel basis for the input
# image(s).

# create an image to operate on
ia.fromshape(’aF’,[10,10],overwrite=true)
# give it interesting values
ia.addnoise()
# free up system resources
ia.done()
# do the calculation and write results to image cF
myim=ia.imagecalc(’cF’, ’min(aF, (min(aF)+max(aF))/2)’, overwrite=true)
# do whatever stuff you want with myim and the close it to free
# up system resources
myim.done()
"""

Example

"""
# Here’s an example of a more complicated function. Currently
# ia.fromshape() only creates real-valued images so the real()
# function is not particularly exciting in this case but illustrates
# possibilities. Trigonometric functions such as sin() assume the
# pixel values are in radians.
ia.fromshape(’aD’,[10,10],overwrite=true)
ia.addnoise()
ia.fromshape(’aF’,[10,10],overwrite=true)
ia.addnoise()
ia.fromshape(’bF’,[10,10],overwrite=true)
ia.addnoise()
ia.fromshape(’aC’,[10,10],overwrite=true)
ia.addnoise()
ia.done()
myim = ia.imagecalc(’eF’, ’sin(aD)+(aF*2)+min(bF)+real(aC)’, overwrite=true)
myim.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