@smartnet360/svelte-components 0.0.101 → 0.0.103

package/dist/core/CoverageMap/core/SignalProcessor.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Signal Processor
+ *
+ * This module processes antenna patterns and calculates signal strength
+ * in specific directions, accounting for:
+ * - Horizontal antenna pattern (azimuth plane)
+ * - Vertical antenna pattern (elevation plane)
+ * - Mechanical tilt (physical antenna tilt)
+ * - Electrical tilt (built into antenna design)
+ * - Combined 3D antenna pattern
+ *
+ * The signal processor is the bridge between:
+ * - Antenna pattern data (stored as attenuation values)
+ * - Geographic calculations (angles, distances)
+ * - RF link budget (EIRP, path loss, received power)
+ */
+import type { AntennaPattern, Position2D, RFParameters } from '../types';
+/**
+ * Get horizontal pattern attenuation for a specific azimuth angle
+ *
+ * The horizontal pattern describes how antenna gain varies in the
+ * azimuth plane (looking down from above). This is critical for
+ * determining coverage in different directions.
+ *
+ * Pattern interpretation:
+ *   - 0° = main beam direction (maximum gain, 0 dB attenuation)
+ *   - Positive angles = rotation clockwise from main beam
+ *   - Pattern stored as attenuation values (0 = max, higher = weaker)
+ *
+ * Process:
+ * 1. Calculate relative angle (target bearing - antenna azimuth)
+ * 2. Normalize to 0-360° range
+ * 3. Look up attenuation from pattern array
+ * 4. Interpolate if angle is non-integer
+ *
+ * @param pattern - Horizontal antenna pattern (360 values)
+ * @param targetBearing - Bearing to target (0-360°, 0 = North)
+ * @param antennaAzimuth - Antenna pointing direction (0-360°, 0 = North)
+ * @returns Attenuation in dB (positive value, 0 = maximum gain direction)
+ *
+ * @example
+ * // Antenna pointing North (0°), target to Northeast (45°)
+ * const atten = getHorizontalAttenuation(pattern, 45, 0);
+ * // Returns pattern[45], e.g., 3 dB attenuation
+ * // Meaning: 3 dB less gain than main beam direction
+ */
+export declare function getHorizontalAttenuation(pattern: number[], targetBearing: number, antennaAzimuth: number): number;
+/**
+ * Get vertical pattern attenuation for a specific elevation angle
+ *
+ * The vertical pattern describes how antenna gain varies in the
+ * elevation plane (looking from the side). This is critical for:
+ * - Understanding coverage at different distances
+ * - Applying mechanical and electrical tilt
+ * - Optimizing coverage vs interference
+ *
+ * Elevation angle sign convention:
+ *   - Negative = below horizon (typical for cellular)
+ *   - Zero = horizontal
+ *   - Positive = above horizon
+ *
+ * Tilt application:
+ *   - Mechanical tilt: Physical antenna rotation (tilts entire pattern)
+ *   - Electrical tilt: Phase shift between elements (tilts beam electronically)
+ *   - Total tilt = mechanical + electrical
+ *
+ * Why tilt matters:
+ *   - 0° tilt: Maximum range, but strong interference to neighbors
+ *   - 6° tilt: Focuses energy closer, reduces interference
+ *   - 12° tilt: Short range, minimal interference (urban/dense areas)
+ *
+ * Pattern interpretation:
+ *   - Vertical patterns typically stored with 0° = horizon
+ *   - Need to account for both elevation angle AND tilt
+ *   - Pattern lookup angle = elevation + total_tilt
+ *
+ * @param verticalPattern - Vertical antenna pattern (360 values)
+ * @param elevationAngle - Elevation angle to target (degrees, negative = below)
+ * @param mechanicalTilt - Physical antenna tilt (degrees, positive = downward)
+ * @param electricalTilt - Electrical tilt from antenna specs (degrees, positive = downward)
+ * @returns Attenuation in dB (positive value)
+ *
+ * @example
+ * // Target 2° below antenna, 3° mechanical + 3° electrical tilt
+ * const atten = getVerticalAttenuation(pattern, -2, 3, 3);
+ * // Effective angle: -2 + 3 + 3 = 4°
+ * // Returns pattern[4], e.g., 1 dB attenuation
+ */
+export declare function getVerticalAttenuation(verticalPattern: number[], elevationAngle: number, mechanicalTilt: number, electricalTilt: number): number;
+/**
+ * Calculate combined 3D antenna gain
+ *
+ * Antennas are 3D structures, so we need to combine:
+ * 1. Horizontal pattern (azimuth variation)
+ * 2. Vertical pattern (elevation variation)
+ *
+ * Combination methods:
+ *
+ * Method 1: Add attenuations (conservative, used here)
+ *   Total_Attenuation = H_Attenuation + V_Attenuation
+ *   This assumes patterns are independent (reasonable approximation)
+ *
+ * Method 2: Multiply field patterns (more accurate but complex)
+ *   Would require field pattern data (not just power patterns)
+ *
+ * Why Method 1 works:
+ *   - In dB domain, attenuation addition = power multiplication
+ *   - For most cellular antennas, H and V patterns are ~independent
+ *   - Error typically < 1 dB compared to measured 3D patterns
+ *
+ * Process:
+ * 1. Get maximum antenna gain (from specs)
+ * 2. Get horizontal attenuation at target bearing
+ * 3. Get vertical attenuation at target elevation
+ * 4. Combined gain = max_gain - h_atten - v_atten
+ *
+ * @param antennaPattern - Complete antenna pattern data
+ * @param targetBearing - Bearing to target (0-360°)
+ * @param antennaAzimuth - Antenna pointing direction (0-360°)
+ * @param elevationAngle - Elevation angle to target (degrees)
+ * @param mechanicalTilt - Physical tilt (degrees)
+ * @param electricalTilt - Electrical tilt (degrees)
+ * @returns Combined antenna gain in direction (dBi)
+ *
+ * @example
+ * const gain = calculateCombinedGain(
+ *   antenna,     // 15 dBd max gain antenna
+ *   45,          // Target bearing: 45° (NE)
+ *   0,           // Antenna points: 0° (N)
+ *   -2,          // Target elevation: -2° (below)
+ *   3,           // Mechanical tilt: 3°
+ *   3            // Electrical tilt: 3°
+ * );
+ * // H pattern at 45°: -3 dB
+ * // V pattern at -2+6=-4°: -1 dB
+ * // Max gain: 15 dBd = 17.15 dBi
+ * // Combined: 17.15 - 3 - 1 = 13.15 dBi
+ */
+export declare function calculateCombinedGain(antennaPattern: AntennaPattern, targetBearing: number, antennaAzimuth: number, elevationAngle: number, mechanicalTilt: number, electricalTilt: number): number;
+/**
+ * Calculate signal strength at a specific point
+ *
+ * This is the core function that brings everything together:
+ * 1. Calculate geometry (distance, bearing, elevation)
+ * 2. Determine antenna gain in direction
+ * 3. Calculate EIRP (TX power + antenna gain)
+ * 4. Apply path loss
+ * 5. Account for receiver characteristics
+ *
+ * Link budget equation (dB domain):
+ *   P_rx = EIRP - PathLoss + RX_Gain - RX_Losses
+ *
+ * Where:
+ *   - EIRP = TX_Power + Antenna_Gain(direction) - Cable_Loss
+ *   - PathLoss = f(distance, frequency, environment)
+ *   - RX_Gain = Receiver antenna gain (≈0 dBi for mobile)
+ *   - RX_Losses = Body loss, cable loss, etc. (≈3 dB for mobile)
+ *
+ * For mobile devices:
+ *   - Omnidirectional antenna (0 dBi gain)
+ *   - Body loss when held to head (3 dB)
+ *   - Net effect: -3 dB
+ *
+ * Signal interpretation:
+ *   -70 dBm or better:  Excellent (max throughput)
+ *   -85 dBm or better:  Good (high throughput)
+ *   -95 dBm or better:  Fair (medium throughput)
+ *   -105 dBm or better: Poor (low throughput, voice OK)
+ *   Worse than -105:    No service
+ *
+ * @param rfParams - Complete RF parameter set (antenna, position, power, etc.)
+ * @param targetPosition - Geographic position to calculate signal at
+ * @param pathLoss - Path loss in dB (from path loss model)
+ * @param options - Receiver characteristics (gain, losses)
+ * @returns Received signal strength in dBm
+ *
+ * @example
+ * const rssi = calculateSignalStrength(
+ *   {
+ *     position: { lat: 40.7128, lng: -74.0060, height: 30 },
+ *     azimuth: 45,
+ *     mechanicalTilt: 3,
+ *     electricalTilt: 3,
+ *     txPower: 43,
+ *     frequency: 1800,
+ *     antennaPattern: myAntenna
+ *   },
+ *   { lat: 40.7150, lng: -74.0070 },
+ *   110  // 110 dB path loss at 1 km
+ * );
+ * // Process:
+ * // 1. Calculate bearing: ~45° (matches antenna)
+ * // 2. Calculate elevation: -1.5° (below antenna)
+ * // 3. Antenna gain: 15 dBi - 0 dB (h) - 1 dB (v) = 14 dBi
+ * // 4. EIRP: 43 + 14 - 0.5 = 56.5 dBm
+ * // 5. RX power: 56.5 - 110 + 0 - 3 = -56.5 dBm (excellent!)
+ */
+export declare function calculateSignalStrength(rfParams: RFParameters, targetPosition: Position2D, pathLoss: number, options?: {
+    rxGain?: number;
+    rxLosses?: number;
+    cableLoss?: number;
+}): number;
+/**
+ * Calculate signal strength for multiple sectors at once
+ *
+ * Common scenario: A cell site has 3 sectors (Alpha, Beta, Gamma),
+ * each covering 120°. We want to know signal from all sectors at a point.
+ *
+ * This function:
+ * 1. Calculates signal from each sector independently
+ * 2. Returns results as an object keyed by sector ID
+ * 3. Identifies which sector provides strongest signal
+ *
+ * Use cases:
+ *   - Multi-sector cell sites
+ *   - Handover zone analysis
+ *   - Interference calculations
+ *   - Dominant server prediction
+ *
+ * @param sectors - Array of RF parameter sets (one per sector)
+ * @param targetPosition - Position to calculate signal at
+ * @param pathLosses - Path loss for each sector (must match order)
+ * @returns Object with signal strength from each sector plus dominant sector
+ *
+ * @example
+ * const result = calculateMultiSectorSignal(
+ *   [alphaParams, betaParams, gammaParams],
+ *   { lat: 40.7150, lng: -74.0070 },
+ *   [110, 110, 110]
+ * );
+ * // Returns:
+ * // {
+ * //   signals: { 'alpha': -60, 'beta': -70, 'gamma': -85 },
+ * //   dominantSector: 'alpha',
+ * //   dominantSignal: -60
+ * // }
+ */
+export declare function calculateMultiSectorSignal(sectors: Array<RFParameters & {
+    sectorId: string;
+}>, targetPosition: Position2D, pathLosses: number[]): {
+    signals: Record<string, number>;
+    dominantSector: string | null;
+    dominantSignal: number;
+};
+/**
+ * Check if a target is within antenna's main lobe
+ *
+ * Main lobe = directions where antenna provides significant gain
+ * Typically defined as attenuation < 3 dB (half-power beamwidth)
+ *
+ * @param pattern - Antenna pattern
+ * @param targetBearing - Bearing to target
+ * @param antennaAzimuth - Antenna pointing direction
+ * @param threshold - Attenuation threshold in dB (default: 3 dB)
+ * @returns true if target is in main lobe
+ */
+export declare function isInMainLobe(pattern: number[], targetBearing: number, antennaAzimuth: number, threshold?: number): boolean;
+/**
+ * Calculate half-power beamwidth from antenna pattern
+ *
+ * Beamwidth is the angular width where gain is within 3 dB of maximum.
+ * Typical values:
+ *   - Omnidirectional: 360°
+ *   - Wide beam: 90-120°
+ *   - Sector antenna: 60-90°
+ *   - Narrow beam: 30-60°
+ *   - Pencil beam: < 30°
+ *
+ * @param pattern - Horizontal antenna pattern
+ * @returns Beamwidth in degrees
+ */
+export declare function calculateBeamwidth(pattern: number[]): number;
+/**
+ * Estimate front-to-back ratio
+ *
+ * F/B ratio compares gain in main beam direction vs opposite direction.
+ * Higher = better (less backside radiation)
+ *
+ * Typical values:
+ *   - Omnidirectional: 0 dB (equal all around)
+ *   - Basic sector: 15-20 dB
+ *   - Good sector: 20-25 dB
+ *   - Excellent sector: > 25 dB
+ *
+ * @param pattern - Horizontal antenna pattern
+ * @returns Front-to-back ratio in dB
+ */
+export declare function calculateFrontToBackRatio(pattern: number[]): number;