mortie

Documentation Tests Docs CodSpeed codecov PyPI version Python 3.10+ CodSpeed Badge Binder

Morty using mortie

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.

Documentation

The full documentation — the generated API reference alongside the specification, interchange and coverage guides — is published at espg.github.io/mortie. Every page below is rendered there; the in-tree markdown links are the same content at the revision you are reading.

The normative encoding and conventions — the packed-word bit layout, the decimal string grammar, the order 0–29 resolution table, the morton-hive store layout, and the coverage-MOC serializations, all frozen for the 1.x series — are documented in docs/specification.md. Moving a packed word to and from the wider HEALPix ecosystem (cdshealpix / healpy (order, nested-pixel) pairs) is covered in docs/healpix_interchange.md.

Example notebooks

Runnable walkthroughs live in examples/; each opens on Binder from the badge in its first cell. Two of them need no downloads at all — morton_set_algebra.ipynb for the MOC boolean verbs, and toc_temporal_coverage.ipynb for the toc word (temporal order coverage: encoding, the conservative merge, the comparator-free sort, window predicates, and the UTC/GPS boundary).

Performance

Mortie's morton core is a Rust extension and the sole runtime path — there is no Python implementation to fall back on — so performance is reported as absolute throughput rather than a speedup ratio. Encoding (geo2mort) and decoding (mort2geo) run at tens of millions of morton indices per second on one core, staying within roughly 2× across orders 4–29.

See docs/benchmarks.md for the full cross-order table (raw encode / decode throughput and coverage timing at orders 4 / 12 / 18 / 29), regenerated in place by a committed script. Cell counts there are deterministic; timings are machine/run dependent.

Pre-built wheels are available for Linux, macOS, and Windows. The Rust extension is required and is included in all pip-installed wheels.

Installation

pip install mortie

For development builds with Rust, see BUILDING.md.

Spatial Buffer

Mortie provides a morton_buffer function for expanding a set of morton cells by a configurable border ring. This is useful for... well, buffering.

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)

Latitude convention. Since 0.10 geo2mort and the coverage kernels take WGS84 geodetic latitude and map it to the authalic sphere, so cells are equal-area on the ellipsoid. Cell ids therefore differ from pre-0.10 mortie and from raw-spherical HEALPix libraries; pass latitude="geodetic-spherical" for the old behaviour. See docs/specification.md §9.

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

Polygon Coverage

morton_coverage computes the set of morton indices that cover a polygon defined by lat/lon vertices. It uses a top-down hierarchical descent over the HEALPix tree: starting from the 12 base cells it keeps cells inside the polygon, prunes cells outside, and refines cells the boundary passes through down to the requested order. Cost scales with the polygon's boundary, not its area — interior regions collapse to a few coarse cells, so a large but simple polygon is cheap. Vertex count still matters (a one-time O(V) edge/seed setup, plus per-boundary-cell work that grows with local edge density), but far more gently than the old O(cells × vertices) approach — a 1M-vertex polygon covers in ~1 s, roughly 40× faster than before.

import mortie

# Define polygon vertices (lat, lon in degrees)
lats = [40.0, 40.0, 50.0, 50.0]
lons = [-125.0, -115.0, -115.0, -125.0]

# Flat cover — every cell at order 6
cells = mortie.morton_coverage(lats, lons, order=6)

# Compact Multi-Order Coverage — coarse interior, fine boundary (usually far smaller)
moc = mortie.morton_coverage_moc(lats, lons, order=10)

# Adaptive boundary: stop at an angular tolerance, or cap the cell count
moc_tol = mortie.morton_coverage_moc(lats, lons, order=10, tolerance=0.5)   # degrees
moc_bud = mortie.morton_coverage_moc(lats, lons, order=10, max_cells=500)

The function handles concave polygons, antimeridian-crossing polygons, and polar regions. Multipart polygons and holes are supported by passing a list of rings (even-odd fill): disjoint parts are unioned and a nested ring carves a hole, so a donut is [outer, hole]. Helpers compress_moc (merge 4-sibling groups) and moc_to_order (densify a MOC to a flat order) round out the API. See docs/coverage_methods.md for the full method/precision/runtime trade-offs and a benchmark matrix.

The Moc object

mortie.moc(...) wraps the same cover as an object, so coverage geometry reads as geometry:

from mortie import moc

cali = moc(cali_geojson)      # multi-order coverage; no order argument
q    = moc(aoi_geojson)       # GeoJSON dicts, ring arrays, or a uint64 word array
assert cali.contains(q)
shards = q.to_order(9)        # fixed-order cast when a consumer's grid wants one

Two layers, and they stay separate. The free moc_* functions above are the kernel / batch layer — words in, words out, no wrapping cost — and they are unchanged and un-deprecated; the plural batch forms (mocs_and, mocs_intersect, mocs_to_orders, polygons_to_morton_mocs) stay function-shaped permanently. Moc is ergonomics only: a thin view over the canonical uint64 word array, where every method is a single delegation to one of those kernels. The array stays the interchange format — Moc.__morton_moc__() hands the words back, and any object exposing that dunder is accepted wherever a Moc is.

Vocabulary mirrors MOCpy where it applies, so the crosswalk is short:

MOCpy mortie object mortie kernel
MOC.from_polygon(lon, lat, max_depth=…) Moc.from_polygon(lats, lons), or moc(geojson) morton_coverage_moc(lats, lons, order=…)
a.union(b), a | b a.union(b), a | b moc_or(a, b)
a.intersection(b), a & b a.intersection(b), a & b moc_and(a, b)
a.difference(b), a - b a.difference(b), a - b moc_minus(a, b)
a.symmetric_difference(b) a.symmetric_difference(b), a ^ b moc_xor(a, b)
b.difference(a).empty() a.contains(b), b.within(a) moc_minus(b, a).size == 0
a.contains_lonlat(lon, lat) — (kernel only) moc_intersects(a, geo2mort(lat, lon, order))
— a.intersects(b) moc_intersects(a, b)
a.degrade_to_order(n).flatten() a.to_order(n) moc_to_order(a, n)
a.complement() — (kernel only) moc_not(a, domain)

Mind the two places where the vocabulary matches but the meaning does not. MOCpy's from_polygon(lon, lat, …) takes its coordinates in the opposite order to Moc.from_polygon(lats, lons, …); and MOCpy's MOC.contains is a point-in-MOC mask (deprecated there in favour of contains_lonlat), not the MOC-in-MOC test a.contains(b) is. a.to_order(n) also densifies when n is finer than the cover, which degrade_to_order(n).flatten() does not.

The predicates are cover algebra, not polygon algebra — both sides dilate their polygons to cell boundaries, so intersects can over-report near a boundary while a False stays decisive. docs/api/moc_object.md carries the conservative-direction table and the full constructor matrix.

mortie.moc is no longer a submodule. It is the constructor as of issue #196; import mortie.moc and from mortie.moc import x break. The flat package names (mortie.moc_to_order, mortie.compress_moc, …) are unchanged and are the supported spelling — see the CHANGELOG.

Dependencies

numpy. All HEALPix operations use the Rust-native healpix crate bundled in the compiled extension — no external HEALPix library is needed.

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

[1] 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

Project links

Data verified by PyPI on Aug 19, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.9.11)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for espg from gravatar.com espg

Credits

Author: Shane Grigsby (espg)

GitHub Statistics

Data verified by PyPI on Aug 19, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License

Requires

Python >=3.10

Provides Extra

arro3 bench examples pandas pyarrow test

Tags

healpix geohashing morton index

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mortie-0.9.10.tar.gz (17.2 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

mortie-0.9.10-cp310-abi3-win_amd64.whl (15.0 MB view details)

Uploaded CPython 3.10+Windows x86-64

mortie-0.9.10-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (15.0 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

mortie-0.9.10-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (14.9 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

mortie-0.9.10-cp310-abi3-macosx_11_0_arm64.whl (14.9 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

mortie-0.9.10-cp310-abi3-macosx_10_12_x86_64.whl (14.9 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file mortie-0.9.10.tar.gz.

File metadata

  • Download URL: mortie-0.9.10.tar.gz
  • Upload date:
  • Size: 17.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mortie-0.9.10.tar.gz
Algorithm Hash digest
SHA256 d03d0e3808e66a0c66da4ab312e91849a4c642f8a6bb605ed4887580ca592153
MD5 0a61f6268697543fb649c3348adfd20f
BLAKE2b-256 8ae991ec5521de80b667373f27bb167fd9e4900d026a3f4f8c4a000597191ded

See more details on using hashes here.

Provenance

The following attestation bundles were made for mortie-0.9.10.tar.gz:

Publisher: build-wheels.yml on espg/mortie

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mortie-0.9.10-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: mortie-0.9.10-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 15.0 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mortie-0.9.10-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 d8a5a374f89e9a939b4b9cee208b12a875d37cdb3b13d053a9ad3bb49c17d099
MD5 92c331759f53976bdfcc81aa938f0be6
BLAKE2b-256 09d4a9fce393aad80d85fa4a46f47ef1603a83c14bf1869529a616aa78e43a41

See more details on using hashes here.

Provenance

The following attestation bundles were made for mortie-0.9.10-cp310-abi3-win_amd64.whl:

Publisher: build-wheels.yml on espg/mortie

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mortie-0.9.10-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mortie-0.9.10-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 5e410bc65a175e41fe5845be20613592137f8a9ef4e8cf771160b8fe7f01e33c
MD5 b8cd0adeb0ea5d379deb58c6fdc380ce
BLAKE2b-256 a7a45af934343ee611e1006a2012dea5f81cbb3f191f2f75b9e4961b8bf047f9

See more details on using hashes here.

Provenance

The following attestation bundles were made for mortie-0.9.10-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: build-wheels.yml on espg/mortie

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mortie-0.9.10-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for mortie-0.9.10-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 41b02662a6d90c713cdce870a80c5ac8ff2d00abfd0ec26fb930eb805112fc6c
MD5 c3f5a73c5fe17390ffcad7a580f80fdc
BLAKE2b-256 b089b04f70da581dda635f5c286be338b7d6b41553553d398df7bf9818e33d0e

See more details on using hashes here.

Provenance

The following attestation bundles were made for mortie-0.9.10-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: build-wheels.yml on espg/mortie

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mortie-0.9.10-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mortie-0.9.10-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0faca3df0e98a10d180bce28e94e56075027a25908c6f7df9d24c983a95f508f
MD5 751053663fbe896030c70ac8dade48be
BLAKE2b-256 ad2d1d91c0e4d919fa8597b574f7ab514dd705bd0e67d11e8c5b88d26a8276e3

See more details on using hashes here.

Provenance

The following attestation bundles were made for mortie-0.9.10-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: build-wheels.yml on espg/mortie

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mortie-0.9.10-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for mortie-0.9.10-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 9a4a29d440162437e4afd8b412718b87c5af86b3d3435641b4409541bf5e68cb
MD5 8287c5b51a2575d6489c55d2c73a9f83
BLAKE2b-256 e6e17b83aeab036625d41e6509313b7b26409e271d8b47ad860374825c7ab6b3

See more details on using hashes here.

Provenance

The following attestation bundles were made for mortie-0.9.10-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: build-wheels.yml on espg/mortie

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.9.11

6 files

This release

0.9.10 This release

6 files

0.9.9

6 files

0.9.8

6 files

0.9.7

6 files

0.9.6

6 files

0.9.5

6 files

0.9.4

6 files

0.9.3

6 files

0.9.2

6 files

0.9.1

6 files

0.9.0

6 files

0.8.5

6 files

0.8.4

6 files

0.8.3

6 files

0.8.2

6 files

0.8.1

6 files

0.8.0

6 files

0.7.2

6 files

0.7.1

6 files

0.7.0

6 files

0.6.6

6 files

0.6.5

6 files

0.6.4

6 files

0.6.3

6 files

0.6.2

6 files

0.6.1

6 files

0.5.2

6 files

0.5.1

5 files

0.5.0

5 files

0.4.10

5 files

0.4.8

5 files

0.4.7

5 files

0.4.6

5 files

0.4.5

5 files

0.4.4

5 files

0.4.3

5 files

0.4.0

5 files

0.3.1

2 files

0.2.0

2 files

0.1.0

1 file

0.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page