Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/coordsys.py: 84%

1##################### generated by xml-casa (v2) from coordsys.xml ################## 

2##################### c2b79b049eed021d6e3447da1327c9c2 ############################## 

3from __future__ import absolute_import 

4from .__casac__.coordsys import coordsys as _coordsys 

5 

6from .errors import create_error_string 

7from .typecheck import CasaValidator as _validator 

8_pc = _validator( ) 

9from .coercetype import coerce as _coerce 

10_wrap_coordsys = lambda swig_object: coordsys(swig_object=swig_object) 

11 

12class coordsys: 

13 _info_group_ = """images""" 

14 _info_desc_ = """Operations on CoordinateSystems""" 

15 ### self 

16 def __init__(self, *args, **kwargs): 

17 """ 

18 """ 

19 self._swigobj = kwargs.get('swig_object',None) 

20 if self._swigobj is None: 

21 self._swigobj = _coordsys() 

22 

23 def newcoordsys(self, direction=False, spectral=False, stokes=[ ], linear=int(0), tabular=False): 

24 """By default, this constructor makes an empty Coordsys tool. You can ask 

25 it to include various sorts of coordinates through the arguments. 

26 Except for Stokes, you don't have any control over the coordinate 

27 contents (e.g. reference value etc.) it does make for you on request. 

28 But you can edit the Coordinate System after creation if you wish. 

29  

30 If you wish to make a Stokes coordinate, then you assign 

31 {stfaf stokes} to a string (or a vector of strings) saying 

32 which Stokes you want. casa allows rather 

33 a lot of potential Stokes types. 

34  

35 Probably most useful is some combination of the 

36 basic I, Q, U, V, XX, YY, XY, YX, RR, LL, RL, and LR. 

37  

38 However, a more esoteric choice is also possible: 

39 RX, RY, LX, LY, XR, XL, YR, YL (these are mixed 

40 linear and circular), PP, PQ, QP, QQ (general quasi-orthogonal correlation products) 

41 RCircular, LCircular, Linear (single dish polarization types). 

42  

43 You can also specify some polarization `Stokes' types: 

44 Ptotal (Polarized intensity ($(Q^2+U^2+V^2)^{1/2}$), 

45 Plinear (Linearly Polarized intensity ($(Q^2+U^2)^{1/2}$), 

46 PFtotal (Polarization Fraction (Ptotal/I)), 

47 PFlinear (Linear Polarization Fraction (Plinear/I)), and 

48 Pangle (Linear Polarization Angle ($0.5~arctan(U/Q)$ in radians)). 

49  

50 Probably you will find the more unusual types aren't fully 

51 supported throughout the system. 

52  

53 You can make a LinearCoordinate with as many uncoupled axes as you like. 

54 Thus, {stfaf linear=2} makes one LinearCoordinate with 2 axes (think 

55 of it like a DirectionCoordinate which also has 2 axes [but coupled in 

56 this case], a longitude and a latitude). 

57  

58 If you make a TabularCoordinate, it is linear to start with. 

59 You can change it to a non-linear one by providing 

60 a list of pixel and world values to function 

61 settabular. 

62 """ 

63 return _wrap_coordsys(swig_object=self._swigobj.newcoordsys(direction, spectral, stokes, linear, tabular)) 

64 

65 def addcoordinate(self, direction=False, spectral=False, stokes=[ ], linear=int(0), tabular=False): 

66 """Add default coordinates of the specified types. This function allows 

67 multiple coordinates of the same type which are not well supported. 

68 Use only for assay tests. 

69 """ 

70 return self._swigobj.addcoordinate(direction, spectral, stokes, linear, tabular) 

71 

72 def axesmap(self, toworld=True): 

73 """This function returns a vector describing the mapping from pixel to 

74 world or world to pixel axes. It is not for general user use. 

75  

76 See the htmlref{discussion}{COORDSYS:PWAXES} about pixel and world axis 

77 ordering. Generally they will be in the same order. 

78 """ 

79 return self._swigobj.axesmap(toworld) 

80 

81 def axiscoordinatetypes(self, world=True): 

82 """This function returns a vector string 

83 giving the coordinate type for each axis (world or pixel) 

84 in the Coordinate System. 

85  

86 See the htmlref{discussion}{COORDSYS:PWAXES} about pixel and world axis 

87 ordering. 

88 """ 

89 return self._swigobj.axiscoordinatetypes(world) 

90 

91 def conversiontype(self, type='direction'): 

92 """Some coordinates contain a reference code. Examples of reference codes 

93 are B1950 and J2000 for direction coordinates, or LSRK and BARY for 

94 spectral coordinates. When you do conversions between pixel and world 

95 coordinate, the coordinates are in the reference frame corresponding to 

96 these codes. 

97  

98 Function setconversiontype 

99 allows you to specify a different reference frame 

100 which is used when converting between world and pixel coordinate. 

101  

102 This function allows you to recover those conversion types. If no extra 

103 conversion layer has been set, you get back the native reference types. 

104 """ 

105 return self._swigobj.conversiontype(type) 

106 

107 def convert(self, coordin, absin=[ bool(True) ], dopplerin='radio', unitsin=[ 'Native' ], absout=[ bool(True) ], dopplerout='radio', unitsout=[ 'Native' ], shape=[ int(-1) ]): 

108 """This function converts between mixed pixel/world/abs/rel numeric 

109 coordinates. The input and output coordinates are specified via a 

110 numeric vector giving coordinate values, a string vector giving units, a 

111 boolean vector specifying whether the coordinate is absolute or relative 

112 (to the reference pixel) and doppler strings specifying the doppler 

113 convention for velocities. 

114  

115 The units string may include {cf pix} for pixel coordinates and 

116 velocity units (i.e. any unit consistent with {cf m/s}). 

117  

118 The allowed doppler strings and definition are described 

119 in function summary. 

120  

121 The {stfaf shape} argument is optional. If your Coordinate 

122 System is from an image, then assign the image shape to this 

123 argument. It is used only when making mixed (pixel/world) conversions 

124 for Direction Coordinates to resolve ambiguity. 

125  

126 The example clarifies the use of this function. 

127 """ 

128 return self._swigobj.convert(coordin, absin, dopplerin, unitsin, absout, dopplerout, unitsout, shape) 

129 

130 def convertdirection(self, frame): 

131 """Convert the direction coordinate in the coordinate system to the specified frame by 

132 rotating about the reference pixel so that the resulting coordinate axes are parallel 

133 to the cardinal directions. The resulting coordinate will not have a conversion layer, 

134 even if the input direction coordinate does. A conversion layer can be set after by 

135 running cs.setconversiontype(). Be aware that if you attach the resulting coordinate 

136 system to an image whose pixels have not been rotated around the reference pixel in 

137 the same manner, you will likely get an image for which the pixels do not match 

138 up to world coordinate values. This method should only be used by experienced users who 

139 know what they are doing. It was written originally to facilitate rotating the 

140 direction coordinate since the implementation of imregrid requires this in certain 

141 circumstances. The conversion is done in place; a new coordinate system tool is not 

142 created. The returned record represents an angular quantity through which the old 

143 direction coordinate was rotated to create the new coordinate. 

144  

145 """ 

146 return self._swigobj.convertdirection(frame) 

147 

148 def convertmany(self, coordin=[ ], absin=[ bool(True) ], dopplerin='radio', unitsin=[ 'Native' ], absout=[ bool(True) ], dopplerout='radio', unitsout=[ 'Native' ], shape=[ int(-1) ]): 

149 """This function converts between many mixed pixel/world/abs/rel numeric 

150 coordinates. See function convert 

151 for more information. 

152  

153 The only diffference with that function is that you 

154 provide a matrix holding many coordinates to convert 

155 and a matrix of many converted coordinates is returned. 

156 """ 

157 return self._swigobj.convertmany(coordin, absin, dopplerin, unitsin, absout, dopplerout, unitsout, shape) 

158 

159 def coordinatetype(self, which=int(-1)): 

160 """This function returns a string describing 

161 the type of the specified coordinate. If {stfaf which=unset} the types 

162 for all coordinates are returned. 

163  

164 Possible output values are 'Direction', 'Spectral', 'Stokes', 'Linear', and 

165 'Tabular' 

166 """ 

167 return self._swigobj.coordinatetype(which) 

168 

169 def copy(self): 

170 """This function returns a copy, not a reference, of the Coordsys tool. 

171 It is your responsibility to call the {stff done} function 

172 on the new tool. 

173 """ 

174 return _wrap_coordsys(swig_object=self._swigobj.copy()) 

175 

176 def done(self): 

177 """If you no longer need to use a Coordsys tool calling this function 

178 will free up its resources and restore the default coordsys tool. 

179 """ 

180 return self._swigobj.done() 

181 

182 def epoch(self): 

183 """This function returns the epoch of the observation as a 

184 Measure. 

185 """ 

186 return self._swigobj.epoch() 

187 

188 def findaxis(self, world=True, axis=int(0)): 

189 """This function finds the specified axis in 

190 the Coordinate System. If the axis does not exist, it throws an exception. 

191 """ 

192 return self._swigobj.findaxis(world, axis) 

193 

194 def findaxisbyname(self, axisname='', allowfriendlyname=True): 

195 """Find the world axis based on its name. Matching is not case sensitive and minimal match is supported, eg "dec" will match "Declination". 

196 In addition, if allowfriendlyname is True, other common terms will match the expected axis. Currently supported are: 

197 "spectral" matches frequency type axes, eg "Frequency" or "Velocity", 

198 "ra" matches "Right Ascension". These names must be spelled out completely; eg "spectral" rather than simply "spec". 

199 The first matching axis (zero-based) number is returned. If no axis can be matched, an exception is thrown. 

200  

201 """ 

202 return self._swigobj.findaxisbyname(axisname, allowfriendlyname) 

203 

204 def findcoordinate(self, type='direction', which=int(0)): 

205 """This function finds the axes in the 

206 Coordinate System for the specified coordinate (minimum match is active 

207 for argument {stfaf type}). By default it finds the first coordinate, 

208 but if there is more than one (can happen for linear coordinates), you 

209 can specify which. It returns a dictionary with 'return', 'pixel', and 

210 'world' as keys. The associated value of 'return' is a boolean indicating if 

211 the specified coordinate was found. The values of 'pixel' and 'world' are 

212 arrays indicating the indices of the associated pixel and world axes, respectively, 

213 of the specified coordinate. If the coordinate does not exist, these arrays 

214 will be empty. 

215  

216 See also the function axesmap 

217 which returns the mapping between pixel and world axes. 

218 """ 

219 return self._swigobj.findcoordinate(type, which) 

220 

221 def frequencytofrequency(self, value, frequnit='', velocity=[ ]): 

222 """This function converts frequencies to frequencies by applying a 

223 relativistic Doppler shift: 

224 fout = fin * sqrt((1.-v/c)/(1.+v/c)) . 

225  

226 The input frequencies are specified via a vector of numeric values and 

227 a specified unit ({stfaf frequnit}). If you don't give a frequency 

228 unit, it is assumed that the units are those given by function coordsys units() for 

229 the spectral coordinate. 

230  

231 This function does not make any frame conversions (e.g. LSR to BARY). 

232  

233 This function fails if there is no spectral coordinate 

234 in the Coordinate System. See also function 

235 frequencytovelocity. 

236 """ 

237 return self._swigobj.frequencytofrequency(value, frequnit, velocity) 

238 

239 def frequencytovelocity(self, value, frequnit='', doppler='radio', velunit='km/s'): 

240 """This function converts frequencies to 

241 velocities. 

242  

243 The input frequencies are specified via a vector of numeric values and 

244 a specified unit ({stfaf frequnit}). If you don't give a frequency 

245 unit, it is assumed that the units are those given by function coordsys units() for 

246 the spectral coordinate. 

247  

248 This function does not make any frame conversions (e.g. LSR to BARY) 

249 but you can specifiy the velocity doppler definition via the {stfaf 

250 doppler} argument (see image summary() for 

251 possible values). 

252  

253 The velocities are returned in a vector for which you specify the 

254 units ({stfaf velunit} - default is km/s). 

255  

256 This function will return a fail if there is no spectral coordinate 

257 in the Coordinate System. See also function 

258 velocitytofrequency. 

259 """ 

260 return self._swigobj.frequencytovelocity(value, frequnit, doppler, velunit) 

261 

262 def fromrecord(self, record): 

263 """You can convert a Coordinate System to a record 

264 (torecord). This function 

265 (fromrecord) allows you to set the contents of an existing Coordinate 

266 System from such a record. In doing so, you overwrite its current 

267 contents. 

268 """ 

269 return self._swigobj.fromrecord(record) 

270 

271 def increment(self, format='n', type=''): 

272 """Each axis associated with the Coordinate System has a reference value, 

273 reference pixel and an increment (per pixel). These are used in the 

274 mapping from pixel to world coordinate. 

275  

276 This function returns the increment (in 

277 world axis order). You can recover the increments either for all 

278 coordinates (leave {stfaf type} unset) or for a specific coordinate 

279 type (mimumum match of the allowed types will do). If you ask for a 

280 non-existent coordinate an exception is generated. 

281  

282 See the htmlref{discussion}{COORDSYS:FORMATTING} regarding the 

283 formatting possibilities available via argument {stfaf format}. 

284  

285 You can set the increment with function 

286 setincrement. 

287 """ 

288 return self._swigobj.increment(format, type) 

289 

290 def lineartransform(self, type): 

291 """Recover the linear transform component for the specified coordinate type. 

292  

293 You can set the linear transform with function 

294 setlineartransform. 

295 """ 

296 return self._swigobj.lineartransform(type) 

297 

298 def names(self, type=''): 

299 """Each axis associated with the Coordinate System has a name (they don't 

300 mean anything fundamental). This function returns those names in 

301 world axis order. 

302  

303 You can recover the names either for all coordinates (leave {stfaf 

304 type} unset) or for a specific coordinate type (mimumum match of the 

305 allowed types will do). If you ask for a non-existent coordinate an 

306 exception is generated. 

307  

308 You can set the names with function 

309 setnames. 

310 """ 

311 return self._swigobj.names(type) 

312 

313 def naxes(self, world=True): 

314 """Find the number of axes in the Coordinate System. 

315  

316 You may find the number of world or pixel axes; these are generally the 

317 same and general users can ignore the distinction. See the 

318 htmlref{discussion}{COORDSYS:PWAXES} about pixel and world axis 

319 ordering. 

320 """ 

321 return self._swigobj.naxes(world) 

322 

323 def ncoordinates(self): 

324 """This function recovers the number of 

325 coordinates in the Coordinate System. 

326 """ 

327 return self._swigobj.ncoordinates() 

328 

329 def observer(self): 

330 """This function returns the name of the observer. 

331 You can set it with the function setobserver. 

332 """ 

333 return self._swigobj.observer() 

334 

335 def projection(self, type=''): 

336 """If the Coordinate System contains a direction coordinate, this function 

337 can be used to recover information about the 

338 projection. For discussion about celestial coordinate systems, 

339 including projections, see the papers by Mark Calabretta and Eric 

340 Greisen. The initial draft from 1996 (implemented in 

341 casa. Background information can be 

342 found 

343 htmladdnormallink{here}{http://www.atnf.csiro.au/people/mark.calabretta/WCS}. 

344  

345 What this function returns depends upon the value 

346 you assign to {stfaf type}. 

347  

348 begin{itemize} 

349  

350 item {stfaf type=unset}. In this case (the default), the actual 

351 projection type and projection parameters are returned in a 

352 record with fields {cf type} and {cf parameters}, respectively. 

353  

354 item {stfaf type='all'}. In this case, a vector of strings 

355 containing all of the possible projection codes is returned. 

356  

357 item {stfaf type=code}. If you specify a valid 

358 projection type code (see list by setting {stfaf type='all'}) 

359 then what is returned is the number of parameters required 

360 to describe that projection (useful in function 

361 setprojection). 

362  

363 end{itemize} 

364  

365 You can change the projection with 

366 setprojection. 

367  

368 If the Coordinate System does not contain a direction coordinate, 

369 an exception is generated. 

370 """ 

371 return self._swigobj.projection(type) 

372 

373 def referencecode(self, type='', list=False): 

374 """This function returns the reference code 

375 for all, or the specified coordinate type. Examples of the reference 

376 code are B1950 and J2000 for direction coordinates, or LSRK and BARY for 

377 spectral coordinates. 

378  

379 If {stfaf type} is left unset, then a vector of strings is returned, 

380 one code for each coordinate type in the Coordinate System. 

381  

382 If you specify {stfaf type} then select from 

383 'direction', 'spectral', 'stokes', and 'linear' 

384 (the first two letters will do). However, only the first two 

385 coordinate types will return a non-empty string. 

386 If the Coordinate System does not contain a coordinate of 

387 the type you specify, an exception is generated. 

388  

389 The argument {stfaf list} is ignored unless you specify a specific {stfaf type}. 

390 If {stfaf list=T}, then this function returns the list of all possible 

391 reference codes for the specified coordinate type. Otherwise, it just 

392 returns the actual code current set in the Coordinate System. 

393  

394 The list of all possible types is returned as a record (it is 

395 actually generated by the 

396 listcodes function in the 

397 measures system). This record has two 

398 fields. These are called 'normal' 

399 (containing all normal codes) and 'extra' (maybe empty, with all extra 

400 codes like planets). 

401  

402 You can set the reference code with 

403 setreferencecode. 

404 """ 

405 return self._swigobj.referencecode(type, list) 

406 

407 def referencepixel(self, type=''): 

408 """Each axis associated with the Coordinate System has a reference value, 

409 reference pixel and an increment (per pixel). These are used in the 

410 mapping from pixel to world coordinate. 

411  

412 This function returns the reference pixel 

413 (in pixel axis order). You can recover the reference pixel either for 

414 all coordinates (leave {stfaf type} unset) or for a specific coordinate 

415 type (mimumum match of the allowed types will do). If you ask for a 

416 non-existent coordinate an exception is generated. 

417  

418 You can set the reference pixel with function 

419 setreferencepixel. 

420 """ 

421 return self._swigobj.referencepixel(type) 

422 

423 def referencevalue(self, format='n', type=''): 

424 """Each axis associated with the Coordinate System has a reference value, 

425 reference pixel and an increment (per pixel). These are used in the 

426 mapping from pixel to world coordinate. 

427  

428 This function returns the reference value 

429 (in world axis order). You can recover the reference value either for all 

430 coordinates (leave {stfaf type} unset) or for a specific coordinate 

431 type (mimumum match of the allowed types will do). If you ask for a 

432 non-existent coordinate an exception is generated. 

433  

434 See the htmlref{discussion}{COORDSYS:FORMATTING} regarding the 

435 formatting possibilities available via argument {stfaf format}. 

436  

437 You can set the reference value with function 

438 setreferencevalue. 

439 """ 

440 return self._swigobj.referencevalue(format, type) 

441 

442 def reorder(self, order): 

443 """This function reorders the coordinates in the Coordinate System. 

444 You specify the new order of the coordinates in terms of their old 

445 order. 

446 """ 

447 return self._swigobj.reorder(order) 

448 

449 def transpose(self, order): 

450 """This method transposes the axes (both world and pixel) in the coordinate system. 

451 You specify the new order of the axes in terms of their old 

452 order, so eg order=[1,0,3,2] means reorder the axes so that the zeroth 

453 axis becomes the first axis, the first axis becomes the zeroth axis, 

454 the second axis becomes the third axis, and the third axis becomes the 

455 second axis. 

456 """ 

457 return self._swigobj.transpose(order) 

458 

459 def replace(self, csys, whichin, whichout): 

460 """This function replaces one coordinate in the current Coordinate System by 

461 one coordinate in the given Coordinate System. The specified 

462 coordinates must have the same number of axes. 

463 """ 

464 return self._swigobj.replace(csys, whichin, whichout) 

465 

466 def restfrequency(self): 

467 """If the Coordinate System contains a spectral coordinate, then 

468 it has a rest frequency. In fact, the spectral coordinate 

469 can hold several rest frequencies (to handle for example, 

470 an observation where the band covers many lines), although 

471 only one is active (for velocity conversions) at a time. 

472  

473 This function recovers the rest frequencies 

474 as a quantity vector. The first frequency is the active one. 

475  

476 You can change the rest frequencies with 

477 setrestfrequency. 

478  

479 If the Coordinate System does not contain a frequency coordinate, 

480 an exception is generated. 

481 """ 

482 return self._swigobj.restfrequency() 

483 

484 def setconversiontype(self, direction='', spectral=''): 

485 """Some coordinates contain a reference code. Examples of reference codes 

486 are B1950 and J2000 for direction coordinates, or LSRK and BARY for 

487 spectral coordinates. When you do conversions between pixel and world 

488 coordinate, the coordinates are in the reference frame corresponding to 

489 these codes. 

490  

491 This function allows you to specify a different reference frame which 

492 is used when converting between world and pixel coordinate (see 

493 function conversiontype 

494 to recover the conversion types). If it returns F, it means that 

495 although the conversion machines were successfully created, a trial 

496 conversion failed. This usually means the REST frame was involved 

497 which requires a radial velocity (not yet implemented). If this 

498 happens, the conversion type will be left as it was. The function 

499 fails if more blatant things are wrong like a missing coordinate, or 

500 an incorrect reference code. 

501  

502 The list of possible reference codes can be obtained via function 

503 referencecode. 

504  

505 With this function, you specify the desired reference code. Then, 

506 when a conversion between pixel and world is requested, an extra 

507 conversion is done to ({stff toWorld}) or from ({stff toPixel}) the 

508 specified reference frame. 

509  

510 The summary 

511 function shows the extra conversion reference system to the right of 

512 the native reference system (if it is different) and in parentheses. 

513  

514 Note that to convert between different spectral reference frames, you 

515 need a position, epoch and direction. The position (telescope) and 

516 epoch (date of observation), if not in your coordinate system can be set 

517 with functions settelescope and 

518 setepoch. The direction is the 

519 reference direction of the {it required} direction coordinate in the 

520 coordinate system. 

521  

522 bigskipgoodbreak 

523 As an example, let us say you are working with a spectral coordinate 

524 which was constructed with the LSRK reference frame. You want to convert 

525 some pixel coordinates to barycentric velocities (reference code BARY). 

526  

527 begin{verbatim} 

528  

529 # 

530 print "t----t setconversiontype Ex 1 t----" 

531 csys = cs.newcoordsys(direction=True, spectral=True); # Create coordinate system 

532 rtn=csys.findcoordinate('spectral') # Find spectral coordinate 

533 wa=rtn['world'] 

534 pa=rtn['pixel'] 

535 u = csys.units()[wa] # Spectral unit 

536 print csys.referencecode(type='spectral') # Which is in LSRK reference frame 

537 #LSRK 

538 p = [10,20,30] 

539 w = csys.toworld(p, format='n') # Convert a pixel to LSRK world 

540 print 'pixel, world = ', p, w['numeric'] 

541 #pixel, world = [10, 20, 30] [21589.999816660376, 20.000112822985134, 1415030000.0] 

542 p2 = csys.topixel(w) # and back to pixel 

543 print 'world, pixel = ', w['numeric'], p2 

544 #world, pixel = [21589.999816660376, 20.000112822985134, 1415030000.0] 

545 # [10.00000000000248, 19.999999999999801, 30.0] 

546 # Convert LSRK frequency to LSRK velocity 

547 v = csys.frequencytovelocity(value=w['numeric'][wa], frequnit=u, 

548 doppler='RADIO', velunit='m/s'); 

549 print 'pixel, frequency, velocity = ', p[pa], w['numeric'][wa], v 

550 #pixel, frequency, velocity = 30 1415030000.0 1134612.30321 

551 csys.setconversiontype(spectral='BARY') # Specify BARY reference code 

552 w = csys.toworld(p, format='n') # Convert a pixel to BARY world 

553 print 'pixel, world = ', p, w['numeric'] 

554 #pixel, world = [10, 20, 30] [21589.999816660376, 20.000112822985134, 1415031369.0081882] 

555 p2 = csys.topixel(w) # and back to pixel 

556 print 'world, pixel = ', w['numeric'], p2 

557 #world, pixel = [21589.999816660376, 20.000112822985134, 1415031369.0081882] 

558 # [10.00000000000248, 19.999999999999801, 30.0] 

559 # Convert BARY frequency to BARY velocity 

560 v = csys.frequencytovelocity(value=w['numeric'][wa], frequnit=u, 

561 doppler='RADIO', velunit='m/s'); 

562 print 'pixel, frequency, velocity = ', p[pa], w['numeric'][wa], v 

563 #pixel, frequency, velocity = 30 1415031369.01 1134323.35878 

564 # 

565  

566 end{verbatim} 

567  

568  

569 You must also be aware of when this extra layer is active and when it is 

570 not. It's a bit nasty. 

571  

572 begin{itemize} 

573  

574 item - Whenever you use {stff toWorld}, {stff toPixel} 

575 {stff toWorldMany}, or {stff toPixelMany} the layer is active. 

576  

577 item - Whenever you use {stff convert} or {stff convertMany} 

578 the layer {it may} be active. Here are the rules ! 

579  

580 It is only relevant to spectral and direction coordinates. 

581  

582 For the direction coordinate part of your conversion, if you request a 

583 pure world or pixel conversion it is active. Any pixel/world mix will 

584 not invoke it (because it is ill defined). 

585  

586 For the spectral coordinate part it is always active (only one axis 

587 so must be pixel or world). 

588  

589 item - This layer is irrelevant to all functions converting between 

590 frequency and velocity, and absolute and relative. The values are in 

591 whatever frame you are working with. 

592  

593 end{itemize} 

594  

595 The summary function 

596 lists the reference frame for direction and spectral coordinates. If 

597 you have also set a conversion reference code it also lists that (to 

598 the right in parentheses). 

599 """ 

600 return self._swigobj.setconversiontype(direction, spectral) 

601 

602 def getconversiontype(self, type='', showconversion=True): 

603 """See conversiontype for more complete description. 

604 """ 

605 return self._swigobj.getconversiontype(type, showconversion) 

606 

607 def setdirection(self, refcode='', proj='', projpar=[ float(-1) ], refpix=[ float(-1) ], refval=[ ], incr=[ ], xform=[ ], poles=[ ]): 

608 """When you construct a Coordsys tool, if you include a Direction 

609 Coordinate, it will have some default parameters. 

610 This function simply allows you to 

611 replace the values of the Direction Coordinate. 

612  

613 You can also change almost all of those parameters (such as projection, reference value 

614 etc.) via the individual functions 

615 setreferencecode, 

616 setprojection, 

617 setreferencepixel, 

618 setreferencevalue, 

619 setincrement, and 

620 setlineartransform 

621 provided by the Coordsys tool. See those functions for more details 

622 about the formatting of the above function arguments. 

623  

624 Bear in mind, that if your Coordinate System came from a real image, then 

625 the reference pixel is special and you should not change it. 

626 """ 

627 return self._swigobj.setdirection(refcode, proj, projpar, refpix, refval, incr, xform, poles) 

628 

629 def setepoch(self, value): 

630 """This function sets a new epoch (supplied as an 

631 epoch measure) of the observation. You 

632 can get the current epoch with function 

633 epoch. 

634 """ 

635 return self._swigobj.setepoch(value) 

636 

637 def setincrement(self, value=[ ], type=''): 

638 """Each axis associated with the Coordinate System has a reference value, 

639 reference pixel and an increment (per pixel). These are used in the 

640 mapping from pixel to world coordinate. 

641  

642 This function allows you to set a new 

643 increment. You should not do this on "stokes" axes unless you are an 

644 adept or a big risk taker. 

645  

646 You can set the increments either for all axes ({stfaf 

647 type=unset}) or for just the axes associated with a particular 

648 coordinate type. 

649  

650 You may supply the increments in all of the formats described in 

651 the htmlref{formatting}{COORDSYS:FORMATTING} discussion. 

652  

653 In addition, you can also supply the increments as a quantity of vector 

654 of doubles. For example {stfaf qa.quantity([-1,2],'arcsec')}. 

655  

656 You can recover the current increments with function 

657 increment. 

658 """ 

659 return self._swigobj.setincrement(value, type) 

660 

661 def setlineartransform(self, type='', value=[ ]): 

662 """This function set the linear transform component. For Stokes Coordinates 

663 this function will return T but do nothing. 

664  

665 You can recover the current linear transform with function 

666 lineartransform. 

667 """ 

668 return self._swigobj.setlineartransform(type, value) 

669 

670 def setnames(self, value, type=''): 

671 """Each axis associated with the Coordinate System has a name. 

672 It isn't used in any fundamental way. 

673  

674 This function allows you to set 

675 new axis names. 

676  

677 You can set the names either for all axes ({stfaf 

678 type=unset}) or for just the axes associated with a particular 

679 coordinate type. 

680  

681 You can recover the current axis names with function 

682 names. 

683 """ 

684 return self._swigobj.setnames(value, type) 

685 

686 def setobserver(self, value): 

687 """If you want to grab all the glory, or transfer the blame, this function 

688 sets a new observer of the 

689 observation. You can get the current observer with function observer. The 

690 observer's name is not fundamental to the Coordinate System ! 

691 """ 

692 return self._swigobj.setobserver(value) 

693 

694 def setprojection(self, type, parameters=[ float(-1) ]): 

695 """If the Coordinate System contains a direction coordinate, this 

696 function can be used to set the 

697 projection. For discussion about celestial coordinate systems, 

698 including projections, see the papers by Mark Calabretta and Eric 

699 Greisen. The initial draft from 1996 (implemented in casa) can be 

700 found 

701 htmladdnormallink{here}{http://www.atnf.csiro.au/people/mark.calabretta/WCS}. 

702  

703 You can use the function projection 

704 to find out all the possible types of projection. You can also use it 

705 to find out how many parameters you need to describe a particular 

706 projection. See Calabretta and Greisen for details about those 

707 parameters (see section 4 of their paper); in FITS terms these 

708 parameters are what are labelled as PROJP. 

709  

710 Some brief help here on the more common projections in astronomy. 

711  

712 begin{itemize} 

713  

714 item SIN has either 0 parameters or 2. For coplanar arrays like 

715 East-West arrays, one can use what is widely termed the NCP projection. 

716 This is actually a SIN projection where the parameters are 0 and 

717 $1/tan(delta_0)$ where $delta_0$ is the reference declination. Images 

718 made from the ATNF's Compact Array with casa will have such a 

719 projection. Otherwise, the SIN projection requires no parameters (but 

720 you can give it two each of which is zero if you wish). 

721  

722 item TAN is used widely in optical astronomy. It requires 0 

723 parameters. 

724  

725 item ZEA (zenithal equal area) is used widely in survey work. 

726 It requires 0 parameters. 

727  

728 end{itemize} 

729  

730 If the Coordinate System does not contain a direction coordinate, 

731 an exception is generated. 

732 """ 

733 return self._swigobj.setprojection(type, parameters) 

734 

735 def setreferencecode(self, value, type='direction', adjust=True): 

736 """This function sets the reference 

737 code for the specified coordinate type. Examples of reference codes 

738 are B1950 and J2000 for direction coordinates, or LSRK and BARY for 

739 spectral coordinates. 

740  

741 You must specify {stfaf type}, selecting from 'direction', or 

742 'spectral' (the first two letters will do). If the Coordinate System 

743 does not contain a coordinate of the type you specify, an exception is 

744 generated. 

745  

746 Specify the new code with argument {stfaf value}. To see the list of 

747 possible codes, use the function referencecode 

748 (see example). 

749  

750 If {stfaf adjust} is T, then the reference value is recomputed. 

751 This is invariably the correct thing to do. If {stfaf adjust} is F, 

752 then the reference code is simply overwritten; do this very carefully. 

753 """ 

754 return self._swigobj.setreferencecode(value, type, adjust) 

755 

756 def setreferencelocation(self, pixel=[ int(-1) ], world=[ ], mask=[ bool(False) ]): 

757 """This function sets the reference pixel and 

758 reference value to the specified values. The world coordinate can be 

759 specified in any of the formats that the output world coordinate is 

760 returned in by the toworld function. 

761  

762 You can specify a mask (argument {stfaf mask}) indicating which pixel 

763 axes are set (T) and which are left unchanged (F). This function will 

764 refuse to change the reference location of a Stokes axis (gets you into 

765 trouble otherwise). 

766  

767 This function can be rather useful when regridding 

768 images. It allows you to keep easily a particular feature centered in the 

769 regridded image. 

770 """ 

771 return self._swigobj.setreferencelocation(pixel, world, mask) 

772 

773 def setreferencepixel(self, value, type=''): 

774 """Each axis associated with the Coordinate System has a reference value, 

775 reference pixel and an increment (per pixel). These are used in the 

776 mapping from pixel to world coordinate. 

777  

778 This function allows you to set a new reference pixel. You should not 

779 do this on "stokes" axes unless you are an adept or a big risk taker. 

780  

781 You can set the reference pixel either for all axes ({stfaf 

782 type=unset}) or for just the axes associated with a particular 

783 coordinate type. 

784  

785 Bear in mind, that if your Coordinate System came from a real image, 

786 then the reference pixel is special and you should not change it for 

787 Direction Coordinates. 

788  

789 You can recover the current reference pixel with function 

790 referencepixel. 

791 """ 

792 return self._swigobj.setreferencepixel(value, type) 

793 

794 def setreferencevalue(self, value=[ ], type=''): 

795 """Each axis associated with the Coordinate System has a reference value, 

796 reference pixel and an increment (per pixel). These are used in the 

797 mapping from pixel to world coordinate. 

798  

799 This function allows you to set a new 

800 reference value. You should not do this on "stokes" axes unless you 

801 are an adept or a big risk taker. 

802  

803 You may supply the reference value in all of the formats described in 

804 the htmlref{formatting}{COORDSYS:FORMATTING} discussion. 

805  

806 You can recover the current reference value with function 

807 referencevalue. 

808  

809 Note that the value argument should be one of the specified 

810 possibilitioes. Especially a {stff measure} will be accepted, but 

811 will have a null effect, due to the interpretation as a generic 

812 record. 

813 """ 

814 return self._swigobj.setreferencevalue(value, type) 

815 

816 def setrestfrequency(self, value=[ ], which=int(0), append=False): 

817 """If the Coordinate System contains a spectral coordinate, then 

818 it has a rest frequency. In fact, the spectral coordinate 

819 can hold several rest frequencies (to handle for example, 

820 an observation where the band covers many lines), although 

821 only one is active (for velocity conversions) at a time. 

822  

823 This function allows you to set new rest 

824 frequencies. You can provide the rest frequency as a quantity, or as 

825 a quantity string, or a double (units of current rest frequency assumed). 

826  

827 You specify whether the list of frequencies will be appended 

828 to the current list or whether it will replace that list. 

829 You must select which of the frequencies will become the active 

830 one. By default its the first in the list. The index refers 

831 to the final list (either appended or replaced). 

832  

833 You can recover the current rest frequencies with 

834 restfrequency. 

835  

836 If the Coordinate System does not contain a frequency coordinate, 

837 an exception is generated. 

838 """ 

839 return self._swigobj.setrestfrequency(value, which, append) 

840 

841 def setspectral(self, refcode='', restfreq=[ ], frequencies=[ ], doppler='', velocities=[ ]): 

842 """When you construct a Coordsys tool, if you include a Spectral Coordinate, it 

843 will be linear in frequency. This function allows you to replace the 

844 Spectral Coordinate by a finite table of values. Coordinate 

845 conversions between pixel and world are then done by interpolation. 

846  

847 You may specify either a vector of frequencies or velocities. If you specify 

848 frequencies, you can optionally specify a (new) reference code (see 

849 function setreferencecode 

850 for more details) and rest frequency (else the existing ones will be used). 

851  

852 If you specify velocities, you can optionally specify a (new) reference code 

853 and rest frequency (else the existing ones will be used). You must also give 

854 the doppler type (see 

855 function summary for more 

856 details). The velocities are then converted to frequency for creation of the 

857 Spectral Coordinate (which is fundamentally described by frequency). 

858  

859 You may specify the rest frequency as a Quantum or a double (native units 

860 of Spectral Coordinate used). 

861 """ 

862 return self._swigobj.setspectral(refcode, restfreq, frequencies, doppler, velocities) 

863 

864 def setstokes(self, stokes): 

865 """If the Coordinate System contains a Stokes Coordinate, this function allows 

866 you to change the Stokes types defining it. If there is no Stokes 

867 Coordinate, an exception is generated. 

868  

869 See the coordsys constructor 

870 to see the possible Stokes types you can set. 

871  

872 You can set the Stokes types with function 

873 setstokes. 

874 """ 

875 return self._swigobj.setstokes(stokes) 

876 

877 def settabular(self, pixel=[ float(-1) ], world=[ float(-1) ], which=int(0)): 

878 """When you construct a Coordsys tool, if you include a Tabular 

879 Coordinate, it will be linear. This function allows you to replace the 

880 Tabular Coordinate by a finite table of values. Coordinate conversions 

881 between pixel and world are then done by interpolation (or extrapolation 

882 beyond the end). The table of values must be at least of length 2 

883 or an exception will occur. 

884  

885 You may specify a vector of pixel and world values (in the current units 

886 of the Tabular Coordinate). These vectors must be the same length. If 

887 you leave one of them unset, then the old values are used, but again, 

888 ultimately, the pixel and world vectors must be the same length. 

889  

890 The new reference pixel will be the first pixel value. 

891 The new reference value will be the first world value. 

892  

893 Presently, there is no way for you to recover the lookup table 

894 once you have set it. 

895  

896 If you have more than one Tabular Coordinate, use argument 

897 {stfaf which} to specify which one you want to modify. 

898 """ 

899 return self._swigobj.settabular(pixel, world, which) 

900 

901 def settelescope(self, value): 

902 """This function sets a new telescope of the observation. The telescope 

903 position may be needed for reference code conversions; this is why it is 

904 maintained in the Coordinate System. So it is fundamental 

905 to the Coordinate System and should be correct. 

906  

907 You can find a list of the observatory names know to casa with the 

908 Measures obslist function. 

909  

910 You can get the current telescope with function 

911 telescope. 

912 """ 

913 return self._swigobj.settelescope(value) 

914 

915 def setunits(self, value, type='', overwrite=False, which=int(-10)): 

916 """Each axis associated with the Coordinate System has a unit. This 

917 function allows you to set new axis units. 

918  

919 You can set the units either for all axes ({stfaf 

920 type=unset}) or for just the axes associated with a particular 

921 coordinate type. 

922  

923 In general, the units must be consistent with the old units. When you 

924 change the units, the increment and reference value will be adjusted 

925 appropriately. However, for a linear or tabular coordinate, and only 

926 when you specify {stfaf type='linear'} or {stfaf type='tabular'} 

927 (i.e. you supply units only for the specified linear of tabular 

928 coordinate), and if you set {stfaf overwrite=T}, you can just overwrite 

929 the units with no further adjustments. Otherwise, the {stfaf 

930 overwrite} argument will be silently ignored. Use argument 

931 {stfaf which} to specify which coordinate if you have more 

932 than one of the specified type. 

933  

934 You can recover the current axis units with function 

935 units. 

936 """ 

937 return self._swigobj.setunits(value, type, overwrite, which) 

938 

939 def stokes(self): 

940 """If the Coordinate System contains a Stokes Coordinate, this function recovers the 

941 Stokes types defining it. If there is no Stokes 

942 Coordinate, an exception is generated. 

943  

944 You can set the Stokes types with function 

945 setstokes. 

946 """ 

947 return self._swigobj.stokes() 

948 

949 def summary(self, doppler='RADIO', list=True): 

950 """This function summarizes the information 

951 contained in the Coordinate System. 

952  

953 For spectral coordinates, the information is listed as a velocity as well as a 

954 frequency. The argument {stfaf doppler} allows you to specify what 

955 doppler convention it is listed in. You can choose from {stfaf radio, 

956 optical} and {stfaf beta}. Alternative names are {stfaf z} for 

957 {stfaf optical}, and {stfaf relativistic} for {stfaf 

958 beta}. The default is {stfaf radio}. The definitions are 

959  

960 begin{itemize} 

961 item radio: $1 - F$ 

962 item optical: $-1 + 1/F$ 

963 item beta: $(1 - F^2)/(1 + F^2)$ 

964 end{itemize} 

965 where $F = nu/nu_0$ and $nu_0$ is the rest frequency. If the rest 

966 frequency has not been set in your image, you can set it with 

967 the function setrestfrequency. 

968  

969 These velocity definitions are provided by the measures 

970 system via the Doppler measure (see example). 

971  

972 If you set {stfaf list=F}, then the summary will not be written 

973 to the global logger. However, the return value will be a vector of strings 

974 holding the summary information, one string per line of the summary. 

975  

976 For direction and spectral coordinates, the reference frame (e.g. J2000 

977 or LSRK) is also listed. Along side this, in parentheses, will be the 

978 conversion reference frame as well (if it is different from the native 

979 reference frame). See function 

980 setconversion to see what this 

981 means. 

982 """ 

983 return self._swigobj.summary(doppler, list) 

984 

985 def telescope(self): 

986 """This function returns the telescope 

987 contained in the Coordinate System as a 

988 simple string. 

989  

990 The telescope position may be needed for reference code conversions; this is 

991 why it is maintained in the Coordinate System. 

992  

993 The conversion from string to position is done with 

994 Measures observatory. 

995 The example shows how. 

996 """ 

997 return self._swigobj.telescope() 

998 

999 def toabs(self, value=[ ], isworld=int(-1)): 

1000 """This function converts a relative coordinate to an absolute coordinate. 

1001 The coordinate may be a pixel coordinate or a world coordinate. 

1002  

1003 If the coordinate is a pixel coordinate, it is supplied as a numeric 

1004 vector. If the coordinate is a world coordinate, you may give it in all 

1005 of the formats described in the 

1006 htmlref{formatting}{COORDSYS:FORMATTING} discussion. 

1007  

1008 If the coordinate value is supplied by a Coordsys tool function (e.g. 

1009 toworld) then the coordinate 'knows' 

1010 whether it is world or pixel (and absolute or relative). However, you 

1011 might supply the value from some other source as a numeric vector (which 

1012 could be world or pixel) in which case you must specify whether it is a 

1013 world or pixel coordinate via the {stfaf isworld} argument. 

1014 """ 

1015 return self._swigobj.toabs(value, isworld) 

1016 

1017 def toabsmany(self, value=[ ], isworld=int(-1)): 

1018 """This function converts many relative coordinates to absolute. It exists 

1019 so you can efficiently make many conversions (which would be rather slow 

1020 if you did them all with toabs). Because 

1021 speed is the object, the interface is purely in terms of numeric 

1022 matrices, rather than being able to accept strings and quanta etc. like 

1023 toabs can. 

1024  

1025 When dealing with world coordinates, the units of the numeric 

1026 values must be the native units, given by function 

1027 units. 

1028 """ 

1029 return self._swigobj.toabsmany(value, isworld) 

1030 

1031 def topixel(self, value=[ ]): 

1032 """This function converts between world (physical) coordinate and absolute pixel 

1033 coordinate (0-rel). 

1034  

1035 The world coordinate can be provided in one of four formats via the 

1036 argument {stfaf world}. These match the output formats of function 

1037 toworld. 

1038  

1039 If you supply fewer world values than there are axes in the Coordinate 

1040 System, your coordinate vector will be padded out with the reference 

1041 value for the missing axes. Excess values will be silently ignored. 

1042  

1043 You may supply the world coordinate in all of the formats described in 

1044 the htmlref{formatting}{COORDSYS:FORMATTING} discussion. 

1045 """ 

1046 return self._swigobj.topixel(value) 

1047 

1048 def topixelmany(self, value=[ ]): 

1049 """This function converts many absolute world coordinates to pixel coordinates. It exists 

1050 so you can efficiently make many conversions (which would be rather slow 

1051 if you did them all with topixel). Because 

1052 speed is the object, the interface is purely in terms of numeric 

1053 matrices, rather than being able to accept strings and quanta etc. like 

1054 topixel can. 

1055  

1056 The units of the numeric values must be the native units, given by 

1057 function units. 

1058 """ 

1059 return self._swigobj.topixelmany(value) 

1060 

1061 def torecord(self): 

1062 """You can convert a Coordinate System to a record with this function. 

1063 There is also fromrecord 

1064 to set a Coordinate System from a record. 

1065  

1066 These functions allow 

1067 Coordsys tools to be used as parameters in the methods of other tools. 

1068 """ 

1069 return self._swigobj.torecord() 

1070 

1071 def subimage(self, originshft=[ ], newshape=[ ]): 

1072 """You can convert a Coordinate System to another coordinatesystem applicable to a 

1073 subImage. The newshape does not matter as this is the coordinatesystem not the 

1074 image except for Stokes axis; therefore you can ignore {tt newshape} except 

1075 when your sub-image you are considering has only a section of your original Stokes 

1076 axis. 

1077 """ 

1078 return self._swigobj.subimage(originshft, newshape) 

1079 

1080 def torel(self, value=[ ], isworld=int(-1)):