+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ ++ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 | 1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +15x +2x +2x +15x +2x +2x +11x +11x +11x +11x +11x +11x +11x +11x +11x +11x +1x +1x +1x +1x +1x +1x +1x +1x +10x +10x +10x +10x +1x +1x +1x +1x +1x +1x +1x +1x +9x +9x +9x +9x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +9x +9x +9x +9x +9x +1x +1x +9x +1x +1x +7x +7x +7x +7x +7x +7x +7x +7x +7x +7x +7x +7x +7x +7x +9x +6x +6x +9x +556x +556x +556x +556x +556x +556x +556x +556x +556x +556x +556x +6x +6x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +8x +8x +8x +8x +8x +8x +8x +8x +8x +8x +8x +8x + | /**
+ * Qibla direction utilities. Pure math, zero external dependencies.
+ *
+ * Computes the initial bearing (forward azimuth) from any point on Earth to
+ * the Ka'bah using the spherical law of cosines. Includes compass direction
+ * lookup, great-circle interpolation, and haversine distance.
+ *
+ * Ka'bah coordinates sourced from verified GPS data.
+ *
+ * @module
+ */
+
+export * from "./types.js";
+
+import {
+ KAABA_LAT,
+ KAABA_LNG,
+ EARTH_RADIUS_KM,
+ COMPASS_ABBR,
+ COMPASS_NAMES,
+ type CompassAbbr,
+ type CompassName,
+} from "./types.js";
+
+const DEG = Math.PI / 180;
+
+/**
+ * Qibla bearing in degrees clockwise from true north.
+ *
+ * Uses the forward azimuth formula from spherical trigonometry.
+ * Result range: [0, 360).
+ *
+ * @param lat - Observer latitude in decimal degrees (-90 to 90).
+ * @param lng - Observer longitude in decimal degrees (-180 to 180).
+ * @returns Bearing in degrees clockwise from north (0 = N, 90 = E, 180 = S, 270 = W).
+ * @throws {RangeError} If latitude is outside [-90, 90] or longitude outside [-180, 180].
+ */
+export function qiblaAngle(lat: number, lng: number): number {
+ if (lat < -90 || lat > 90) {
+ throw new RangeError(`Latitude must be between -90 and 90, got ${lat}`);
+ }
+ if (lng < -180 || lng > 180) {
+ throw new RangeError(`Longitude must be between -180 and 180, got ${lng}`);
+ }
+ const φ1 = lat * DEG,
+ λ1 = lng * DEG;
+ const φ2 = KAABA_LAT * DEG,
+ λ2 = KAABA_LNG * DEG;
+ const y = Math.sin(λ2 - λ1) * Math.cos(φ2);
+ const x =
+ Math.cos(φ1) * Math.sin(φ2) -
+ Math.sin(φ1) * Math.cos(φ2) * Math.cos(λ2 - λ1);
+ return (Math.atan2(y, x) / DEG + 360) % 360;
+}
+
+/**
+ * Eight-point compass abbreviation for a bearing.
+ *
+ * @param bearing - Bearing in degrees (0-360).
+ * @returns Two-letter compass abbreviation (N, NE, E, SE, S, SW, W, NW).
+ */
+export function compassDir(bearing: number): CompassAbbr {
+ // Non-null assertion: index is always 0-7 (Math.round(bearing/45) % 8), which is within COMPASS_ABBR bounds.
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+ return COMPASS_ABBR[Math.round(bearing / 45) % 8]!;
+}
+
+/**
+ * Full compass direction name for a bearing.
+ *
+ * @param bearing - Bearing in degrees (0-360).
+ * @returns Full direction name (North, Northeast, etc.).
+ */
+export function compassName(bearing: number): CompassName {
+ // Non-null assertion: index is always 0-7 (Math.round(bearing/45) % 8), which is within COMPASS_NAMES bounds.
+ // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+ return COMPASS_NAMES[Math.round(bearing / 45) % 8]!;
+}
+
+/**
+ * Great-circle waypoints from [lat, lng] to the Ka'bah.
+ *
+ * Uses the Slerp (spherical linear interpolation) formula. Useful for
+ * drawing Qibla direction lines on maps.
+ *
+ * @param lat - Origin latitude in decimal degrees.
+ * @param lng - Origin longitude in decimal degrees.
+ * @param steps - Number of segments (default: 120, producing 121 points).
+ * @returns Array of [latitude, longitude] pairs in degrees.
+ * @throws {RangeError} If latitude is outside [-90, 90] or longitude outside [-180, 180].
+ */
+export function qiblaGreatCircle(
+ lat: number,
+ lng: number,
+ steps = 120,
+): [number, number][] {
+ if (lat < -90 || lat > 90) {
+ throw new RangeError(`Latitude must be between -90 and 90, got ${lat}`);
+ }
+ if (lng < -180 || lng > 180) {
+ throw new RangeError(`Longitude must be between -180 and 180, got ${lng}`);
+ }
+ const φ1 = lat * DEG,
+ λ1 = lng * DEG;
+ const φ2 = KAABA_LAT * DEG,
+ λ2 = KAABA_LNG * DEG;
+
+ const d =
+ 2 *
+ Math.asin(
+ Math.sqrt(
+ Math.sin((φ2 - φ1) / 2) ** 2 +
+ Math.cos(φ1) * Math.cos(φ2) * Math.sin((λ2 - λ1) / 2) ** 2,
+ ),
+ );
+
+ if (d === 0) return [[lat, lng]];
+
+ const points: [number, number][] = [];
+ for (let i = 0; i <= steps; i++) {
+ const f = i / steps;
+ const A = Math.sin((1 - f) * d) / Math.sin(d);
+ const B = Math.sin(f * d) / Math.sin(d);
+ const x = A * Math.cos(φ1) * Math.cos(λ1) + B * Math.cos(φ2) * Math.cos(λ2);
+ const y = A * Math.cos(φ1) * Math.sin(λ1) + B * Math.cos(φ2) * Math.sin(λ2);
+ const z = A * Math.sin(φ1) + B * Math.sin(φ2);
+ points.push([
+ Math.atan2(z, Math.sqrt(x * x + y * y)) / DEG,
+ Math.atan2(y, x) / DEG,
+ ]);
+ }
+ return points;
+}
+
+/**
+ * Haversine distance between two coordinate pairs.
+ *
+ * @param lat1 - First point latitude in decimal degrees.
+ * @param lng1 - First point longitude in decimal degrees.
+ * @param lat2 - Second point latitude in decimal degrees.
+ * @param lng2 - Second point longitude in decimal degrees.
+ * @returns Distance in kilometers (spherical Earth approximation).
+ */
+export function distanceKm(
+ lat1: number,
+ lng1: number,
+ lat2: number,
+ lng2: number,
+): number {
+ const dLat = (lat2 - lat1) * DEG;
+ const dLng = (lng2 - lng1) * DEG;
+ const a =
+ Math.sin(dLat / 2) ** 2 +
+ Math.cos(lat1 * DEG) * Math.cos(lat2 * DEG) * Math.sin(dLng / 2) ** 2;
+ return EARTH_RADIUS_KM * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 | 1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x +1x + | /** Latitude of the Ka'bah center, Masjid al-Haram, Mecca (degrees north). */ +export const KAABA_LAT = 21.422511; + +/** Longitude of the Ka'bah center, Masjid al-Haram, Mecca (degrees east). */ +export const KAABA_LNG = 39.82615; + +/** Mean radius of the Earth in kilometers (WGS-84 volumetric mean). */ +export const EARTH_RADIUS_KM = 6371; + +/** Eight-point compass abbreviations. */ +export const COMPASS_ABBR = [ + "N", + "NE", + "E", + "SE", + "S", + "SW", + "W", + "NW", +] as const; + +/** Eight-point compass full names. */ +export const COMPASS_NAMES = [ + "North", + "Northeast", + "East", + "Southeast", + "South", + "Southwest", + "West", + "Northwest", +] as const; + +/** Compass abbreviation type. */ +export type CompassAbbr = (typeof COMPASS_ABBR)[number]; + +/** Compass full name type. */ +export type CompassName = (typeof COMPASS_NAMES)[number]; + |