Image Analysis Tasks Needed

CASA Modification Request 8C108, November 2007



1. Introduction

Several important image analysis tools are needed in casa. The most important ones are described.

2. Background

Much of the initial work to be done is implementing what was in AIPS++ in the CASA task level. Belows are the references used for the new CASA tasks to be developed.

*References:

3. Requirements

Tasks are ordered in the same order in which they are going to be address, ie. requirement 3.1 will be dealt with first. The general philosophy in the ordering is to to do the simpler ones first and work towards the more challenging issues.

The suggested casa image analysis tasks that are needed in casa follow:

3.1 Image combination (math)

A task is needed to do arithmetic combination of images. This includes binary operations (im1 .op. im2 => im3) and unary operations(im1 .op. => im2). This should replicate much of the functionality of AIPS COMB task.

Highest priority, but no C++ coding required this cycle. Just make basic tool capabilities available.

Image combinations: Simple image combination tasks are needed and the capabilities were available in aips++.

3.2 Image contortion

A task is needed to change the griding of an image: rotate, shift, stretch, etc. This is similar to regridimage except there is no template image.

3.3 Image statistics

A simple image statistics task is required. This should take an image (cube) plus some region and/or box specification and output and return the basic region statistics (e.g. to a dictionary).

3.4 Image cube continuum subtraction

The task imcontsub is needed to subtract a set of designated continuum channels from a spectral line image cubebase. It is a specialized type of image math. Mostly just expose the functionality of ia.continuumsub at the task level, though some extra facility to deal with the regions (ie. through a box specification and use of boxfiles as in clean) is also needed as in 3.3 above.

3.5 Image source finder and model fitter

A task to find discrete sources on an image above a certain threshold, and to fit the source with a model, is needed. Many optical packages and AIPS (via SAD) have such programs. Aips++ has some capabilities also. Some overlap (in the modelfitting) with 3.7 below.

3.6 Image cube spectral fitting

The fitting of one dimensional spectra are needed. It might be useful to combine the sky plane and the spectral direction fitting into one three-dimensional fitting scheme.

3.7 Image model fitting

Fitting one or many Gaussian components to restricted part of an image: This basic analysis tool is used to obtain parameters from relatively discrete radio components on an image. A tool in the aips++ system is available. A task like JMFIT in AIPS is a reasonable start, but the task should be interactive and coordinated with the viewer, as it was in the old aips++.

4. Design

For many of the requirements the job at hand is creating tasks to the imaging tool functionality. I propose tasks based on how the various image tool methods have been group in the the documentation( http://casa.nrao.edu/docs/casaref/image-Tool.html#x5-50001.1.1 ).

Note that the design of the fitting (analysis) will be left for a further date, as the problem is not well understood at this point.

The proposed task names are:
  • imhead : Gets and puts image header values, as well as provides statistics over an entire image, can be altered to provide stats on regions of an image as well.
  • imcontsub : Continuum subtraction from an image.
  • immath : Old AIPS++ imcalc routine
  • imutils : Catch all for useful image routines
  • imfit : Perform fitting of Gaussians on an image, as well as source detection.

Some of the tasks require a region or regions to be specified. Normally if a user would be using the tools the "rg" tool would be used to specify a region in an image. This region is then fed into the various "ia" tools. However, it's not acceptable to have the user use the region tool when operating at the task level, so we need to develop a region selection syntax that at the very least encompasses the typical case.

4.1 imhead

This task already exists but needs some work! First step is to deal with all of the imhead Jira issues: CAS-246, CAS-200, CAS-126, CAS-411, CAS-489, CAS-450, and CAS-470. Some of these may be issues in the image C++ layer, in which case they may be left until later. It would be nice to be have a priority assigned to these.

Should also either extend it to include stats on regions or pull the statistical reporting stuff out and putting it in a new task called imstats.

Fulfills requirement 3.3

4.2 imconsub

This looks like a straight forward task to build. It looks like it will be a task that calls ia.continuumsub plus has some box to region conversion etc.

Fulfills requirement 3.4

4.3 immath

This also looks like a straight forward task to build. It looks like it will be a one-line task that calls ia.calc, the old AIPS++ im.calc task. We may wish to call this imcalc. We may need to add options to make use if the ia.calcmask facilities.

Fulfills requirement 3.3

4.3 imutils

Not entirely sure what this task will entail, a bit of a catch all for a number of the image tool methods. It might be a good idea to also consider how me might want to group the image tool functions into a set of tasks. If we continue as we are we'll have a task for each tool method and that will flood the task space tremendously!

Some likely image tool methods that are relevant to this task are:
  • ia.adddegaxes
  • ia.coordsys
  • ia.makecomplex
  • ia.modify
  • ia.regrid
  • ia.rotate
  • ia.setcoordsys
  • ia.subimage
  • ia.topixel
  • ia.toworld
  • ia.makearray

Assuming this issues entails requirements 3.1 (image combinations), and 3.2 (image regridding)

4.4 imfit

The first step of this task is to make a task that makes use of what is already available in the images tool, as follows:
  • ia.findsources
  • ia.fitallprofiles
  • ia.fitpolynomial
  • ia.fitprofile
  • ia.fitsky
  • ia.maxfit

The next step will be to make this functionality availble from the GUI.

The final steps will be to enhance the functionality, as per directed.

Fulfills requirements 3.5, 3.6 and 3.7

5. Example Sessions

This section show a few examples of how to use the image tasks described above.

5.1 Getting statistics for a region within a 3D cube.

imhead( mode='statistics', axes=[0,1,2], bregion=['10,20,30,100,200,300','50,60,70,500,400,300'], pregion=['50,60,40,100,50,110'] * mode: tells imhead to print statistics * axes: Is used to obtain a region, in this case the user has selected the x(0), y(1) and z(2) axes of the 3-D image. We need to use number here rather then letters because we can have data that has more then 3 dimensions * bregion: List the box regions using blc followed by trc. More then one can be given. Since we are using 3 axes then for the blc and trc values we need to each have to value. In this example the user has selected 2 boxes. * pregion: List the polygonal regions as a lists a polygonal region. A polygon region is specified as a list of coordinates. Since we only are using two axes in this example each point consists of an x and y value. The coordinates for the polygon are: 50,60 40,100 50,110

Note that each shape in the region selection is enclosed in quotes, this could be brackets, could be just about anything. There seems to be an avoidance of lists of lists, and in general more complicated python data types. Perhaps a list of strings is easier.

I like having the region types in separate parameter rather then having some flag that denotes the type, I believe the above is more readable and easier for someone to figure out months after they right a little script for processing data. I would prefer if we are to use a flag that it is a test string, so it might look something like: region=['box,10,20,30,100,200,300', 'poly,10,20,30,100,200,300,70,80,80']

I've proposed extening the imhead task because it already does stats, but stats for the whole image. However, I also think it makes sense to have a separate imstats task and to move the stats portion of imhead into it. There is a need to extend imhead to add (and probably remove) new values to the header making this task a bit overloaded in my opinion. One suggested example is to add image names to the header, for example.

6. Deployment Checklist

7. Test Plan

7.1 Internal Testing

7.2 Sponsor Testing

Can be tested easily since the reordering of the cleaning will be obvious

6.3 Integration/Regression Tests

Probably included in regression tests already

6.4 Testing for Scientific Validity

Some deep cleans of spectral line data should be compared using the clean before and after the suggest implementation. There may be some differences in the images because of the non-linear properties of clean (depends on the order that clean components are removed), but they should be within the noise level.


Signatures

APPROVED: I acknowledge that my request is fully contained in this MR, and if the CASA development group delivers exactly what I specified, I will be happy.

ACCEPTED: I acknowledge that I have validated the completed code according to the acceptance tests, and I am happy with the results.

Written - - - - -
Checked - - - - -
Approved by Scientific Sponsor - - - - -
Accepted/Delivered by Sponsor - - - - -

Symbols:
  • Use %X% if MR is not complete (will display ALERT!)
  • Use %Y% if MR iscomplete (will display DONE)


Discussion Area

-- NicoleRadziwill - 30 Oct 2007

-- EdFomalont - 01 Nov 2007

-- EdFomalont - 05 Nov 2007

-- EdFomalont - 05 Nov 2007

-- ShannonJaeger - 13 Dec 2007

-- ShannonJaeger - 19 Dec 2007
Topic revision: r12 - 2008-01-16, ShannonJaeger
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback