aric/qibla
1
0
Fork 0
mirror of https://github.com/acamarata/qibla.git synced 2026-07-01 19:34: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. | | `lat` | `number` | Observer latitude in decimal degrees. Valid range: −90 to 90. |
| `lng` | `number` | Observer longitude in decimal degrees. Valid range: −180 to 180. | | `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. **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). | | `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 ```typescript
import { compassDir } from "@acamarata/qibla"; 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). | | `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 ```typescript
import { compassName } from "@acamarata/qibla"; 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 | | Name | Type | Default | Description |
| ------- | -------- | ------- | ---------------------------------------------------- | | ------- | -------- | ------- | ---------------------------------------------------- |
| `lat` | `number` | — | Observer latitude in decimal degrees (−90 to 90). | | `lat` | `number` |: | Observer latitude in decimal degrees (−90 to 90). |
| `lng` | `number` | — | Observer longitude in decimal degrees (−180 to 180). | | `lng` | `number` |: | Observer longitude in decimal degrees (−180 to 180). |
| `steps` | `number` | `120` | Number of segments. Result has `steps + 1` points. | | `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. **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. | | `lat2` | `number` | Second point latitude in decimal degrees. |
| `lng2` | `number` | Second point longitude in decimal degrees. | | `lng2` | `number` | Second point longitude in decimal degrees. |
**Returns:** `number` — Distance in kilometers. **Returns:** `number`: Distance in kilometers.
```typescript ```typescript
import { distanceKm, KAABA_LAT, KAABA_LNG } from "@acamarata/qibla"; 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. `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. `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: Lat/lng are converted to 3D Cartesian unit vectors on the unit sphere:
@ -40,7 +40,7 @@ y = cos(φ) · sin(λ)
z = 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: 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) ) ) 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]: 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. 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 ## 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) → 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 ## Pages
- [API Reference](API-Reference) — Full function and constant reference - [API Reference](API-Reference): Full function and constant reference
- [Architecture](Architecture) — Algorithm design, spherical trigonometry, implementation decisions - [Architecture](Architecture): Algorithm design, spherical trigonometry, implementation decisions
## What It Does ## What It Does
This library computes three things: 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 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 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 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. 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 ## Related Packages
- [pray-calc](https://github.com/acamarata/pray-calc) — Islamic prayer times - [pray-calc](https://github.com/acamarata/pray-calc): Islamic prayer times
- [nrel-spa](https://github.com/acamarata/nrel-spa) — NREL Solar Position Algorithm - [nrel-spa](https://github.com/acamarata/nrel-spa): NREL Solar Position Algorithm
- [moon-sighting](https://github.com/acamarata/moon-sighting) — Lunar crescent visibility - [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): 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 - [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 - [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 - [Architecture](https://github.com/acamarata/qibla/wiki/Architecture): Algorithm design, spherical trigonometry, Slerp implementation
## Related ## Related
- [pray-calc](https://github.com/acamarata/pray-calc) — Islamic prayer times calculator - [pray-calc](https://github.com/acamarata/pray-calc): Islamic prayer times calculator
- [nrel-spa](https://github.com/acamarata/nrel-spa) — NREL Solar Position Algorithm - [nrel-spa](https://github.com/acamarata/nrel-spa): NREL Solar Position Algorithm
- [moon-sighting](https://github.com/acamarata/moon-sighting) — Lunar crescent visibility - [moon-sighting](https://github.com/acamarata/moon-sighting): Lunar crescent visibility
## Acknowledgments ## Acknowledgments