irfpy.util.skymap

Module for the sky mapping.

A sky map is sometimes needed to display the instrument FOV in an instrument-center frame. This is identical to the azimuth-altitude system. https://en.wikipedia.org/wiki/File:Azimut_altitude.svg

To avoid the confusion in the term “altitude”, frequently used to describe the distance from the surface, we instead use the “elevation” here.

  • Elevation angle \(\alpha\) or El: The angle from the “horizon”.

    • Polar angle \(\theta\) or T: 90 degrees - elevation angle.

  • Azimuthal angle \(\beta\) or Az: North is 0, East is 90, South is +-180, and West is -90. Usually, the Az shall be defined in the range (-180, 180].

  • Primary axis $hat{p}$ or P: The primary axis defines the zenith, i.e., elevation = 90. (Frequently $z$ axis)

  • Secondary axis $hat{s}$ or S: The secondary axis defines the north, frequenty $x$ axis. More precisely speaking, the meridan defined by the primary and secondary axes contains the north.

  • Third axis $hat{t}$ or T: The third axis. This defines the west (frequently $y$ axis). This axis is calculated from the primary and secondary axes.

  • Distance, d or D, is also important for space physics, as a distance to the object of interest.

The interface always accept the angles in the unit of “degrees”.

Note

Traditionally, several variants of the azimuth angle have been defined, so it sometimes confusing. Here irfpy follow the defintition described in https://www.sciencedirect.com/science/article/abs/pii/S0038092X0300450X

See also https://en.wikipedia.org/wiki/Solar_azimuth_angle.

class irfpy.util.skymap.SkymapFrame(primary_axis, secondary_axis)[source]

Bases: object

Define the skymap frame.

A skymap frame is defined, following the defintion above.

Parameters:

  • primary_axis – The primary axis, (3,) shape numpy array.

  • secondary_axis – The secondary axis, (3,) shape numpy array.

Raises:

ValueError – Raised when the given axes do not provide appropriate cartesian.

>>> skymap_frame = SkymapFrame([0, 0, 1], [1, 0, 0])
>>> print(skymap_frame)   
Skymap object: P= 0.0000   S= 1.0000   T= 0.0000
                  0.0000      0.0000      1.0000
                  1.0000      0.0000      0.0000

This skymap is relatively simple example, namely, z is the zenith and x is “north”. In this case, the vector (0, 0, 100) will be converted to d=100, el=90 and az=(N.A.).

>>> d, el, az = skymap_frame.vec2dea(0, 0, 100)
>>> print(d)
100.0
>>> print(el)
90.0

The vector (1, 0, 0), looking north will be d=1, el=0, az=0.

>>> print(skymap_frame.vec2dea(1, 0, 0))
(1.0, 0.0, -0.0)

The vector (0, 1, 0), looking west will be d=1, el=0, az=-90. Here note the sign of az.

>>> print(skymap_frame.vec2dea(0, 1, 0))
(1.0, 0.0, -90.0)

vec2dea() can eat a list as arguments.

>>> print(skymap_frame.vec2dea([1, 0], [0, 1], [0, 0]))   
(array([1., 1.]), array([0., 0.]), array([ -0., -90.]))
vec2dea(x, y, z)[source]

Vector list ([x_i], [y_i], [z_i]) is converted to distance-elevation-azimuth.

A vector $vec{v}$ is converted to (d, e, a).

property primary_axis

The primary axis, the 90 degrees of elevation.

The primary axis, or equivalently the z axis. (Zenithward)

property secondary_axis

The secondary axis, the 0 elevation and 0 azimuth.

The secondary axis, or equivalently the x axis. (Northward)

property third_axis

The third axis, the 0 elevation and 90 azimuth

The third axis, or eqiuvalently the y axis. (Eastward)

limb_of_sphere(position: ndarray, radius: float, resolution: int = 16) → tuple[numpy.ndarray, numpy.ndarray][source]

Return a limb of sphere coordinates mapped on the sky.

Parameters:

  • position – Position of the sphere. (3,) shaped numpy array.

  • radius – Radius of the sphere.

Returns:

A tuple, (elevation_array, azimuth_array) in degrees.

>>> sk = SkymapFrame([0, 0, 1], [1, 0, 0])
>>> e, a = sk.limb_of_sphere([0, 0, 3], 1)
>>> print(f'{e.max():.2f} {e.min():.2f}')   # Must be 70.52877937 for both.
70.53 70.53
>>> print(f'{a[1]:.2f}')
-24.00
>>> print(a)   
[0 -24 -48 -72 -96 -120 -144 -168 168 144 120 96 72 48 24 0]

>>> e, a = sk.limb_of_sphere([0, 3, 0], 1, resolution=360)
>>> print(f'{e.max():.2f} {e.min():.2f}')
19.47 -19.47
>>> print(a)  
[ -90.          -90.35451559  -90.70889547  -91.06300404  -91.41670596
  -91.76986629  -92.1223506   -92.47402508  -92.82475668
...
  -86.82558674  -87.17524332  -87.52597492  -87.8776494   -88.23013371
  -88.58329404  -88.93699596  -89.29110453  -89.64548441  -90.        ]
>>> print(f'{a.min():.2f} {a.max():.2f}')
-109.47 -70.53
parallel_on_sphere(sphere_position, sphere_radius, sphere_primary_axis, angle, resolution=16, mask_invisible=True)[source]

Obtain elevation and azimuth angle list of parallel line on the sphere

Suppose we have a sphere (e.g., Venus), and want to draw equator. This method do that.

Parameters:

  • sphere_position – The central position of the sphere

  • sphere_radius – The radius of sphere (in the dimension of length, e.g., km)

  • sphere_primary_axis – The primary axis direction measured from the central position of the sphere.

  • angle – The angle measured from the sphere_primary_axis.

  • resolution – Resolution.

  • mask_invisible – Mask the elevation, azimuth angle if that location cannot be visible from the observer. Default, True (i.e., masked)