Metadata-Version: 2.4
Name: mortie
Version: 0.6.1
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Dist: numpy>=1.20
Requires-Dist: pytest ; extra == 'bench'
Requires-Dist: pytest-cov>=4.0 ; extra == 'bench'
Requires-Dist: pytest-codspeed>=4.3.0 ; extra == 'bench'
Requires-Dist: pytest>=8.0 ; extra == 'test'
Requires-Dist: pytest-cov>=4.0 ; extra == 'test'
Provides-Extra: bench
Provides-Extra: test
License-File: LICENSE
Summary: Morton numbering and indexing for healpix grids
Keywords: healpix,geohashing,morton index
Author-email: "Shane Grigsby (espg)" <refuge@rocktalus.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/espg/mortie/issues
Project-URL: Homepage, https://github.com/espg/mortie

mortie
======

[![Tests](https://github.com/espg/mortie/actions/workflows/test.yml/badge.svg)](https://github.com/espg/mortie/actions/workflows/test.yml)
[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge/json/espg/mortie&style=flat)](https://codspeed.io/espg/mortie?utm_source=badge)
[![codecov](https://codecov.io/gh/espg/mortie/branch/main/graph/badge.svg)](https://codecov.io/gh/espg/mortie)
[![PyPI version](https://badge.fury.io/py/mortie.svg)](https://badge.fury.io/py/mortie)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/espg/mortie?utm_source=badge)

![Morty using mortie](./morty.jpg)

Mortie is a library for applying morton indexing to healpix grids. Morton
numbering (also called z-ordering) facilitates several geospatial operators
such as buffering and neighborhood look-ups, and can generally be thought of as
a type of geohashing.

This particular implementation focuses on hierarchical healpix maps, and is
mostly inspired from [this paper](https://doi.org/10.1016/j.heliyon.2017.e00332).

## Performance

Mortie uses **Rust-accelerated** morton indexing functions for high performance, with an automatic fallback to pure Python if Rust is unavailable. The Rust implementation provides dramatic speedups:

| Dataset Size | Rust | Pure Python | Speedup |
|--------------|------|-------------|---------|
| 1,000 values | 1.93 ms | 4.14 ms | **2.1x** |
| 100,000 values | 1.85 ms | 410.59 ms | **222x** |
| 1.2M coordinates | 102.51 ms | 5.1 sec | **50x** |

Pre-built wheels are available for Linux, macOS, and Windows. If a wheel is unavailable for your platform, mortie will automatically use the pure Python fallback.

## Installation

```bash
# With healpy (default HEALPix backend)
pip install mortie[healpy]

# With cdshealpix (Rust-backed, better ARM64 support)
pip install mortie[cdshealpix]

# Both backends
pip install mortie[all]
```

For development builds with Rust, see [BUILDING.md](BUILDING.md).

## HEALPix Backend

Mortie supports two HEALPix backends — **healpy** (C/Fortran) and **cdshealpix** (Rust). By default, mortie auto-detects whichever is installed (preferring cdshealpix). You can force a specific backend:

```bash
export MORTIE_HEALPIX_BACKEND=healpy      # or cdshealpix
```

## Spatial Buffer

Mortie provides a `morton_buffer` function for expanding a set of morton cells by a configurable border ring. This is useful for capturing edge cells missed by sparse vertex sampling (e.g., near HEALPix pole holes).

```python
import numpy as np
import mortie

# Convert coordinates to morton cells at order 6
cells = np.unique(mortie.geo2mort(lats, lons, order=6))

# Expand by 1-cell ring (8-connected neighbors)
border = mortie.morton_buffer(cells, k=1)
expanded = np.union1d(cells, border)
```

All input indices must be at the same order. The function returns only the new border cells, not the input cells themselves.

## Dependencies

**numpy** and one of **healpy** or **cdshealpix**. The Rust-accelerated morton functions are optional — if unavailable, mortie will automatically fall back to a pure Python implementation.

## Funding
Initial funding of this work was supported by the ICESat-2 project science
office, at the Laboratory for Cryospheric Sciences (NASA Goddard, Section 615).

## References
<a id="1">[1]</a>
Youngren, Robert W., and Mikel D. Petty.
"A multi-resolution HEALPix data structure for spherically mapped point data."
Heliyon 3.6 (2017): e00332. [doi: 10.1016/j.heliyon.2017.e00332](https://doi.org/10.1016/j.heliyon.2017.e00332)

