mirror of
https://github.com/acamarata/qibla.git
synced 2026-07-01 03:14:30 +00:00
176 lines
5.1 KiB
Markdown
176 lines
5.1 KiB
Markdown
# API Reference
|
||
|
||
## Functions
|
||
|
||
### `qiblaAngle(lat, lng)`
|
||
|
||
Computes the initial bearing from the given coordinates to the Ka'bah.
|
||
|
||
Uses the forward azimuth formula from spherical trigonometry:
|
||
|
||
```
|
||
θ = atan2(sin(Δλ)·cos(φ₂), cos(φ₁)·sin(φ₂) − sin(φ₁)·cos(φ₂)·cos(Δλ))
|
||
```
|
||
|
||
where φ₁, λ₁ is the observer and φ₂, λ₂ is the Ka'bah.
|
||
|
||
**Parameters:**
|
||
|
||
| Name | Type | Description |
|
||
| ----- | -------- | ---------------------------------------------------------------- |
|
||
| `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).
|
||
|
||
**Throws:** `RangeError` if either coordinate is out of bounds.
|
||
|
||
```typescript
|
||
import { qiblaAngle } from "@acamarata/qibla";
|
||
|
||
qiblaAngle(40.7128, -74.006); // ~58.48 (New York → Mecca)
|
||
qiblaAngle(51.5074, -0.1278); // ~119.0 (London → Mecca)
|
||
qiblaAngle(35.6762, 139.6503); // ~293.3 (Tokyo → Mecca)
|
||
```
|
||
|
||
---
|
||
|
||
### `compassDir(bearing)`
|
||
|
||
Returns the eight-point compass abbreviation for a bearing.
|
||
|
||
Maps the bearing to one of eight 45° sectors, selecting the nearest cardinal or intercardinal direction.
|
||
|
||
**Parameters:**
|
||
|
||
| Name | Type | Description |
|
||
| --------- | -------- | --------------------------- |
|
||
| `bearing` | `number` | Bearing in degrees (0–360). |
|
||
|
||
**Returns:** `CompassAbbr`: One of: `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, `NW`.
|
||
|
||
```typescript
|
||
import { compassDir } from "@acamarata/qibla";
|
||
|
||
compassDir(0); // "N"
|
||
compassDir(45); // "NE"
|
||
compassDir(58.5); // "NE"
|
||
compassDir(270); // "W"
|
||
```
|
||
|
||
---
|
||
|
||
### `compassName(bearing)`
|
||
|
||
Returns the full compass direction name for a bearing.
|
||
|
||
**Parameters:**
|
||
|
||
| Name | Type | Description |
|
||
| --------- | -------- | --------------------------- |
|
||
| `bearing` | `number` | Bearing in degrees (0–360). |
|
||
|
||
**Returns:** `CompassName`: One of: `North`, `Northeast`, `East`, `Southeast`, `South`, `Southwest`, `West`, `Northwest`.
|
||
|
||
```typescript
|
||
import { compassName } from "@acamarata/qibla";
|
||
|
||
compassName(58.5); // "Northeast"
|
||
```
|
||
|
||
---
|
||
|
||
### `qiblaGreatCircle(lat, lng, steps?)`
|
||
|
||
Generates waypoints along the great-circle geodesic from the observer to the Ka'bah, using the Slerp (spherical linear interpolation) formula.
|
||
|
||
Useful for drawing the Qibla direction line on a map. Returns `steps + 1` points uniformly spaced along the geodesic.
|
||
|
||
**Parameters:**
|
||
|
||
| Name | Type | Default | Description |
|
||
| ------- | -------- | ------- | ---------------------------------------------------- |
|
||
| `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.
|
||
|
||
**Throws:** `RangeError` if coordinates are out of bounds.
|
||
|
||
Special case: if the observer is at the Ka'bah (distance = 0), returns `[[lat, lng]]`.
|
||
|
||
```typescript
|
||
import { qiblaGreatCircle } from "@acamarata/qibla";
|
||
|
||
const path = qiblaGreatCircle(40.7128, -74.006); // 121 points
|
||
// path[0] ≈ [40.7128, -74.006] (New York)
|
||
// path[120] ≈ [21.42, 39.83] (Ka'bah)
|
||
```
|
||
|
||
---
|
||
|
||
### `distanceKm(lat1, lng1, lat2, lng2)`
|
||
|
||
Haversine distance between two points in kilometers.
|
||
|
||
Uses the haversine formula with a spherical Earth (R = 6,371 km, WGS-84 volumetric mean). Accurate to within 0.5% globally.
|
||
|
||
**Parameters:**
|
||
|
||
| Name | Type | Description |
|
||
| ------ | -------- | ------------------------------------------ |
|
||
| `lat1` | `number` | First point latitude in decimal degrees. |
|
||
| `lng1` | `number` | First point longitude in decimal degrees. |
|
||
| `lat2` | `number` | Second point latitude in decimal degrees. |
|
||
| `lng2` | `number` | Second point longitude in decimal degrees. |
|
||
|
||
**Returns:** `number`: Distance in kilometers.
|
||
|
||
```typescript
|
||
import { distanceKm, KAABA_LAT, KAABA_LNG } from "@acamarata/qibla";
|
||
|
||
distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG); // ~9,634 km
|
||
```
|
||
|
||
---
|
||
|
||
## Constants
|
||
|
||
| Constant | Value | Description |
|
||
| ----------------- | ----------- | ------------------------------------------------ |
|
||
| `KAABA_LAT` | `21.422511` | Ka'bah center latitude in decimal degrees north. |
|
||
| `KAABA_LNG` | `39.82615` | Ka'bah center longitude in decimal degrees east. |
|
||
| `EARTH_RADIUS_KM` | `6371` | WGS-84 volumetric mean radius in kilometers. |
|
||
|
||
```typescript
|
||
import { KAABA_LAT, KAABA_LNG, EARTH_RADIUS_KM } from "@acamarata/qibla";
|
||
```
|
||
|
||
---
|
||
|
||
## Types
|
||
|
||
### `CompassAbbr`
|
||
|
||
```typescript
|
||
type CompassAbbr = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW";
|
||
```
|
||
|
||
### `CompassName`
|
||
|
||
```typescript
|
||
type CompassName =
|
||
| "North"
|
||
| "Northeast"
|
||
| "East"
|
||
| "Southeast"
|
||
| "South"
|
||
| "Southwest"
|
||
| "West"
|
||
| "Northwest";
|
||
```
|
||
|
||
---
|
||
|
||
[Home](Home) | [Architecture](Architecture)
|