0
# Coordinate Systems and Measures
1
2
Astronomical reference frames, coordinate conversions, and measurement systems. Handles directions, positions, epochs, frequencies, Doppler shifts, and baseline/UVW coordinates with full support for reference frame transformations and precise astronomical calculations.
3
4
## Core Imports
5
6
```python
7
from casacore.measures import measures, is_measure
8
```
9
10
## Capabilities
11
12
### Measures Server
13
14
Central server for managing astronomical reference frames and performing coordinate transformations.
15
16
```python { .api }
17
class measures:
18
def __init__(self):
19
"""Create measures server instance."""
20
21
def measure(self, v, rf, off=None):
22
"""
23
Convert measure to specified reference frame.
24
25
Parameters:
26
- v: dict, measure to convert
27
- rf: str, target reference frame
28
- off: dict, optional offset measure
29
30
Returns:
31
dict, converted measure
32
"""
33
34
def doframe(self, v):
35
"""
36
Set measure as part of reference frame.
37
38
Parameters:
39
- v: dict, measure to add to frame
40
41
Returns:
42
bool, True if successfully added to frame
43
"""
44
45
def list_codes(self, m):
46
"""
47
Get valid reference codes for measure type.
48
49
Parameters:
50
- m: dict, measure to get codes for
51
52
Returns:
53
dict with 'normal' and 'extra' code lists
54
"""
55
56
def is_measure(v):
57
"""
58
Check if object is a valid measure.
59
60
Parameters:
61
- v: object to check
62
63
Returns:
64
bool, True if valid measure
65
"""
66
```
67
68
### Direction Measures
69
70
Handle celestial directions with support for various coordinate systems and epochs.
71
72
```python { .api }
73
class measures:
74
def direction(self, rf='', v0='0..', v1='90..', off=None):
75
"""
76
Create direction measure.
77
78
Parameters:
79
- rf: str, reference frame ('J2000', 'B1950', 'GALACTIC', 'AZEL', etc.)
80
- v0: str or quantity, longitude/RA (angle)
81
- v1: str or quantity, latitude/Dec (angle)
82
- off: dict, optional offset direction
83
84
Returns:
85
dict, direction measure with 'type': 'direction'
86
87
Reference frames:
88
- J2000, JMEAN, JTRUE: Julian epoch systems
89
- B1950, BMEAN, BTRUE: Besselian epoch systems
90
- APP: Apparent (topocentric)
91
- GALACTIC: Galactic coordinates
92
- SUPERGAL: Supergalactic coordinates
93
- ECLIPTIC, MECLIPTIC, TECLIPTIC: Ecliptic systems
94
- HADEC: Hour angle/declination
95
- AZEL: Azimuth/elevation (requires position frame)
96
- Planets: MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, NEPTUNE, PLUTO, MOON, SUN
97
"""
98
```
99
100
### Position Measures
101
102
Handle terrestrial and celestial positions with various geodetic systems.
103
104
```python { .api }
105
class measures:
106
def position(self, rf='', v0='0..', v1='90..', v2='0m', off=None):
107
"""
108
Create position measure.
109
110
Parameters:
111
- rf: str, reference frame ('WGS84', 'ITRF')
112
- v0: str or quantity, longitude or X (angle or length)
113
- v1: str or quantity, latitude or Y (angle or length)
114
- v2: str or quantity, height or Z (length)
115
- off: dict, optional offset position
116
117
Returns:
118
dict, position measure with 'type': 'position'
119
120
Reference frames:
121
- WGS84: World Geodetic System 1984
122
- ITRF: International Terrestrial Reference Frame
123
"""
124
125
def observatory(self, name):
126
"""
127
Get position measure for known observatory.
128
129
Parameters:
130
- name: str, observatory name (case insensitive)
131
132
Returns:
133
dict, position measure for observatory
134
135
Known observatories include:
136
ALMA, ATCA, BIMA, CLRO, DRAO, DWL, GB, JCMT,
137
MOPRA, NRAO12M, PKS, VLA, WSRT, and others
138
"""
139
140
def get_observatories(self):
141
"""
142
Get list of known observatory names.
143
144
Returns:
145
list of str, observatory names
146
"""
147
```
148
149
### Epoch and Time Measures
150
151
Handle time epochs with various time systems and conversions.
152
153
```python { .api }
154
class measures:
155
def epoch(self, rf='', v0='0.0d', off=None):
156
"""
157
Create epoch measure.
158
159
Parameters:
160
- rf: str, time reference frame
161
- v0: str or quantity, time value
162
- off: dict, optional offset epoch
163
164
Returns:
165
dict, epoch measure with 'type': 'epoch'
166
167
Reference frames:
168
- UTC: Coordinated Universal Time
169
- TAI: International Atomic Time
170
- LAST: Local Apparent Sidereal Time (requires position)
171
- LMST: Local Mean Sidereal Time (requires position)
172
- GMST1: Greenwich Mean Sidereal Time
173
- GAST: Greenwich Apparent Sidereal Time
174
- UT1: Universal Time 1
175
- UT2: Universal Time 2
176
- TDT: Terrestrial Dynamical Time
177
- TCG: Geocentric Coordinate Time
178
- TDB: Barycentric Dynamical Time
179
- TCB: Barycentric Coordinate Time
180
"""
181
182
def framenow(self):
183
"""Set epoch frame to current time."""
184
```
185
186
### Frequency and Spectral Measures
187
188
Handle radio frequencies with Doppler corrections and reference frame conversions.
189
190
```python { .api }
191
class measures:
192
def frequency(self, rf='', v0='0Hz', off=None):
193
"""
194
Create frequency measure.
195
196
Parameters:
197
- rf: str, reference frame
198
- v0: str or quantity, frequency value
199
- off: dict, optional offset frequency
200
201
Returns:
202
dict, frequency measure with 'type': 'frequency'
203
204
Reference frames:
205
- REST: Rest frequency
206
- LSRK: Local Standard of Rest (kinematic)
207
- LSRD: Local Standard of Rest (dynamic)
208
- BARY: Barycentric
209
- GEO: Geocentric (requires epoch)
210
- TOPO: Topocentric (requires epoch and position)
211
- GALACTO: Galactocentric
212
"""
213
214
def doppler(self, rf='', v0=0.0, off=None):
215
"""
216
Create Doppler measure.
217
218
Parameters:
219
- rf: str, Doppler convention
220
- v0: float, str, or quantity, Doppler value
221
- off: dict, optional offset Doppler
222
223
Returns:
224
dict, Doppler measure with 'type': 'doppler'
225
226
Conventions:
227
- RADIO: Radio convention (f_rest - f_obs)/f_rest
228
- OPTICAL: Optical convention (λ_obs - λ_rest)/λ_rest
229
- Z: Redshift z
230
- RATIO: Velocity ratio v/c
231
- RELATIVISTIC: Relativistic formula
232
- BETA: β = v/c
233
- GAMMA: Lorentz factor γ
234
"""
235
236
def radialvelocity(self, rf='', v0='0m/s', off=None):
237
"""
238
Create radial velocity measure.
239
240
Parameters:
241
- rf: str, reference frame (same as frequency frames)
242
- v0: str or quantity, velocity value
243
- off: dict, optional offset velocity
244
245
Returns:
246
dict, radial velocity measure with 'type': 'radialvelocity'
247
"""
248
249
def line(self, name):
250
"""
251
Get frequency measure for spectral line.
252
253
Parameters:
254
- name: str, spectral line name (minimum match)
255
256
Returns:
257
dict, frequency measure for line
258
259
Known lines include:
260
HI, OH1612, OH1665, OH1667, OH1720, CO115271,
261
H2O22235, SiO86847, CO230538, and others
262
"""
263
264
def get_lines(self):
265
"""
266
Get list of known spectral line names.
267
268
Returns:
269
list of str, line names
270
"""
271
```
272
273
### Baseline and UVW Coordinates
274
275
Handle interferometric baseline coordinates and UVW transformations.
276
277
```python { .api }
278
class measures:
279
def baseline(self, rf='', v0='0..', v1='', v2='', off=None):
280
"""
281
Create baseline measure.
282
283
Parameters:
284
- rf: str, reference frame ('ITRF' or direction codes)
285
- v0: str or quantity, X or longitude
286
- v1: str or quantity, Y or latitude
287
- v2: str or quantity, Z or height
288
- off: dict, optional offset baseline
289
290
Returns:
291
dict, baseline measure with 'type': 'baseline'
292
"""
293
294
def uvw(self, rf='', v0='0..', v1='', v2='', off=None):
295
"""
296
Create UVW coordinate measure.
297
298
Parameters:
299
- rf: str, reference frame ('ITRF' or direction codes)
300
- v0: str or quantity, U coordinate
301
- v1: str or quantity, V coordinate
302
- v2: str or quantity, W coordinate
303
- off: dict, optional offset UVW
304
305
Returns:
306
dict, UVW measure with 'type': 'uvw'
307
"""
308
309
def touvw(self, v):
310
"""
311
Convert baseline to UVW coordinates.
312
Requires direction and epoch in frame.
313
314
Parameters:
315
- v: dict, baseline measure
316
317
Returns:
318
dict with UVW measure and derivatives
319
"""
320
321
def expand(self, v):
322
"""
323
Calculate baseline differences from positions.
324
325
Parameters:
326
- v: dict, position, baseline, or UVW measure
327
328
Returns:
329
dict with expanded measure and coordinate differences
330
"""
331
332
def asbaseline(self, pos):
333
"""
334
Convert position to baseline measure.
335
336
Parameters:
337
- pos: dict, position measure
338
339
Returns:
340
dict, baseline measure
341
"""
342
```
343
344
### Coordinate Conversions
345
346
Convert between different measure types with proper reference frame handling.
347
348
```python { .api }
349
class measures:
350
def tofrequency(self, rf, v0, rfq):
351
"""
352
Convert Doppler to frequency.
353
354
Parameters:
355
- rf: str, frequency reference frame
356
- v0: dict, Doppler measure
357
- rfq: dict or quantity, rest frequency
358
359
Returns:
360
dict, frequency measure
361
"""
362
363
def to_frequency(self, rf, v0, rfq):
364
"""Alias for tofrequency."""
365
366
def todoppler(self, rf, v0, rfq):
367
"""
368
Convert frequency or radial velocity to Doppler.
369
370
Parameters:
371
- rf: str, Doppler convention
372
- v0: dict, frequency or radial velocity measure
373
- rfq: dict or quantity, rest frequency (for frequency input)
374
375
Returns:
376
dict, Doppler measure
377
"""
378
379
def to_doppler(self, rf, v0, rfq):
380
"""Alias for todoppler."""
381
382
def toradialvelocity(self, rf, v0):
383
"""
384
Convert Doppler to radial velocity.
385
386
Parameters:
387
- rf: str, velocity reference frame
388
- v0: dict, Doppler measure
389
390
Returns:
391
dict, radial velocity measure
392
"""
393
394
def to_radialvelocity(self, rf, v0):
395
"""Alias for toradialvelocity."""
396
397
def torestfrequency(self, f0, d0):
398
"""
399
Calculate rest frequency from observed frequency and Doppler.
400
401
Parameters:
402
- f0: dict, frequency measure
403
- d0: dict, Doppler measure
404
405
Returns:
406
dict, rest frequency measure
407
"""
408
409
def to_restfrequency(self, f0, d0):
410
"""Alias for torestfrequency."""
411
```
412
413
### Astronomical Calculations
414
415
Perform astronomical calculations like rise/set times, separations, and position angles.
416
417
```python { .api }
418
class measures:
419
def rise(self, crd, ev='5deg'):
420
"""
421
Calculate rise/set hour angles.
422
Requires position and epoch in frame.
423
424
Parameters:
425
- crd: dict, direction measure
426
- ev: str or quantity, elevation limit
427
428
Returns:
429
dict with 'rise' and 'set' hour angles, or strings 'above'/'below'
430
"""
431
432
def riseset(self, crd, ev="5deg"):
433
"""
434
Calculate rise/set times in UTC and sidereal time.
435
436
Parameters:
437
- crd: dict, direction measure
438
- ev: str or quantity, elevation limit
439
440
Returns:
441
dict with rise/set times and solution status
442
"""
443
444
def posangle(self, m0, m1):
445
"""
446
Calculate position angle between two directions.
447
448
Parameters:
449
- m0: dict, first direction measure
450
- m1: dict, second direction measure
451
452
Returns:
453
quantity, position angle
454
"""
455
456
def separation(self, m0, m1):
457
"""
458
Calculate angular separation between two directions.
459
460
Parameters:
461
- m0: dict, first direction measure
462
- m1: dict, second direction measure
463
464
Returns:
465
quantity, angular separation
466
"""
467
```
468
469
### Source and Reference Catalogs
470
471
Access built-in catalogs of astronomical sources and reference objects.
472
473
```python { .api }
474
class measures:
475
def source(self, name):
476
"""
477
Get direction measure for astronomical source.
478
479
Parameters:
480
- name: str, source name (minimum match)
481
482
Returns:
483
dict, direction measure for source
484
"""
485
486
def get_sources(self):
487
"""
488
Get list of known source names.
489
490
Returns:
491
list of str, source names
492
"""
493
```
494
495
### Earth Magnetic Field
496
497
Handle Earth's magnetic field measurements and models.
498
499
```python { .api }
500
class measures:
501
def earthmagnetic(self, rf='', v0='0G', v1='0..', v2='90..', off=None):
502
"""
503
Create Earth magnetic field measure.
504
505
Parameters:
506
- rf: str, reference frame ('IGRF')
507
- v0: str or quantity, field strength or longitude
508
- v1: str or quantity, latitude
509
- v2: str or quantity, height
510
- off: dict, optional offset
511
512
Returns:
513
dict, earth magnetic measure with 'type': 'earthmagnetic'
514
515
Reference frames:
516
- IGRF: International Geomagnetic Reference Field
517
"""
518
```
519
520
### Observatory and Reference Data
521
522
Access built-in catalogs of observatories and spectral lines.
523
524
```python { .api }
525
class measures:
526
def observatory(self, name):
527
"""
528
Get position measure for named observatory.
529
530
Parameters:
531
- name: str, observatory name (case-insensitive)
532
533
Returns:
534
dict, position measure for observatory
535
536
Common observatories: ALMA, ATCA, BIMA, CLRO, DRAO, DWL, GB, JCMT,
537
MOPRA, NRAO12M, PKS, VLA, WSRT
538
"""
539
540
def get_observatories(self):
541
"""
542
Get list of known observatory names.
543
544
Returns:
545
list of str, observatory names
546
"""
547
548
def line(self, name):
549
"""
550
Get frequency measure for spectral line.
551
552
Parameters:
553
- name: str, spectral line name (minimum match)
554
555
Returns:
556
dict, frequency measure for line
557
558
Common lines: HI, OH1612, OH1665, OH1667, OH1720, CO115271,
559
H2O22235, SiO86847, CO230538, H107A, H110A, etc.
560
"""
561
562
def get_lines(self):
563
"""
564
Get list of known spectral line names.
565
566
Returns:
567
list of str, spectral line names
568
"""
569
```
570
571
### Baseline and UVW Operations
572
573
Handle baseline measures and UVW coordinate transformations for interferometry.
574
575
```python { .api }
576
class measures:
577
def touvw(self, v):
578
"""
579
Convert baseline to UVW coordinates.
580
581
Requires direction and epoch in reference frame.
582
583
Parameters:
584
- v: dict, baseline measure
585
586
Returns:
587
dict, UVW measure with additional 'xyz' and 'dot' quantities
588
"""
589
590
def expand(self, v):
591
"""
592
Calculate differences between position/baseline measures.
593
594
Parameters:
595
- v: dict, baseline, position, or UVW measure
596
597
Returns:
598
dict with 'measure' and 'xyz' difference quantities
599
"""
600
601
def asbaseline(self, pos):
602
"""
603
Convert position measure to baseline measure.
604
605
Parameters:
606
- pos: dict, position measure
607
608
Returns:
609
dict, baseline measure
610
"""
611
612
def as_baseline(self, pos):
613
"""Alias for asbaseline."""
614
```
615
616
### Frame Management
617
618
Advanced reference frame management and time handling.
619
620
```python { .api }
621
class measures:
622
def framenow(self):
623
"""Set epoch frame to current time."""
624
625
def frame_now(self):
626
"""Alias for framenow."""
627
628
def set_data_path(self, pth):
629
"""
630
Set path to measures data directory.
631
632
Parameters:
633
- pth: str, absolute path to data directory
634
"""
635
```
636
637
### Measure Utilities
638
639
Utility functions for working with measures and extracting information.
640
641
```python { .api }
642
class measures:
643
def getvalue(self, v):
644
"""
645
Get quantity values from measure.
646
647
Parameters:
648
- v: dict, measure
649
650
Returns:
651
list of quantities (m0, m1, m2, ...)
652
"""
653
654
def get_value(self, v):
655
"""Alias for getvalue."""
656
657
def get_type(self, m):
658
"""
659
Get measure type.
660
661
Parameters:
662
- m: dict, measure
663
664
Returns:
665
str, measure type
666
"""
667
668
def get_ref(self, m):
669
"""
670
Get reference frame.
671
672
Parameters:
673
- m: dict, measure
674
675
Returns:
676
str, reference frame code
677
"""
678
679
def get_offset(self, m):
680
"""
681
Get offset measure.
682
683
Parameters:
684
- m: dict, measure
685
686
Returns:
687
dict, offset measure or None
688
"""
689
```
690
691
## Usage Examples
692
693
### Basic Coordinate Transformations
694
695
```python
696
from casacore.measures import measures
697
from casacore.quanta import quantity
698
699
# Create measures server
700
dm = measures()
701
702
# Set reference frame (position and time)
703
dm.doframe(dm.observatory('VLA'))
704
dm.doframe(dm.epoch('UTC', 'today'))
705
706
# Create source direction
707
source = dm.direction('J2000', '12h30m00s', '-30d00m00s')
708
print(f"Source: RA={source['m0']}, Dec={source['m1']}")
709
710
# Convert to azimuth/elevation
711
azel = dm.measure(source, 'AZEL')
712
print(f"Az/El: Az={azel['m0']}, El={azel['m1']}")
713
714
# Convert to galactic coordinates
715
galactic = dm.measure(source, 'GALACTIC')
716
print(f"Galactic: l={galactic['m0']}, b={galactic['m1']}")
717
```
718
719
### Frequency and Doppler Conversions
720
721
```python
722
# Create frequency measure
723
obs_freq = dm.frequency('TOPO', '1.42040575GHz') # Observed HI frequency
724
725
# Create Doppler measure
726
doppler = dm.doppler('RADIO', '100km/s')
727
728
# Get rest frequency for HI line
729
hi_rest = dm.line('HI')
730
print(f"HI rest frequency: {hi_rest['m0']}")
731
732
# Convert Doppler to frequency
733
conv_freq = dm.tofrequency('LSRK', doppler, hi_rest)
734
print(f"Converted frequency: {conv_freq['m0']}")
735
736
# Convert frequency to velocity
737
velocity = dm.todoppler('RADIO', obs_freq, hi_rest)
738
radial_vel = dm.toradialvelocity('LSRK', velocity)
739
print(f"Radial velocity: {radial_vel['m0']}")
740
```
741
742
### Rise/Set Calculations
743
744
```python
745
# Calculate rise/set times for a source
746
source = dm.source('3C147') # Use known source
747
748
# Set observation parameters
749
dm.doframe(dm.observatory('WSRT'))
750
dm.doframe(dm.epoch('UTC', '2023-06-15/12:00:00'))
751
752
# Calculate rise/set
753
riseset = dm.riseset(source, ev='10deg') # 10 degree elevation limit
754
755
if riseset['solved']:
756
print(f"Rise time (UTC): {riseset['rise']['utc']['m0']}")
757
print(f"Set time (UTC): {riseset['set']['utc']['m0']}")
758
print(f"Rise time (LST): {riseset['rise']['last']['m0']}")
759
print(f"Set time (LST): {riseset['set']['last']['m0']}")
760
else:
761
print("Source is always above or below horizon")
762
```
763
764
### Baseline to UVW Transformation
765
766
```python
767
# Create baseline measure (antenna separation)
768
baseline = dm.baseline('ITRF', '100m', '200m', '50m')
769
770
# Set observation parameters for UVW calculation
771
dm.doframe(dm.source('CYGA')) # Set source direction
772
dm.doframe(dm.epoch('UTC', '2023-06-15/18:00:00'))
773
774
# Convert baseline to UVW coordinates
775
uvw_result = dm.touvw(baseline)
776
uvw_coords = uvw_result
777
print(f"UVW: U={uvw_coords['m0']}, V={uvw_coords['m1']}, W={uvw_coords['m2']}")
778
779
# Get time derivatives (for Earth rotation tracking)
780
if 'dot' in uvw_result:
781
print(f"UVW rates: {uvw_result['dot']}")
782
```
783
784
### Angular Measurements
785
786
```python
787
# Calculate separation between two sources
788
source1 = dm.source('CYGA')
789
source2 = dm.source('CASB')
790
791
separation = dm.separation(source1, source2)
792
print(f"Angular separation: {separation}")
793
794
# Calculate position angle
795
pos_angle = dm.posangle(source1, source2)
796
print(f"Position angle: {pos_angle}")
797
```