@gkucmierz/healpixjs-bigint

A true mathematically sound BigInt port of the popular HEALPix spatial mapping algorithm.

Motivation: Breaking the 32-bit ceiling 🚀

The original healpixjs engine is a fantastic library. However, under the hood it computes Z-order curves and bitwise coordinate spreads (like xyf2pix) using standard JavaScript bitwise operators (<<, >>, |, &).

By specification, JavaScript forces bitwise operators onto 32-bit signed integers. This means any Nside resolution that generates spatial face indices greater than $2,147,483,647$ mathematically overflows causing the map grids to fracture or the CPU to loop infinitely.

HEALPix Order <= 13 is the absolute limit for standard JavaScript math.

@gkucmierz/healpixjs-bigint rewrites the core geometry algorithms using native BigInt (e.g., 1n << 20n). This allows you to construct and query mapping grids at massive depths (virtually tested up to Order 29) without ever triggering NaN rendering freezes or out-of-bounds array overflows.

Usage

npm install @gkucmierz/healpixjs-bigint

// Native ESM architecture
import { Healpix, Pointing } from '@gkucmierz/healpixjs-bigint';

// Constructing an massive grid (e.g. Order 20 -> Nside 1048576)
const hp = new Healpix(1n << 20n);

const ptg = new Pointing(1.57, 0.5); // (theta, phi)

// Radius is in radians. Fact is the oversampling multiplier (e.g. 4)
const ranges = hp.queryDiscInclusive(ptg, 0.05, 4);

// ranges.r contains pure BigInt boundaries spanning massive precision
console.log(ranges.r); // BigInt64Array [158671400n, 158671408n, ...]

Live Implementation Example

This library powers extreme sub-meter zoom depths mathematically perfect in realtime. You can test a massive HEALPix order calculation on the Geo-Words Interactive 3D Map. Source code available at geo-words.

Credits

All credit for the structural JavaScript foundation algorithms goes to the original authors of healpixjs. This fork modifies it exclusively for precision integer performance in WebGL/Canvas pipelines.