imcollapse.py

Go to the documentation of this file.

#
# This file was generated using xslt from its XML file
#
# Copyright 2009, Associated Universities Inc., Washington DC
#
import sys
import os
from  casac import *
import string
from taskinit import casalog
#from taskmanager import tm
import task_imcollapse
def imcollapse(imagename='', function='', axes=[0], outfile='', box='', region='', chans='', stokes='', mask='', wantreturn=False, overwrite=False, stretch=False):

        """Collapse image along one axis, aggregating pixel values along that axis.
PARAMETER SUMMARY
imagename        Name of the input (CASA, FITS, MIRIAD) image
function         Function used to compute aggregation of pixel values along the collapsed
                 axis. Supported functions are max, mean, median, min, rms, stdev,
                 sum, variance. Minimum match is supported for the function parameter (eg,
                 function="r" will compute the rms of the pixel values).
axis             Zero-based axis number(s) or minimal match strings to compress.
outfile          Name of output CASA image. If not specified, no image is written
                 but an image analysis tool which references the output image is returned.
overwrite        If output file is specified, controls if an already existing file by the
                 same name can be overwritten. If true, the user is not prompted, the file
                 if it exists is automatically overwritten.
box              Direction plane box specification, "blcx, blcy, trcx, trcy". Only one box
                 may be specified. If not specified, region is used if specified. If region
                 is also not specified, entire directional plane unioned with any chans and
                 stokes specification determines the region.
region           Region specification. See help par.region. Default is to not use a region.
chans            Optional contiguous frequency channel number specification. Not used if
                 region is specified. Default is all channels.
stokes           Contiguous stokes planes specification. Not used if region is specified.
                 Default is all stokes.
mask             Mask to use. See help par.mask. Default is none.
stretch          Stretch the input mask if necessary and possible. Only used if a mask is specified.
                 See help par.stretch.
wantreturn       If true, return an image analysis tool referencing the collapsed image, if
                 false, return false.

This task collapses an image along a specified axis or set of axes of N pixels to a single pixel on each
specified axis. It computes the specified aggregate function for pixel values along the specified axes
and places those values in the single remaining plane of those axes in the output image. It returns
an image analysis tool containing the newly created collapsed image if wantreturn=True. Choices of
aggregate functions are: max, mean, median, min, rms, stdev, sum, variance. Minimal unique match is
supported for the function parameter (eg, function="r" will compute the rms of the pixel values, "med"
will compute the median).
        
Axes can be specified as a single integer or array of integers indicating the zero-based axes along
which to collapse the image. Axes may also be specified as a single or array of strings which minimally
and uniquely match (ignoring case) world axes names in the image (eg "dec" or ["ri, "d"] for
collapsing along the declination axis or along the right ascension and declination axes, respectively).
        
If outfile is not specified (or contains only white spaces), no image is written but, if wantreturn=True,
the collapsed image is still able to be accessed via the returned image analysis tool which references
the collpased image. If the returned object is not wanted it should still be captured and deleted via its
done() method. If this is not done, there is no gaurantee for when the python garbage collector will delete
it. If the returned object is wanted, it should be deleted as soon as possible for the same reasons, eg
        
collapsed_image = imcollapse(..., wantreturn=T)
# do things (or not) with collapsed_image and when done with object, do
collapsed_image.done()

The reference pixel of the collapsed axis is set to 0 and its reference value is set to the mean
of the the first and last values of that axis in the specified region of the input image.

# myimage.im is a 512x512x128x4 (ra,dec,freq,stokes) image
imagename = "myimage.im"
# collapse a subimage of it along its spectral axis avoiding the 8 edge
# channels at each end of the band, computing the mean value of the pixels
# resulting image is 256x256x1x4 in size.
outfile="collapse_spec_mean.im"
function="mean"
axis=2
box="127,127,383,383"
chans="8~119"
collapsed = imcollapse(imagename=imagename, outfile=outfile, function=function, axes=axis, box=box, chans=chans, wantreturn=True)
# manipulate collapsed
collapsed.done()
T

        """

#
#    The following is work around to avoid a bug with current python translation
#
        mytmp = {}

        mytmp['imagename'] = imagename
        mytmp['function'] = function
        mytmp['axes'] = axes
        mytmp['outfile'] = outfile
        mytmp['box'] = box
        mytmp['region'] = region
        mytmp['chans'] = chans
        mytmp['stokes'] = stokes
        mytmp['mask'] = mask
        mytmp['wantreturn'] = wantreturn
        mytmp['overwrite'] = overwrite
        mytmp['stretch'] = stretch
        pathname='file:///'+os.environ.get('CASAPATH').split()[0]+'/share/xml/'
        trec = casac.utils().torecord(pathname+'imcollapse.xml')

        casalog.origin('imcollapse')
        if trec.has_key('imcollapse') and casac.utils().verify(mytmp, trec['imcollapse']) :
            result = task_imcollapse.imcollapse(imagename, function, axes, outfile, box, region, chans, stokes, mask, wantreturn, overwrite, stretch)

        else :
          result = False
        return result