The pj_healpix Module¶

`healpix`([a, e])	Return a function object that wraps the HEALPix projection and its inverse of an ellipsoid with major radius a and eccentricity e.
`healpix_ellipsoid`(lam, phi[, e])	Compute the signature functions of the HEALPix projection of an oblate ellipsoid with eccentricity e whose authalic sphere is the unit sphere.
`healpix_ellipsoid_inverse`(x, y[, e])	Compute the inverse of healpix_ellipsoid().
`healpix_sphere`(lam, phi)	Compute the signature function of the HEALPix projection of the unit sphere.
`healpix_sphere_inverse`(x, y)	Compute the inverse of the healpix_sphere().
`in_healpix_image`(x, y)	Return True if and only if (x, y) lies in the image of the HEALPix projection of the unit sphere, allowing a margin of about 1e-10 outside it so that points computed to lie on the boundary are not rejected for rounding error.

Array inputs¶

The callable returned by healpix accepts numpy arrays as well as floats: pass two arrays of a common shape and every point is projected (or inverted) in one array pass, returning a pair of float64 arrays. Scalar calls are unchanged. If any point of an inverse batch lies outside the projection’s image the whole call raises ValueError, naming the count and the first offending point.

This Python 3.11 module implements the HEALPix map projection as described in [CaRo2007].

[CaRo2007]

Mark R. Calabretta and Boudewijn F. Roukema, Mapping on the healpix grid, Monthly Notices of the Royal Astronomical Society 381 (2007), no. 2, 865–872.

Alexander Raichev (AR), 2013-01-26: Refactored code from release 0.3.

NOTE:

All lengths are measured in meters and all angles are measured in radians unless indicated otherwise. By ‘ellipsoid’ below, I mean an oblate ellipsoid of revolution.

rhealpixdggs.pj_healpix.healpix(a: float = 1, e: float = 0) → ProjectionFunction[source]¶

Return a function object that wraps the HEALPix projection and its inverse of an ellipsoid with major radius a and eccentricity e.

EXAMPLES:

>>> from rhealpixdggs.utils import my_round
>>> f = healpix(a=2, e=0)
>>> print(tuple(x.tolist() for x in my_round(f(0, pi/3, radians=True), 15)))
(0.574951359778215, 2.145747686573111)
>>> p = (0, 60)
>>> q = f(*p, radians=False); print(tuple(x.tolist() for x in my_round(q, 15)))
(0.574951359778215, 2.145747686573111)
>>> print(tuple(x.tolist() for x in my_round(f(*q, radians=False, inverse=True), 15)))
(6e-15, 59.999999999999986)
>>> print(my_round(p, 15))
(0, 60)

OUTPUT:

A function object of the form f(u, v, radians=False, inverse=False). u and v may be floats or numpy arrays of a common shape; arrays come back as a pair of float64 arrays.

rhealpixdggs.pj_healpix.healpix_ellipsoid(lam: float, phi: float, e: float = 0) → tuple[float, float][source]¶

Compute the signature functions of the HEALPix projection of an oblate ellipsoid with eccentricity e whose authalic sphere is the unit sphere. Works when e = 0 (spherical case) too.

INPUT:

lam, phi - Geodetic longitude-latitude coordinates in radians. Assume -pi <= lam < pi and -pi/2 <= phi <= pi/2.
e - Eccentricity of the oblate ellipsoid.

EXAMPLES:

>>> from rhealpixdggs.utils import my_round
>>> print(tuple(x if type(x) is int else x.tolist() for x in my_round(healpix_ellipsoid(0, pi/7), 15)))
(0, 0.511157237746422)
>>> print(tuple(x if type(x) is int else x.tolist() for x in my_round(healpix_ellipsoid(0, pi/7, e=0.8), 15)))
(0, 0.268484450857837)

rhealpixdggs.pj_healpix.healpix_ellipsoid_inverse(x: float, y: float, e: float = 0) → tuple[float, float][source]¶

Compute the inverse of healpix_ellipsoid().

EXAMPLES:

>>> from rhealpixdggs.utils import my_round
>>> p = (0, pi/7)
>>> q = healpix_ellipsoid(*p)
>>> print(tuple(x if type(x) is int else x.tolist() for x in my_round(healpix_ellipsoid_inverse(*q), 15)))
(0, 0.448798950512828)
>>> print(my_round(p, 15))
(0, 0.448798950512828)

rhealpixdggs.pj_healpix.healpix_sphere(lam: float, phi: float) → tuple[float, float][source]¶

Compute the signature function of the HEALPix projection of the unit sphere.

INPUT:

lam, phi - Geodetic longitude-latitude coordinates in radians. Assume -pi <= lam < pi and -pi/2 <= phi <= pi/2.

EXAMPLES:

>>> print(healpix_sphere(0, arcsin(2.0/3)) == (0, pi/4))
True

rhealpixdggs.pj_healpix.healpix_sphere_inverse(x: float, y: float) → tuple[float, float][source]¶

Compute the inverse of the healpix_sphere().

INPUT:

x, y - Planar coordinates in meters in the image of the HEALPix projection of the unit sphere.

EXAMPLES:

>>> print(healpix_sphere_inverse(0, pi/4) == (0, arcsin(2.0/3)))
True

rhealpixdggs.pj_healpix.in_healpix_image(x: float, y: float) → bool[source]¶

Return True if and only if (x, y) lies in the image of the HEALPix projection of the unit sphere, allowing a margin of about 1e-10 outside it so that points computed to lie on the boundary are not rejected for rounding error.

EXAMPLES:

>>> eps = 0     # Test boundary points.
>>> hp = [
... (-pi - eps, pi/4),
... (-3*pi/4, pi/2 + eps),
... (-pi/2, pi/4 + eps),
... (-pi/4, pi/2 + eps),
... (0, pi/4 + eps),
... (pi/4, pi/2 + eps),
... (pi/2, pi/4 + eps),
... (3*pi/4, pi/2 + eps),
... (pi + eps, pi/4),
... (pi + eps,-pi/4),
... (3*pi/4,-pi/2 - eps),
... (pi/2,-pi/4 - eps),
... (pi/4,-pi/2 - eps),
... (0,-pi/4 - eps),
... (-pi/4,-pi/2 - eps),
... (-pi/2,-pi/4 - eps),
... (-3*pi/4,-pi/2 - eps),
... (-pi - eps,-pi/4)
... ]
>>> for p in hp:
...     if not in_healpix_image(*p):
...             print('Fail')
...
>>> in_healpix_image(0, 0)
True
>>> in_healpix_image(0, pi/4 + 0.1)
False