aric/qibla
1
0
Fork 0
mirror of https://github.com/acamarata/qibla.git synced 2026-06-30 19:04:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

style: replace em dashes with colons in docs and wiki

Browse source
This commit is contained in:
Aric Camarata 2026-03-08 17:28:03 -04:00
parent d59a92f413
commit 1e9f57f3f9
4 changed files with 29 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
.wiki/API-Reference.md
View file

@ -21,7 +21,7 @@ where φ₁, λ₁ is the observer and φ₂, λ₂ is the Ka'bah.
| `lat` | `number` | Observer latitude in decimal degrees. Valid range: −90 to 90. |
| `lng` | `number` | Observer longitude in decimal degrees. Valid range: −180 to 180. |
**Returns:** `number` — Bearing in degrees clockwise from true north. Range: [0, 360).
**Returns:** `number`: Bearing in degrees clockwise from true north. Range: [0, 360).
**Throws:** `RangeError` if either coordinate is out of bounds.
@ -47,7 +47,7 @@ Maps the bearing to one of eight 45° sectors, selecting the nearest cardinal or
| --------- | -------- | --------------------------- |
| `bearing` | `number` | Bearing in degrees (0–360). |
**Returns:** `CompassAbbr` — One of: `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, `NW`.
**Returns:** `CompassAbbr`: One of: `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, `NW`.
```typescript
import { compassDir } from "@acamarata/qibla";
@ -70,7 +70,7 @@ Returns the full compass direction name for a bearing.
| --------- | -------- | --------------------------- |
| `bearing` | `number` | Bearing in degrees (0–360). |
**Returns:** `CompassName` — One of: `North`, `Northeast`, `East`, `Southeast`, `South`, `Southwest`, `West`, `Northwest`.
**Returns:** `CompassName`: One of: `North`, `Northeast`, `East`, `Southeast`, `South`, `Southwest`, `West`, `Northwest`.
```typescript
import { compassName } from "@acamarata/qibla";
@ -90,11 +90,11 @@ Useful for drawing the Qibla direction line on a map. Returns `steps + 1` points
| Name | Type | Default | Description |
| ------- | -------- | ------- | ---------------------------------------------------- |
| `lat` | `number` | — | Observer latitude in decimal degrees (−90 to 90). |
| `lng` | `number` | — | Observer longitude in decimal degrees (−180 to 180). |
| `lat` | `number` |: | Observer latitude in decimal degrees (−90 to 90). |
| `lng` | `number` |: | Observer longitude in decimal degrees (−180 to 180). |
| `steps` | `number` | `120` | Number of segments. Result has `steps + 1` points. |
**Returns:** `[number, number][]` — Array of `[latitude, longitude]` pairs in degrees.
**Returns:** `[number, number][]`: Array of `[latitude, longitude]` pairs in degrees.
**Throws:** `RangeError` if coordinates are out of bounds.
@ -125,7 +125,7 @@ Uses the haversine formula with a spherical Earth (R = 6,371 km, WGS-84 volumetr
| `lat2` | `number` | Second point latitude in decimal degrees. |
| `lng2` | `number` | Second point longitude in decimal degrees. |
**Returns:** `number` — Distance in kilometers.
**Returns:** `number`: Distance in kilometers.
```typescript
import { distanceKm, KAABA_LAT, KAABA_LNG } from "@acamarata/qibla";

16
.wiki/Architecture.md
View file

@ -22,7 +22,7 @@ x = cos(φ₁) · sin(φ₂) − sin(φ₁) · cos(φ₂) · cos(λ₂ − λ₁
`atan2` produces a result in (−π, π]. Adding 360° and taking modulo 360 converts to the [0, 360) convention, where 0° = North, 90° = East.
This gives the bearing at the observer's location, not the arrival bearing at the Ka'bah. For a short trip within a city, the difference is negligible. For a trans-oceanic path, the bearing rotates continuously along the geodesic — `qiblaGreatCircle` shows this progression.
This gives the bearing at the observer's location, not the arrival bearing at the Ka'bah. For a short trip within a city, the difference is negligible. For a trans-oceanic path, the bearing rotates continuously along the geodesic: `qiblaGreatCircle` shows this progression.
---
@ -30,7 +30,7 @@ This gives the bearing at the observer's location, not the arrival bearing at th
`qiblaGreatCircle` uses the Slerp (spherical linear interpolation) formula to generate uniformly spaced waypoints along the geodesic.
**Step 1 — Convert to 3D unit vectors**
**Step 1: Convert to 3D unit vectors**
Lat/lng are converted to 3D Cartesian unit vectors on the unit sphere:
@ -40,7 +40,7 @@ y = cos(φ) · sin(λ)
z = sin(φ)
```
**Step 2 — Compute the angular distance**
**Step 2: Compute the angular distance**
The central angle d between the two points uses the formula:
@ -48,9 +48,9 @@ The central angle d between the two points uses the formula:
d = 2 · asin( sqrt( sin²((φ₂−φ₁)/2) + cos(φ₁)·cos(φ₂)·sin²((λ₂−λ₁)/2) ) )
```
This is equivalent to the haversine formula. If d = 0, the observer is at the Ka'bah — return immediately.
This is equivalent to the haversine formula. If d = 0, the observer is at the Ka'bah: return immediately.
**Step 3 — Interpolate**
**Step 3: Interpolate**
For each interpolation parameter f ∈ [0, 1]:
@ -62,7 +62,7 @@ P = A·P₁ + B·P₂
where P₁ and P₂ are the 3D unit vectors. Convert the result back to lat/lng.
This is numerically stable for all separations except d = 0 (handled separately) and d = π (antipodal points, undefined great circle). For practical use — observer and Ka'bah are never antipodal — this is not a concern.
This is numerically stable for all separations except d = 0 (handled separately) and d = π (antipodal points, undefined great circle). For practical use: observer and Ka'bah are never antipodal: this is not a concern.
---
@ -96,7 +96,7 @@ Rounding (not flooring) ensures each sector is centered on its cardinal/intercar
## Ka'bah Coordinates
The Ka'bah center is fixed at 21.422511°N, 39.82615°E. These coordinates come from verified GPS data and match the values used by major Islamic authority applications. The value is a constant — no runtime fetching.
The Ka'bah center is fixed at 21.422511°N, 39.82615°E. These coordinates come from verified GPS data and match the values used by major Islamic authority applications. The value is a constant: no runtime fetching.
---
@ -109,7 +109,7 @@ src/index.ts → tsup → dist/index.cjs (CommonJS)
→ dist/index.d.mts (type definitions, ESM)
```
tsup config uses `platform: 'neutral'` — the library has no Node.js-specific API calls and works identically in browsers, Deno, Bun, and all bundlers.
tsup config uses `platform: 'neutral'`: the library has no Node.js-specific API calls and works identically in browsers, Deno, Bun, and all bundlers.
---

16
.wiki/Home.md
View file

@ -4,16 +4,16 @@ Qibla direction, great-circle path, and haversine distance. Pure math, zero depe
## Pages
- [API Reference](API-Reference) — Full function and constant reference
- [Architecture](Architecture) — Algorithm design, spherical trigonometry, implementation decisions
- [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
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.
@ -52,9 +52,9 @@ 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
- [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
---

12
README.md
View file

@ -95,15 +95,15 @@ const bearing: number = qiblaAngle(40.7128, -74.006);
Full reference available on the [GitHub Wiki](https://github.com/acamarata/qibla/wiki):
- [Home](https://github.com/acamarata/qibla/wiki/Home) — Overview and quick start
- [API Reference](https://github.com/acamarata/qibla/wiki/API-Reference) — Full function and constant reference
- [Architecture](https://github.com/acamarata/qibla/wiki/Architecture) — Algorithm design, spherical trigonometry, Slerp implementation
- [Home](https://github.com/acamarata/qibla/wiki/Home): Overview and quick start
- [API Reference](https://github.com/acamarata/qibla/wiki/API-Reference): Full function and constant reference
- [Architecture](https://github.com/acamarata/qibla/wiki/Architecture): Algorithm design, spherical trigonometry, Slerp implementation
## Related
- [pray-calc](https://github.com/acamarata/pray-calc) — Islamic prayer times calculator
- [nrel-spa](https://github.com/acamarata/nrel-spa) — NREL Solar Position Algorithm
- [moon-sighting](https://github.com/acamarata/moon-sighting) — Lunar crescent visibility
- [pray-calc](https://github.com/acamarata/pray-calc): Islamic prayer times calculator
- [nrel-spa](https://github.com/acamarata/nrel-spa): NREL Solar Position Algorithm
- [moon-sighting](https://github.com/acamarata/moon-sighting): Lunar crescent visibility
## Acknowledgments