User Guide#

This guide explains the fundamental concepts of healpix-geo and how to use them effectively.

Guide organisation#

If you begin with healpix-geo and HEALPix, read in the order :

When the basis are acquired :

Fundamental concepts

Understanding what HEALPix is, why to use it, and the basic principles of equal-area spherical tiling.

Ellipsoids

Earth models, reference ellipsoids, and their impact on your calculations.

Coordinate systems

Conversions between longitude/latitude and HEALPix indices. Nested schemes, ring, and zuniq.

Hierarchical indexing

Navigating the hierarchy: parents, children, neighbors, and multiple resolution levels.

Coverage queries

Find all cells that intersect a region: circles, polygons, bounding boxes.

Performance

Optimize your calculations: vectorization, multi-threading, and best practices for processing large volumes.

In this guide, we are using the following conventions :

Term	Definition
HEALPix	Hierarchical Equal Area isoLatitude Pixelization
Depth	Resolution level (0 = coarser, 29 = finer)
Nested	Hierarchical indexing scheme
Ring	Latitude ring indexing scheme
Zuniq	Indexing scheme for MOC
MOC	Multi-Order Coverage - compact representation of regions
Ellipsoid	Mathematical model of the shape of the Earth
WGS84	World Geodetic System 1984

Module	When to use it	Principal functionalities
nested	General applications, Hierarchical requests, Multi-resolution	Coordinates conversions, Coverage, Hierarchy, Distances
ring	Compatibility legacy, Specific order requested	Coordinates conversions, Distances, Limited neighbours
zuniq	Work with MOC, Interoperability	Conversions nested ↔ zuniq, Cell Coordinates