@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 on the geo-words interactive 3D map.

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.