Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/impv.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 17:39 +0000
1##################### generated by xml-casa (v2) from impv.xml ######################
2##################### 9ab21b989585436ac77e0cb1c221919a ##############################
3from __future__ import absolute_import
4import numpy
5from casatools.typecheck import CasaValidator as _val_ctor
6_pc = _val_ctor( )
7from casatools.coercetype import coerce as _coerce
8from casatools.errors import create_error_string
9from .private.task_impv import impv as _impv_t
10from casatasks.private.task_logging import start_log as _start_log
11from casatasks.private.task_logging import end_log as _end_log
12from casatasks.private.task_logging import except_log as _except_log
14class _impv:
15 """
16 impv ---- Construct a position-velocity image by choosing two points in the direction plane.
18 --------- parameter descriptions ---------------------------------------------
20 imagename Name of the input image
21 outfile Output image name. If empty, no image is written.
22 mode If "coords", use start and end values. If "length", use center, length, and pa values.
23 start The starting pixel in the direction plane (array of two values).
24 end The ending pixel in the direction plane (array of two values).
25 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.
26 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.
27 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.
28 width Width of slice for averaging pixels perpendicular to the slice. Must be an odd positive integer or valid quantity. See help for details.
29 unit Unit for the offset axis in the resulting image. Must be a unit of angular measure.
30 overwrite Overwrite the output if it exists?
31 region Region selection. Default is entire image. No selection is permitted in the direction plane.
32 chans Channels to use. Channels must be contiguous. Default is to use all channels.
33 stokes Stokes planes to use. Planes must be contiguous. Default is to use all stokes.
34 mask Mask to use. Default is none.
35 stretch Stretch the mask if necessary and possible? Default False
36 [1;42mRETURNS[1;m image
38 --------- examples -----------------------------------------------------------
41 PARAMETER SUMMARY
42 imagename Name of the input (CASA, FITS, MIRIAD) image
43 outfile Name of output CASA image. Must be specified.
44 mode Indicates which sets of parameters to use for defining the slice. mode="coords" means use
45 start and end parameters. mode="length" means use center, length, and pa parameters to define
46 the slice.
47 start The starting pixel in the direction plane (array of two values), such as [20, 5] or ["14h20m20.5s","-30d45m25.4s"].
48 Used iff mode="coords".
49 end The ending pixel in the direction plane (array of two values), such as [200, 300].
50 Used iff mode="coords".
51 center The center of the slice in the direction plane (array of two values), such as [20, 5] or ["14h20m20.5s","-30d45m25.4s"].
52 Used iff mode="length".
53 length The length of the slice in the direction plane. May be specified as a single numerical value, in which
54 case it is interpreted as the number of pixels, or as a valid quantity which must be conformant with
55 the direction axes units (eg "40arcsec", {"value": 40, "unit": "arcsec"}).
56 Used iff mode="length".
57 pa Position angle of the slice, measured from the direction of positive latitude of the positive longitude
58 (eg north through east in an equatorial coordinate system). Must be expressed as a valid angular
59 quantity (eg "40deg", {"value": 40, "unit": "deg"}).
60 Used iff mode="length".
61 width Width of slice for averaging pixels perpendicular to the slice which must be an odd positive integer or
62 valid quantity. The averaging using this value occurs after the image has been rotated so the slice lies horizontally.
63 An integer value is interpreted as the number of pixels to average.
64 A value of 1 means no averaging. A value of 3 means average one pixel on each
65 side of the slice and the pixel on the slice. A value of 5 means average 2 pixels
66 on each side of the slice and the pixel on the slice, etc. If a quantity (eg. "4arcsec", qa.quantity("4arcsec"))
67 is specified, the equivalent number of pixels is calculated, and if necessary, rounded up
68 to the next odd integer.
69 unit Allows the user to set the unit for the angular offset axis. Must be a unit of angular
70 measure.
71 overwrite If output file is specified, this parameter controls if an already existing file by the
72 same name can be overwritten. If true, the user is not prompted, the file
73 if it exists is automatically overwritten.
74 region Region specification. Default is to not use a region. If specified,
75 the entire direction plane must be specified. If specified do not specify chans or stokes.
76 chans Optional contiguous frequency channel number specification. Default is all channels.
77 If specified, do not specify region.
78 stokes Contiguous stokes planes specification. If specified, do not specify region.
79 mask Mask to use. Default is none.
80 stretch Stretch the input mask if necessary and possible. Only used if a mask is specified.
83 Create a position-velocity image. The way the slice is specified is controlled by the mode parameter. When
84 mode="coords", start end end are used to specified the points between which a slice is taken in the direction
85 coordinate. If mode="length" center, pa (position angle), and length are used to specify the slice. The spectral
86 extent of the resulting image will be that provided by the region specification or the entire spectral range of
87 the input image if no region is specified. One may not specify a region in direction space; that is accomplished by
88 specifying the slice as described previously. The parameters start and end may be specified as two
89 element arrays of numerical values, in which case these values will be interpreted as pixel locations in the input
90 image. Alternatively, they may be expressed as arrays of two strings each representing the direction. These strings
91 can either represent quantities (eg ["40.5deg", "0.5rad") or be sexigesimal format (eg ["14h20m20.5s","-30d45m25.4s"],
92 ["14:20:20.5s","-30.45.25.4"]). In addition, they may be expressed as a single string containing the longitude-like and
93 latitude-like values and optionally a reference frame value, eg "J2000 14:20:20.5s -30.45.25.4".The center parameter can
94 be specified in the same way. The length parameter may be specified as a single numerical value, in which case it is
95 interpreted as the length in pixels, or a valid quantity, in which case it must have units conformant with the
96 direction axes units. The pa (position angle) parameter must be specified as a valid quantity with angular units.
97 The position angle is interpreted in the usual astronomical sense; eg measured from north through east in an equatorial
98 coordinate system. The slice in this case starts at the specified position angle and ends on the opposite side of
99 the specified center. Thus pa="45deg" means start at a point at a pa of 45 degrees relative to the specified center and
100 end at a point at a pa of 215 degrees relative to the center. Either start/end or center/pa/length must be specified;
101 if a parameter from one of these sets is specified, a parameter from the other set may not be specified. In either
102 case, the end points of the segment must fail within the input image, and they both must be at least 2 pixels from the
103 edge of the input image to facilite rotation (see below).
105 One may specify a width, which represents the number of pixels centered along and perpendicular
106 to the direction slice that are used for averaging along the slice. The width may be specified as an integer, in which
107 case it must be positive and odd. Alternatively, it may be specified as a valid quantity string (eg, "4arcsec") or
108 quantity record (eg qa.quantity("4arcsec"). In this case, units must be conformant to the direction axes units (usually
109 angular units) and the specified quantity will be rounded up, if necessary, to the next highest equivalent odd integer number
110 of pixels. The default value of 1 represents no averaging.
111 A value of 3 means average one pixel on each side of the slice and the pixel on the slice.
112 Note that this width is applied to pixels in the image after it has been rotated (see below for a description
113 of the algorithm used).
115 One may specify the unit for the angular offset axis.
117 Internally, the image is first rotated, padding if necessary to include relevant pixels that would otherwise
118 be excluded by the rotation operation, so that the slice is horizontal, with the starting pixel left of the
119 ending pixel. Then, the pixels within the specified width of the slice are averaged and the resulting image is
120 written and/or returned. The output image has a linear coordinate in place of the direction coordinate of the
121 input image, and the corresponding axis represents angular offset with the center pixel having a value of 0.
123 The equivalent coordinate system, with a (usually) rotated direction coordinate (eg, RA and Dec) is written
124 to the output image as a table record. It can be retrieved using the table tool as shown in the example below.
126 # create a pv image with the position axis running from ra, dec pixel positions of [45, 50] to [100, 120]
127 # in the input image
128 impv(imagename="my_spectral_cube.im", outfile="mypv.im", start=[45,50], end=[100,120])
129 # analyze the pv image, such as get statistics
130 pvstats = imstat("mypv.im")
131 #
132 # get the alternate coordinate system information
133 tb.open("mypv.im")
134 alternate_csys_record = tb.getkeyword("misc")["secondary_coordinates"]
135 tb.done()
139 """
141 _info_group_ = """analysis"""
142 _info_desc_ = """Construct a position-velocity image by choosing two points in the direction plane."""
144 def __call__( self, imagename='', outfile='', mode='coords', start='', end='', center='', length='', pa='', width=int(1), unit='arcsec', overwrite=False, region='', chans='', stokes='', mask='', stretch=False ):
145 schema = {'imagename': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'outfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'mode': {'type': 'cStr', 'coerce': _coerce.to_str}, 'start': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'end': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'center': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'length': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cFloat', 'coerce': _coerce.to_float}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, {'type': 'cInt'}, {'type': 'cDict'}]}, 'pa': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cDict'}]}, 'width': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cInt'}, {'type': 'cDict'}]}, 'unit': {'type': 'cStr', 'coerce': _coerce.to_str}, 'overwrite': {'type': 'cBool'}, 'region': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cDict'}]}, 'chans': {'type': 'cStr', 'coerce': _coerce.to_str}, 'stokes': {'type': 'cStr', 'coerce': _coerce.to_str}, 'mask': {'type': 'cStr', 'coerce': _coerce.to_str}, 'stretch': {'type': 'cBool'}}
146 doc = {'imagename': imagename, 'outfile': outfile, 'mode': mode, 'start': start, 'end': end, 'center': center, 'length': length, 'pa': pa, 'width': width, 'unit': unit, 'overwrite': overwrite, 'region': region, 'chans': chans, 'stokes': stokes, 'mask': mask, 'stretch': stretch}
147 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
148 _logging_state_ = _start_log( 'impv', [ 'imagename=' + repr(_pc.document['imagename']), 'outfile=' + repr(_pc.document['outfile']), 'mode=' + repr(_pc.document['mode']), 'start=' + repr(_pc.document['start']), 'end=' + repr(_pc.document['end']), 'center=' + repr(_pc.document['center']), 'length=' + repr(_pc.document['length']), 'pa=' + repr(_pc.document['pa']), 'width=' + repr(_pc.document['width']), 'unit=' + repr(_pc.document['unit']), 'overwrite=' + repr(_pc.document['overwrite']), 'region=' + repr(_pc.document['region']), 'chans=' + repr(_pc.document['chans']), 'stokes=' + repr(_pc.document['stokes']), 'mask=' + repr(_pc.document['mask']), 'stretch=' + repr(_pc.document['stretch']) ] )
149 task_result = None
150 try:
151 task_result = _impv_t( _pc.document['imagename'], _pc.document['outfile'], _pc.document['mode'], _pc.document['start'], _pc.document['end'], _pc.document['center'], _pc.document['length'], _pc.document['pa'], _pc.document['width'], _pc.document['unit'], _pc.document['overwrite'], _pc.document['region'], _pc.document['chans'], _pc.document['stokes'], _pc.document['mask'], _pc.document['stretch'] )
152 except Exception as exc:
153 _except_log('impv', exc)
154 raise
155 finally:
156 task_result = _end_log( _logging_state_, 'impv', task_result )
157 return task_result
159impv = _impv( )