@smartnet360/svelte-components 0.0.102 → 0.0.103

package/dist/core/CoverageMap/utils/geoUtils.js

@@ -0,0 +1,374 @@
+/**
+ * Geographic Utility Functions
+ *
+ * This module provides heavily commented geographic calculations:
+ * - Distance calculations (Haversine formula)
+ * - Bearing calculations (initial and final bearings)
+ * - Destination point calculations (given distance and bearing)
+ * - Coordinate conversions
+ *
+ * All calculations assume:
+ * - Earth is a sphere (acceptable for ranges < 100km)
+ * - Radius = 6371 km (mean Earth radius)
+ * - Angles in degrees for input/output, radians for calculations
+ */
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/**
+ * Earth's mean radius in kilometers
+ * Used for all distance and bearing calculations
+ */
+const EARTH_RADIUS_KM = 6371;
+/**
+ * Conversion factors
+ */
+const DEG_TO_RAD = Math.PI / 180;
+const RAD_TO_DEG = 180 / Math.PI;
+// ============================================================================
+// DISTANCE CALCULATIONS
+// ============================================================================
+/**
+ * Calculate distance between two points using Haversine formula
+ *
+ * The Haversine formula calculates the great-circle distance between two points
+ * on a sphere given their longitudes and latitudes.
+ *
+ * Formula:
+ *   a = sin²(Δlat/2) + cos(lat1) × cos(lat2) × sin²(Δlon/2)
+ *   c = 2 × atan2(√a, √(1−a))
+ *   d = R × c
+ *
+ * Where:
+ *   - Δlat = lat2 - lat1 (difference in latitude)
+ *   - Δlon = lon2 - lon1 (difference in longitude)
+ *   - R = Earth's radius (6371 km)
+ *   - All angles in radians for calculation
+ *
+ * Accuracy:
+ *   - Very accurate for distances < 100 km
+ *   - Error < 0.5% for distances up to 1000 km
+ *   - Assumes spherical Earth (good enough for RF planning)
+ *
+ * @param point1 - First position (lat, lng in degrees)
+ * @param point2 - Second position (lat, lng in degrees)
+ * @returns Distance in kilometers
+ *
+ * @example
+ * const distance = calculateDistance(
+ *   { lat: 40.7128, lng: -74.0060 },  // New York
+ *   { lat: 51.5074, lng: -0.1278 }    // London
+ * );
+ * // Returns: ~5570 km
+ */
+export function calculateDistance(point1, point2) {
+    // Convert degrees to radians for trigonometric calculations
+    const lat1Rad = point1.lat * DEG_TO_RAD;
+    const lat2Rad = point2.lat * DEG_TO_RAD;
+    // Calculate differences in coordinates
+    const deltaLatRad = (point2.lat - point1.lat) * DEG_TO_RAD;
+    const deltaLngRad = (point2.lng - point1.lng) * DEG_TO_RAD;
+    // Haversine formula - Step 1: Calculate 'a'
+    // sin²(Δlat/2) represents the north-south component
+    const sinDeltaLat = Math.sin(deltaLatRad / 2);
+    const sinDeltaLatSquared = sinDeltaLat * sinDeltaLat;
+    // sin²(Δlon/2) represents the east-west component, scaled by latitude
+    const sinDeltaLng = Math.sin(deltaLngRad / 2);
+    const sinDeltaLngSquared = sinDeltaLng * sinDeltaLng;
+    // Combine components, accounting for Earth's curvature at different latitudes
+    const a = sinDeltaLatSquared + Math.cos(lat1Rad) * Math.cos(lat2Rad) * sinDeltaLngSquared;
+    // Haversine formula - Step 2: Calculate angular distance 'c'
+    // atan2 is used instead of asin for numerical stability
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    // Haversine formula - Step 3: Convert angular distance to linear distance
+    const distanceKm = EARTH_RADIUS_KM * c;
+    return distanceKm;
+}
+/**
+ * Calculate 3D distance including height difference
+ *
+ * For RF calculations, we often need to account for antenna height and
+ * target height (e.g., mobile at 1.5m). This uses Pythagoras in 3D:
+ *
+ * Formula:
+ *   d_3d = √(d_horizontal² + Δh²)
+ *
+ * Where:
+ *   - d_horizontal = Haversine distance (horizontal plane)
+ *   - Δh = height difference in km (h2 - h1)
+ *
+ * Note: For typical cellular ranges (< 10km) and heights (< 100m),
+ * the height component is usually negligible (< 0.1% error if ignored)
+ *
+ * @param point1 - First position with height
+ * @param point2 - Second position (height defaults to 1.5m if not provided)
+ * @returns 3D distance in kilometers
+ */
+export function calculate3DDistance(point1, point2) {
+    // Calculate horizontal distance using Haversine
+    const horizontalDistanceKm = calculateDistance(point1, point2);
+    // Height difference in meters (assume ground-level device if not specified)
+    const defaultDeviceHeight = 1.5; // meters (typical mobile phone height)
+    // Calculate height difference
+    // point2 can be Position2D or Position3D
+    const point2Height = point2.height ?? 0;
+    const heightDifferenceMeters = point1.height - point2Height; // Convert height difference to kilometers
+    const heightDifferenceKm = heightDifferenceMeters / 1000;
+    // Pythagoras: d = √(horizontal² + vertical²)
+    const distance3DKm = Math.sqrt(horizontalDistanceKm * horizontalDistanceKm + heightDifferenceKm * heightDifferenceKm);
+    return distance3DKm;
+}
+// ============================================================================
+// BEARING CALCULATIONS
+// ============================================================================
+/**
+ * Calculate initial bearing from point1 to point2
+ *
+ * Bearing (or azimuth) is the compass direction from one point to another.
+ * This calculates the INITIAL bearing - the direction you would initially
+ * travel on a great circle route.
+ *
+ * Formula:
+ *   θ = atan2(sin(Δlon) × cos(lat2),
+ *             cos(lat1) × sin(lat2) - sin(lat1) × cos(lat2) × cos(Δlon))
+ *
+ * Important notes:
+ *   - Bearing changes along a great circle path (Earth is curved!)
+ *   - For short distances (< 100 km), this is effectively constant
+ *   - Result is in degrees: 0° = North, 90° = East, 180° = South, 270° = West
+ *
+ * RF Planning Usage:
+ *   Use this to determine the relative angle between antenna and target.
+ *   Subtract antenna azimuth to get the angle relative to main beam direction.
+ *
+ * @param from - Starting position (lat, lng in degrees)
+ * @param to - Destination position (lat, lng in degrees)
+ * @returns Bearing in degrees (0-360), where 0 = North
+ *
+ * @example
+ * const bearing = calculateBearing(
+ *   { lat: 40.7128, lng: -74.0060 },  // From New York
+ *   { lat: 51.5074, lng: -0.1278 }    // To London
+ * );
+ * // Returns: ~51° (northeast)
+ */
+export function calculateBearing(from, to) {
+    // Convert to radians
+    const lat1Rad = from.lat * DEG_TO_RAD;
+    const lat2Rad = to.lat * DEG_TO_RAD;
+    const deltaLngRad = (to.lng - from.lng) * DEG_TO_RAD;
+    // Calculate bearing components
+    // y-component: East-West displacement, scaled by destination latitude
+    const y = Math.sin(deltaLngRad) * Math.cos(lat2Rad);
+    // x-component: North-South displacement, accounting for curvature
+    const x = Math.cos(lat1Rad) * Math.sin(lat2Rad) -
+        Math.sin(lat1Rad) * Math.cos(lat2Rad) * Math.cos(deltaLngRad);
+    // atan2 gives angle in radians, handling all quadrants correctly
+    const bearingRad = Math.atan2(y, x);
+    // Convert to degrees and normalize to 0-360 range
+    let bearingDeg = bearingRad * RAD_TO_DEG;
+    bearingDeg = (bearingDeg + 360) % 360; // Ensure 0-360 range
+    return bearingDeg;
+}
+// ============================================================================
+// DESTINATION POINT CALCULATIONS
+// ============================================================================
+/**
+ * Calculate destination point given start point, distance, and bearing
+ *
+ * This is the inverse of the bearing calculation. Given a starting point,
+ * a distance, and a direction, it calculates where you would end up.
+ *
+ * Formula (spherical Earth):
+ *   lat2 = asin(sin(lat1) × cos(d/R) + cos(lat1) × sin(d/R) × cos(θ))
+ *   lon2 = lon1 + atan2(sin(θ) × sin(d/R) × cos(lat1),
+ *                       cos(d/R) - sin(lat1) × sin(lat2))
+ *
+ * Where:
+ *   - d/R = angular distance (distance / Earth radius)
+ *   - θ = bearing in radians
+ *
+ * RF Planning Usage:
+ *   This is used to project antenna coverage patterns onto the map.
+ *   For each angle around the antenna, calculate signal range, then
+ *   use this function to get the geographic coordinate at that range.
+ *
+ * @param start - Starting position (lat, lng in degrees)
+ * @param distanceKm - Distance to travel in kilometers
+ * @param bearingDeg - Direction to travel in degrees (0 = North, 90 = East)
+ * @returns Destination position (lat, lng in degrees)
+ *
+ * @example
+ * const destination = calculateDestinationPoint(
+ *   { lat: 40.7128, lng: -74.0060 },  // New York
+ *   100,                               // 100 km
+ *   45                                 // Northeast
+ * );
+ * // Returns position ~100km northeast of New York
+ */
+export function calculateDestinationPoint(start, distanceKm, bearingDeg) {
+    // Convert inputs to radians
+    const lat1Rad = start.lat * DEG_TO_RAD;
+    const lng1Rad = start.lng * DEG_TO_RAD;
+    const bearingRad = bearingDeg * DEG_TO_RAD;
+    // Calculate angular distance (distance on sphere)
+    // This converts linear distance to angle subtended at Earth's center
+    const angularDistance = distanceKm / EARTH_RADIUS_KM;
+    // Calculate destination latitude
+    // Formula accounts for spherical geometry - latitude changes based on:
+    // 1. How far north/south we travel (cos component)
+    // 2. Starting latitude and direction (sin component)
+    const lat2Rad = Math.asin(Math.sin(lat1Rad) * Math.cos(angularDistance) +
+        Math.cos(lat1Rad) * Math.sin(angularDistance) * Math.cos(bearingRad));
+    // Calculate destination longitude
+    // Formula accounts for:
+    // 1. Lines of longitude converge at poles (cos(lat) factor)
+    // 2. East-West component of bearing (sin(bearing) factor)
+    const lng2Rad = lng1Rad +
+        Math.atan2(Math.sin(bearingRad) * Math.sin(angularDistance) * Math.cos(lat1Rad), Math.cos(angularDistance) - Math.sin(lat1Rad) * Math.sin(lat2Rad));
+    // Convert back to degrees and normalize longitude to -180 to +180
+    const lat2 = lat2Rad * RAD_TO_DEG;
+    let lng2 = lng2Rad * RAD_TO_DEG;
+    // Normalize longitude to -180 to +180 range
+    lng2 = ((lng2 + 540) % 360) - 180;
+    return { lat: lat2, lng: lng2 };
+}
+// ============================================================================
+// ELEVATION ANGLE CALCULATIONS
+// ============================================================================
+/**
+ * Calculate elevation angle from antenna to target
+ *
+ * Elevation angle is the vertical angle from horizontal plane to target.
+ * This is critical for RF calculations because:
+ * 1. Antenna vertical pattern varies with elevation angle
+ * 2. Mechanical/electrical tilt affects this relationship
+ *
+ * Formula:
+ *   elevation = atan((h_antenna - h_target) / d_horizontal)
+ *
+ * Sign convention:
+ *   - Positive angle = target above antenna (upward tilt needed)
+ *   - Negative angle = target below antenna (downward tilt, typical case)
+ *   - Zero angle = target at same height as antenna
+ *
+ * Typical Values (cellular networks):
+ *   - Antenna at 30m, mobile at 1.5m, distance 1km → elevation ≈ -1.6°
+ *   - Antenna at 30m, mobile at 1.5m, distance 5km → elevation ≈ -0.3°
+ *   - Most cellular targets are within ±10° elevation
+ *
+ * @param antennaPos - Antenna position with height (meters above ground)
+ * @param targetPos - Target position (lat, lng)
+ * @param targetHeight - Target height in meters (default: 1.5m for mobile)
+ * @returns Elevation angle in degrees (negative = below horizon)
+ *
+ * @example
+ * const elevation = calculateElevationAngle(
+ *   { lat: 40.7128, lng: -74.0060, height: 30 },  // 30m antenna
+ *   { lat: 40.7150, lng: -74.0070 },              // Target location
+ *   1.5                                            // 1.5m mobile height
+ * );
+ * // Returns: ~-1.5° (target below antenna)
+ */
+export function calculateElevationAngle(antennaPos, targetPos, targetHeight = 1.5) {
+    // Calculate horizontal distance (ignoring height)
+    const horizontalDistanceKm = calculateDistance(antennaPos, targetPos);
+    const horizontalDistanceMeters = horizontalDistanceKm * 1000;
+    // Calculate height difference (positive = target above antenna)
+    const heightDifferenceMeters = targetHeight - antennaPos.height;
+    // Calculate elevation angle using arctangent
+    // atan gives angle whose tangent is (opposite/adjacent)
+    // opposite = height difference
+    // adjacent = horizontal distance
+    const elevationRad = Math.atan(heightDifferenceMeters / horizontalDistanceMeters);
+    const elevationDeg = elevationRad * RAD_TO_DEG;
+    return elevationDeg;
+}
+// ============================================================================
+// BOUNDING BOX CALCULATIONS
+// ============================================================================
+/**
+ * Calculate bounding box for a square grid around a center point
+ *
+ * Given a center point and a radius, calculates the geographic bounds
+ * (north, south, east, west) that fully contain a square grid.
+ *
+ * This is used to:
+ * 1. Determine grid extents for coverage calculations
+ * 2. Set map viewport to show entire coverage area
+ * 3. Optimize calculations (skip points outside bounds)
+ *
+ * Note: Creates a square box, not a circle, for simplicity
+ *
+ * @param center - Center position (lat, lng)
+ * @param radiusKm - Radius from center in kilometers
+ * @returns Bounding box (north, south, east, west in degrees)
+ */
+export function calculateBounds(center, radiusKm) {
+    // Calculate corner points by projecting radius in cardinal directions
+    const north = calculateDestinationPoint(center, radiusKm, 0); // North (0°)
+    const south = calculateDestinationPoint(center, radiusKm, 180); // South (180°)
+    const east = calculateDestinationPoint(center, radiusKm, 90); // East (90°)
+    const west = calculateDestinationPoint(center, radiusKm, 270); // West (270°)
+    return {
+        north: north.lat,
+        south: south.lat,
+        east: east.lng,
+        west: west.lng
+    };
+}
+/**
+ * Calculate the area of a geographic bounding box
+ *
+ * Approximates area using spherical geometry.
+ * For small areas (< 100 km²), treats as rectangle on flat surface.
+ *
+ * @param bounds - Geographic bounds
+ * @returns Area in square kilometers
+ */
+export function calculateBoundsArea(bounds) {
+    // Calculate north-south distance
+    const nsDistance = calculateDistance({ lat: bounds.south, lng: (bounds.east + bounds.west) / 2 }, { lat: bounds.north, lng: (bounds.east + bounds.west) / 2 });
+    // Calculate east-west distance at center latitude
+    const centerLat = (bounds.north + bounds.south) / 2;
+    const ewDistance = calculateDistance({ lat: centerLat, lng: bounds.west }, { lat: centerLat, lng: bounds.east });
+    // Area = width × height
+    return nsDistance * ewDistance;
+}
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+/**
+ * Normalize angle to 0-360 range
+ *
+ * @param angle - Angle in degrees (any value)
+ * @returns Normalized angle (0-360)
+ */
+export function normalizeAngle(angle) {
+    return ((angle % 360) + 360) % 360;
+}
+/**
+ * Calculate angular difference between two bearings
+ * Always returns the smallest angle between them (0-180)
+ *
+ * @param bearing1 - First bearing in degrees
+ * @param bearing2 - Second bearing in degrees
+ * @returns Angular difference in degrees (0-180)
+ */
+export function angleDifference(bearing1, bearing2) {
+    const diff = Math.abs(bearing1 - bearing2);
+    return diff > 180 ? 360 - diff : diff;
+}
+/**
+ * Check if a point is within a bounding box
+ *
+ * @param point - Position to check
+ * @param bounds - Bounding box
+ * @returns true if point is inside bounds
+ */
+export function isPointInBounds(point, bounds) {
+    return (point.lat >= bounds.south &&
+        point.lat <= bounds.north &&
+        point.lng >= bounds.west &&
+        point.lng <= bounds.east);
+}

package/dist/core/CoverageMap/utils/rfUtils.d.ts

@@ -0,0 +1,329 @@
+/**
+ * RF Utility Functions
+ *
+ * This module provides heavily commented RF (Radio Frequency) calculations:
+ * - dB arithmetic (addition, subtraction, conversion)
+ * - EIRP (Effective Isotropic Radiated Power) calculations
+ * - Link budget calculations
+ * - Power conversions (dBm, watts, dBd, dBi)
+ *
+ * RF calculations are done in dB (decibel) domain because:
+ * 1. Multiplication becomes addition (easier math)
+ * 2. Large dynamic range (can represent 1mW to 1MW easily)
+ * 3. Industry standard
+ */
+/**
+ * Conversion factor between dBd and dBi
+ *
+ * dBd = gain relative to dipole antenna
+ * dBi = gain relative to isotropic antenna (theoretical point source)
+ *
+ * Relationship: dBi = dBd + 2.15
+ *
+ * Example:
+ *   A 10 dBd antenna = 12.15 dBi
+ *   Most commercial specs use dBd, calculations often need dBi
+ */
+export declare const DBD_TO_DBI = 2.15;
+/**
+ * Convert dBm to watts (linear power)
+ *
+ * dBm is power relative to 1 milliwatt on a logarithmic scale:
+ *   P_dBm = 10 × log₁₀(P_mW / 1mW)
+ *
+ * To convert back to watts:
+ *   P_watts = 10^(P_dBm / 10) / 1000
+ *
+ * Common values to remember:
+ *   0 dBm = 1 mW = 0.001 W
+ *   10 dBm = 10 mW = 0.01 W
+ *   20 dBm = 100 mW = 0.1 W
+ *   30 dBm = 1 W
+ *   40 dBm = 10 W
+ *   43 dBm = 20 W (typical cellular base station)
+ *
+ * @param dBm - Power in dBm
+ * @returns Power in watts
+ *
+ * @example
+ * const power = dBmToWatts(43);  // Typical cell site TX power
+ * // Returns: 19.95 watts (≈ 20W)
+ */
+export declare function dBmToWatts(dBm: number): number;
+/**
+ * Convert watts to dBm
+ *
+ * @param watts - Power in watts
+ * @returns Power in dBm
+ *
+ * @example
+ * const dBm = wattsTodBm(20);  // 20 watt transmitter
+ * // Returns: 43.01 dBm
+ */
+export declare function wattsTodBm(watts: number): number;
+/**
+ * Convert dBd to dBi
+ *
+ * dBd = gain relative to half-wave dipole antenna
+ * dBi = gain relative to isotropic radiator
+ *
+ * An isotropic antenna radiates equally in all directions (theoretical).
+ * A dipole has slight directionality, giving it 2.15 dB gain over isotropic.
+ *
+ * Therefore: dBi = dBd + 2.15
+ *
+ * @param dBd - Gain in dBd
+ * @returns Gain in dBi
+ */
+export declare function dBdTodBi(dBd: number): number;
+/**
+ * Convert dBi to dBd
+ *
+ * @param dBi - Gain in dBi
+ * @returns Gain in dBd
+ */
+export declare function dBiTodBd(dBi: number): number;
+/**
+ * Add two power values in dB domain
+ *
+ * IMPORTANT: You cannot just add dB values to combine powers!
+ *
+ * Correct method:
+ * 1. Convert both dB values to linear (watts)
+ * 2. Add the linear values
+ * 3. Convert back to dB
+ *
+ * Formula:
+ *   P_total_dB = 10 × log₁₀(10^(P1_dB/10) + 10^(P2_dB/10))
+ *
+ * Special cases:
+ *   - Two equal powers: P_total = P1 + 3 dB (doubling power = +3 dB)
+ *   - Powers differ by >10 dB: P_total ≈ larger value (small contribution ignored)
+ *
+ * @param dB1 - First power in dB
+ * @param dB2 - Second power in dB
+ * @returns Combined power in dB
+ *
+ * @example
+ * const combined = addPowersdB(20, 20);  // Two 20 dBm sources
+ * // Returns: 23 dBm (not 40!)
+ */
+export declare function addPowersdB(dB1: number, dB2: number): number;
+/**
+ * Subtract two power values in dB domain (for interference calculations)
+ *
+ * This calculates the power remaining after subtracting one power from another.
+ *
+ * Formula:
+ *   P_diff_dB = 10 × log₁₀(10^(P1_dB/10) - 10^(P2_dB/10))
+ *
+ * Note: Returns -Infinity if P2 >= P1 (can't subtract more than you have)
+ *
+ * @param dB1 - First power in dB (larger)
+ * @param dB2 - Second power in dB (smaller)
+ * @returns Difference in dB
+ */
+export declare function subtractPowersdB(dB1: number, dB2: number): number;
+/**
+ * Calculate EIRP (Effective Isotropic Radiated Power)
+ *
+ * EIRP is the apparent power radiated by an antenna in the direction of peak gain.
+ * It combines:
+ * 1. Transmitter power
+ * 2. Cable/connector losses (reduces power)
+ * 3. Antenna gain (increases power in specific direction)
+ *
+ * Formula (in dB domain - simple addition!):
+ *   EIRP = P_tx + G_antenna - L_cable
+ *
+ * Where:
+ *   - P_tx = Transmit power (dBm)
+ *   - G_antenna = Antenna gain (dBi) - must be in dBi, not dBd!
+ *   - L_cable = Cable and connector losses (dB) - positive value
+ *
+ * In linear domain, this would be multiplication/division:
+ *   EIRP = P_tx × G_antenna / L_cable
+ *
+ * Why EIRP matters:
+ *   - Determines maximum signal strength at receiver
+ *   - Regulatory limits often specified as EIRP
+ *   - Used in link budget calculations
+ *
+ * Typical values:
+ *   - Small cell: 30-40 dBm EIRP
+ *   - Macro cell: 50-65 dBm EIRP
+ *   - Microwave link: 40-50 dBm EIRP
+ *
+ * @param txPowerdBm - Transmit power in dBm
+ * @param antennaGaindBi - Antenna gain in dBi (not dBd!)
+ * @param cableLossdB - Cable and connector losses in dB (default: 0.5 dB)
+ * @returns EIRP in dBm
+ *
+ * @example
+ * const eirp = calculateEIRP(43, 15, 1);
+ * // 43 dBm TX power (20W)
+ * // + 15 dBi antenna gain
+ * // - 1 dB cable loss
+ * // = 57 dBm EIRP (500W equivalent isotropic)
+ */
+export declare function calculateEIRP(txPowerdBm: number, antennaGaindBi: number, cableLossdB?: number): number;
+/**
+ * Calculate effective EIRP in a specific direction
+ *
+ * Antennas don't radiate equally in all directions - they have patterns.
+ * This calculates the EIRP in a specific direction by:
+ * 1. Starting with maximum EIRP (boresight direction)
+ * 2. Subtracting the pattern attenuation for the given direction
+ *
+ * Formula:
+ *   EIRP_direction = EIRP_max - Attenuation(angle)
+ *
+ * Where:
+ *   - EIRP_max = Maximum EIRP (boresight)
+ *   - Attenuation(angle) = Pattern loss at specific angle (dB)
+ *
+ * Example:
+ *   - EIRP_max = 60 dBm
+ *   - At 30° off boresight, pattern shows -3 dB
+ *   - EIRP at 30° = 60 - 3 = 57 dBm
+ *
+ * @param maxEIRP - Maximum EIRP (dBm)
+ * @param patternAttenuation - Pattern attenuation at angle (dB, positive value)
+ * @returns Effective EIRP in direction (dBm)
+ */
+export declare function calculateEffectiveEIRP(maxEIRP: number, patternAttenuation: number): number;
+/**
+ * Calculate received signal strength
+ *
+ * This is the fundamental equation for RF coverage prediction:
+ *
+ *   P_received = EIRP - PathLoss + RX_Gain - RX_Losses
+ *
+ * Where (all in dB):
+ *   - EIRP = Effective Isotropic Radiated Power (dBm)
+ *   - PathLoss = Free space or propagation loss (dB) - positive value
+ *   - RX_Gain = Receiver antenna gain (dBi) - usually small for mobiles
+ *   - RX_Losses = Receiver losses, body loss, etc. (dB) - positive value
+ *
+ * For mobile devices:
+ *   - RX_Gain ≈ 0 dBi (omnidirectional antenna)
+ *   - RX_Losses ≈ 3 dB (body loss, hand proximity)
+ *   - Net effect: -3 dB
+ *
+ * Interpretation:
+ *   - P_received > -70 dBm: Excellent signal
+ *   - P_received > -85 dBm: Good signal
+ *   - P_received > -95 dBm: Fair signal (data services OK)
+ *   - P_received > -105 dBm: Poor signal (voice calls only)
+ *   - P_received < -105 dBm: No service
+ *
+ * @param eirp - Effective radiated power in direction (dBm)
+ * @param pathLoss - Path loss in dB (positive value)
+ * @param rxGain - Receiver antenna gain in dBi (default: 0)
+ * @param rxLosses - Receiver losses in dB (default: 3)
+ * @returns Received signal strength in dBm
+ *
+ * @example
+ * const rxPower = calculateReceivedPower(57, 110, 0, 3);
+ * // 57 dBm EIRP
+ * // - 110 dB path loss (1 km at 700 MHz)
+ * // + 0 dBi receiver gain
+ * // - 3 dB receiver losses
+ * // = -56 dBm (excellent signal)
+ */
+export declare function calculateReceivedPower(eirp: number, pathLoss: number, rxGain?: number, rxLosses?: number): number;
+/**
+ * Calculate maximum range for a given signal threshold
+ *
+ * This inverts the link budget equation to find the distance where
+ * received power equals a specific threshold (e.g., -95 dBm).
+ *
+ * Starting from:
+ *   P_rx = EIRP - PathLoss(d)
+ *
+ * Rearranging:
+ *   PathLoss(d) = EIRP - P_rx_threshold
+ *
+ * Then using path loss model (e.g., FSPL):
+ *   FSPL = 32.45 + 20log₁₀(d_km) + 20log₁₀(f_MHz)
+ *
+ * Solving for d:
+ *   d_km = 10^((FSPL - 32.45 - 20log₁₀(f_MHz)) / 20)
+ *
+ * This gives us the theoretical maximum range in ideal conditions.
+ *
+ * @param eirp - Effective radiated power (dBm)
+ * @param frequencyMHz - Frequency in MHz
+ * @param threshold - Minimum received power (dBm), e.g., -95
+ * @param rxGain - Receiver gain (dBi), default: 0
+ * @param rxLosses - Receiver losses (dB), default: 3
+ * @returns Maximum range in kilometers
+ */
+export declare function calculateMaxRange(eirp: number, frequencyMHz: number, threshold: number, rxGain?: number, rxLosses?: number): number;
+/**
+ * Convert antenna pattern attenuation to gain
+ *
+ * Antenna pattern files typically store attenuation values:
+ *   - 0 dB = maximum gain (boresight direction)
+ *   - Positive values = attenuation (less gain)
+ *   - Example: 3 dB attenuation = 3 dB below maximum
+ *
+ * To get actual gain in a direction:
+ *   Gain(angle) = MaxGain - Attenuation(angle)
+ *
+ * @param maxGain - Maximum antenna gain (dBi or dBd)
+ * @param attenuation - Pattern attenuation at angle (dB)
+ * @returns Effective gain at angle
+ *
+ * @example
+ * const gain = attenuationToGain(15, 3);
+ * // 15 dBi max gain
+ * // - 3 dB attenuation at 30°
+ * // = 12 dBi gain at 30°
+ */
+export declare function attenuationToGain(maxGain: number, attenuation: number): number;
+/**
+ * Interpolate antenna pattern value for non-integer angles
+ *
+ * Antenna patterns typically have 360 samples (one per degree).
+ * For angles between samples, use linear interpolation.
+ *
+ * @param pattern - Array of 360 pattern values
+ * @param angle - Angle in degrees (can be non-integer)
+ * @returns Interpolated pattern value
+ */
+export declare function interpolatePattern(pattern: number[], angle: number): number;
+/**
+ * Classify signal quality based on received power
+ *
+ * @param rssi - Received signal strength in dBm
+ * @returns Quality category
+ */
+export declare function classifySignalQuality(rssi: number): 'excellent' | 'good' | 'fair' | 'poor' | 'no-signal';
+/**
+ * Calculate signal-to-noise ratio (SNR)
+ *
+ * SNR = Signal Power - Noise Power (both in dBm)
+ *
+ * Typical noise floor: -100 to -120 dBm depending on bandwidth
+ *
+ * @param signalPower - Signal power in dBm
+ * @param noisePower - Noise power in dBm
+ * @returns SNR in dB
+ */
+export declare function calculateSNR(signalPower: number, noisePower: number): number;
+/**
+ * Calculate thermal noise floor
+ *
+ * Formula: N = -174 + 10log₁₀(BW) + NF
+ *
+ * Where:
+ *   - -174 dBm/Hz is thermal noise density at room temperature
+ *   - BW is bandwidth in Hz
+ *   - NF is receiver noise figure in dB (typically 5-9 dB)
+ *
+ * @param bandwidthHz - Signal bandwidth in Hz
+ * @param noiseFigure - Receiver noise figure in dB (default: 7)
+ * @returns Noise floor in dBm
+ */
+export declare function calculateNoiseFloor(bandwidthHz: number, noiseFigure?: number): number;