|
|||
NRAO Home > CASA > CASA Toolkit Reference Manual |
|
image.pv - Function
1.1.1 Construct a position-velocity image between two points in the direction
plane.
Description
Create a position-velocity image by specifying either two points between which
a slice is taken in the direction coordinate or a center, position angle, and
length describing 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 start and end points or the
center, length, and position angle of the slice. 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 and latitude values and optionally a reference
frame value, eg ”J2000 14:20:20.5s -30.45.25.4”. The center parameter is
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; ie measured from north through east. 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 is 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). The end points of the specified 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 the unit for the angular offset axis.
A true value for the wantreturn parameter indicates that an image analysis tool attached to the created image should be returned. Nothing is returned if wantreturn is false, but then outfile should be specified (unless perhaps you are debugging).
Internally, the image is first rotated, padding first 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.
Arguments
Inputs |
| ||
outfile |
| Output image name. If empty, no image is written.
Default ”” | |
| allowed: | string |
|
| Default: |
|
|
start |
| The starting point in the direction plane (array of two
values). If specified, end must also be specified and none
of center, pa, nor length may be specified.
| |
| allowed: | any |
|
| Default: | variant
|
|
end |
| The ending point in the direction plane (array of two
values). If specified, start must also be specified and none
of center, pa, nor length may be specified.
| |
| 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 in pixels for averaging pixels perpendicular to the
slice. Must be an odd integer >= 1 (1 means only use
the pixels along the slice), or a quantity which will be
rounded up if necessary so it corresponds to the next
highest odd number of pixels.
| |
| 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 to use the full image. No
selection is permitted in the direction plane.
| |
| allowed: | any |
|
| Default: | variant
|
|
chans |
| Channels to use. 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 planes.
| |
| allowed: | string |
|
| Default: |
|
|
mask |
| Mask to use. Default is none.
| |
| allowed: | string |
|
| Default: | variant
|
|
stretch |
| Stretch the mask if necessary and possible? Default False
| |
| allowed: | bool |
|
| Default: | false |
|
wantreturn |
| Return an image analysis tool attached to the created
image?
| |
| allowed: | bool |
|
| Default: | true |
|
image
Example
ia.open("my_spectral_cube.im")
# create a pv image with the position axis running from ra, dec pixel positions of [45, 50] to [100, 120]
# in the input image
mypv = ia.pv(outfile="pv.im", start=[45,50], end=[100,120], wantreturn=true)
ia.done()
# analyze the pv image, such as get statistics
pvstats = mypv.statistics()
# when done, close the tool to release system resources
mypv.done()
# get the alternate coordinate system information
tb.open("pv.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