Grzegorz Kucmierz
b19b253e68
All checks were successful
npm-publish / publish (push) Successful in 4s
46 lines
2.3 KiB
Markdown
46 lines
2.3 KiB
Markdown
# @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
|
|
|
|
```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 mathematically perfect in realtime. You can test a massive HEALPix order calculation on the [Geo-Words Interactive 3D Map](http://geo-words.7u.pl/). Source code available at [geo-words](https://gitea.7u.pl/gkucmierz/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.
|