NRAO Home > CASA > CASA Task Reference Manual

0.1.89 impv

Requires:

Synopsis
Construct a position-velocity image by choosing two points in the direction plane.

Arguments





Inputs

imagename

Name of the input image

allowed:

string

Default:

outfile

Output image name. If empty, no image is written.

allowed:

string

Default:

mode

If ”coords”, use start and end values. If ”length”, use center, length, and pa values.

allowed:

string

Default:

coords

start

The starting pixel in the direction plane (array of two values).

allowed:

any

Default:

variant

end

The ending pixel in the direction plane (array of two values).

allowed:

any

Default:

variant

center

The center point in the direction plane (array of two values). If specified, length and pa must also be specified and neither of start nor end may be specified.

allowed:

any

Default:

variant

length

The length of the segment in the direction plane. If specified, center and pa must also be specified and neither of start nor end may be specified.

allowed:

any

Default:

variant

pa

The position angle of the segment in the direction plane, measured from north through east. If specified, center and length must also be specified and neither of start nor end may be specified.

allowed:

any

Default:

variant

width

Width of slice for averaging pixels perpendicular to the slice. Must be an odd positive integer or valid quantity. See help for details.

allowed:

any

Default:

variant 1

unit

Unit for the offset axis in the resulting image. Must be a unit of angular measure.

allowed:

string

Default:

arcsec

overwrite

Overwrite the output if it exists?

allowed:

bool

Default:

False

region

Region selection. Default is entire image. No selection is permitted in the direction plane. See help par.region.

allowed:

any

Default:

variant ””

chans

Channels to use. See ”help par.chans” for examples. Channels must be contiguous. Default is to use all channels.

allowed:

string

Default:

stokes

Stokes planes to use. Planes must be contiguous. Default is to use all stokes.

allowed:

string

Default:

mask

Mask to use. See help par.mask. Default is none.

allowed:

string

Default:

variant

stretch

Stretch the mask if necessary and possible? See help par.stretch. Default False

allowed:

bool

Default:

False

Returns
image

Example

 
PARAMETER SUMMARY  
imagename        Name of the input (CASA, FITS, MIRIAD) image  
outfile          Name of output CASA image. Must be specified.  
mode             Indicates which sets of parameters to use for defining the slice. mode="coords" means use  
                 start and end parameters. mode="length" means use center, length, and pa parameters to define  
                 the slice.  
start            The starting pixel in the direction plane (array of two values), such as [20, 5] or ["14h20m20.5s","-30d45m25.4s"].  
                 Used iff mode="coords".  
end              The ending pixel in the direction plane (array of two values), such as [200, 300].  
                 Used iff mode="coords".  
center           The center of the slice in the direction plane (array of two values), such as [20, 5] or ["14h20m20.5s","-30d45m25.4s"].  
                 Used iff mode="length".  
length           The length of the slice in the direction plane. May be specified as a single numerical value, in which  
                 case it is interpreted as the number of pixels, or as a valid quantity which must be conformant with  
                 the direction axes units (eg "40arcsec", {"value": 40, "unit": "arcsec"}).  
                 Used iff mode="length".  
pa               Position angle of the slice, measured from the direction of positive latitude of the positive longitude  
                 (eg north through east in an equatorial coordinate system). Must be expressed as a valid angular  
                 quantity (eg "40deg", {"value": 40, "unit": "deg"}).  
                 Used iff mode="length".  
width            Width of slice for averaging pixels perpendicular to the slice which must be an odd positive integer or  
                 valid quantity. The averaging using this value occurs after the image has been rotated so the slice lies horizontally.  
                 An integer value is interpreted as the number of pixels to average.  
                 A value of 1 means no averaging. A value of 3 means average one pixel on each  
                 side of the slice and the pixel on the slice. A value of 5 means average 2 pixels  
                 on each side of the slice and the pixel on the slice, etc. If a quantity (eg. "4arcsec", qa.quantity("4arcsec"))  
                 is specified, the equivalent number of pixels is calculated, and if necessary, rounded up  
                 to the next odd integer.  
unit             Allows the user to set the unit for the angular offset axis. Must be a unit of angular  
                 measure.  
overwrite        If output file is specified, this parameter 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.  
region           Region specification. See help par.region. Default is to not use a region. If specified,  
                 the entire direction plane must be specified. If specified do not specify chans or stokes.  
chans            Optional contiguous frequency channel number specification. Default is all channels.  
                 If specified, do not specify region. See "help par.chans" for examples.  
stokes           Contiguous stokes planes specification. If specified, do not specify region.  
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.  
 
Create a position-velocity image. The way the slice is specified is controlled by the mode parameter. When  
mode="coords", start end end are used to specified the points between which a slice is taken in the direction  
coordinate. If mode="length"  center, pa (position angle), and length are used to specify the slice. The spectral  
extent of the resulting image will be that provided by the region specification or the entire spectral range of  
the input image if no region is specified. One may not specify a region in direction space; that is accomplished by  
specifying the slice as described previously. The parameters start and end may be specified as two  
element arrays of numerical values, in which case these values will be interpreted as pixel locations in the input  
image. Alternatively, they may be expressed as arrays of two strings each representing the direction. These strings  
can either represent quantities (eg ["40.5deg", "0.5rad") or be sexigesimal format (eg ["14h20m20.5s","-30d45m25.4s"],  
["14:20:20.5s","-30.45.25.4"]). In addition, they may be expressed as a single string containing the longitude-like and  
latitude-like values and optionally a reference frame value, eg "J2000 14:20:20.5s -30.45.25.4".The center parameter can  
be specified in the same way. The length parameter may be specified as a single numerical value, in which case it is  
interpreted as the length in pixels, or a valid quantity, in which case it must have units conformant with the  
direction axes units. The pa (position angle) parameter must be specified as a valid quantity with angular units.  
The position angle is interpreted in the usual astronomical sense; eg measured from north through east in an equatorial  
coordinate system. The slice in this case starts at the specified position angle and ends on the opposite side of  
the specified center. Thus pa="45deg" means start at a point at a pa of 45 degrees relative to the specified center and  
end at a point at a pa of 215 degrees relative to the center. Either start/end or center/pa/length must be specified;  
if a parameter from one of these sets is specified, a parameter from the other set may not be specified. In either  
case, the end points of the segment must fail within the input image, and they both must be at least 2 pixels from the  
edge of the input image to facilite rotation (see below).  
 
One may specify a width, which represents the number of pixels centered along and perpendicular  
to the direction slice that are used for averaging along the slice. The width may be specified as an integer, in which  
case it must be positive and odd. Alternatively, it may be specified as a valid quantity string (eg, "4arcsec") or  
quantity record (eg qa.quantity("4arcsec"). In this case, units must be conformant to the direction axes units (usually  
angular units) and the specified quantity will be rounded up, if necessary, to the next highest equivalent odd integer number  
of pixels. The default value of 1 represents no averaging.  
A value of 3 means average one pixel on each side of the slice and the pixel on the slice.  
Note that this width is applied to pixels in the image after it has been rotated (see below for a description  
of the algorithm used).  
 
One may specify the unit for the angular offset axis.  
 
Internally, the image is first rotated, padding if necessary to include relevant pixels that would otherwise  
be excluded by the rotation operation, so that the slice is horizontal, with the starting pixel left of the  
ending pixel. Then, the pixels within the specified width of the slice are averaged and the resulting image is  
written and/or returned. The output image has a linear coordinate in place of the direction coordinate of the  
input image, and the corresponding axis represents angular offset with the center pixel having a value of 0.  
 
The equivalent coordinate system, with a (usually) rotated direction coordinate (eg, RA and Dec) is written  
to the output image as a table record. It can be retrieved using the table tool as shown in the example below.  
 
# create a pv image with the position axis running from ra, dec pixel positions of [45, 50] to [100, 120]  
# in the input image  
impv(imagename="my_spectral_cube.im", outfile="mypv.im", start=[45,50], end=[100,120])  
# analyze the pv image, such as get statistics  
pvstats = imstat("mypv.im")  
#  
# get the alternate coordinate system information  
tb.open("mypv.im")  
alternate_csys_record = tb.getkeyword("misc")["secondary_coordinates"]  
tb.done()  


More information about CASA may be found at the CASA web page

Copyright 2016 Associated Universities Inc., Washington, D.C.

This code is available under the terms of the GNU General Public Lincense


Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search