 News |
FAQ
|
| Search
|
Home
|
| Getting Started | Documentation | Glish | Learn More | Programming | Contact Us |
|
| Version 1.9 Build 1488 |
|
| Package | general | |
| Module | images |
include "image.g"
| 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 |
| 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
Finally, some foreign image formats (e.g. Miriad, GIPSY) can be converted to AIPS++ (if the foreign packages are installed locally) via an intermediate FITS file.
The coordsys tool provides more extensive coordinate system manipulation.
In the future filtering other than convolution will be provided
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.
- 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()
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:
- 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.
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:
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.
- 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.
- 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.
- 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.
- 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.
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.
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
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.
- 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.
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
Events
An image tool may emit five events. These are generated by the view display function. See it for details of the event values.
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)