Coverage for /wheeldirectory/casa-6.7.0-11-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/__casac__/coordsys.py: 44%
230 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-23 15:54 +0000
1# This file was automatically generated by SWIG (http://www.swig.org).
2# Version 3.0.12
3#
4# Do not make changes to this file unless you know what you are doing--modify
5# the SWIG interface file instead.
7from sys import version_info as _swig_python_version_info
8if _swig_python_version_info >= (2, 7, 0):
9 def swig_import_helper():
10 import importlib
11 pkg = __name__.rpartition('.')[0]
12 mname = '.'.join((pkg, '_coordsys')).lstrip('.')
13 try:
14 return importlib.import_module(mname)
15 except ImportError:
16 return importlib.import_module('_coordsys')
17 _coordsys = swig_import_helper()
18 del swig_import_helper
19elif _swig_python_version_info >= (2, 6, 0):
20 def swig_import_helper():
21 from os.path import dirname
22 import imp
23 fp = None
24 try:
25 fp, pathname, description = imp.find_module('_coordsys', [dirname(__file__)])
26 except ImportError:
27 import _coordsys
28 return _coordsys
29 try:
30 _mod = imp.load_module('_coordsys', fp, pathname, description)
31 finally:
32 if fp is not None:
33 fp.close()
34 return _mod
35 _coordsys = swig_import_helper()
36 del swig_import_helper
37else:
38 import _coordsys
39del _swig_python_version_info
41try:
42 _swig_property = property
43except NameError:
44 pass # Python < 2.2 doesn't have 'property'.
46try:
47 import builtins as __builtin__
48except ImportError:
49 import __builtin__
51def _swig_setattr_nondynamic(self, class_type, name, value, static=1):
52 if (name == "thisown"):
53 return self.this.own(value)
54 if (name == "this"):
55 if type(value).__name__ == 'SwigPyObject':
56 self.__dict__[name] = value
57 return
58 method = class_type.__swig_setmethods__.get(name, None)
59 if method:
60 return method(self, value)
61 if (not static):
62 if _newclass:
63 object.__setattr__(self, name, value)
64 else:
65 self.__dict__[name] = value
66 else:
67 raise AttributeError("You cannot add attributes to %s" % self)
70def _swig_setattr(self, class_type, name, value):
71 return _swig_setattr_nondynamic(self, class_type, name, value, 0)
74def _swig_getattr(self, class_type, name):
75 if (name == "thisown"):
76 return self.this.own()
77 method = class_type.__swig_getmethods__.get(name, None)
78 if method:
79 return method(self)
80 raise AttributeError("'%s' object has no attribute '%s'" % (class_type.__name__, name))
83def _swig_repr(self):
84 try:
85 strthis = "proxy of " + self.this.__repr__()
86 except __builtin__.Exception:
87 strthis = ""
88 return "<%s.%s; %s >" % (self.__class__.__module__, self.__class__.__name__, strthis,)
90try:
91 _object = object
92 _newclass = 1
93except __builtin__.Exception:
94 class _object:
95 pass
96 _newclass = 0
98class coordsys(_object):
99 """Proxy of C++ casac::coordsys class."""
101 __swig_setmethods__ = {}
102 __setattr__ = lambda self, name, value: _swig_setattr(self, coordsys, name, value)
103 __swig_getmethods__ = {}
104 __getattr__ = lambda self, name: _swig_getattr(self, coordsys, name)
105 __repr__ = _swig_repr
107 def __init__(self):
108 """__init__(self) -> coordsys"""
109 this = _coordsys.new_coordsys()
110 try:
111 self.this.append(this)
112 except __builtin__.Exception:
113 self.this = this
115 def newcoordsys(self, *args, **kwargs):
116 """
117 newcoordsys(self, _direction, _spectral, _stokes, _linear, _tabular) -> coordsys
121 Summary:
122 Create a non-default coordsys tool
124 Description:
128 By default, this constructor makes an empty Coordsys tool. You can ask
129 it to include various sorts of coordinates through the arguments.
130 Except for Stokes, you don't have any control over the coordinate
131 contents (e.g. reference value etc.) it does make for you on request.
132 But you can edit the Coordinate System after creation if you wish.
134 If you wish to make a Stokes coordinate, then you assign
135 {stfaf stokes} to a string (or a vector of strings) saying
136 which Stokes you want. casa allows rather
137 a lot of potential Stokes types.
139 Probably most useful is some combination of the
140 basic I, Q, U, V, XX, YY, XY, YX, RR, LL, RL, and LR.
142 However, a more esoteric choice is also possible:
143 RX, RY, LX, LY, XR, XL, YR, YL (these are mixed
144 linear and circular), PP, PQ, QP, QQ (general quasi-orthogonal correlation products)
145 RCircular, LCircular, Linear (single dish polarization types).
147 You can also specify some polarization `Stokes' types:
148 Ptotal (Polarized intensity ($(Q^2+U^2+V^2)^{1/2}$),
149 Plinear (Linearly Polarized intensity ($(Q^2+U^2)^{1/2}$),
150 PFtotal (Polarization Fraction (Ptotal/I)),
151 PFlinear (Linear Polarization Fraction (Plinear/I)), and
152 Pangle (Linear Polarization Angle ($0.5~arctan(U/Q)$ in radians)).
154 Probably you will find the more unusual types aren't fully
155 supported throughout the system.
157 You can make a LinearCoordinate with as many uncoupled axes as you like.
158 Thus, {stfaf linear=2} makes one LinearCoordinate with 2 axes (think
159 of it like a DirectionCoordinate which also has 2 axes [but coupled in
160 this case], a longitude and a latitude).
162 If you make a TabularCoordinate, it is linear to start with.
163 You can change it to a non-linear one by providing
164 a list of pixel and world values to function
165 settabular.
167 Input Parameters:
168 direction Make a direction coordinate ?
169 spectral Make a spectral coordinate ?
170 stokes Make a Stokes coordinate with these Stokes
171 linear Make a linear coordinate with this many axes
172 tabular Make a tabular coordinate
174 Example:
177 #
178 print 't----t newcoordsys Ex 1 t----'
179 cs1=cs.newcoordsys()
180 print 'ncoordinates =',cs1.ncoordinates()
181 #0
182 cs1.done()
183 #True
184 cs2=cs.newcoordsys(direction=True,stokes=['I','V'])
185 print 'ncoordinates =',cs2.ncoordinates()
186 #2L
187 print cs2.coordinatetype()
188 #['Direction', 'Stokes']
189 cs2.summary()
190 #
193 The second Coordinate System contains a direction coordinate
194 and a Stokes coordinate. This means that there are three `axes'
195 associated with the 2 coordinates.
197 --------------------------------------------------------------------------------
199 """
200 return _coordsys.coordsys_newcoordsys(self, *args, **kwargs)
203 def addcoordinate(self, *args, **kwargs):
204 """
205 addcoordinate(self, _direction, _spectral, _stokes, _linear, _tabular) -> bool
209 Summary:
210 Add default coordinates. (For assay testing only.)
212 Description:
215 Add default coordinates of the specified types. This function allows
216 multiple coordinates of the same type which are not well supported.
217 Use only for assay tests.
219 Input Parameters:
220 direction Add a direction coordinate ?
221 spectral Add a spectral coordinate ?
222 stokes Add a Stokes coordinate with these Stokes
223 linear Add a linear coordinate with this many axes
224 tabular Add a tabular coordinate
226 Example:
229 #
230 print 't----t addcoordinate Ex 1 t----'
231 mycs=cs.newcoordsys()
232 mycs.addcoordinate(direction=True)
233 mycs.done()
234 #
237 --------------------------------------------------------------------------------
239 """
240 return _coordsys.coordsys_addcoordinate(self, *args, **kwargs)
243 def axesmap(self, *args, **kwargs):
244 """
245 axesmap(self, _toworld) -> std::vector< long >
249 Summary:
250 Find mapping between world and pixel axes
252 Description:
256 This function returns a vector describing the mapping from pixel to
257 world or world to pixel axes. It is not for general user use.
259 See the htmlref{discussion}{COORDSYS:PWAXES} about pixel and world axis
260 ordering. Generally they will be in the same order.
262 Input Parameters:
263 toworld Map from pixel to world ?
265 Example:
268 #
269 print 't----t axesmap Ex 1 t----'
270 csys = cs.newcoordsys(direction=True, spectral=True)
271 csys.axesmap(T);
272 #[1L, 2L, 3L]
273 csys.axesmap(F);
274 #[1L, 2L, 3L]
275 #
278 --------------------------------------------------------------------------------
280 """
281 return _coordsys.coordsys_axesmap(self, *args, **kwargs)
284 def axiscoordinatetypes(self, *args, **kwargs):
285 """
286 axiscoordinatetypes(self, _world) -> std::vector< std::string >
290 Summary:
291 Return types of coordinates for each axis
293 Description:
297 This function returns a vector string
298 giving the coordinate type for each axis (world or pixel)
299 in the Coordinate System.
301 See the htmlref{discussion}{COORDSYS:PWAXES} about pixel and world axis
302 ordering.
304 Input Parameters:
305 world World or pixel axes ?
307 Example:
310 #
311 print 't----t axiscoordinatetypes Ex 1 t----'
312 csys=cs.newcoordsys(direction=True,spectral=True)
313 csys.axiscoordinatetypes()
314 #['Direction', 'Direction', 'Spectral']
315 #
318 --------------------------------------------------------------------------------
320 """
321 return _coordsys.coordsys_axiscoordinatetypes(self, *args, **kwargs)
324 def conversiontype(self, *args, **kwargs):
325 """
326 conversiontype(self, _type) -> string
330 Summary:
331 Get extra reference conversion layer
333 Description:
337 Some coordinates contain a reference code. Examples of reference codes
338 are B1950 and J2000 for direction coordinates, or LSRK and BARY for
339 spectral coordinates. When you do conversions between pixel and world
340 coordinate, the coordinates are in the reference frame corresponding to
341 these codes.
343 Function setconversiontype
344 allows you to specify a different reference frame
345 which is used when converting between world and pixel coordinate.
347 This function allows you to recover those conversion types. If no extra
348 conversion layer has been set, you get back the native reference types.
350 Input Parameters:
351 type Coordinate type, direction, spectral
353 Example:
356 #
357 print 't----t conversiontype Ex 1 t----'
358 csys = cs.newcoordsys(direction=True, spectral=True)
359 print csys.conversiontype (type='direction'), ' ', csys.conversiontype (type='spectral')
360 #J2000 LSRK
361 csys.setconversiontype (direction='GALACTIC', spectral='BARY')
362 print csys.conversiontype (type='direction'), ' ', csys.conversiontype (type='spectral')
363 #GALACTIC BARY
364 #
367 --------------------------------------------------------------------------------
369 """
370 return _coordsys.coordsys_conversiontype(self, *args, **kwargs)
373 def convert(self, *args, **kwargs):
374 """
375 convert(self, _coordin, _absin, _dopplerin, _unitsin, _absout, _dopplerout, _unitsout, _shape) -> std::vector< double >
379 Summary:
380 Convert a numeric mixed coordinate
382 Description:
386 This function converts between mixed pixel/world/abs/rel numeric
387 coordinates. The input and output coordinates are specified via a
388 numeric vector giving coordinate values, a string vector giving units, a
389 boolean vector specifying whether the coordinate is absolute or relative
390 (to the reference pixel) and doppler strings specifying the doppler
391 convention for velocities.
393 The units string may include {cf pix} for pixel coordinates and
394 velocity units (i.e. any unit consistent with {cf m/s}).
396 The allowed doppler strings and definition are described
397 in function summary.
399 The {stfaf shape} argument is optional. If your Coordinate
400 System is from an image, then assign the image shape to this
401 argument. It is used only when making mixed (pixel/world) conversions
402 for Direction Coordinates to resolve ambiguity.
404 The example clarifies the use of this function.
406 Input Parameters:
407 coordin Input coordinate, as a numeric vector
408 absin Are input coordinate elements absolute ?
409 dopplerin Input doppler type for velocities
410 unitsin Input units, string vector
411 absout Are output coordinate elements absolute ?
412 dopplerout Output doppler type for velocities
413 unitsout Output units
414 shape Image shape, integer vector
416 Example:
418 In this example we convert from a vector of absolute pixels
419 to a mixture of pixel/world and abs/rel.
422 #
423 print 't----t convert Ex 1 t----'
424 csys=cs.newcoordsys(direction=True, spectral=True) # 3 axes
425 cout=csys.convert(coordin=[10,20,30],absin=[T,T,T],
426 unitsin=['pix','pix','pix'],
427 absout=[T,F,T], dopplerout='optical',
428 unitsout=['pix','arcsec','km/s'])
429 print cout
430 #[10.0, 1140.0058038878046, 1139.1354056919731]
431 #
434 --------------------------------------------------------------------------------
436 """
437 return _coordsys.coordsys_convert(self, *args, **kwargs)
440 def convertdirection(self, *args, **kwargs):
441 """
442 convertdirection(self, _frame) -> record *
446 Summary:
447 Convert the direction coordinate to the specified frame by rotating as necessary about the reference pixel so the axes line up with the cardinal directions.
449 Description:
452 Convert the direction coordinate in the coordinate system to the specified frame by
453 rotating about the reference pixel so that the resulting coordinate axes are parallel
454 to the cardinal directions. The resulting coordinate will not have a conversion layer,
455 even if the input direction coordinate does. A conversion layer can be set after by
456 running cs.setconversiontype(). Be aware that if you attach the resulting coordinate
457 system to an image whose pixels have not been rotated around the reference pixel in
458 the same manner, you will likely get an image for which the pixels do not match
459 up to world coordinate values. This method should only be used by experienced users who
460 know what they are doing. It was written originally to facilitate rotating the
461 direction coordinate since the implementation of imregrid requires this in certain
462 circumstances. The conversion is done in place; a new coordinate system tool is not
463 created. The returned record represents an angular quantity through which the old
464 direction coordinate was rotated to create the new coordinate.
467 Input Parameters:
468 frame Reference frame to convert to.
470 --------------------------------------------------------------------------------
472 """
473 return _coordsys.coordsys_convertdirection(self, *args, **kwargs)
476 def convertmany(self, *args, **kwargs):
477 """
478 convertmany(self, _coordin, _absin, _dopplerin, _unitsin, _absout, _dopplerout, _unitsout, _shape) -> variant *
482 Summary:
483 Convert many numeric mixed coordinates
485 Description:
489 This function converts between many mixed pixel/world/abs/rel numeric
490 coordinates. See function convert
491 for more information.
493 The only diffference with that function is that you
494 provide a matrix holding many coordinates to convert
495 and a matrix of many converted coordinates is returned.
497 Input Parameters:
498 coordin Input coordinate, numeric matrix
499 absin Are input coordinate elements absolute ?
500 dopplerin Input doppler type for velocities
501 unitsin Input units, string vector
502 absout Are output coordinate elements absolute ?
503 dopplerout Output doppler type for velocities
504 unitsout Output units
505 shape Image shape, integer array
507 Example:
510 #
511 print 't----t convertmany Ex 1 t----'
512 csys = cs.newcoordsys(direction=True, spectral=True) # 3 axes
513 # absolute pixel coordinates; 10 conversions each of length 3; spectral
514 cin=[(15, 15, 15, 15, 15, 15, 15, 15, 15, 15), # pixel runs from 1 to 10
515 (20, 20, 20, 20, 20, 20, 20, 20, 20, 20),
516 ( 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)]
517 cout = csys.convertmany (coordin=cin,
518 absin=[T,T,T],
519 unitsin=['pix','pix','pix'],
520 absout=[T,F,T],
521 dopplerout='optical',
522 unitsout=['pix','deg','km/s']);
523 print cout
524 #[(15.0, 15.0, 15.0, 15.0, 15.0, 15.0, 15.0, 15.0, 15.0, 15.0),
525 # (0.31666827885771637, 0.31666827885771637, 0.31666827885771637,
526 # 0.31666827885771637, 0.31666827885771637, 0.31666827885771637,
527 # 0.31666827885771637, 0.31666827885771637, 0.31666827885771637,
528 # 0.31666827885771637),
529 # (1145.3029083129913, 1145.0902316004676, 1144.8775551885467,
530 # 1144.6648790772279, 1144.4522032665102, 1144.2395277563601,
531 # 1144.0268525468437, 1143.8141776379266, 1143.6015030296085,
532 # 1143.3888287218554)]
533 #
536 --------------------------------------------------------------------------------
538 """
539 return _coordsys.coordsys_convertmany(self, *args, **kwargs)
542 def coordinatetype(self, *args, **kwargs):
543 """
544 coordinatetype(self, _which) -> std::vector< std::string >
548 Summary:
549 Return type of specified coordinate
551 Description:
555 This function returns a string describing
556 the type of the specified coordinate. If {stfaf which=unset} the types
557 for all coordinates are returned.
559 Possible output values are 'Direction', 'Spectral', 'Stokes', 'Linear', and
560 'Tabular'
562 Input Parameters:
563 which Which coordinate ? (0-rel)
565 Example:
568 #
569 print 't----t coordinatetype Ex 1 t----'
570 csys = cs.newcoordsys(direction=True, spectral=True)
571 csys.coordinatetype(0)
572 #'Direction'
573 cs.coordinatetype()
574 #['Direction', 'Spectral']
575 #
578 --------------------------------------------------------------------------------
580 """
581 return _coordsys.coordsys_coordinatetype(self, *args, **kwargs)
584 def copy(self):
585 """
586 copy(self) -> coordsys
590 Summary:
591 Copy this Coordsys tool
593 Description:
599 This function returns a copy, not a reference, of the Coordsys tool.
600 It is your responsibility to call the {stff done} function
601 on the new tool.
603 Example:
606 #
607 print 't----t copy Ex 1 t----'
608 cs1 = cs.newcoordsys(direction=True, spectral=True)
609 cs2 = cs1 # Reference
610 print cs1, cs2
611 cs1.summary()
612 cs2.summary()
613 cs1.done() # done invokes default coordsys tool
614 cs1.summary()
615 cs2.summary() # cs2 gets doned when cs1 does
616 cs1 = cs.newcoordsys(direction=True, spectral=True)
617 cs2 = cs1.copy() # Copy
618 cs1.done()
619 cs1.summary() # cs1 is default coordsys tool
620 cs2.summary() # cs2 is still viable
621 cs2.done()
622 cs2.summary() # Now it's done (done just invokes default constructor)
623 #
626 --------------------------------------------------------------------------------
628 """
629 return _coordsys.coordsys_copy(self)
632 def done(self):
633 """
634 done(self) -> bool
638 Summary:
639 Destroy this Coordsys tool, restore default tool
641 Description:
645 If you no longer need to use a Coordsys tool calling this function
646 will free up its resources and restore the default coordsys tool.
648 Example:
651 #
652 print 't----t done Ex 1 t----'
653 csys = cs.newcoordsys(direction=True, spectral=True)
654 csys.done()
655 print csys.torecord() # default tool
656 #
659 --------------------------------------------------------------------------------
661 """
662 return _coordsys.coordsys_done(self)
665 def epoch(self):
666 """
667 epoch(self) -> record *
671 Summary:
672 Return the epoch
674 Description:
678 This function returns the epoch of the observation as a
679 Measure.
681 Example:
684 #
685 print 't----t epoch Ex 1 t----'
686 csys = cs.newcoordsys()
687 ep = csys.epoch()
688 print ep
689 #{'type': 'epoch', 'm0': {'value': 54151.96481085648, 'unit': 'd'}, 'refer': 'UTC'}
690 time = me.getvalue(ep) # Extract time with measures
691 print time
692 #{'m0': {'value': 54151.96481085648, 'unit': 'd'}}
693 qa.time(time) # Format with quanta
694 #'23:09:20'
695 #
698 --------------------------------------------------------------------------------
700 """
701 return _coordsys.coordsys_epoch(self)
704 def findaxis(self, *args, **kwargs):
705 """
706 findaxis(self, _world, _axis) -> record *
710 Summary:
711 Find specified axis in coordinate system
713 Description:
717 This function finds the specified axis in
718 the Coordinate System. If the axis does not exist, it throws an exception.
720 Input Parameters:
721 world is axis a world or pixel axis ?
722 axis Axis in coordinate system
724 Example:
727 #
728 print 't----t findaxis Ex 1 t----'
729 csys=cs.newcoordsys(direction=True, linear=2) # RA/DEC/Lin1/Lin2
730 rtn=csys.findaxis(T,1) # DEC
731 rtn
732 #{'axisincoordinate': 1L, 'coordinate': 0L}
733 rtn = csys.findaxis(T,2) # Lin1
734 rtn
735 #{'axisincoordinate': 0L, 'coordinate': 1L}
736 #
740 In these examples, the Coordinate System has 2 coordinates and 4 axes
741 (0-rel, both world and pixel the same). The first example finds the
742 DEC axis (coordinate system axis 1) to be the second axis of the
743 Direction Coordinate (coordinate 0). The second example finds the
744 first linear axis (coordinate system axis 2) to be the first axis of
745 the Linear Coordinate (coordinate 1).
747 --------------------------------------------------------------------------------
749 """
750 return _coordsys.coordsys_findaxis(self, *args, **kwargs)
753 def findaxisbyname(self, *args, **kwargs):
754 """
755 findaxisbyname(self, _axisname, _allowfriendlyname) -> long
759 Summary:
760 Find specified axis in coordinate system.
762 Description:
765 Find the world axis based on its name. Matching is not case sensitive and minimal match is supported, eg 'dec' will match 'Declination'.
766 In addition, if allowfriendlyname is True, other common terms will match the expected axis. Currently supported are:
767 'spectral' matches frequency type axes, eg 'Frequency' or 'Velocity',
768 'ra' matches 'Right Ascension'. These names must be spelled out completely; eg 'spectral' rather than simply 'spec'.
769 The first matching axis (zero-based) number is returned. If no axis can be matched, an exception is thrown.
772 Input Parameters:
773 axisname Name of axis to find. Minimal match supported
774 allowfriendlyname Support friendly naming. Eg 'spectral' will match 'frequency' or 'velocity', 'ra' will match 'right ascension'
776 Example:
778 # Find the declination axis
779 ia.open('myimage')
780 csys = ia.coordsys()
781 ia.done()
782 try:
783 dec_axis_number = csys.findaxisbyname('dec', False)
784 except Exception
785 print 'Declination axis not found
787 # find the spectral axis
788 try:
789 spec_axis_number = csys.findaxisbyname('spectral', True)
790 except Exception:
791 print 'Spectral axis could not be found.
793 --------------------------------------------------------------------------------
795 """
796 return _coordsys.coordsys_findaxisbyname(self, *args, **kwargs)
799 def findcoordinate(self, *args, **kwargs):
800 """
801 findcoordinate(self, _type, _which) -> record *
805 Summary:
806 Find axes of specified coordinate
808 Description:
812 This function finds the axes in the
813 Coordinate System for the specified coordinate (minimum match is active
814 for argument {stfaf type}). By default it finds the first coordinate,
815 but if there is more than one (can happen for linear coordinates), you
816 can specify which. It returns a dictionary with 'return', 'pixel', and
817 'world' as keys. The associated value of 'return' is a boolean indicating if
818 the specified coordinate was found. The values of 'pixel' and 'world' are
819 arrays indicating the indices of the associated pixel and world axes, respectively,
820 of the specified coordinate. If the coordinate does not exist, these arrays
821 will be empty.
823 See also the function axesmap
824 which returns the mapping between pixel and world axes.
826 Input Parameters:
827 type Type of coordinate to find: direction, stokes, spectral, linear, or tabular
828 which Which coordinate if more than one
830 Example:
833 #
834 print 't----t findcoordinate Ex 1 t----'
835 csys=cs.newcoordsys(direction=True)
836 rtn=cs.findcoordinate('direction')
837 print rtn
838 #{'world': [0L, 1L], 'pixel': [0L, 1L]}
839 print 'pixel, world axes =', rtn['pixel'], rtn['world']
840 #pixel, world axes = [0 1] [0 1]
841 #
844 --------------------------------------------------------------------------------
846 """
847 return _coordsys.coordsys_findcoordinate(self, *args, **kwargs)
850 def frequencytofrequency(self, *args, **kwargs):
851 """
852 frequencytofrequency(self, _value, _frequnit, _velocity) -> std::vector< double >
856 Summary:
857 Apply relativistic Doppler shift to a list of frequencies
859 Description:
862 This function converts frequencies to frequencies by applying a
863 relativistic Doppler shift:
864 fout = fin * sqrt((1.-v/c)/(1.+v/c)) .
866 The input frequencies are specified via a vector of numeric values and
867 a specified unit ({stfaf frequnit}). If you don't give a frequency
868 unit, it is assumed that the units are those given by function coordsys units() for
869 the spectral coordinate.
871 This function does not make any frame conversions (e.g. LSR to BARY).
873 This function fails if there is no spectral coordinate
874 in the Coordinate System. See also function
875 frequencytovelocity.
877 Input Parameters:
878 value Frequencies to convert
879 frequnit Unit of input frequencies. Default is unit of the spectral coordinate.
880 velocity Velocity
882 Example:
885 ia.open('M100line.image')
886 mycs = ia.coordsys()
887 ia.close()
889 mycs.frequencytofrequency(value=[115271201800.0], frequnit='Hz', velocity='1000km/s')
890 results in
891 array([114887337607.0])
893 Let's see if this is correct
894 print 115271201800.0*sqrt((1.-1000000./299792458.0)/(1.+1000000./299792458.0))
895 Result: 1.14887337607e+11
898 --------------------------------------------------------------------------------
900 """
901 return _coordsys.coordsys_frequencytofrequency(self, *args, **kwargs)
904 def frequencytovelocity(self, *args, **kwargs):
905 """
906 frequencytovelocity(self, _value, _frequnit, _doppler, _velunit) -> std::vector< double >
910 Summary:
911 Convert frequency to velocity
913 Description:
917 This function converts frequencies to
918 velocities.
920 The input frequencies are specified via a vector of numeric values and
921 a specified unit ({stfaf frequnit}). If you don't give a frequency
922 unit, it is assumed that the units are those given by function coordsys units() for
923 the spectral coordinate.
925 This function does not make any frame conversions (e.g. LSR to BARY)
926 but you can specifiy the velocity doppler definition via the {stfaf
927 doppler} argument (see image summary() for
928 possible values).
930 The velocities are returned in a vector for which you specify the
931 units ({stfaf velunit} - default is km/s).
933 This function will return a fail if there is no spectral coordinate
934 in the Coordinate System. See also function
935 velocitytofrequency.
937 Input Parameters:
938 value Frequency to convert
939 frequnit Unit of input frequencies. Default is unit of the spectral coordinate.
940 doppler Velocity doppler definition
941 velunit Unit of output velocities
943 Example:
946 #
947 print 't----t frequencytovelocity Ex 1 t----'
948 im = ia.fromshape(shape=[10,10,10])
949 csys = ia.coordsys()
950 rtn = csys.findcoordinate('spectral') # Find spectral axis
951 pa=rtn['pixel']
952 wa=rtn['world']
953 pixel = csys.referencepixel(); # Use reference pixel for non-spectral
954 nFreq = ia.shape()[pa]; # Length of spectral axis
955 freq = [];
956 for i in range(nFreq):
957 pixel[pa] = i # Assign value for spectral axis of pixel coordinate
958 w = csys.toworld(value=pixel, format='n') # Convert pixel to world
959 freq.append(w['numeric'][wa]); # Fish out frequency
960 print 'freq=', freq
961 #freq= [1414995000.0, 1414996000.0, 1414997000.0, 1414998000.0,
962 # 1414999000.0, 1415000000.0, 1415001000.0, 1415002000.0, 1415003000.0, 1415004000.0]
963 vel = csys.frequencytovelocity(value=freq, doppler='optical', velunit='km/s')
964 print 'vel=', vel
965 #vel= [1146.3662963847394, 1146.153618169159, 1145.9409402542183, 1145.7282626398826,
966 # 1145.5155853261515, 1145.3029083129911, 1145.0902316004676, 1144.8775551885467,
967 # 1144.6648790772279, 1144.4522032665104]
968 #
972 In this example, we find the optical velocity in km/s of every pixel
973 along the spectral axis of our image. First we obtain the Coordinate
974 System from the image. Then we find which axis of the Coordinate System
975 (image) pertain to the spectral coordinate. Then we loop over each
976 pixel of the spectral axis, and convert a pixel coordinate (one for each
977 axis of the image) to world. We obtain the value for the spectral axis
978 from that world vector, and add it to the vector of frequencies. Then
979 we convert that vector of frequencies to velocity.
981 --------------------------------------------------------------------------------
983 """
984 return _coordsys.coordsys_frequencytovelocity(self, *args, **kwargs)
987 def fromrecord(self, *args, **kwargs):
988 """
989 fromrecord(self, _record) -> bool
993 Summary:
994 Fill Coordinate System from a record
996 Description:
1000 You can convert a Coordinate System to a record
1001 (torecord). This function
1002 (fromrecord) allows you to set the contents of an existing Coordinate
1003 System from such a record. In doing so, you overwrite its current
1004 contents.
1006 Input Parameters:
1007 record Record containing Coordinate System
1009 Example:
1012 #
1013 print 't----t fromrecord Ex 1 t----'
1014 csys = cs.newcoordsys(direction=True, stokes='I Q')
1015 print csys.ncoordinates()
1016 #2
1017 r = csys.torecord()
1018 cs2 = cs.newcoordsys()
1019 print cs2.ncoordinates()
1020 #0
1021 cs2.fromrecord(r)
1022 print cs2.ncoordinates()
1023 #2
1024 #
1027 --------------------------------------------------------------------------------
1029 """
1030 return _coordsys.coordsys_fromrecord(self, *args, **kwargs)
1033 def increment(self, *args, **kwargs):
1034 """
1035 increment(self, _format, _type) -> record *
1039 Summary:
1040 Recover the increments
1042 Description:
1046 Each axis associated with the Coordinate System has a reference value,
1047 reference pixel and an increment (per pixel). These are used in the
1048 mapping from pixel to world coordinate.
1050 This function returns the increment (in
1051 world axis order). You can recover the increments either for all
1052 coordinates (leave {stfaf type} unset) or for a specific coordinate
1053 type (mimumum match of the allowed types will do). If you ask for a
1054 non-existent coordinate an exception is generated.
1056 See the htmlref{discussion}{COORDSYS:FORMATTING} regarding the
1057 formatting possibilities available via argument {stfaf format}.
1059 You can set the increment with function
1060 setincrement.
1062 Input Parameters:
1063 format Format string from combination of 'n', 'q', 's', 'm'
1064 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular'. Leave empty for all.
1066 Example:
1069 #
1070 print 't----t increment Ex 1 t----'
1071 csys=cs.newcoordsys(direction=True,spectral=True)
1072 print csys.increment(format='q')
1073 #{'quantity': {'*1': {'unit': ''', 'value': -1.0},
1074 # '*2': {'unit': ''', 'value': 1.0},
1075 # '*3': {'unit': 'Hz', 'value': 1000.0}}}
1076 print csys.increment(format='n')
1077 #{'numeric': [-1.0, 1.0, 1000.0]}
1078 print csys.increment(format='n', type='spectral')
1079 #{'numeric': [1000.0]}
1080 #
1083 --------------------------------------------------------------------------------
1085 """
1086 return _coordsys.coordsys_increment(self, *args, **kwargs)
1089 def lineartransform(self, *args, **kwargs):
1090 """
1091 lineartransform(self, _type) -> variant *
1095 Summary:
1096 Recover the linear transform matrix
1098 Description:
1102 Recover the linear transform component for the specified coordinate type.
1104 You can set the linear transform with function
1105 setlineartransform.
1107 Input Parameters:
1108 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular'
1110 Example:
1113 #
1114 print 't----t lineartransform Ex 1 t----'
1115 csys=cs.newcoordsys(direction=True,linear=3)
1116 csys.lineartransform('dir') # 2 x 2
1117 # [(1.0, 0.0), (0.0, 1.0)]
1118 csys.lineartransform('lin') # 3 x 3
1119 # [(1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)]
1120 #
1123 --------------------------------------------------------------------------------
1125 """
1126 return _coordsys.coordsys_lineartransform(self, *args, **kwargs)
1129 def names(self, *args, **kwargs):
1130 """
1131 names(self, _type) -> std::vector< std::string >
1135 Summary:
1136 Recover the names for each axis
1138 Description:
1142 Each axis associated with the Coordinate System has a name (they don't
1143 mean anything fundamental). This function returns those names in
1144 world axis order.
1146 You can recover the names either for all coordinates (leave {stfaf
1147 type} unset) or for a specific coordinate type (mimumum match of the
1148 allowed types will do). If you ask for a non-existent coordinate an
1149 exception is generated.
1151 You can set the names with function
1152 setnames.
1154 Input Parameters:
1155 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular'. Leave empty for all.
1157 Example:
1160 #
1161 print 't----t names Ex 1 t----'
1162 csys = cs.newcoordsys(direction=True, spectral=True)
1163 n = csys.names()
1164 print n[0]
1165 #Right Ascension
1166 print n[1]
1167 #Declination
1168 print n[2]
1169 #Frequency
1170 print cs.names('spec')
1171 #Frequency
1172 #
1175 --------------------------------------------------------------------------------
1177 """
1178 return _coordsys.coordsys_names(self, *args, **kwargs)
1181 def naxes(self, *args, **kwargs):
1182 """
1183 naxes(self, _world) -> long
1187 Summary:
1188 Recover the number of axes
1190 Description:
1194 Find the number of axes in the Coordinate System.
1196 You may find the number of world or pixel axes; these are generally the
1197 same and general users can ignore the distinction. See the
1198 htmlref{discussion}{COORDSYS:PWAXES} about pixel and world axis
1199 ordering.
1201 Input Parameters:
1202 world Find number of world or pixel axes ?
1204 Example:
1207 #
1208 print 't----t naxes Ex 1 t----'
1209 csys = cs.newcoordsys(direction=True, spectral=True)
1210 n = csys.naxes(T)
1211 print n
1212 #3 # 2 direction axes, 1 spectral
1213 n = csys.naxes(F)
1214 print n
1215 #3
1216 #
1219 --------------------------------------------------------------------------------
1221 """
1222 return _coordsys.coordsys_naxes(self, *args, **kwargs)
1225 def ncoordinates(self):
1226 """
1227 ncoordinates(self) -> long
1231 Summary:
1232 Recover the number of coordinates in the Coordinate System
1234 Description:
1238 This function recovers the number of
1239 coordinates in the Coordinate System.
1241 Example:
1244 #
1245 print 't----t ncoordinates Ex 1 t----'
1246 csys = cs.newcoordsys(direction=True, spectral=True)
1247 print csys.ncoordinates()
1248 #2
1249 cs2 = cs.newcoordsys(linear=4)
1250 print cs2.ncoordinates()
1251 #1
1252 #
1255 --------------------------------------------------------------------------------
1257 """
1258 return _coordsys.coordsys_ncoordinates(self)
1261 def observer(self):
1262 """
1263 observer(self) -> string
1267 Summary:
1268 Return the name of the observer
1270 Description:
1274 This function returns the name of the observer.
1275 You can set it with the function setobserver.
1277 Example:
1280 #
1281 print 't----t observer Ex 1 t----'
1282 csys = cs.newcoordsys()
1283 print csys.observer()
1284 #Karl Jansky
1285 #
1288 --------------------------------------------------------------------------------
1290 """
1291 return _coordsys.coordsys_observer(self)
1294 def projection(self, *args, **kwargs):
1295 """
1296 projection(self, _type) -> record *
1300 Summary:
1301 Recover the direction coordinate projection
1303 Description:
1307 If the Coordinate System contains a direction coordinate, this function
1308 can be used to recover information about the
1309 projection. For discussion about celestial coordinate systems,
1310 including projections, see the papers by Mark Calabretta and Eric
1311 Greisen. The initial draft from 1996 (implemented in
1312 casa. Background information can be
1313 found
1314 htmladdnormallink{here}{http://www.atnf.csiro.au/people/mark.calabretta/WCS}.
1316 What this function returns depends upon the value
1317 you assign to {stfaf type}.
1319 begin{itemize}
1321 item {stfaf type=unset}. In this case (the default), the actual
1322 projection type and projection parameters are returned in a
1323 record with fields {cf type} and {cf parameters}, respectively.
1325 item {stfaf type='all'}. In this case, a vector of strings
1326 containing all of the possible projection codes is returned.
1328 item {stfaf type=code}. If you specify a valid
1329 projection type code (see list by setting {stfaf type='all'})
1330 then what is returned is the number of parameters required
1331 to describe that projection (useful in function
1332 setprojection).
1334 end{itemize}
1336 You can change the projection with
1337 setprojection.
1339 If the Coordinate System does not contain a direction coordinate,
1340 an exception is generated.
1342 Input Parameters:
1343 type Type of projection. Defaults to current projection.
1345 Example:
1348 #
1349 print 't----t projection Ex 1 t----'
1350 csys = cs.newcoordsys(direction=True)
1351 print csys.projection()
1352 #{'type': 'SIN', 'parameters': [0.0, 0.0]}
1353 print csys.projection('all')
1354 #{'all': True, 'types': ['AZP', 'TAN', 'SIN', 'STG', 'ARC', 'ZPN', 'ZEA',
1355 # 'AIR', 'CYP', 'CAR', 'MER', 'CEA', 'COP', 'COD', 'COE', 'COO', 'BON',
1356 # 'PCO', 'SFL', 'PAR', 'AIT', 'MOL', 'CSC', 'QSC', 'TSC']}
1357 print csys.projection('ZPN')
1358 #{'nparameters': 100}
1359 #
1362 We first recover the projection type and parameters from
1363 the direction coordinate. Then we find the list of all
1364 possible projection types. FInally, we recover the number of
1365 parameters required to describe the 'ZPN' projection.
1367 --------------------------------------------------------------------------------
1369 """
1370 return _coordsys.coordsys_projection(self, *args, **kwargs)
1373 def referencecode(self, *args, **kwargs):
1374 """
1375 referencecode(self, _type, _list) -> std::vector< std::string >
1379 Summary:
1380 Return specified reference code
1382 Description:
1386 This function returns the reference code
1387 for all, or the specified coordinate type. Examples of the reference
1388 code are B1950 and J2000 for direction coordinates, or LSRK and BARY for
1389 spectral coordinates.
1391 If {stfaf type} is left unset, then a vector of strings is returned,
1392 one code for each coordinate type in the Coordinate System.
1394 If you specify {stfaf type} then select from
1395 'direction', 'spectral', 'stokes', and 'linear'
1396 (the first two letters will do). However, only the first two
1397 coordinate types will return a non-empty string.
1398 If the Coordinate System does not contain a coordinate of
1399 the type you specify, an exception is generated.
1401 The argument {stfaf list} is ignored unless you specify a specific {stfaf type}.
1402 If {stfaf list=T}, then this function returns the list of all possible
1403 reference codes for the specified coordinate type. Otherwise, it just
1404 returns the actual code current set in the Coordinate System.
1406 The list of all possible types is returned as a record (it is
1407 actually generated by the
1408 listcodes function in the
1409 measures system). This record has two
1410 fields. These are called 'normal'
1411 (containing all normal codes) and 'extra' (maybe empty, with all extra
1412 codes like planets).
1414 You can set the reference code with
1415 setreferencecode.
1417 Input Parameters:
1418 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular'. Leave empty for all.
1419 list List all possibilities?
1421 Example:
1424 #
1425 print 't----t referencecode Ex 1 t----'
1426 csys = cs.newcoordsys(direction=True)
1427 clist = csys.referencecode('dir', True)
1428 print clist
1429 # ['J2000', 'JMEAN', 'JTRUE', 'APP', 'B1950', 'B1950_VLA', 'BMEAN', 'BTRUE', 'GALACTIC', 'HADEC', 'AZEL', 'AZELSW', 'AZELNE', 'AZELGEO', 'AZELSWGEO', 'AZELNEGEO', 'JNAT', 'ECLIPTIC', 'MECLIPTIC', 'TECLIPTIC', 'SUPERGAL', 'ITRF', 'TOPO', 'ICRS', 'MERCURY', 'VENUS', 'MARS', 'JUPITER', 'SATURN', 'URANUS', 'NEPTUNE', 'PLUTO', 'SUN', 'MOON', 'COMET']
1430 print csys.referencecode('dir')
1431 #J2000
1432 #
1436 In this example we first get the list of all possible reference codes
1437 ofor a direction coordinate. Then we
1438 get the actual reference code for the direction coordinate in our
1439 Coordinate System.
1441 --------------------------------------------------------------------------------
1443 """
1444 return _coordsys.coordsys_referencecode(self, *args, **kwargs)
1447 def referencepixel(self, *args, **kwargs):
1448 """
1449 referencepixel(self, _type) -> record *
1453 Summary:
1454 Recover the reference pixel
1456 Description:
1460 Each axis associated with the Coordinate System has a reference value,
1461 reference pixel and an increment (per pixel). These are used in the
1462 mapping from pixel to world coordinate.
1464 This function returns the reference pixel
1465 (in pixel axis order). You can recover the reference pixel either for
1466 all coordinates (leave {stfaf type} unset) or for a specific coordinate
1467 type (mimumum match of the allowed types will do). If you ask for a
1468 non-existent coordinate an exception is generated.
1470 You can set the reference pixel with function
1471 setreferencepixel.
1473 Input Parameters:
1474 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular'. Leave empty for all.
1476 Example:
1479 #
1480 print 't----t referencepixel Ex 1 t----'
1481 csys = cs.newcoordsys(spectral=True, linear=2)
1482 csys.setreferencepixel([1.0, 2.0, 3.0])
1483 print csys.referencepixel()
1484 #{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([ 1., 2., 3.])}
1485 print csys.referencepixel('lin')
1486 #{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([ 2., 3.])}
1487 #
1490 --------------------------------------------------------------------------------
1492 """
1493 return _coordsys.coordsys_referencepixel(self, *args, **kwargs)
1496 def referencevalue(self, *args, **kwargs):
1497 """
1498 referencevalue(self, _format, _type) -> record *
1502 Summary:
1503 Recover the reference value
1505 Description:
1509 Each axis associated with the Coordinate System has a reference value,
1510 reference pixel and an increment (per pixel). These are used in the
1511 mapping from pixel to world coordinate.
1513 This function returns the reference value
1514 (in world axis order). You can recover the reference value either for all
1515 coordinates (leave {stfaf type} unset) or for a specific coordinate
1516 type (mimumum match of the allowed types will do). If you ask for a
1517 non-existent coordinate an exception is generated.
1519 See the htmlref{discussion}{COORDSYS:FORMATTING} regarding the
1520 formatting possibilities available via argument {stfaf format}.
1522 You can set the reference value with function
1523 setreferencevalue.
1525 Input Parameters:
1526 format Format string. Combination of 'n', 'q', 's', 'm'
1527 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular'. Leave empty for all.
1529 Example:
1532 #
1533 print 't----t referencevalue Ex 1 t----'
1534 csys = cs.newcoordsys(direction=True, spectral=True)
1535 print csys.referencevalue(format='q')
1536 #{'ar_type': 'absolute',
1537 # 'pw_type': 'world',
1538 # 'quantity': {'*1': {'unit': ''', 'value': 0.0},
1539 # '*2': {'unit': ''', 'value': 0.0},
1540 # '*3': {'unit': 'Hz', 'value': 1415000000.0}}}
1541 print csys.referencevalue(format='n')
1542 #{'ar_type': 'absolute',
1543 # 'numeric': array([ 0.00000000e+00, 0.00000000e+00, 1.41500000e+09]),
1544 # 'pw_type': 'world'}
1545 print csys.referencevalue(format='n', type='spec')
1546 #{'ar_type': 'absolute',
1547 # 'numeric': array([ 1.41500000e+09]),
1548 # 'pw_type': 'world'}
1549 #
1552 --------------------------------------------------------------------------------
1554 """
1555 return _coordsys.coordsys_referencevalue(self, *args, **kwargs)
1558 def reorder(self, *args, **kwargs):
1559 """
1560 reorder(self, _order) -> bool
1564 Summary:
1565 Reorder the coordinates
1567 Description:
1571 This function reorders the coordinates in the Coordinate System.
1572 You specify the new order of the coordinates in terms of their old
1573 order.
1575 Input Parameters:
1576 order New coordinate order
1578 Example:
1581 #
1582 print 't----t reorder Ex 1 t----'
1583 csys = cs.newcoordsys(direction=True, spectral=True, linear=2)
1584 print csys.coordinatetype()
1585 #['Direction', 'Spectral', 'Linear']
1586 csys.reorder([1,2,0]);
1587 print csys.coordinatetype()
1588 #['Spectral', 'Linear', 'Direction']
1589 #
1592 --------------------------------------------------------------------------------
1594 """
1595 return _coordsys.coordsys_reorder(self, *args, **kwargs)
1598 def transpose(self, *args, **kwargs):
1599 """
1600 transpose(self, _order) -> bool
1604 Summary:
1605 Transpose the axes.
1607 Description:
1611 This method transposes the axes (both world and pixel) in the coordinate system.
1612 You specify the new order of the axes in terms of their old
1613 order, so eg order=[1,0,3,2] means reorder the axes so that the zeroth
1614 axis becomes the first axis, the first axis becomes the zeroth axis,
1615 the second axis becomes the third axis, and the third axis becomes the
1616 second axis.
1618 Input Parameters:
1619 order New axis order
1621 Example:
1623 csys = cstool()
1625 # Create a coordinate system with axes, RA, Dec, Stokes, and Frequency
1626 csys.newcoordsys(direction=True, spectral=True, stokes=['I','Q'])
1628 # transpose the axes so that the order is RA, Dec, Frequency, and Stokes
1629 csys.transpose(order=[0, 1, 3, 2])
1631 --------------------------------------------------------------------------------
1633 """
1634 return _coordsys.coordsys_transpose(self, *args, **kwargs)
1637 def replace(self, *args, **kwargs):
1638 """
1639 replace(self, _csys, _whichin, _whichout) -> bool
1643 Summary:
1644 Replace a coordinate
1646 Description:
1650 This function replaces one coordinate in the current Coordinate System by
1651 one coordinate in the given Coordinate System. The specified
1652 coordinates must have the same number of axes.
1654 Input Parameters:
1655 csys Coordinate System to replace from. Use coordsys' torecord() to generate required record.
1656 whichin Index of input coordinate (0-rel)
1657 whichout Index of output coordinate
1659 Example:
1662 #
1663 print 't----t replace Ex 1 t----'
1664 cs1 = cs.newcoordsys(direction=True, linear=1)
1665 print cs1.coordinatetype()
1666 #['Direction', 'Linear']
1667 cs2 = cs.newcoordsys(spectral=True)
1668 cs1.replace (cs2.torecord(),0,1)
1669 print cs1.coordinatetype()
1670 #['Direction', 'Spectral']
1671 #
1674 --------------------------------------------------------------------------------
1676 """
1677 return _coordsys.coordsys_replace(self, *args, **kwargs)
1680 def restfrequency(self):
1681 """
1682 restfrequency(self) -> record *
1686 Summary:
1687 Recover the rest frequency
1689 Description:
1693 If the Coordinate System contains a spectral coordinate, then
1694 it has a rest frequency. In fact, the spectral coordinate
1695 can hold several rest frequencies (to handle for example,
1696 an observation where the band covers many lines), although
1697 only one is active (for velocity conversions) at a time.
1699 This function recovers the rest frequencies
1700 as a quantity vector. The first frequency is the active one.
1702 You can change the rest frequencies with
1703 setrestfrequency.
1705 If the Coordinate System does not contain a frequency coordinate,
1706 an exception is generated.
1708 Example:
1711 #
1712 print 't----t restfrequency Ex 1 t----'
1713 csys = cs.newcoordsys(spectral=True)
1714 print csys.restfrequency()
1715 #{'value': [1420405751.7860003], 'unit': 'Hz'}
1716 csys.setrestfrequency (value=qa.quantity([1.2e9, 1.3e9],'Hz'), which=1, append=False)
1717 print csys.restfrequency()
1718 #{'value': [1300000000.0, 1200000000.0], 'unit': 'Hz'}
1719 #
1722 In the example, the initial spectral coordinate has 1 rest frequency.
1723 Then we set it with two, nominating the second as the active rest frequency,
1724 and recover them.
1726 --------------------------------------------------------------------------------
1728 """
1729 return _coordsys.coordsys_restfrequency(self)
1732 def setconversiontype(self, *args, **kwargs):
1733 """
1734 setconversiontype(self, _direction, _spectral) -> bool
1738 Summary:
1739 Set extra reference conversion layer
1741 Description:
1745 Some coordinates contain a reference code. Examples of reference codes
1746 are B1950 and J2000 for direction coordinates, or LSRK and BARY for
1747 spectral coordinates. When you do conversions between pixel and world
1748 coordinate, the coordinates are in the reference frame corresponding to
1749 these codes.
1751 This function allows you to specify a different reference frame which
1752 is used when converting between world and pixel coordinate (see
1753 function conversiontype
1754 to recover the conversion types). If it returns F, it means that
1755 although the conversion machines were successfully created, a trial
1756 conversion failed. This usually means the REST frame was involved
1757 which requires a radial velocity (not yet implemented). If this
1758 happens, the conversion type will be left as it was. The function
1759 fails if more blatant things are wrong like a missing coordinate, or
1760 an incorrect reference code.
1762 The list of possible reference codes can be obtained via function
1763 referencecode.
1765 With this function, you specify the desired reference code. Then,
1766 when a conversion between pixel and world is requested, an extra
1767 conversion is done to ({stff toWorld}) or from ({stff toPixel}) the
1768 specified reference frame.
1770 The summary
1771 function shows the extra conversion reference system to the right of
1772 the native reference system (if it is different) and in parentheses.
1774 Note that to convert between different spectral reference frames, you
1775 need a position, epoch and direction. The position (telescope) and
1776 epoch (date of observation), if not in your coordinate system can be set
1777 with functions settelescope and
1778 setepoch. The direction is the
1779 reference direction of the {it required} direction coordinate in the
1780 coordinate system.
1782 bigskipgoodbreak
1783 As an example, let us say you are working with a spectral coordinate
1784 which was constructed with the LSRK reference frame. You want to convert
1785 some pixel coordinates to barycentric velocities (reference code BARY).
1787 begin{verbatim}
1789 #
1790 print 't----t setconversiontype Ex 1 t----'
1791 csys = cs.newcoordsys(direction=True, spectral=True); # Create coordinate system
1792 rtn=csys.findcoordinate('spectral') # Find spectral coordinate
1793 wa=rtn['world']
1794 pa=rtn['pixel']
1795 u = csys.units()[wa] # Spectral unit
1796 print csys.referencecode(type='spectral') # Which is in LSRK reference frame
1797 #LSRK
1798 p = [10,20,30]
1799 w = csys.toworld(p, format='n') # Convert a pixel to LSRK world
1800 print 'pixel, world = ', p, w['numeric']
1801 #pixel, world = [10, 20, 30] [21589.999816660376, 20.000112822985134, 1415030000.0]
1802 p2 = csys.topixel(w) # and back to pixel
1803 print 'world, pixel = ', w['numeric'], p2
1804 #world, pixel = [21589.999816660376, 20.000112822985134, 1415030000.0]
1805 # [10.00000000000248, 19.999999999999801, 30.0]
1806 # Convert LSRK frequency to LSRK velocity
1807 v = csys.frequencytovelocity(value=w['numeric'][wa], frequnit=u,
1808 doppler='RADIO', velunit='m/s');
1809 print 'pixel, frequency, velocity = ', p[pa], w['numeric'][wa], v
1810 #pixel, frequency, velocity = 30 1415030000.0 1134612.30321
1811 csys.setconversiontype(spectral='BARY') # Specify BARY reference code
1812 w = csys.toworld(p, format='n') # Convert a pixel to BARY world
1813 print 'pixel, world = ', p, w['numeric']
1814 #pixel, world = [10, 20, 30] [21589.999816660376, 20.000112822985134, 1415031369.0081882]
1815 p2 = csys.topixel(w) # and back to pixel
1816 print 'world, pixel = ', w['numeric'], p2
1817 #world, pixel = [21589.999816660376, 20.000112822985134, 1415031369.0081882]
1818 # [10.00000000000248, 19.999999999999801, 30.0]
1819 # Convert BARY frequency to BARY velocity
1820 v = csys.frequencytovelocity(value=w['numeric'][wa], frequnit=u,
1821 doppler='RADIO', velunit='m/s');
1822 print 'pixel, frequency, velocity = ', p[pa], w['numeric'][wa], v
1823 #pixel, frequency, velocity = 30 1415031369.01 1134323.35878
1824 #
1826 end{verbatim}
1829 You must also be aware of when this extra layer is active and when it is
1830 not. It's a bit nasty.
1832 begin{itemize}
1834 item - Whenever you use {stff toWorld}, {stff toPixel}
1835 {stff toWorldMany}, or {stff toPixelMany} the layer is active.
1837 item - Whenever you use {stff convert} or {stff convertMany}
1838 the layer {it may} be active. Here are the rules !
1840 It is only relevant to spectral and direction coordinates.
1842 For the direction coordinate part of your conversion, if you request a
1843 pure world or pixel conversion it is active. Any pixel/world mix will
1844 not invoke it (because it is ill defined).
1846 For the spectral coordinate part it is always active (only one axis
1847 so must be pixel or world).
1849 item - This layer is irrelevant to all functions converting between
1850 frequency and velocity, and absolute and relative. The values are in
1851 whatever frame you are working with.
1853 end{itemize}
1855 The summary function
1856 lists the reference frame for direction and spectral coordinates. If
1857 you have also set a conversion reference code it also lists that (to
1858 the right in parentheses).
1860 Input Parameters:
1861 direction Reference code
1862 spectral Reference code
1864 --------------------------------------------------------------------------------
1866 """
1867 return _coordsys.coordsys_setconversiontype(self, *args, **kwargs)
1870 def getconversiontype(self, *args, **kwargs):
1871 """
1872 getconversiontype(self, _type, _showconversion) -> string
1876 Summary:
1877 Get extra reference conversion layer (aka conversiontype).
1879 Description:
1881 See conversiontype for more complete description.
1883 Input Parameters:
1884 type Conversion type
1885 showconversion Show the conversion layer
1887 --------------------------------------------------------------------------------
1889 """
1890 return _coordsys.coordsys_getconversiontype(self, *args, **kwargs)
1893 def setdirection(self, *args, **kwargs):
1894 """
1895 setdirection(self, _refcode, _proj, _projpar, _refpix, _refval, _incr, _xform, _poles) -> bool
1899 Summary:
1900 Set direction coordinate values
1902 Description:
1906 When you construct a Coordsys tool, if you include a Direction
1907 Coordinate, it will have some default parameters.
1908 This function simply allows you to
1909 replace the values of the Direction Coordinate.
1911 You can also change almost all of those parameters (such as projection, reference value
1912 etc.) via the individual functions
1913 setreferencecode,
1914 setprojection,
1915 setreferencepixel,
1916 setreferencevalue,
1917 setincrement, and
1918 setlineartransform
1919 provided by the Coordsys tool. See those functions for more details
1920 about the formatting of the above function arguments.
1922 Bear in mind, that if your Coordinate System came from a real image, then
1923 the reference pixel is special and you should not change it.
1925 Input Parameters:
1926 refcode Reference code. Default is no change.
1927 proj Projection type. Default is no change.
1928 projpar Projection parameters. Default is no change.
1929 refpix Reference pixel. Default is no change.
1930 refval Reference value. Default is no change.
1931 incr Increment. Default is no change.
1932 xform Linear transform. Default is no change.
1933 poles Native poles. Default is no change.
1935 Example:
1938 #
1939 print 't----t setdirection Ex 1 t----'
1940 csys = cs.newcoordsys(direction=True);
1941 csys.setdirection (refcode='GALACTIC', proj='SIN', projpar=[0,0],
1942 refpix=[-10,20], refval='10deg -20deg');
1943 print csys.projection()
1944 #{'type': 'SIN', 'parameters': array([ 0., 0.])}
1945 print csys.referencepixel()
1946 #{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([-10., 20.])}
1947 print csys.referencevalue(format='s')
1948 #{'ar_type': 'absolute', 'pw_type': 'world',
1949 # 'string': array(['10.00000000 deg', '-20.00000000 deg'], dtype='|S17')}
1950 #
1953 --------------------------------------------------------------------------------
1955 """
1956 return _coordsys.coordsys_setdirection(self, *args, **kwargs)
1959 def setepoch(self, *args, **kwargs):
1960 """
1961 setepoch(self, _value) -> bool
1965 Summary:
1966 Set a new epoch
1968 Description:
1972 This function sets a new epoch (supplied as an
1973 epoch measure) of the observation. You
1974 can get the current epoch with function
1975 epoch.
1977 Input Parameters:
1978 value New epoch measure
1980 Example:
1983 #
1984 print 't----t setepoch Ex 1 t----'
1985 csys = cs.newcoordsys()
1986 ep = csys.epoch()
1987 print ep
1988 #{'type': 'epoch', 'm0': {'value': 54161.766782997685, 'unit': 'd'}, 'refer': 'UTC'}
1989 ep = me.epoch('UTC', 'today')
1990 csys.setepoch(ep)
1991 print csys.epoch()
1992 #{'type': 'epoch', 'm0': {'value': 54161.766782997685, 'unit': 'd'}, 'refer': 'UTC'}
1993 #
1996 --------------------------------------------------------------------------------
1998 """
1999 return _coordsys.coordsys_setepoch(self, *args, **kwargs)
2002 def setincrement(self, *args, **kwargs):
2003 """
2004 setincrement(self, _value, _type) -> bool
2008 Summary:
2009 Set the increment
2011 Description:
2015 Each axis associated with the Coordinate System has a reference value,
2016 reference pixel and an increment (per pixel). These are used in the
2017 mapping from pixel to world coordinate.
2019 This function allows you to set a new
2020 increment. You should not do this on 'stokes' axes unless you are an
2021 adept or a big risk taker.
2023 You can set the increments either for all axes ({stfaf
2024 type=unset}) or for just the axes associated with a particular
2025 coordinate type.
2027 You may supply the increments in all of the formats described in
2028 the htmlref{formatting}{COORDSYS:FORMATTING} discussion.
2030 In addition, you can also supply the increments as a quantity of vector
2031 of doubles. For example {stfaf qa.quantity([-1,2],'arcsec')}.
2033 You can recover the current increments with function
2034 increment.
2036 Input Parameters:
2037 value Increments
2038 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular'. Leave empty for all
2040 Example:
2043 #
2044 print 't----t setincrement Ex 1 t----'
2045 csys=cs.newcoordsys(direction=True, spectral=True)
2046 rv = csys.increment(format='q')
2047 print rv
2048 # {'ar_type': 'absolute', 'pw_type': 'world',
2049 # 'quantity': {'*1': {'value': -1.0, 'unit': '''},
2050 # '*2': {'value': 1.0, 'unit': '''},
2051 # '*3': {'value': 1000.0, 'unit': 'Hz'}}}
2052 rv2 = qa.quantity('4kHz');
2053 csys.setincrement(value=rv2, type='spec')
2054 print csys.increment(type='spec', format='q')
2055 #{'ar_type': 'absolute', 'pw_type': 'world',
2056 # 'quantity': {'*1': {'value': 4000.0, 'unit': 'Hz'}}}
2057 csys.setincrement(value='5kHz', type='spec')
2058 print csys.increment(type='spec', format='q')
2059 #{'ar_type': 'absolute', 'pw_type': 'world',
2060 # 'quantity': {'*1': {'value': 5000.0, 'unit': 'Hz'}}}
2061 print csys.increment(format='q')
2062 #{'ar_type': 'absolute', 'pw_type': 'world',
2063 # 'quantity': {'*1': {'value': -1.0, 'unit': '''},
2064 # '*2': {'value': 1.0, 'unit': '''},
2065 # '*3': {'value': 5000.0, 'unit': 'Hz'}}}
2066 csys.setincrement (value='-2' 2' 2e4Hz')
2067 print csys.increment(format='q')
2068 #{'ar_type': 'absolute', 'pw_type': 'world',
2069 # 'quantity': {'*1': {'value': -2.0, 'unit': '''},
2070 # '*2': {'value': 2.0, 'unit': '''},
2071 # '*3': {'value': 20000.0, 'unit': 'Hz'}}}
2072 #
2076 In the example we first recover the increments as a vector of
2077 quantities. We then create a quantity for a new value for the spectral
2078 coordinate increment. Note we use units of kHz whereas the spectral
2079 coordinate is currently expressed in units of Hz. We then set the
2080 increment for the spectral coordinate. We then recover the increment
2081 again; you can see 4kHz has been converted to 4000Hz. We also show
2082 how to set the increment using a string interface.
2084 --------------------------------------------------------------------------------
2086 """
2087 return _coordsys.coordsys_setincrement(self, *args, **kwargs)
2090 def setlineartransform(self, *args, **kwargs):
2091 """
2092 setlineartransform(self, _type, _value) -> bool
2096 Summary:
2097 Set the linear transform
2099 Description:
2103 This function set the linear transform component. For Stokes Coordinates
2104 this function will return T but do nothing.
2106 You can recover the current linear transform with function
2107 lineartransform.
2109 Input Parameters:
2110 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular'. Leave empty for all.
2111 value Linear transform
2113 Example:
2116 #
2117 print 't----t setlineartransform Ex 1 t----'
2118 csys = cs.newcoordsys(spectral=True, linear=3)
2119 xf = csys.lineartransform('lin')
2120 print xf
2121 #[(1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)]
2122 xf[0]=list(xf[0])
2123 xf[0][1]=0.01
2124 #xf[0]=tuple(xf[0])
2125 csys.setlineartransform('lin',xf)
2126 print csys.lineartransform('lin')
2127 #[(1.0, 0.01, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)]
2130 --------------------------------------------------------------------------------
2132 """
2133 return _coordsys.coordsys_setlineartransform(self, *args, **kwargs)
2136 def setnames(self, *args, **kwargs):
2137 """
2138 setnames(self, _value, _type) -> bool
2142 Summary:
2143 Set the axis names
2145 Description:
2149 Each axis associated with the Coordinate System has a name.
2150 It isn't used in any fundamental way.
2152 This function allows you to set
2153 new axis names.
2155 You can set the names either for all axes ({stfaf
2156 type=unset}) or for just the axes associated with a particular
2157 coordinate type.
2159 You can recover the current axis names with function
2160 names.
2162 Input Parameters:
2163 value Names
2164 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular' or leave empty for all
2166 Example:
2169 #
2170 print 't----t setnames Ex 1 t----'
2171 csys = cs.newcoordsys(spectral=True, linear=2)
2172 csys.setnames(value='a b c')
2173 print csys.names()
2174 #['a', 'b', 'c']
2175 csys.setnames('flying fish', 'lin')
2176 print csys.names()
2177 #['a', 'flying', 'fish']
2178 #
2181 --------------------------------------------------------------------------------
2183 """
2184 return _coordsys.coordsys_setnames(self, *args, **kwargs)
2187 def setobserver(self, *args, **kwargs):
2188 """
2189 setobserver(self, _value) -> bool
2193 Summary:
2194 Set a new observer
2196 Description:
2200 If you want to grab all the glory, or transfer the blame, this function
2201 sets a new observer of the
2202 observation. You can get the current observer with function observer. The
2203 observer's name is not fundamental to the Coordinate System !
2205 Input Parameters:
2206 value New observer
2208 Example:
2211 #
2212 print 't----t setobserver Ex 1 t----'
2213 csys = cs.newcoordsys()
2214 print csys.observer()
2215 #Karl Jansky
2216 csys.setobserver('Ronald Biggs')
2217 print csys.observer()
2218 #Ronald Biggs
2219 #
2222 --------------------------------------------------------------------------------
2224 """
2225 return _coordsys.coordsys_setobserver(self, *args, **kwargs)
2228 def setprojection(self, *args, **kwargs):
2229 """
2230 setprojection(self, _type, _parameters) -> bool
2234 Summary:
2235 Set the direction coordinate projection
2237 Description:
2241 If the Coordinate System contains a direction coordinate, this
2242 function can be used to set the
2243 projection. For discussion about celestial coordinate systems,
2244 including projections, see the papers by Mark Calabretta and Eric
2245 Greisen. The initial draft from 1996 (implemented in casa) can be
2246 found
2247 htmladdnormallink{here}{http://www.atnf.csiro.au/people/mark.calabretta/WCS}.
2249 You can use the function projection
2250 to find out all the possible types of projection. You can also use it
2251 to find out how many parameters you need to describe a particular
2252 projection. See Calabretta and Greisen for details about those
2253 parameters (see section 4 of their paper); in FITS terms these
2254 parameters are what are labelled as PROJP.
2256 Some brief help here on the more common projections in astronomy.
2258 begin{itemize}
2260 item SIN has either 0 parameters or 2. For coplanar arrays like
2261 East-West arrays, one can use what is widely termed the NCP projection.
2262 This is actually a SIN projection where the parameters are 0 and
2263 $1/tan(delta_0)$ where $delta_0$ is the reference declination. Images
2264 made from the ATNF's Compact Array with casa will have such a
2265 projection. Otherwise, the SIN projection requires no parameters (but
2266 you can give it two each of which is zero if you wish).
2268 item TAN is used widely in optical astronomy. It requires 0
2269 parameters.
2271 item ZEA (zenithal equal area) is used widely in survey work.
2272 It requires 0 parameters.
2274 end{itemize}
2276 If the Coordinate System does not contain a direction coordinate,
2277 an exception is generated.
2279 Input Parameters:
2280 type Type of projection
2281 parameters Projection parameters
2283 Example:
2286 #
2287 print 't----t Ex setprojection 1 t----'
2288 im = ia.maketestimage('cena',overwrite=true)
2289 csys = ia.coordsys()
2290 print csys.projection()
2291 #{'type': 'SIN', 'parameters': array([ 0., 0.])}
2292 print csys.projection('ZEA')
2293 #{'nparameters': 0}
2294 csys.setprojection('ZEA')
2295 im2 = ia.regrid('cena.zea', csys=csys.torecord(), overwrite=true)
2296 #
2299 We change the projection of an image from SIN to
2300 ZEA (which requires no parameters).
2302 --------------------------------------------------------------------------------
2304 """
2305 return _coordsys.coordsys_setprojection(self, *args, **kwargs)
2308 def setreferencecode(self, *args, **kwargs):
2309 """
2310 setreferencecode(self, _value, _type, _adjust) -> bool
2314 Summary:
2315 Set new reference code
2317 Description:
2321 This function sets the reference
2322 code for the specified coordinate type. Examples of reference codes
2323 are B1950 and J2000 for direction coordinates, or LSRK and BARY for
2324 spectral coordinates.
2326 You must specify {stfaf type}, selecting from 'direction', or
2327 'spectral' (the first two letters will do). If the Coordinate System
2328 does not contain a coordinate of the type you specify, an exception is
2329 generated.
2331 Specify the new code with argument {stfaf value}. To see the list of
2332 possible codes, use the function referencecode
2333 (see example).
2335 If {stfaf adjust} is T, then the reference value is recomputed.
2336 This is invariably the correct thing to do. If {stfaf adjust} is F,
2337 then the reference code is simply overwritten; do this very carefully.
2339 Input Parameters:
2340 value Reference code
2341 type Coordinate type: direction or spectral
2342 adjust Adjust reference value ?
2344 Example:
2347 #
2348 print 't----t Ex setreferencecode 1 t----'
2349 csys = cs.newcoordsys(direction=True)
2350 clist = csys.referencecode('dir', True) # See possibilities
2351 print clist
2352 #['J2000', 'JMEAN', 'JTRUE', 'APP', 'B1950', 'B1950_VLA', 'BMEAN', 'BTRUE', 'GALACTIC', 'HADEC', 'AZEL', 'AZELSW', 'AZELNE', 'AZELGEO', 'AZELSWGEO', 'AZELNEGEO', 'JNAT', 'ECLIPTIC', 'MECLIPTIC', 'TECLIPTIC', 'SUPERGAL', 'ITRF', 'TOPO', 'ICRS', 'MERCURY', 'VENUS', 'MARS', 'JUPITER', 'SATURN', 'URANUS', 'NEPTUNE', 'PLUTO', 'SUN', 'MOON', 'COMET']
2354 print cs.referencecode('dir')
2355 #J2000
2356 cs.setreferencecode('B1950', 'dir', True)
2357 #
2361 In this example we first get the list of all possible reference codes
2362 for a direction coordinate. Then we set the actual reference code for the direction
2363 coordinate in our Coordinate System.
2368 #
2369 print 't----t Ex setreferencecode 2 t----'
2370 ia.maketestimage('myimage.j2000',overwrite=True) # Open image
2371 csys = ia.coordsys() # Get Coordinate System
2372 print csys.referencecode('dir', F)
2373 #J2000
2374 csys.setreferencecode('B1950', 'dir', T) # Set new direction system
2375 im2 = ia.regrid(outfile='myimage.b1950', csys=csys.torecord(),
2376 overwrite=true) # Regrid and make new image
2377 #
2381 In this example we show how to regrid an image from J2000
2382 to B1950. First we recover the Coordinate System into the Coordsys
2383 tool called {stf cs}. We then set a new direction reference code,
2384 making sure we recompute the reference value. Then the
2385 new Coordinate System is supplied in the regridding process
2386 (done with an Image tool).
2388 --------------------------------------------------------------------------------
2390 """
2391 return _coordsys.coordsys_setreferencecode(self, *args, **kwargs)
2394 def setreferencelocation(self, *args, **kwargs):
2395 """
2396 setreferencelocation(self, _pixel, _world, _mask) -> bool
2400 Summary:
2401 Set reference pixel and value
2403 Description:
2407 This function sets the reference pixel and
2408 reference value to the specified values. The world coordinate can be
2409 specified in any of the formats that the output world coordinate is
2410 returned in by the toworld function.
2412 You can specify a mask (argument {stfaf mask}) indicating which pixel
2413 axes are set (T) and which are left unchanged (F). This function will
2414 refuse to change the reference location of a Stokes axis (gets you into
2415 trouble otherwise).
2417 This function can be rather useful when regridding
2418 images. It allows you to keep easily a particular feature centered in the
2419 regridded image.
2421 Input Parameters:
2422 pixel New reference pixel. Defaults to old reference pixel.
2423 world New reference value. Defaults to old reference value.
2424 mask Indicates which axes to center. Defaults to all.
2426 Example:
2429 #
2430 print 't----t setreferencelocation Ex 1 t----'
2431 csys = cs.newcoordsys(linear=2)
2432 print csys.referencepixel()
2433 #[0.0, 0.0]
2434 print csys.referencevalue()
2435 #{'numeric': array([ 0., 0.])}
2436 w = csys.toworld([19,19], format='n')
2437 shp = [128,128]
2438 p = [64, 64]
2439 csys.setreferencelocation (pixel=p, world=w)
2440 print csys.referencepixel()
2441 #[64.0, 64.0]
2442 print csys.referencevalue()
2443 #{'numeric': array([ 19., 19.])}
2444 #
2447 --------------------------------------------------------------------------------
2449 """
2450 return _coordsys.coordsys_setreferencelocation(self, *args, **kwargs)
2453 def setreferencepixel(self, *args, **kwargs):
2454 """
2455 setreferencepixel(self, _value, _type) -> bool
2459 Summary:
2460 Set the reference pixel
2462 Description:
2466 Each axis associated with the Coordinate System has a reference value,
2467 reference pixel and an increment (per pixel). These are used in the
2468 mapping from pixel to world coordinate.
2470 This function allows you to set a new reference pixel. You should not
2471 do this on 'stokes' axes unless you are an adept or a big risk taker.
2473 You can set the reference pixel either for all axes ({stfaf
2474 type=unset}) or for just the axes associated with a particular
2475 coordinate type.
2477 Bear in mind, that if your Coordinate System came from a real image,
2478 then the reference pixel is special and you should not change it for
2479 Direction Coordinates.
2481 You can recover the current reference pixel with function
2482 referencepixel.
2484 Input Parameters:
2485 value Reference pixel
2486 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular' or leave unset for all
2488 Example:
2491 #
2492 print 't----t setreferencepixel Ex 1 t----'
2493 csys = cs.newcoordsys(spectral=True, linear=2)
2494 csys.setreferencepixel(value=[1.0, 2.0, 3.0])
2495 print csys.referencepixel()
2496 #[1.0, 2.0, 3.0]
2497 csys.setreferencepixel([-1, -1], 'lin')
2498 print csys.referencepixel()
2499 #[1.0, -1.0, -1.0]
2500 #
2503 --------------------------------------------------------------------------------
2505 """
2506 return _coordsys.coordsys_setreferencepixel(self, *args, **kwargs)
2509 def setreferencevalue(self, *args, **kwargs):
2510 """
2511 setreferencevalue(self, _value, _type) -> bool
2515 Summary:
2516 Set the reference value
2518 Description:
2522 Each axis associated with the Coordinate System has a reference value,
2523 reference pixel and an increment (per pixel). These are used in the
2524 mapping from pixel to world coordinate.
2526 This function allows you to set a new
2527 reference value. You should not do this on 'stokes' axes unless you
2528 are an adept or a big risk taker.
2530 You may supply the reference value in all of the formats described in
2531 the htmlref{formatting}{COORDSYS:FORMATTING} discussion.
2533 You can recover the current reference value with function
2534 referencevalue.
2536 Note that the value argument should be one of the specified
2537 possibilitioes. Especially a {stff measure} will be accepted, but
2538 will have a null effect, due to the interpretation as a generic
2539 record.
2541 Input Parameters:
2542 value Reference value
2543 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabular' or leave empty for all.
2545 Example:
2548 #
2549 print 't----t setreferencevalue Ex 1 t----'
2550 csys = cs.newcoordsys(direction=True, spectral=True)
2551 rv = csys.referencevalue(format='q')
2552 print rv
2553 #{'quantity': {'*1': {'value': 0.0, 'unit': '''},
2554 # '*2': {'value': 0.0, 'unit': '''}, '*3': {'value': 1415000000.0, 'unit': 'Hz'}}}
2555 rv2 = rv['quantity']['*3']
2556 rv2['value'] = 2.0e9
2557 print rv2
2558 #{'value': 2000000000.0, 'unit': 'Hz'}
2559 csys.setreferencevalue(type='spec', value=rv2)
2560 print csys.referencevalue(format='n')
2561 #{'numeric': array([ 0.00000000e+00, 0.00000000e+00, 2.00000000e+09])}
2562 #
2563 # To set a new direction reference value, the easiest way, given a
2564 # direction measure dr would be:
2565 dr = me.direction('j2000','30deg','40deg')
2566 # SHOULD BE SIMPLIFIED!!!
2567 newrv=csys.referencevalue(format='q')
2568 newrv['quantity']['*1']=dr['m0']
2569 newrv['quantity']['*2']=dr['m1']
2570 csys.setreferencevalue(value=newrv)
2571 print csys.referencevalue(format='q')
2572 #{'ar_type': 'absolute', 'pw_type': 'world',
2573 # 'quantity': {'*1': {'value': 1800.0, 'unit': '''},
2574 # '*2': {'value': 2399.9999999999995, 'unit': '''},
2575 # '*3': {'value': 1415000000.0, 'unit': 'Hz'}}}
2576 #
2579 --------------------------------------------------------------------------------
2581 """
2582 return _coordsys.coordsys_setreferencevalue(self, *args, **kwargs)
2585 def setrestfrequency(self, *args, **kwargs):
2586 """
2587 setrestfrequency(self, _value, _which, _append) -> bool
2591 Summary:
2592 Set the rest frequency
2594 Description:
2598 If the Coordinate System contains a spectral coordinate, then
2599 it has a rest frequency. In fact, the spectral coordinate
2600 can hold several rest frequencies (to handle for example,
2601 an observation where the band covers many lines), although
2602 only one is active (for velocity conversions) at a time.
2604 This function allows you to set new rest
2605 frequencies. You can provide the rest frequency as a quantity, or as
2606 a quantity string, or a double (units of current rest frequency assumed).
2608 You specify whether the list of frequencies will be appended
2609 to the current list or whether it will replace that list.
2610 You must select which of the frequencies will become the active
2611 one. By default its the first in the list. The index refers
2612 to the final list (either appended or replaced).
2614 You can recover the current rest frequencies with
2615 restfrequency.
2617 If the Coordinate System does not contain a frequency coordinate,
2618 an exception is generated.
2620 Input Parameters:
2621 value New rest frequencies
2622 which Which is the active rest frequency
2623 append Append this list or overwrite ?
2625 Example:
2628 #
2629 print 't----t setrestfrequency Ex 1 t----'
2630 csys = cs.newcoordsys(spectral=True)
2631 print csys.restfrequency()
2632 #{'value': array([ 1.42040575e+09]), 'unit': 'Hz'}
2633 csys.setrestfrequency(qa.quantity('1.4GHz'))
2634 print csys.restfrequency()
2635 #{'value': array([ 1.40000000e+09]), 'unit': 'Hz'}
2636 csys.setrestfrequency(1.3e9)
2637 print csys.restfrequency()
2638 #{'value': array([ 1.30000000e+09]), 'unit': 'Hz'}
2639 csys.setrestfrequency (value=[1.2e9, 1.3e9], which=1)
2640 print csys.restfrequency()
2641 #{'value': array([ 1.30000000e+09, 1.20000000e+09]), 'unit': 'Hz'}
2642 csys.setrestfrequency (qa.quantity([1,2],'GHz'), which=3, append=True)
2643 print csys.restfrequency()
2644 #{'value': array([ 2.00000000e+09, 1.20000000e+09, 1.30000000e+09,
2645 # 1.00000000e+09]), 'unit': 'Hz'}
2646 csys.setrestfrequency ('1.4E9Hz 1667MHz')
2647 print csys.restfrequency()
2648 #{'value': array([ 1.40000000e+09, 1.66700000e+09]), 'unit': 'Hz'}
2649 #
2652 --------------------------------------------------------------------------------
2654 """
2655 return _coordsys.coordsys_setrestfrequency(self, *args, **kwargs)
2658 def setspectral(self, *args, **kwargs):
2659 """
2660 setspectral(self, _refcode, _restfreq, _frequencies, _doppler, _velocities) -> bool
2664 Summary:
2665 Set tabular values for the spectral coordinate
2667 Description:
2671 When you construct a Coordsys tool, if you include a Spectral Coordinate, it
2672 will be linear in frequency. This function allows you to replace the
2673 Spectral Coordinate by a finite table of values. Coordinate
2674 conversions between pixel and world are then done by interpolation.
2676 You may specify either a vector of frequencies or velocities. If you specify
2677 frequencies, you can optionally specify a (new) reference code (see
2678 function setreferencecode
2679 for more details) and rest frequency (else the existing ones will be used).
2681 If you specify velocities, you can optionally specify a (new) reference code
2682 and rest frequency (else the existing ones will be used). You must also give
2683 the doppler type (see
2684 function summary for more
2685 details). The velocities are then converted to frequency for creation of the
2686 Spectral Coordinate (which is fundamentally described by frequency).
2688 You may specify the rest frequency as a Quantum or a double (native units
2689 of Spectral Coordinate used).
2691 Input Parameters:
2692 refcode Reference code. Leave unset for no change.
2693 restfreq Rest frequency. Leave unset for no change.
2694 frequencies Vector of frequencies. Leave unset for no change.
2695 doppler Doppler type. Leave unset for no change.
2696 velocities Vector of velocities types. Leave unset for no change.
2698 Example:
2700 print 't----t setspectral Ex 1 t----'
2701 csys = cs.newcoordsys(spectral=True);
2702 f1 = [1,1.01,1.03,1.4]
2703 fq = qa.quantity(f1, 'GHz')
2704 csys.setspectral(frequencies=fq)
2705 v = csys.frequencytovelocity(f1, 'GHz', 'radio', 'km/s')
2706 print 'v=', v
2707 #v= [88731.317461076716, 86620.706055687479, 82399.483244909003, 4306.8612455073862]
2708 vq = qa.quantity(v, 'km/s')
2709 csys.setspectral(velocities=vq, doppler='radio')
2710 f2 = csys.velocitytofrequency(v, 'GHz', 'radio', 'km/s')
2711 print 'f1 = ', f1
2712 #f1 = [1, 1.01, 1.03, 1.3999999999999999]
2713 print 'f2 = ', f2
2714 #f2 = [1.0, 1.01, 1.03, 1.3999999999999999]
2716 We make a linear Spectral Coordinate. Then overwrite it with
2717 a list of frequenices. Convert those values to velocity,
2718 then overwrite the coordinate starting with a list of
2719 velocities. Then convert the velocities to frequency
2720 and show we get the original result.
2722 --------------------------------------------------------------------------------
2724 """
2725 return _coordsys.coordsys_setspectral(self, *args, **kwargs)
2728 def setstokes(self, *args, **kwargs):
2729 """
2730 setstokes(self, _stokes) -> bool
2734 Summary:
2735 Set the Stokes types
2737 Description:
2741 If the Coordinate System contains a Stokes Coordinate, this function allows
2742 you to change the Stokes types defining it. If there is no Stokes
2743 Coordinate, an exception is generated.
2745 See the coordsys constructor
2746 to see the possible Stokes types you can set.
2748 You can set the Stokes types with function
2749 setstokes.
2751 Input Parameters:
2752 stokes Stokes types
2754 Example:
2757 #
2758 print 't----t setstokes Ex 1 t----'
2759 csys = cs.newcoordsys(stokes='I V')
2760 print csys.stokes()
2761 #['I', 'V']
2762 csys.setstokes('XX RL')
2763 print csys.stokes()
2764 #['XX', 'RL']
2765 #
2768 --------------------------------------------------------------------------------
2770 """
2771 return _coordsys.coordsys_setstokes(self, *args, **kwargs)
2774 def settabular(self, *args, **kwargs):
2775 """
2776 settabular(self, _pixel, _world, _which) -> bool
2780 Summary:
2781 Set tabular values for the tabular coordinate
2783 Description:
2787 When you construct a Coordsys tool, if you include a Tabular
2788 Coordinate, it will be linear. This function allows you to replace the
2789 Tabular Coordinate by a finite table of values. Coordinate conversions
2790 between pixel and world are then done by interpolation (or extrapolation
2791 beyond the end). The table of values must be at least of length 2
2792 or an exception will occur.
2794 You may specify a vector of pixel and world values (in the current units
2795 of the Tabular Coordinate). These vectors must be the same length. If
2796 you leave one of them unset, then the old values are used, but again,
2797 ultimately, the pixel and world vectors must be the same length.
2799 The new reference pixel will be the first pixel value.
2800 The new reference value will be the first world value.
2802 Presently, there is no way for you to recover the lookup table
2803 once you have set it.
2805 If you have more than one Tabular Coordinate, use argument
2806 {stfaf which} to specify which one you want to modify.
2808 Input Parameters:
2809 pixel Vector of (0-rel) pixel values. Default is no change.
2810 world Vector of world values. Default is no change.
2811 which Which Tabular coordinate
2813 Example:
2816 #
2817 print 't----t settabular Ex 1 t----'
2818 csys = cs.newcoordsys(tabular=True);
2819 print csys.settabular (pixel=[1,10,15,20,100], world=[10,20,50,100,500])
2820 #True
2821 #
2824 We make a linear Tabular Coordinate. Then overwrite it with
2825 a non-linear list of pixel and world values.
2827 --------------------------------------------------------------------------------
2829 """
2830 return _coordsys.coordsys_settabular(self, *args, **kwargs)
2833 def settelescope(self, *args, **kwargs):
2834 """
2835 settelescope(self, _value) -> bool
2839 Summary:
2840 Set a new telescope
2842 Description:
2846 This function sets a new telescope of the observation. The telescope
2847 position may be needed for reference code conversions; this is why it is
2848 maintained in the Coordinate System. So it is fundamental
2849 to the Coordinate System and should be correct.
2851 You can find a list of the observatory names know to casa with the
2852 Measures obslist function.
2854 You can get the current telescope with function
2855 telescope.
2857 Input Parameters:
2858 value New telescope
2860 Example:
2863 #
2864 print 't----t settelescope Ex 1 t----'
2865 csys = cs.newcoordsys()
2866 print csys.telescope()
2867 #ATCA
2868 csys.settelescope('VLA')
2869 print csys.telescope()
2870 #VLA
2871 csys.settelescope('The One In My Backyard')
2872 #Tue Mar 6 21:41:24 2007 WARN coordsys::settelescope:
2873 #This telescope is not known to the casapy system
2874 #You can request that it be added
2875 print me.obslist()
2876 #ALMA ARECIBO ATCA BIMA CLRO DRAO DWL GB GBT GMRT IRAM PDB IRAM_PDB
2877 # JCMT MOPRA MOST NRAO12M NRAO_GBT PKS SAO SMA VLA VLBA WSRT
2878 #
2881 --------------------------------------------------------------------------------
2883 """
2884 return _coordsys.coordsys_settelescope(self, *args, **kwargs)
2887 def setunits(self, *args, **kwargs):
2888 """
2889 setunits(self, _value, _type, _overwrite, _which) -> bool
2893 Summary:
2894 Set the axis units
2896 Description:
2900 Each axis associated with the Coordinate System has a unit. This
2901 function allows you to set new axis units.
2903 You can set the units either for all axes ({stfaf
2904 type=unset}) or for just the axes associated with a particular
2905 coordinate type.
2907 In general, the units must be consistent with the old units. When you
2908 change the units, the increment and reference value will be adjusted
2909 appropriately. However, for a linear or tabular coordinate, and only
2910 when you specify {stfaf type='linear'} or {stfaf type='tabular'}
2911 (i.e. you supply units only for the specified linear of tabular
2912 coordinate), and if you set {stfaf overwrite=T}, you can just overwrite
2913 the units with no further adjustments. Otherwise, the {stfaf
2914 overwrite} argument will be silently ignored. Use argument
2915 {stfaf which} to specify which coordinate if you have more
2916 than one of the specified type.
2918 You can recover the current axis units with function
2919 units.
2921 Input Parameters:
2922 value Units
2923 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear', 'tabules' or leave unset for all.
2924 overwrite Overwrite linear or tabular coordinate units?
2925 which Which coordinate if more than one of same type. Default is first.
2927 Example:
2930 #
2931 print 't----t setunits Ex 1 t----'
2932 csys = cs.newcoordsys(direction=True, spectral=True)
2933 csys.summary()
2934 csys.setunits(value='deg rad mHz');
2935 csys.summary()
2936 #
2939 --------------------------------------------------------------------------------
2941 """
2942 return _coordsys.coordsys_setunits(self, *args, **kwargs)
2945 def stokes(self):
2946 """
2947 stokes(self) -> std::vector< std::string >
2951 Summary:
2952 Recover the Stokes types
2954 Description:
2958 If the Coordinate System contains a Stokes Coordinate, this function recovers the
2959 Stokes types defining it. If there is no Stokes
2960 Coordinate, an exception is generated.
2962 You can set the Stokes types with function
2963 setstokes.
2965 Example:
2968 #
2969 print 't----t stokes Ex 1 t----'
2970 csys = cs.newcoordsys(stokes=['I','V'])
2971 print csys.stokes()
2972 #['I', 'V']
2973 csys = cs.newcoordsys(stokes='Q U')
2974 print csys.stokes()
2975 #['Q', 'U']
2976 #
2979 --------------------------------------------------------------------------------
2981 """
2982 return _coordsys.coordsys_stokes(self)
2985 def summary(self, *args, **kwargs):
2986 """
2987 summary(self, _doppler, _list) -> std::vector< std::string >
2991 Summary:
2992 Summarize basic information about the Coordinate System
2994 Description:
2998 This function summarizes the information
2999 contained in the Coordinate System.
3001 For spectral coordinates, the information is listed as a velocity as well as a
3002 frequency. The argument {stfaf doppler} allows you to specify what
3003 doppler convention it is listed in. You can choose from {stfaf radio,
3004 optical} and {stfaf beta}. Alternative names are {stfaf z} for
3005 {stfaf optical}, and {stfaf relativistic} for {stfaf
3006 beta}. The default is {stfaf radio}. The definitions are
3008 begin{itemize}
3009 item radio: $1 - F$
3010 item optical: $-1 + 1/F$
3011 item beta: $(1 - F^2)/(1 + F^2)$
3012 end{itemize}
3013 where $F = nu/nu_0$ and $nu_0$ is the rest frequency. If the rest
3014 frequency has not been set in your image, you can set it with
3015 the function setrestfrequency.
3017 These velocity definitions are provided by the measures
3018 system via the Doppler measure (see example).
3020 If you set {stfaf list=F}, then the summary will not be written
3021 to the global logger. However, the return value will be a vector of strings
3022 holding the summary information, one string per line of the summary.
3024 For direction and spectral coordinates, the reference frame (e.g. J2000
3025 or LSRK) is also listed. Along side this, in parentheses, will be the
3026 conversion reference frame as well (if it is different from the native
3027 reference frame). See function
3028 setconversion to see what this
3029 means.
3031 Input Parameters:
3032 doppler List velocity information with this doppler definition
3033 list List to global logger
3035 Example:
3038 #
3039 print 't----t summary Ex 1 t----'
3040 d = me.doppler('beta')
3041 print me.listcodes(d)
3042 #[normal=RADIO Z RATIO BETA GAMMA OPTICAL TRUE RELATIVISTIC, extra=]
3043 csys = cs.newcoordsys(direction=True, spectral=True)
3044 print csys.summary(list=False)
3045 #
3046 #Direction reference : J2000
3047 #Spectral reference : LSRK
3048 #Velocity type : RADIO
3049 #Rest frequency : 1.42041e+09 Hz
3050 #Telescope : ATCA
3051 #Observer : Karl Jansky
3052 #Date observation : 2007/07/14/04:49:31
3053 #
3054 #Axis Coord Type Name Proj Coord value at pixel Coord incr Units
3055 #-------------------------------------------------------------------------------------
3056 #0 0 Direction Right Ascension SIN 00:00:00.000 0.00 -6.000000e+01 arcsec
3057 #1 0 Direction Declination SIN +00.00.00.000 0.00 6.000000e+01 arcsec
3058 #2 1 Spectral Frequency 1.415e+09 0.00 1.000000e+03 Hz
3059 # Velocity 1140.94 0.00 -2.110611e-01 km/s
3060 #
3061 #
3064 --------------------------------------------------------------------------------
3066 """
3067 return _coordsys.coordsys_summary(self, *args, **kwargs)
3070 def telescope(self):
3071 """
3072 telescope(self) -> string
3076 Summary:
3077 Return the telescope
3079 Description:
3083 This function returns the telescope
3084 contained in the Coordinate System as a
3085 simple string.
3087 The telescope position may be needed for reference code conversions; this is
3088 why it is maintained in the Coordinate System.
3090 The conversion from string to position is done with
3091 Measures observatory.
3092 The example shows how.
3094 Example:
3097 #
3098 print 't----t telescope Ex 1 t----'
3099 csys = cs.newcoordsys()
3100 print csys.telescope()
3101 #ATCA
3102 print me.observatory(csys.telescope())
3103 #{'type': 'position', 'refer': 'ITRF',
3104 # 'm1': {'value': -0.5261379196128062, 'unit': 'rad'},
3105 # 'm0': {'value': 2.6101423190348916, 'unit': 'rad'},
3106 # 'm2': {'value': 6372960.2577234386, 'unit': 'm'}}
3107 #
3111 We get the telescope as a string.
3112 The Measures system is used to convert from
3113 the simple name to a position Measure.
3115 --------------------------------------------------------------------------------
3117 """
3118 return _coordsys.coordsys_telescope(self)
3121 def toabs(self, *args, **kwargs):
3122 """
3123 toabs(self, _value, _isworld) -> record *
3127 Summary:
3128 Convert relative coordinate to absolute
3130 Description:
3134 This function converts a relative coordinate to an absolute coordinate.
3135 The coordinate may be a pixel coordinate or a world coordinate.
3137 If the coordinate is a pixel coordinate, it is supplied as a numeric
3138 vector. If the coordinate is a world coordinate, you may give it in all
3139 of the formats described in the
3140 htmlref{formatting}{COORDSYS:FORMATTING} discussion.
3142 If the coordinate value is supplied by a Coordsys tool function (e.g.
3143 toworld) then the coordinate 'knows'
3144 whether it is world or pixel (and absolute or relative). However, you
3145 might supply the value from some other source as a numeric vector (which
3146 could be world or pixel) in which case you must specify whether it is a
3147 world or pixel coordinate via the {stfaf isworld} argument.
3149 Input Parameters:
3150 value Relative coordinate
3151 isworld Is coordinate world or pixel? Default is unset.
3153 Example:
3156 #
3157 print 't----t toabs Ex 1 t----'
3158 csys = cs.newcoordsys(direction=True, spectral=True)
3159 aw = csys.toworld([100,100,24], 's')
3160 rw = csys.torel(aw)
3161 aw2 = csys.toabs(rw)
3162 print aw
3163 #{'ar_type': 'absolute', 'pw_type': 'world',
3164 # 'string': array(['23:53:19.77415678', '+01.40.00.84648186',
3165 # '1.41502400e+09 Hz'], dtype='|S19')}
3166 print rw
3167 #{'ar_type': 'relative', 'pw_type': 'world',
3168 # 'string': array(['-6.00084720e+03 arcsec', '6.00084648e+03 arcsec',
3169 # '2.40000000e+04 Hz'], dtype='|S23')}
3170 print aw2
3171 #{'ar_type': 'absolute', 'pw_type': 'world',
3172 # 'string': array(['23:53:19.77415672', '+01.40.00.84648000',
3173 # '1.41502400e+09 Hz'], dtype='|S19')}
3174 #
3178 This example uses world coordinates.
3182 #
3183 print 't----t toabs Ex 2 t----'
3184 csys = cs.newcoordsys(direction=True, spectral=True)
3185 ap = csys.topixel() # Reference value
3186 rp = csys.torel(ap)
3187 ap2 = csys.toabs(rp)
3188 print ap
3189 #{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([ 0., 0., 0.])}
3190 print rp
3191 #{'ar_type': 'relative', 'pw_type': 'world',
3192 # 'numeric': array([ 0.00000000e+00, 0.00000000e+00, -1.41500000e+09])}
3193 print ap2
3194 #{'ar_type': 'absolute', 'pw_type': 'world', 'numeric': array([ 0., 0., 0.])}
3195 #
3198 This example uses pixel coordinates.
3200 --------------------------------------------------------------------------------
3202 """
3203 return _coordsys.coordsys_toabs(self, *args, **kwargs)
3206 def toabsmany(self, *args, **kwargs):
3207 """
3208 toabsmany(self, _value, _isworld) -> record *
3212 Summary:
3213 Convert many numeric relative coordinates to absolute
3215 Description:
3219 This function converts many relative coordinates to absolute. It exists
3220 so you can efficiently make many conversions (which would be rather slow
3221 if you did them all with toabs). Because
3222 speed is the object, the interface is purely in terms of numeric
3223 matrices, rather than being able to accept strings and quanta etc. like
3224 toabs can.
3226 When dealing with world coordinates, the units of the numeric
3227 values must be the native units, given by function
3228 units.
3230 Input Parameters:
3231 value Relative coordinates
3232 isworld Is coordinate world or pixel? Default is unset.
3234 Example:
3237 #
3238 print 't----t toabsmany Ex 1 t----'
3239 csys = cs.newcoordsys(direction=True, spectral=True) # 3 axes
3240 rv = csys.referencevalue(); # reference value
3241 w = csys.torel(rv) # make relative
3242 inc = csys.increment(); # increment
3243 off=[]
3244 for idx in range(100):
3245 off.append(inc['numeric'][2]*idx) # offset for third axis
3246 wrel = ia.makearray(0,[3,100]) # 100 conversions each of length 3
3247 for i in range(3):
3248 for j in range(100):
3249 wrel[i][j]=w['numeric'][i]
3250 for j in range(100):
3251 wrel[2][j] += off[j] # Make spectral axis values change
3252 wabs = csys.toabsmany (wrel, T)['numeric'] # Convert
3253 print wabs[0][0],wabs[1][0],wabs[2,0] # First absolute coordinate
3254 #0.0 0.0 1415000000.0
3255 print wabs[0][99],wabs[1][99],wabs[2][99] # 100th absolute coordinate
3256 #0.0 0.0 1415099000.0
3257 #
3260 This example uses world coordinates.
3262 --------------------------------------------------------------------------------
3264 """
3265 return _coordsys.coordsys_toabsmany(self, *args, **kwargs)
3268 def topixel(self, *args, **kwargs):
3269 """
3270 topixel(self, _value) -> record *
3274 Summary:
3275 Convert from absolute world to pixel coordinate
3277 Description:
3281 This function converts between world (physical) coordinate and absolute pixel
3282 coordinate (0-rel).
3284 The world coordinate can be provided in one of four formats via the
3285 argument {stfaf world}. These match the output formats of function
3286 toworld.
3288 If you supply fewer world values than there are axes in the Coordinate
3289 System, your coordinate vector will be padded out with the reference
3290 value for the missing axes. Excess values will be silently ignored.
3292 You may supply the world coordinate in all of the formats described in
3293 the htmlref{formatting}{COORDSYS:FORMATTING} discussion.
3295 Input Parameters:
3296 value Absolute world coordinate
3298 Example:
3301 #
3302 print 't----t topixel Ex 1 t----'
3303 csys = cs.newcoordsys(direction=True, spectral=True, stokes='I V', linear=2)
3304 w = csys.toworld([-2,2,1,2,23,24], 'n')
3305 print csys.topixel(w)
3306 #{'ar_type': 'absolute', 'pw_type': 'pixel',
3307 # 'numeric': array([ -2., 2., 1., 2., 23., 24.])}
3308 w = csys.toworld([-2,2,1,2,23,24], 'q')
3309 print csys.topixel(w)
3310 #{'ar_type': 'absolute', 'pw_type': 'pixel',
3311 # 'numeric': array([ -2., 2., 1., 2., 23., 24.])}
3312 w = csys.toworld([-2,2,1,2,23,24], 'm')
3313 print csys.topixel(w)
3314 #{'ar_type': 'absolute', 'pw_type': 'pixel',
3315 # 'numeric': array([ -2., 2., 1., 2., 23., 24.])}
3316 w = csys.toworld([-2,2,1,2,23,24], 's')
3317 print cs.topixel(w)
3318 #{'ar_type': 'absolute', 'pw_type': 'pixel',
3319 # 'numeric': array([ -2., 2., 1., 2., 23., 24.])}
3320 w = csys.toworld([-2,2,1,2,23,24], 'mnq')
3321 print cs.topixel(w)
3322 #{'ar_type': 'absolute', 'pw_type': 'pixel',
3323 # 'numeric': array([ -2., 2., 1., 2., 23., 24.])}
3324 #
3330 #
3331 print 't----t topixel Ex 2 t----'
3332 csys = cs.newcoordsys (stokes='I V', linear=2)
3333 print csys.toworld([0,1,2], 's')
3334 #{'ar_type': 'absolute', 'pw_type': 'world',
3335 # 'string': array(['I', '1.00000000e+00 km', '2.00000000e+00 km'],
3336 # dtype='|S18')}
3337 print csys.toworld([0,1,2], 'm')
3338 #{'ar_type': 'absolute', 'pw_type': 'world',
3339 # 'measure': {'stokes': 'I', 'linear': {'*1': {'value': 1.0, 'unit': 'km'},
3340 # '*2': {'value': 2.0, 'unit': 'km'}}}}
3341 print csys.toworld([0,1,2], 'q')
3342 #{'ar_type': 'absolute', 'pw_type': 'world',
3343 # 'quantity': {'*1': {'value': 1.0, 'unit': ''},
3344 # '*2': {'value': 1.0, 'unit': 'km'}, '*3': {'value': 2.0, 'unit': 'km'}}}
3345 #
3351 #
3352 print 't----t topixel Ex 3 t----'
3353 csys = cs.newcoordsys (spectral=True, linear=1)
3354 print csys.toworld([0,1,2], 'q')
3355 #{'ar_type': 'absolute', 'pw_type': 'world',
3356 # 'quantity': {'*1': {'value': 1415000000.0, 'unit': 'Hz'},
3357 # '*2': {'value': 1.0, 'unit': 'km'}}}
3358 #
3361 --------------------------------------------------------------------------------
3363 """
3364 return _coordsys.coordsys_topixel(self, *args, **kwargs)
3367 def topixelmany(self, *args, **kwargs):
3368 """
3369 topixelmany(self, _value) -> record *
3373 Summary:
3374 Convert many absolute numeric world coordinates to pixel
3376 Description:
3380 This function converts many absolute world coordinates to pixel coordinates. It exists
3381 so you can efficiently make many conversions (which would be rather slow
3382 if you did them all with topixel). Because
3383 speed is the object, the interface is purely in terms of numeric
3384 matrices, rather than being able to accept strings and quanta etc. like
3385 topixel can.
3387 The units of the numeric values must be the native units, given by
3388 function units.
3390 Input Parameters:
3391 value Absolute world coordinates
3393 Example:
3396 #
3397 print 't----t topixelmany Ex 1 t----'
3398 csys = cs.newcoordsys(direction=True, spectral=True) # 3 axes
3399 rv = csys.referencevalue(); # reference value
3400 inc = csys.increment(); # increment
3401 off = []
3402 for idx in range(100):
3403 off.append(inc['numeric'][2] * idx) # offset for third axis
3404 wabs = ia.makearray(0, [3,100]) # 100 conversions each of length 3
3405 for i in range(3):
3406 for j in range(100):
3407 wabs[i][j]=rv['numeric'][i]
3408 for j in range(100):
3409 wabs[2][j] += off[j] # Make spectral axis values change
3410 pabs = csys.topixelmany (wabs)['numeric']; # Convert
3411 print pabs[0][0], pabs[1][0], pabs[1][2] # First absolute pixel coordinate
3412 #0.0 0.0 0.0
3413 print pabs[0][99], pabs[1][99], pabs[2][99] # 100th absolute pixel coordinate
3414 #0.0 0.0 99.0
3415 #
3418 --------------------------------------------------------------------------------
3420 """
3421 return _coordsys.coordsys_topixelmany(self, *args, **kwargs)
3424 def torecord(self):
3425 """
3426 torecord(self) -> record *
3430 Summary:
3431 Convert Coordinate System to a record
3433 Description:
3437 You can convert a Coordinate System to a record with this function.
3438 There is also fromrecord
3439 to set a Coordinate System from a record.
3441 These functions allow
3442 Coordsys tools to be used as parameters in the methods of other tools.
3444 Example:
3447 #
3448 print 't----t torecord Ex 1 t----'
3449 csys = cs.newcoordsys(direction=True, stokes='I Q')
3450 rec = csys.torecord();
3451 cs2 = cs.newcoordsys();
3452 print cs2.ncoordinates()
3453 #0
3454 cs2.fromrecord(rec);
3455 print csys.ncoordinates(), cs2.ncoordinates()
3456 #2 2
3457 #
3460 --------------------------------------------------------------------------------
3462 """
3463 return _coordsys.coordsys_torecord(self)
3466 def subimage(self, *args, **kwargs):
3467 """
3468 subimage(self, _originshft, _newshape) -> record *
3472 Summary:
3473 delivers a coordinate origin re-referenced for a subimage
3475 Description:
3479 You can convert a Coordinate System to another coordinatesystem applicable to a
3480 subImage. The newshape does not matter as this is the coordinatesystem not the
3481 image except for Stokes axis; therefore you can ignore {tt newshape} except
3482 when your sub-image you are considering has only a section of your original Stokes
3483 axis.
3485 Input Parameters:
3486 originshft The shift value from original reference (vector of values in pixels)
3487 newshape The new shape of the image it will applicable to (pixel shape)
3489 Example:
3492 #
3493 print 't----t subimage Ex 1 t----'
3494 ia.open('original.image')
3495 csys = ia.coordsys()
3496 imshape=ia.shape()
3497 #want to make an empty sub image of the 11th channel
3498 #keeping other reference pixel as is
3499 refshft=[0,0,0,10]
3500 subcoordsysrec=csys.subimage(neworigin=refshft)
3501 imshape[3]=1
3502 ia.fromshape(outfile='Eleventh_chan_template.image', shape=imshape, csys=subcoordsysrec)
3506 --------------------------------------------------------------------------------
3508 """
3509 return _coordsys.coordsys_subimage(self, *args, **kwargs)
3512 def torel(self, *args, **kwargs):
3513 """
3514 torel(self, _value, _isworld) -> record *
3518 Summary:
3519 Convert absolute coordinate to relative
3521 Description:
3525 This function converts an absolute coordinate to a relative coordinate.
3526 The coordinate may be a pixel coordinate or a world coordinate.
3528 Relative coordinates are relative to the reference pixel (pixel coordinates)
3529 or the reference value (world coordinates) in the sense
3530 $relative = absolute - reference$.
3532 If the coordinate is a pixel coordinate, it is supplied as a numeric
3533 vector. If the coordinate is a world coordinate, you may give it in all
3534 of the formats described in the
3535 htmlref{formatting}{COORDSYS:FORMATTING} discussion.
3537 If the coordinate value is supplied by a Coordsys tool function (e.g.
3538 toworld) then the coordinate 'knows'
3539 whether it is world or pixel (and absolute or relative). However, you
3540 might supply the value from some other source as a numeric vector (which
3541 could be world or pixel) in which case you must specify whether it is a
3542 world or pixel coordinate via the {stfaf isworld} argument.
3544 Input Parameters:
3545 value Absolute coordinate
3546 isworld Is coordinate world or pixel? Default is unset.
3548 Example:
3551 #
3552 print 't----t torel Ex 1 t----'
3553 csys = cs.newcoordsys(direction=True, spectral=True)
3554 aw = csys.toworld([99,99,23], 's')
3555 rw = csys.torel(aw)
3556 aw2 = csys.toabs(rw)
3557 print aw
3558 #{'ar_type': 'absolute', 'pw_type': 'world',
3559 # 'string': array(['23:53:23.78086843', '+01.39.00.82133427',
3560 # '1.41502300e+09 Hz'], dtype='|S19')}
3561 print rw
3562 #{'ar_type': 'relative', 'pw_type': 'world',
3563 # 'string': array(['-5.94082202e+03 arcsec', '5.94082133e+03 arcsec',
3564 # '2.30000000e+04 Hz'], dtype='|S23')}
3565 print aw2
3566 #{'ar_type': 'absolute', 'pw_type': 'world',
3567 # 'string': array(['23:53:23.78086818', '+01.39.00.82133000',
3568 # '1.41502300e+09 Hz'], dtype='|S19')}
3569 #
3573 This example uses world coordinates.
3577 #
3578 print 't----t torel Ex 2 t----'
3579 csys = cs.newcoordsys(direction=True, spectral=True)
3580 ap = csys.topixel() # Reference value
3581 rp = csys.torel(ap)
3582 ap2 = csys.toabs(rp)
3583 print ap
3584 #{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([ 0., 0., 0.])}
3585 print rp
3586 #{'ar_type': 'relative', 'pw_type': 'pixel', 'numeric': array([ 0., 0., 0.])}
3587 print ap2
3588 #{'ar_type': 'absolute', 'pw_type': 'pixel', 'numeric': array([ 0., 0., 0.])}
3589 #
3592 This example uses pixel coordinates.
3594 --------------------------------------------------------------------------------
3596 """
3597 return _coordsys.coordsys_torel(self, *args, **kwargs)
3600 def torelmany(self, *args, **kwargs):
3601 """
3602 torelmany(self, _value, _isworld) -> record *
3606 Summary:
3607 Convert many numeric absolute coordinates to relative
3609 Description:
3613 This function converts many absolute coordinates to relative. It exists
3614 so you can efficiently make many conversions (which would be rather slow
3615 if you did them all with torel). Because
3616 speed is the object, the interface is purely in terms of numeric
3617 matrices, rather than being able to accept strings and quanta etc. like
3618 torel can.
3620 When dealing with world coordinates, the units of the numeric
3621 values must be the native units, given by function
3622 units.
3624 Input Parameters:
3625 value Absolute coordinates
3626 isworld Is coordinate world or pixel? Default is unset.
3628 Example:
3631 #
3632 print 't----t torelmany Ex 1 t----'
3633 csys = cs.newcoordsys(direction=True, spectral=True) # 3 axes
3634 w = csys.referencevalue(); # reference value
3635 inc = csys.increment(); # increment
3636 off = []
3637 for idx in range(100):
3638 off.append(inc['numeric'][2] * idx) # offset for third axis
3639 wabs = ia.makearray(0, [3,100]) # 100 conversions each of length 3
3640 for i in range(3):
3641 for j in range(100):
3642 wabs[i][j] = w['numeric'][i]
3643 for j in range(100):
3644 wabs[2][j] += off[j] # Make spectral axis values change
3645 wrel = cs.torelmany (wabs, T)['numeric'] # Convert
3646 print wrel[0][0], wrel[1][0], wrel[2][0] # First relative coordinate
3647 #0.0 0.0 0.0
3648 print wrel[0][99], wrel[1][99], wrel[2][99] # 100th relative coordinate
3649 #0.0 0.0 99000.0
3650 #
3653 This example uses world coordinates.
3655 --------------------------------------------------------------------------------
3657 """
3658 return _coordsys.coordsys_torelmany(self, *args, **kwargs)
3661 def toworld(self, *args, **kwargs):
3662 """
3663 toworld(self, _value, _format) -> record *
3667 Summary:
3668 Convert from absolute pixel coordinate to world
3670 Description:
3674 This function converts between absolute pixel coordinate (0-rel)
3675 and absolute world (physical coordinate).
3677 If you supply fewer pixel values than there are axes in the Coordinate
3678 System, your coordinate vector will be padded out with the reference
3679 pixel for the missing axes. Excess values will be silently ignored.
3681 You may ask for the world coordinate in all of the formats described in
3682 the htmlref{discussion}{COORDSYS:FORMATTING} regarding the
3683 formatting possibilities available via argument {stfaf format}.
3685 Input Parameters:
3686 value Absolute pixel coordinate. Default is reference pixel.
3687 format Format string: combination of 'n', 'q', 's', 'm'
3689 Example:
3692 #
3693 print 't----t toworld Ex 1 t----'
3694 csys = cs.newcoordsys(direction=True, spectral=True)
3695 print csys.toworld([-3,1,1], 'n')
3696 #{'ar_type': 'absolute', 'pw_type': 'world',
3697 # 'numeric': array([ 3.00000051e+00, 1.00000001e+00, 1.41500100e+09])}
3698 print csys.toworld([-3,1,1], 'q')
3699 #{'ar_type': 'absolute', 'pw_type': 'world',
3700 # 'quantity': {'*1': {'value': 3.0000005076962117, 'unit': '''},
3701 # '*2': {'value': 1.0000000141027674, 'unit': '''},
3702 # '*3': {'value': 1415001000.0, 'unit': 'Hz'}}}
3703 print csys.toworld([-3,1,1], 'm')
3704 #{'ar_type': 'absolute', 'pw_type': 'world', 'measure':
3705 # {'spectral': {'radiovelocity': {'type': 'doppler', 'm0': {'value': 1140733.0762829871, 'unit': 'm/s'}, 'refer': 'RADIO'},
3706 # 'opticalvelocity': {'type': 'doppler', 'm0': {'value': 1145090.2316004676, 'unit': 'm/s'}, 'refer': 'OPTICAL'},
3707 # 'frequency': {'type': 'frequency', 'm0': {'value': 1415001000.0, 'unit': 'Hz'}, 'refer': 'LSRK'},
3708 # 'betavelocity': {'type': 'doppler', 'm0': {'value': 1142903.3485169839, 'unit': 'm/s'}, 'refer': 'TRUE'}},
3709 # 'direction': {'type': 'direction', 'm1': {'value': 0.0002908882127680503, 'unit': 'rad'},
3710 # 'm0': {'value': 0.00087266477368000634, 'unit': 'rad'}, 'refer': 'J2000'}}}
3711 print csys.toworld([-3,1,1], 's')
3712 #{'ar_type': 'absolute', 'pw_type': 'world',
3713 # 'string': array(['00:00:12.00000203', '+00.01.00.00000085', '1.41500100e+09 Hz'], dtype='|S19')}
3714 #
3720 #
3721 print 't----t toworld Ex 2 t----'
3722 csys = cs.newcoordsys (stokes='I V', linear=2)
3723 print csys.toworld([0,1,2], 's')
3724 #{'ar_type': 'absolute', 'pw_type': 'world',
3725 # 'string': array(['I', '1.00000000e+00 km', '2.00000000e+00 km'],
3726 # dtype='|S18')}
3727 print csys.toworld([0,1,2], 'm')
3728 #{'ar_type': 'absolute', 'pw_type': 'world',
3729 # 'measure': {'stokes': 'I', 'linear': {'*1': {'value': 1.0, 'unit': 'km'},
3730 # '*2': {'value': 2.0, 'unit': 'km'}}}}
3731 print csys.toworld([0,1,2], 'q')
3732 #{'ar_type': 'absolute', 'pw_type': 'world',
3733 # 'quantity': {'*1': {'value': 1.0, 'unit': ''},
3734 # '*2': {'value': 1.0, 'unit': 'km'},
3735 # '*3': {'value': 2.0, 'unit': 'km'}}}
3736 #
3742 #
3743 print 't----t toworld Ex 3 t----'
3744 csys = cs.newcoordsys (spectral=True, linear=1)
3745 print cs.toworld([0,1,2], 'q')
3746 #{'ar_type': 'absolute', 'pw_type': 'world',
3747 # 'quantity': {'*1': {'value': 1415000000.0, 'unit': 'Hz'},
3748 # '*2': {'value': 1.0, 'unit': 'km'}}}
3749 #
3752 --------------------------------------------------------------------------------
3754 """
3755 return _coordsys.coordsys_toworld(self, *args, **kwargs)
3758 def toworldmany(self, *args, **kwargs):
3759 """
3760 toworldmany(self, _value) -> record *
3764 Summary:
3765 Convert many absolute pixel coordinates to numeric world
3767 Description:
3771 This function converts many absolute pixel coordinates to world coordinates. It exists
3772 so you can efficiently make many conversions (which would be rather slow
3773 if you did them all with toworld). Because
3774 speed is the object, the interface is purely in terms of numeric
3775 matrices, rather than being able to produce strings and quanta etc. like
3776 toworld can.
3778 The units of the output world values are the native units given by
3779 function units.
3781 Input Parameters:
3782 value Absolute pixel coordinates
3784 Example:
3787 #
3788 print 't----t toworldmany Ex 1 t----'
3789 csys = cs.newcoordsys(direction=True, spectral=True) # 3 axes
3790 rp = csys.referencepixel()['numeric']; # reference pixel
3791 pabs = ia.makearray(0,[3,100]) # 100 conversions each of length 3
3792 for i in range(3):
3793 for j in range(100):
3794 pabs[i][j] = rp[i]
3795 for ioff in range(100): # offset for third axis
3796 pabs[2][ioff] += ioff; # Make spectral axis values change
3797 wabs = csys.toworldmany (pabs)['numeric']; # Convert
3798 print wabs[0][0], wabs[1][0], wabs[2][0] # First absolute pixel coordinate
3799 #0.0 0.0 1415000000.0
3800 print wabs[0][99], wabs[1][99], wabs[2][99] # 100th absolute pixel coordinate
3801 #0.0 0.0 1415099000.0
3802 #
3805 --------------------------------------------------------------------------------
3807 """
3808 return _coordsys.coordsys_toworldmany(self, *args, **kwargs)
3811 def type(self):
3812 """
3813 type(self) -> string
3817 Summary:
3818 Return the type of this tool
3820 Description:
3824 This function returns the string `coordsys'.
3826 --------------------------------------------------------------------------------
3828 """
3829 return _coordsys.coordsys_type(self)
3832 def units(self, *args, **kwargs):
3833 """
3834 units(self, _type) -> std::vector< std::string >
3838 Summary:
3839 Recover the units for each axis
3841 Description:
3845 Each axis associated with the Coordinate System has a unit.
3846 This function returns those units
3847 (in world axis order).
3849 You can recover the units either for all coordinates (leave {stfaf
3850 type} unset) or for a specific coordinate type (mimumum match of the
3851 allowed types will do). If you ask for a non-existent coordinate an
3852 exception is generated.
3854 You can set the units with function
3855 setunits.
3857 Input Parameters:
3858 type Coordinate type: 'direction', 'stokes', 'spectral', 'linear' or leave unset for all
3860 Example:
3863 #
3864 print 't----t units Ex 1 t----'
3865 csys = cs.newcoordsys(direction=True, spectral=True)
3866 print csys.units()
3867 #[''', ''', 'Hz']
3868 print csys.units('spec')
3869 #Hz
3870 #
3873 --------------------------------------------------------------------------------
3875 """
3876 return _coordsys.coordsys_units(self, *args, **kwargs)
3879 def velocitytofrequency(self, *args, **kwargs):
3880 """
3881 velocitytofrequency(self, _value, _frequnit, _doppler, _velunit) -> std::vector< double >
3885 Summary:
3886 Convert velocity to frequency
3888 Description:
3892 This function converts velocities
3893 to frequencies.
3895 The input velocities are specified via a vector of numeric values, a
3896 specified unit ({stfaf velunit}), and a velocity doppler definition ({stfaf
3897 doppler}).
3899 The frequencies are returned in a vector for which you specify the
3900 units ({stfaf frequnit}). If you don't give the unit, it is assumed that
3901 the units are those given by function units
3902 for the spectral coordinate.
3904 This function will return a fail if there is no spectral coordinate
3905 in the Coordinate System. See also the function
3906 frequencytovelocity.
3908 Input Parameters:
3909 value Velocity to convert
3910 frequnit Unit of output frequencies. Default is intrinisic units.
3911 doppler Velocity doppler definition
3912 velunit Unit of input velocities
3914 Example:
3917 #
3918 print 't----t velocitytofrequency Ex 1 t----'
3919 ia.fromshape('hcn.cube',[64,64,32,4], overwrite=true)
3920 csys = ia.coordsys()
3921 rtn = csys.findcoordinate('spectral') # Find spectral axis
3922 pixel = csys.referencepixel(); # Use reference pixel for non-spectral
3923 pa = rtn['pixel']
3924 wa = rtn['world']
3925 nFreq = ia.shape()[pa] # Length of spectral axis
3926 freq = []
3927 for i in range(nFreq):
3928 pixel[pa] = i; # Assign value for spectral axis of pixel coordinate
3929 w = csys.toworld(value=pixel, format='n')# Convert pixel to world
3930 freq.append(w['numeric'][wa]) # Fish out frequency
3931 print 'freq=', freq
3932 vel = csys.frequencytovelocity(value=freq, doppler='optical', velunit='km/s')
3933 freq2 = csys.velocitytofrequency(value=vel, doppler='optical', velunit='km/s')
3934 print 'vel=',vel
3935 print 'freq2=',freq2
3936 csys.done()
3937 #
3938 exit() # This is last example so exit casapy if you wish.
3939 #
3943 In this example, we find the optical velocity in km/s of every pixel
3944 along the spectral axis of our image. First we obtain the Coordinate
3945 System from the image. Then we find which axis of the Coordinate System
3946 (image) pertain to the spectral coordinate. Then we loop over each
3947 pixel of the spectral axis, and convert a pixel coordinate (one for each
3948 axis of the image) to world. We obtain the value for the spectral axis
3949 from that world vector, and add it to the vector of frequencies. Then
3950 we convert that vector of frequencies to velocity. Then we convert it
3951 back to frequency. They better agree.
3953 --------------------------------------------------------------------------------
3955 """
3956 return _coordsys.coordsys_velocitytofrequency(self, *args, **kwargs)
3959 def parentname(self):
3960 """
3961 parentname(self) -> string
3965 Summary:
3966 Get parent image name.
3968 Description:
3972 This function returns the parent image name for `coordsys'.
3974 --------------------------------------------------------------------------------
3976 """
3977 return _coordsys.coordsys_parentname(self)
3980 def setparentname(self, *args, **kwargs):
3981 """
3982 setparentname(self, _imagename) -> bool
3986 Summary:
3987 Set the parent image name (normally not needed by end-users)
3989 Input Parameters:
3990 imagename String named parent image
3992 --------------------------------------------------------------------------------
3994 """
3995 return _coordsys.coordsys_setparentname(self, *args, **kwargs)
3997 __swig_destroy__ = _coordsys.delete_coordsys
3998 __del__ = lambda self: None
3999coordsys_swigregister = _coordsys.coordsys_swigregister
4000coordsys_swigregister(coordsys)
4002# This file is compatible with both classic and new-style classes.