Getting Started Documentation Glish Learn More Programming Contact Us
Version 1.9 Build 1488
News FAQ
Search Home


next up previous contents index
Next: image - Constructor Up: images - Module Previous: images - Module


image - Tool



Package general
Module images


Postscript file available

Operations on images

include "image.g"

Constructors
image Construct an image tool from an AIPS++ image file
imagecalc Construct an AIPS++ image via the image calculator
imageconcat Construct an AIPS++ image by concatenating images
imagefromarray Construct an AIPS++ image from a Glish array
imagefromascii Construct an AIPS++ image by conversion from an ascii file
imagefromfits Construct an AIPS++ image by conversion from a FITS image file
imagefromforeign Construct an AIPS++ image from a foreign package image file
imagefromimage Construct a (sub)image from a region of an AIPS++ image
imagefromshape Construct an empty AIPS++ image from a shape
imagemaketestimage Construct an AIPS++ image from a test FITS file
Functions
adddegaxes Add degenerate axes of the specified type to the image
addnoise Add noise to the image
boundingbox Get the bounding box of the specified region
brightnessunit Get the image brightness unit
calc Image calculator
calcmask Image mask calculator
close Close the image tool
continuumsub Image plane continuum subtraction
convertflux Convert flux density between peak and integral
convertsm Convert image for older versions
convolve Convolve image with a Glish array or another image
convolve2d Convolve image by a 2D kernel
coordmeasures Convert from pixel to world coordinate wrapped as Measures
coordsys Get the Coordinate System of the image
decompose Separate a complex image into individual components
deconvolvecomponentlist Deconvolve a componentlist from the restoring beam
delete Delete the image file associated with this image tool
done Destroy this image tool
fft FFT the image
findsources Find point sources in the sky
fitallprofiles Fit all 1-dimensional profiles in a region
fitpolynomial Fit 1-dimensional polynomials to profiles
fitprofile Fit 1-dimensional profile with functional forms
fitsky Fit 2-dimensional models to the sky
getchunk Get the pixel values from a regular region of the image into a Glish array
getregion Get pixels and mask from a region-of-interest of the image
getslice Get 1-D slice from the image
hanning Convolve one axis of image with a Hanning kernel
haslock Does this image have any locks set ?
histograms Compute histograms from the image
history Recover and/or list the history file
id Return the fundamental identifier of this tool
insert Insert specified image into this image
isopen Is this Image tool open ?
ispersistent Is the image persistent ?
lock Acquire a lock on the image
makecomplex Make a complex image
maskhandler Handle pixel masks
maskhandlergui Handle masks using a GUI interface
maxfit Find maximum and do parabolic fit in the sky
miscinfo Get the miscellaneous information record from an image
modify Modify image with a model
moments Compute moments from an image
momentsgui Compute moments from image via custom GUI interface
name Name of the image file this tool is attached to
open Open a new image file with this image tool
pixelvalue Get value of image and mask at specified pixel coordinate
putchunk Put pixels from a Glish array into a regular region of the image
putregion Put pixels and mask into a region-of-interest of the image
rebin rebin the image by the specified factors
regrid regrid this image to the specified Coordinate System
rename Rename the image file associated with this image tool
replacemaskedpixels replace the values of pixels which are masked bad
restoringbeam Get the restoringbeam
rotate rotate the direction coordinate axes attached to the image and regrid the image to the rotated Coordinate System
sepconvolve Separable convolution
sepconvolvegui Separable convolution via custom GUI interface
set Set pixel and/or mask values with a scalar in a region-of-interest of the image
setbrightnessunit Set the image brightness unit
setcoordsys Set new Coordinate System
sethistory Set the history for an image
setmiscinfo Set the miscellaneous information record for an image
setrestoringbeam Set the restoringbeam
shape Length of each axis in the image
statistics Compute statistics from the image
subimage Create a (sub)image from a region of the image
summary Summarize basic information about the image
toascii Convert the image to an ascii file
tofits Convert the image to a FITS file
topixel Convert from world to pixel coordinate
toworld Convert from pixel to world coordinate
twopointcorrelation Compute two point correlation function from the image
type Return the type of this tool
unlock Release any lock on the image
view Display the current image with the viewer


Summary

Image tools provides access to AIPS++ images. Currently only single precision floating point AIPS++ images are supported by the Image tool. In the future, complex images will also be supported.

Image tools also provide direct (native) access to FITS and Miriad images. You can also convert these foreign formats to AIPS++ format (for optimum processing speed).


Overview of Image tool functionality


General

We refer to an AIPS++ image file when we are referring to the actual data stored on disk. The name that you give an AIPS++ image file is actually the name of a directory containing a collection of AIPS++ tables which together constitute the image file. But you only need to refer to the directory name and you can think of it as one logical file.

Whenever we use the word ``image'', we are just using it in a generic sense. AIPS++ images are manipulated with an Image tool. An image tool is associated with, or bound to, the actual image file via a constructor. Note that some image tools don't have a disk file associated with them. These are called ``virtual'' images and are discussed below

When an image is stored on disk, it can, in principle, be stored in a variety of ways. For example, the image could be stored row by row; this is the way that most older generation packages store images. It makes for very fast row by row access, but very slow in other directions (e.g. extract all the profiles along the third axis of an image). An AIPS++ image file is stored with what is called tiling. This means that small multi-dimensional chunks (a tile) are stored sequentially. It means that row by row access is a little slower, but access speed is essentially the same in all directions. This in turn means that you don't need to (and can't !) reorder images.

Here are some simple examples using image tools.



Example
- include 'image.g'                    # Load image tool functionality
- include 'logger.g'                   # Load logger tool functionality
- dl.gui()                             # Display logger GUI
- im := imagemaketestimage('zz')       # Make test image; writes disk file called 'zz'
- im.summary()                         # Summarize (to logger)
- im.view()                            # Display image 
- im.statistics()		       # Evaluate statistics over entire image
#
- box := drm.box([10,10], [50,50])     # Make a pixel box region with regionmanager
- im2 := im.subimage('zz2', box)       # Make a subimage  called 'zz2'
- im2.statistics()                     # Evaluate statistics
- im2.fft (amp='zz2.amp', phase='zz2.phase')  # FFT subimage and store amp and phase
#
- im.done()                            # Release tool resources (destroys it) - disk file unaffected
- im2.done()


Foreign Images

The Image tool also provides you with native access to some foreign image formats. Presently, these are FITS (Floar, Double, Short and Long are supported) and Miriad. This means that you don't have to convert the file to native AIPS++ format in order to access the image. For example:



Example
- include 'image.g'     
- ima := image('im.app')        # Access aips++ image
- imf := image('im.fits')       # Access FITS image
- imm := image('im.mir')        # Access Miriad image
-
- ims := imagefromimage(infile='im.fits', region=drm.quarter())
Each of these Image tools has access to all the same tool functions.

Where ever you see an argument in an Image tool constructor which is an input image disk file, that disk file can be an AIPS++, FITS, or Miriad image file.

There are some performance penalties that you should be aware of. Firstly, because AIPS++ images are tiled (see above) you get the same access speed regardless of how you access the image. FITS and Miriad images are not tiled. This means that the performance for these Image tools will be poorer for certain operations. For example, extracting a profile along the third axis of an image, or re-ordering an image with the display library.

Secondly, for FITS images, masked values are indicated via ``magic value''. This means that the mask is worked out on the fly every time you access the image.

If you find performance is not good enough or you want a writable image, then use appropriate constructor (imagefromfits or imagefromforeign) to convert to a native AIPS++ image.


Virtual Images

We also have Image tools that are not associated one-to-one with disk files; these are called ``virtual'' images (see also the article in the AugustNewsLetter). For example, with the image calculator, imagecalc, one can create an expression which may contain many images. You can write the result of the expression out to a disk image file, but if you wish, you can also just maintain the expression, evaluating it each time it is needed - nothing is ever written out to disk in this case. There are other Image constructors and functions like this (the documentation for each one explains what it does). The rules are:

  • If you specify the outfile argument, then the image is always written to the specified disk image file.

  • If you leave the outfile argument unset, then if possible, a virtual image will be created. Sometimes this virtual image will be an expression as in the example above (i.e. it references other images) or a temporary image in memory, or a temporary image on disk. (the summary function will list for you the type of image you have). When you destroy that Image tool, the virtual image will be destroyed as well.

  • If you leave outfile unset, and the function or constructor cannot make a virtual image, it will create a disk file for you with a name of its choice (usually input plus function name).

  • You can always write a virtual image to disk with the subimage tool function.


Coordinate Systems

An image contains a Coordinate System. A Coordsys tool is used to manipulate the Coordinate System. An Image tool allows you to recover the Coordinate System into a Coordsys tool through the coordsys) function. You can set a new Coordinate System with the setcoordsys function.

You can do some direct coordinate conversion via the Image tool functions toworld, topixel, and coordmeasures. The actual work is done by a Coordsys tool, for which these Image tool functions are just wrappers.


Lattice Expression Language (LEL)

LEL allows you to manipulate expressions involving images. For example, add this image to that image, or multiply the miniumum value of that image by the square root of this image. The LEL syntax is quite rich and is described in detail in note 223. LEL is accessed via the imagecalc constructor and the calc tool function. Here are some examples.



Example
- include 'image.g'
- im := imagemaketestimage()       # Make virtual test image
- im.calc('$im + min($im)')        # Make the minimum value zero 
-
- im2 := imagemaketestimage('zz')   # Make nonvirtual test image
- im2.calc('zz + min(zz)')          # Make the minimum value zero 
-
- im.done()
- im2.done()

In the first example, the Image tool im is associated with a virtual image. We use the $ syntax in the expression accessing this image via its tool. In the second example, the Image tool im2 is associated with the non-virtual disk file zz. We could still have used the $ syntax if we wanted, but we show here how you can also use the image file name in the expression.

Note that for image file names with special characters in them (like for example), you should (double) escape those characters or put the file name in double quotes. E.g.



Example
- im1 := imagecalc(pixels='test\\-im')     # Note double escape required
- im2 := imagecalc(pixels='"test-im"')


Region-of-interest

A region-of-interest or simply, region, designates which pixels of the image you are interested in for some (generally) astrophysical reason. This complements the pixel mask (see below) which specifies which pixels are good or bad (for statistical reasons). Regions-of-interest are generated and manipulated with the Regionmanager tool.

Briefly, a region-of-interest may be either a simple shape such as a multi-dimensional box, or a 2-D polygon, or some compound combination of regions-of-interest. For example, a 2-D polygon defined in the X and Y axes extended along the Z axis, or perhaps a union or intersection of regions.

See the Regionmanager documentation for more details on regions.

Regions are always supplied to constructors and tool functions via the region argument.


Pixel mask

A pixel mask specifies which pixels are to be considered good (value T) or bad (value F). For example, you may have imported a FITS file which has blanked pixels in it. These will be converted into pixel mask elements whose values are bad (F). Or you may have made an error analysis of an image and computed via a statistical test that certain pixels should be masked out for future analysis.

If there is no pixel mask, all pixels are considered good (if you retrieve the pixel mask when there is none, you will get an all good mask). Pixels for which the pixel mask value is bad are not used in computations (e.g. in the calculation of statistics, moments or convolution).

The image may contain zero, one, or more pixel masks. However, only one mask will be designated as the default mask. This is the pixel mask that is actually applied to the data. You can also indicate that none of the pixel masks are the default, so that effectively an all good pixel mask is applied. The function summary includes in its summary of the image the names of the masks (the first listed, if not in square brackets, is the default).

Pixel masks are handled with the function maskhandler. This allows you to find the names of pixel masks, delete them, copy them, nominate the default and so on. It is not used to change the value of pixel masks.

The functions with which you can change pixel mask values are putregion (put Boolean array), calcmask (put result of Boolean LEL expression), and set (put scalar Boolean).


The argument 'mask'

There is an argument, mask, which can be supplied to many constructors and functions. It is supplied with either a mask region-of-interest (generated via the function wmask) or a LEL Boolean expression string (the same string you would have supplied to the above Regionmanager function). Generally, one just supplies the expression string.

The LEL expression is simply used to generate a pixel mask which is then applied in addition to any default pixel mask in the image (a logical OR). For example

- im := imagemaketestimage('zz')
- im.statistics(mask='zz>0')        # Only evaluate for positive values
- im.calcmask (mask='(2*$im) > 0')  # Create a new mask which is T (good) when twice the 
                                    # image values are positive, else F

The mask expression must in general conform (shape and coordinates) with the image (i.e. that associated with the Image tool). You can use the $ substitution syntax for Image tools (see example above) which is necessary for virtual images and useful otherwise.

When mask is used with function calcmask, a persistent pixel mask is created and stored with the image. With all other functions and constructors, the mask argument operates as a transient (or On-The-Fly [OTF]) pixel mask. It can be very handy for analysing or displaying images with different masking criteria.

Often I will refer to the ``total input mask''. This is the combination (logical OR) of the default pixel mask (if any) and the OTF mask (if any).

In the following example we open a Rotation Measure image. We then evaluate statistics and display it where only those pixels whose error in the Rotation Measure (image file rmerr) is less than the specified value are shown; the others are masked. The nice thing is you can experiment with different pixel masks until you are satisfied, whereupon you might then make the pixel mask persistent with the calcmask function.



Example
- include 'image.g'
- im := image('rm')
- im.statistics(mask='rmerr<10')
- im.view(mask='rmerr<20')
- im.calcmask (mask='rmerr<20')     # Make persistent mask


Finally, a subtlety that is worth explaining.



Example
- im.statistics(mask='zz>0')                 # Mask of zz ignored
- im.statistics(mask='mask(zz) && zz>0')     # Mask of zz used

In the first example, any default mask associated with the image zz is ignored. Only the pixel values are looked at. In the second example, the mask of zz is also taken into account via the LEL mask function. That is, the transient output mask is T (good) only when the mask of zz is T and the expression zz>0 is T.



Example

A useful part of LEL to use with the mask argument is the indexin function. This enables the user to specify a mask based upon selected pixel coordinates (or indices) rather than image values. For example

- im := imagefromshape(shape=[20])
- local pp,mm
- im.getregion (pp,mm, mask='indexin(1, [5:10, 15, 19:20])')
- print mm
[F F F F T T T T T T F F F F T F F F T T]

You can see the mask is good (T) for the specified indices along the specified axis. You can also pass in a premade variable for the specification if you like, viz.

- im := imagefromshape(shape=[20])
- axis := 1
- sel := [5:10, 15, 19:20]
- local pp,mm
- im.getregion (pp,mm, mask='indexin($axis, $sel)')
- print mm
[F F F F T T T T T T F F F F T F F F T T]

This capability is useful for fitting functions. See the example in the fitpolynomial function.


Pixel masks and Regions

Some comment about the combination of pixel masks and regions-of-interest is useful here. See the Regionmanager tool for basic information about regions-of-interest first.

Regions are provided to Image tool functions via the standard region constructor and function argument.

Consider a simple polygonal region. This region-of-interest is defined by a bounding box, the polygonal vertices, and a mask called a region mask. The region mask specifies whether a pixel within the bounding box is inside or outside the polygon. For a simple box region-of-interest, there is obviously no need for a region mask.

Now imagine that you wish to recover the pixel mask of an image from a polygonal region-of-interest. The mask is returned to you in regular Boolean array. Thus, the shape of the returned mask array reflects the bounding-box of the polygonal region. If the actual pixel mask that you apply is all good, then the retrieved mask would be good inside of the polygonal region and bad outside of it. If the actual pixel mask had some bad values in it as well, the retrieved mask would be bad outside of the polygonal region. Inside the polygonal region it would be bad if the pixel mask was bad. More simply put, the mask that you recover is just a logical ``and'' of the pixel mask and the region mask; if the pixel mask is T and the region mask is T then the retrieved mask is T (good), else it is F (bad).

Finally, note that if you use the region and mask (the OTF mask) arguments together then they operate as follows. The shape of the Boolean expression provided by mask must be the same shape as the image to which it is being applied. The region is applied equally to the image and the mask expression. For example



Example
include 'image.g'
- rm1 := image('rm')
- rm2 := image('rmerr')
- rm1.shape(); rm2.shape()
[128 128]
[128 128]
- r := drm.box([10,10], [50,50])
- rm1.statistics(region=r, mask='rmerr<10')       # region applied to 'rmerr' and 'rm'


Error Handling

All the constructors and functions for Image tools return a variable by value. Because of the weak typing of Glish, this variable may take on different forms depending upon the outcome. For example, a constructor such as im := image('hcn.xyv') normally returns an image tool. However, if the operation failed (e.g. the image file hcn.xyv) does not exist, them the return variable will be what is called a Glish fail. You can check any Glish variable with the is_fail(variable) function; it returns T or F. With an Image tool, all errors will cause the returned variable, whether it comes from a constructor or a method, to be a fail. You will not get a false (F) return unless this is a legal return value for the function. This is so that you always know what to check the return variables value for if you are doing careful error checking in a script. The documentation for each constructor and function always tells you what the return variable type could potentially be.



Example
- include 'image.g'
- im := image('rm')
- if (is_fail(im)) {
  note (im::message, origin='myscript', priority='SEVERE')
  return;
}
The scoping operator :: enables to extract out a diagnostic message from the variable im when it is a fail.


Vector Inputs

Many of the functions of an Image tool take vectors (numeric or strings) as their arguments. We take advantage of the weak-typing of Glish so that whenever you see a vector argument, you can assume that

  • For numeric vectors you can enter as an actual numeric vector (e.g. [1.2,2.5,3]), a vector of strings (e.g. "1.2 2.5 3") or even a string with white space and/or comma delimiters (e.g. '1.2 2.5 3').

  • For string vectors you can enter as an actual vector of strings (e.g. "1.2 2.5 3") or a string with white space or comma delimiters (e.g. '1.2 2.5 3').


Events

An image tool may emit five events. These are generated by the view display function. See it for details of the event values.

  • A region event. This signifies that a region-of-interest has been interactively generated via the Viewer.

  • A position event. This signifies that a position has been interactively generated via the Viewer.

  • A statistics event. This signifies that statistics have been interactively generated via the Viewer.

  • a breakfromviewer event. This signifies that the user has pressed the `break' button on the Viewer display panel.

  • a viewerdone event. This signifies that the private Viewer inside the Image tool has been destroyed.


Short-hand names for functions

Many of the function names are rather long to type (e.g. boundingbox, replacemaskedpixels). This doesn't matter with a GUI interface, but can be annoying if you are writing scripts or using Glish interactively. For such long-winded function names, a short-hand synonym is defined and given at the beginning of the documentation for each function.


Miscellaneous

At present only real-valued (single precision) images are supported. Complex images will be supported in the future.

Besides the functions available as tool functions, you may of course add functionality through Glish programming. Glish computing speed will be adequate for many ``chunk-by-chunk'' algorithms. Beware putting large images into an array - this can use up a lot of memory!

Some of the tool functions in this module can be run asynchronously (usually things that might take a long time). This is controlled by the argument async which defaults to !dowait (i.e. the opposite to the value of this Glish Boolean variable). By default when you start Glish dowait=F. You can enter dowait := T if you wish the default to be that these tool functions run synchronously. If you don't want to type this in every time you start Glish then put this statement in your .glishrc resource file that lives in your home directory.

Note that if the tool function is run asynchronously, you have to recover the result in a more indirect fashion as follows in the following example.

- jobnum := im.statistics(async=T) 
- statsout := defaultservers.result(jobnum)




next up previous contents index
Next: image - Constructor Up: images - Module Previous: images - Module   Contents   Index
Please send questions or comments about AIPS++ to aips2-request@nrao.edu.
Copyright © 1995-2000 Associated Universities Inc., Washington, D.C.

Return to AIPS++ Home Page
2006-08-01