Grzegorz Kucmierz
9ad361f0ca
- Replaced 32-bit bitwise shifts (<<) with Math.pow() and BigInt shifts to support large nsides without modulo overflow. - Recalculated compress_bits and spread_bits to explicitly loop 64-bit indexes rather than truncating with 8-bit Uint16Array table lookups (ctab/utab). - Restored original C/C++ geographic precision boundaries allowing the engine to successfully encode and decode high-precision pixels natively up to Order 52.
@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.