mirror of
https://github.com/acamarata/qibla-dart.git
synced 2026-07-01 11:24:27 +00:00
105 lines
2.3 KiB
Markdown
105 lines
2.3 KiB
Markdown
# API Reference
|
|
|
|
## qiblaAngle
|
|
|
|
```dart
|
|
double qiblaAngle(double lat, double lng)
|
|
```
|
|
|
|
Computes the initial bearing (forward azimuth) from the given coordinates to the Ka'bah using the spherical forward azimuth formula.
|
|
|
|
| Parameter | Type | Description |
|
|
| --- | --- | --- |
|
|
| `lat` | `double` | Latitude in decimal degrees (-90 to 90) |
|
|
| `lng` | `double` | Longitude in decimal degrees (-180 to 180) |
|
|
| Returns | `double` | Bearing in degrees clockwise from north (0-360) |
|
|
|
|
Throws `RangeError` if coordinates are out of bounds.
|
|
|
|
```dart
|
|
final bearing = qiblaAngle(40.7128, -74.006); // ~58.48
|
|
```
|
|
|
|
---
|
|
|
|
## compassDir
|
|
|
|
```dart
|
|
String compassDir(double bearing)
|
|
```
|
|
|
|
Returns an eight-point compass abbreviation for the given bearing.
|
|
|
|
| Bearing range | Returns |
|
|
| --- | --- |
|
|
| 337.5 - 22.5 | N |
|
|
| 22.5 - 67.5 | NE |
|
|
| 67.5 - 112.5 | E |
|
|
| 112.5 - 157.5 | SE |
|
|
| 157.5 - 202.5 | S |
|
|
| 202.5 - 247.5 | SW |
|
|
| 247.5 - 292.5 | W |
|
|
| 292.5 - 337.5 | NW |
|
|
|
|
---
|
|
|
|
## compassName
|
|
|
|
```dart
|
|
String compassName(double bearing)
|
|
```
|
|
|
|
Returns the full compass direction name for the given bearing: North, Northeast, East, Southeast, South, Southwest, West, or Northwest.
|
|
|
|
---
|
|
|
|
## qiblaGreatCircle
|
|
|
|
```dart
|
|
List<LatLng> qiblaGreatCircle(double lat, double lng, [int steps = 120])
|
|
```
|
|
|
|
Generates waypoints along the great circle from the observer's location to the Ka'bah using spherical linear interpolation (Slerp). Returns `steps + 1` points including both endpoints.
|
|
|
|
Useful for drawing the Qibla direction line on a map.
|
|
|
|
```dart
|
|
final path = qiblaGreatCircle(40.7128, -74.006);
|
|
// path[0] = observer location
|
|
// path[path.length - 1] = Ka'bah
|
|
```
|
|
|
|
### LatLng fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `lat` | `double` | Latitude in decimal degrees |
|
|
| `lng` | `double` | Longitude in decimal degrees |
|
|
|
|
---
|
|
|
|
## distanceKm
|
|
|
|
```dart
|
|
double distanceKm(double lat1, double lng1, double lat2, double lng2)
|
|
```
|
|
|
|
Haversine distance between two points in kilometers. Uses a spherical Earth model with R = 6,371 km.
|
|
|
|
```dart
|
|
final km = distanceKm(40.7128, -74.006, kaabaLat, kaabaLng); // ~9634
|
|
```
|
|
|
|
---
|
|
|
|
## Constants
|
|
|
|
| Constant | Value | Description |
|
|
| --- | --- | --- |
|
|
| `kaabaLat` | 21.422511 | Ka'bah center latitude (degrees north) |
|
|
| `kaabaLng` | 39.826150 | Ka'bah center longitude (degrees east) |
|
|
| `earthRadiusKm` | 6371 | WGS-84 volumetric mean radius in km |
|
|
|
|
---
|
|
|
|
[Home](Home)
|