# @gkucmierz/healpixjs-bigint

![npm (scoped)](https://img.shields.io/npm/v/@gkucmierz/healpixjs-bigint)
![NPM License](https://img.shields.io/npm/l/%40gkucmierz%2Fhealpixjs-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

```bash
npm install @gkucmierz/healpixjs-bigint
```

```javascript
// 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](https://gitea.7u.pl/gkucmierz/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.