mirror of
https://github.com/acamarata/qibla.git
synced 2026-07-01 03:14:30 +00:00
61 lines
1.7 KiB
Markdown
61 lines
1.7 KiB
Markdown
# @acamarata/qibla
|
|
|
|
Qibla direction, great-circle path, and haversine distance. Pure math, zero dependencies.
|
|
|
|
## Pages
|
|
|
|
- [API Reference](API-Reference): Full function and constant reference
|
|
- [Architecture](Architecture): Algorithm design, spherical trigonometry, implementation decisions
|
|
|
|
## What It Does
|
|
|
|
This library computes three things:
|
|
|
|
1. **Qibla bearing**: the initial compass bearing from any point on Earth to the Ka'bah in Mecca, using the forward azimuth formula from spherical trigonometry
|
|
2. **Great-circle path**: a series of waypoints along the geodesic from origin to Ka'bah, suitable for rendering on a map
|
|
3. **Haversine distance**: the surface distance between two coordinate pairs using the haversine formula
|
|
|
|
All calculations use a spherical Earth model (WGS-84 volumetric mean radius, 6,371 km). The Ka'bah coordinates (21.422511°N, 39.82615°E) are sourced from verified GPS data.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
npm install @acamarata/qibla
|
|
```
|
|
|
|
```typescript
|
|
import {
|
|
qiblaAngle,
|
|
compassDir,
|
|
distanceKm,
|
|
KAABA_LAT,
|
|
KAABA_LNG,
|
|
} from "@acamarata/qibla";
|
|
|
|
const bearing = qiblaAngle(40.7128, -74.006); // New York
|
|
console.log(bearing); // ~58.48
|
|
console.log(compassDir(bearing)); // "NE"
|
|
|
|
const km = distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG);
|
|
console.log(km); // ~9,634
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @acamarata/qibla
|
|
# or
|
|
pnpm add @acamarata/qibla
|
|
# or
|
|
yarn add @acamarata/qibla
|
|
```
|
|
|
|
## Related Packages
|
|
|
|
- [pray-calc](https://github.com/acamarata/pray-calc): Islamic prayer times
|
|
- [nrel-spa](https://github.com/acamarata/nrel-spa): NREL Solar Position Algorithm
|
|
- [moon-sighting](https://github.com/acamarata/moon-sighting): Lunar crescent visibility
|
|
|
|
---
|
|
|
|
[API Reference](API-Reference) | [Architecture](Architecture)
|