The data point(s) to be retrieved are those found in the specified  
     region, which may be:  
        1. A region file from the viewer (region parameter)  
        2. A region specified by a set of rectangular  
           pixel coordinates, the channel ranges and/or the Stokes.  
 
     For directed output, run as  
                    myoutput = imval()  
 
 
Keyword arguments:  
imagename -- Name of input image  
Default: none; Example: imagename=’ngc5921_task.im’  
        region -- region file or name.  
                Use the viewer, then region manager to select regions of  
                   the image to process.  Similar to box, but graphical  
                Or the name of a region stored with the image,  
                      use rg.namesintable()  
                to retrieve the list of names.  
                Default: none  
                Example: region=’myimage.im.rgn’  
                         region=’region1’  
box --  A box region on the directional plane  
        Only pixel values acceptable at this time.  
Default: ’’ (referencepixel values for the Directional coord);  
                Example: box=’10,10,50,50’  
                         box = ’10,10,30,30,35,35,50,50’ (two boxes)  
                         box = ’-1,-1’                   (all points)  
chans -- channel numbers  
        Range of channel numbers to include in statistics  
                  All spectral windows are included  
Default:’’= all;  Example: chans=’3~20’;  
                                           chans=’-1’ (all channels)  
stokes -- Stokes parameters to analyze.  
                Default: none (all); Example: stokes=’IQUV’;  
                                              stokes=’I,Q’  
                                              stokes=’-1’ (all stokes values)  
                Options: ’I’,’Q’,’U’,’V’,’RR’,’RL’,’LR’,’LL’,’XX’,’YX’,’XY’,’YY’, ...  
 
      General procedure:  
 
         1.  Specify inputs, then  
 
         2.  myoutput = imval()  
               or specify inputs directly in calling sequence to task  
             myoutput = imsval(imagename=’image.im’, etc)  
 
         3.  myoutput[’KEYS’] will contain the result associated with any  
               of the keys given below  
 
        KEYS CURRENTLY AVAILABLE  
     blc          - absolute PIXEL coordinate of the bottom left corner of  
               the bounding box surrounding the selected region  
     trc          - the absolute PIXEL coordinate of the top right corner  
                       of the bounding box surrOunding the selected region  
        axes         - List the data stored in each axis of the data block.  
        unit         - unit of the returned data values.  
     data         - data value(s) found in the given region  
     mask         - mask value(s) found in the given region  
 
        NOTE: The data returned is in the same order as it is internally  
        stored, typically RA, DEC, spectral, stokes. Also both the data  
        and mask values are returned as Python Numpy arrays, for more  
        information on how to manipulate them see  
             http://numpy.scipy.org/#array_interface  
 
 
Additional Examples  
# The value and mask value at a single point (5,17,2,Q)  
        imval( ’myImage’, box=’5,5,17,17’, chans=2, stokes=’Q’ )  
 
# Select and report on two box regions  
# box 1, bottom-left coord is 2,3 and top-right coord is 14,15  
# box 2, bottom-left coord is 30,31 and top-right coord is 42,43  
        # Note that only the boxes for the  
imval( ’myImage’, box=’2,3,14,15;30,31,42,43’ )  
 
# Select the same two box regions but only channels 4 and 5  
imval( ’myImage’, box=’2,3,14,15;30,31,42,43’, chan=’4~5’ )  
 
# Select all channels greater the 20 as well as channel 0.  
  # Then the mean and standard deviation are printed  
        # Note that the data returned is a Python numpy array which  
        # has built in operations such as min, max, and means as  
        # demonstrated here.  
results = imval( ’myImage’, chans=’>20;0’ )  
        imval_data=results[’data’]  
        mask=results[’mask’]  
        print "Data max: ", imval_data.max(), "  mean is ", imval_data.mean()  
        swapped_data=imval_data.swapaxes(0,2)  
        swapped_mask=mask.swapaxes(0,2)  
        print "Data values for 21st channel: \n", swapped_data[0]  
        print "Mask values for 21st channel: \n", swapped_mask[0]