mirror of
https://github.com/acamarata/qibla.git
synced 2026-06-30 19:04:28 +00:00
8eb0516119
- Add .wiki/ with Home, API-Reference, and Architecture pages - Add wiki-sync.yml workflow - Fix README: badge and install command now use @acamarata/qibla scope - Add Architecture and Documentation sections to README - Add README.md, CHANGELOG.md, LICENSE to files field - Update pack-check CI to verify README, CHANGELOG, LICENSE in tarball - Fix exports.import.types to ./dist/index.d.mts (matches tsup output) - Enable sourcemap: true in tsup config
55 lines
1.8 KiB
Markdown
55 lines
1.8 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)
|