@smartnet360/svelte-components 0.0.102 → 0.0.104

package/dist/core/CoverageMap/core/SignalProcessor.js

@@ -0,0 +1,424 @@
+/**
+ * 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 { calculateBearing, calculateElevationAngle, normalizeAngle, angleDifference } from '../utils/geoUtils';
+import { attenuationToGain, interpolatePattern, dBdTodBi, calculateEIRP, calculateEffectiveEIRP } from '../utils/rfUtils';
+// ============================================================================
+// ANTENNA PATTERN PROCESSING
+// ============================================================================
+/**
+ * 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 function getHorizontalAttenuation(pattern, targetBearing, antennaAzimuth) {
+    // Calculate angle relative to antenna main beam
+    // Example: Antenna points North (0°), target at East (90°)
+    //          Relative angle = 90° - 0° = 90°
+    let relativeAngle = targetBearing - antennaAzimuth;
+    // Normalize to 0-360 range
+    relativeAngle = normalizeAngle(relativeAngle);
+    // Look up pattern value (with interpolation for non-integer angles)
+    const attenuation = interpolatePattern(pattern, relativeAngle);
+    return attenuation;
+}
+/**
+ * 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 function getVerticalAttenuation(verticalPattern, elevationAngle, mechanicalTilt, electricalTilt) {
+    // Calculate total tilt (mechanical + electrical)
+    const totalTilt = mechanicalTilt + electricalTilt;
+    // Calculate effective elevation angle accounting for tilt
+    // IMPORTANT: Positive tilt values represent DOWN-TILT (beam pointing downward)
+    // In RF engineering convention: +3° tilt = 3° below horizontal
+    // Since elevation angle is negative when target is below antenna,
+    // and down-tilt makes the beam point more downward (more negative),
+    // we SUBTRACT the tilt to get the effective angle relative to the beam center.
+    //
+    // Example: Target at -3° elevation (below antenna), antenna has 3° downtilt
+    //          Effective angle: -3 - (-3) = 0° (target is on beam center)
+    //          OR: elevationAngle - totalTilt = -3 - 3 = -6°? NO!
+    //
+    // Better explanation:
+    // - Elevation angle: angle from antenna to target (negative = below)
+    // - Tilt: angle beam is pointed down from horizontal (positive = down)
+    // - Beam-relative angle = elevationAngle - (-tilt) = elevationAngle + tilt
+    //
+    // Wait, this is confusing. Let's think physically:
+    // - If antenna points down 3° and target is at -3° elevation, 
+    //   target is exactly on beam center → pattern angle should be 0°
+    // - Current math: -3 + 3 = 0° ✓ CORRECT!
+    //
+    // But the user says positive tilt should point DOWN, which is negative direction.
+    // The confusion is: the pattern is stored relative to the ANTENNA orientation,
+    // not ground. If we tilt antenna down 3°, pattern[0] now points at -3° elevation.
+    //
+    // So for ground-relative elevation angle, we need:
+    // patternAngle = elevationAngle - (-totalTilt) = elevationAngle + totalTilt
+    //
+    // This is already correct! The code was right all along.
+    // The user's concern is valid but the math accounts for it correctly.
+    let effectiveElevation = elevationAngle - totalTilt;
+    // Normalize to 0-360 range (vertical patterns wrap around)
+    // Note: Typically we only use -90° to +90°, but normalization handles edge cases
+    effectiveElevation = normalizeAngle(effectiveElevation);
+    // Look up pattern value
+    const attenuation = interpolatePattern(verticalPattern, effectiveElevation);
+    return attenuation;
+}
+/**
+ * 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 function calculateCombinedGain(antennaPattern, targetBearing, antennaAzimuth, elevationAngle, mechanicalTilt, electricalTilt) {
+    // Get maximum antenna gain in dBi
+    // Antenna specs usually give dBd, need to convert to dBi for EIRP calculations
+    const maxGaindBi = dBdTodBi(antennaPattern.gain_dBd);
+    // Get horizontal attenuation
+    const horizontalAttenuation = getHorizontalAttenuation(antennaPattern.pattern, targetBearing, antennaAzimuth);
+    // Get vertical attenuation
+    const verticalAttenuation = getVerticalAttenuation(antennaPattern.vertical_pattern, elevationAngle, mechanicalTilt, electricalTilt);
+    // Calculate combined gain
+    // Start with maximum gain, subtract attenuations
+    const combinedGain = maxGaindBi - horizontalAttenuation - verticalAttenuation;
+    return combinedGain;
+}
+// ============================================================================
+// SIGNAL STRENGTH CALCULATION
+// ============================================================================
+/**
+ * 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 function calculateSignalStrength(rfParams, targetPosition, pathLoss, options) {
+    // Default receiver characteristics (mobile phone)
+    const rxGain = options?.rxGain ?? 0; // Omnidirectional antenna
+    const rxLosses = options?.rxLosses ?? 3; // Body loss + misc
+    const cableLoss = options?.cableLoss ?? 0.5; // TX side cable loss
+    // Step 1: Calculate geometric parameters
+    // ----------------------------------------
+    // Bearing from antenna to target (0-360°, 0 = North)
+    const bearing = calculateBearing(rfParams.position, targetPosition);
+    // Elevation angle (negative = below antenna, typical case)
+    const elevation = calculateElevationAngle(rfParams.position, targetPosition, 1.5 // Assume mobile at 1.5m height
+    );
+    // Step 2: Calculate antenna gain in direction
+    // --------------------------------------------
+    const antennaGain = calculateCombinedGain(rfParams.antennaPattern, bearing, rfParams.azimuth, elevation, rfParams.mechanicalTilt, rfParams.electricalTilt);
+    // Step 3: Calculate EIRP
+    // -----------------------
+    // EIRP = TX Power + Antenna Gain - Cable Loss
+    const eirp = calculateEIRP(rfParams.txPower, antennaGain, cableLoss);
+    // Step 4: Calculate received power (link budget)
+    // -----------------------------------------------
+    // P_rx = EIRP - Path Loss + RX Gain - RX Losses
+    const receivedPower = eirp - pathLoss + rxGain - rxLosses;
+    return receivedPower;
+}
+// ============================================================================
+// BATCH PROCESSING
+// ============================================================================
+/**
+ * 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 function calculateMultiSectorSignal(sectors, targetPosition, pathLosses) {
+    const signals = {};
+    let dominantSector = null;
+    let dominantSignal = -Infinity;
+    // Calculate signal from each sector
+    for (let i = 0; i < sectors.length; i++) {
+        const sector = sectors[i];
+        const pathLoss = pathLosses[i];
+        const signal = calculateSignalStrength(sector, targetPosition, pathLoss);
+        signals[sector.sectorId] = signal;
+        // Track strongest sector
+        if (signal > dominantSignal) {
+            dominantSignal = signal;
+            dominantSector = sector.sectorId;
+        }
+    }
+    return {
+        signals,
+        dominantSector,
+        dominantSignal
+    };
+}
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+/**
+ * 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 function isInMainLobe(pattern, targetBearing, antennaAzimuth, threshold = 3) {
+    const attenuation = getHorizontalAttenuation(pattern, targetBearing, antennaAzimuth);
+    return attenuation <= threshold;
+}
+/**
+ * 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 function calculateBeamwidth(pattern) {
+    const threshold = 3; // 3 dB = half power
+    // Find all angles where attenuation <= 3 dB
+    const inBeam = [];
+    for (let angle = 0; angle < 360; angle++) {
+        if (pattern[angle] <= threshold) {
+            inBeam.push(angle);
+        }
+    }
+    if (inBeam.length === 0)
+        return 0;
+    // Handle wraparound (e.g., 350° to 10°)
+    // If beam crosses 0°/360°, angles will be discontinuous
+    // For simplicity, return count of angles (works for most cases)
+    return inBeam.length;
+}
+/**
+ * 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 function calculateFrontToBackRatio(pattern) {
+    // Front = 0° (main beam)
+    const frontAttenuation = pattern[0];
+    // Back = 180° (opposite direction)
+    const backAttenuation = pattern[180];
+    // F/B ratio = difference in attenuation
+    // Higher back attenuation = better F/B ratio
+    return backAttenuation - frontAttenuation;
+}

package/dist/core/CoverageMap/data/AntennaStore.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Antenna Store
+ *
+ * This module manages antenna pattern data for the coverage calculator.
+ * It integrates with the existing antenna pattern database and provides
+ * a clean API for:
+ * - Loading antenna data
+ * - Caching frequently used antennas
+ * - Converting database format to calculation format
+ * - Managing antenna library
+ *
+ * Integration with existing system:
+ * - Reuses antenna-pattern database (Dexie)
+ * - Compatible with MSI file format
+ * - Shares antenna data across components
+ */
+import type { AntennaPattern } from '../types';
+/**
+ * Antenna Store - Manages antenna pattern data
+ *
+ * Provides caching and convenience methods for accessing
+ * antenna data needed for coverage calculations.
+ *
+ * Features:
+ * - Automatic database connection
+ * - In-memory caching (reduces DB queries)
+ * - Format conversion (DB → AntennaPattern type)
+ * - Search and filtering
+ */
+export declare class AntennaStore {
+    private cache;
+    private initialized;
+    /**
+     * Initialize the antenna store
+     *
+     * Checks database connection and loads frequently used antennas.
+     * Call this once before using other methods.
+     *
+     * @returns Promise resolving to true if initialized successfully
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Get antenna by name
+     *
+     * Retrieves antenna pattern from database (or cache if available).
+     * Returns null if antenna not found.
+     *
+     * @param name - Antenna name (e.g., "ADU4515R17v06")
+     * @param tilt - Electrical tilt (e.g., "3", "6", "9")
+     * @returns Antenna pattern or null
+     *
+     * @example
+     * const antenna = await store.getAntenna("ADU4515R17v06", "3");
+     * if (antenna) {
+     *   console.log(`Gain: ${antenna.gain_dBd} dBd`);
+     * }
+     */
+    getAntenna(name: string, tilt: string): Promise<AntennaPattern | null>;
+    /**
+     * Get antenna by ID
+     *
+     * @param id - Database ID
+     * @returns Antenna pattern or null
+     */
+    getAntennaById(id: number): Promise<AntennaPattern | null>;
+    /**
+     * List all available antennas
+     *
+     * Returns a list of antenna models (without tilt variants).
+     * Useful for populating dropdown menus.
+     *
+     * @returns Array of unique antenna names
+     */
+    listAntennaModels(): Promise<string[]>;
+    /**
+     * Get available tilts for an antenna model
+     *
+     * @param name - Antenna model name
+     * @returns Array of available tilts (e.g., ["0", "3", "6", "9"])
+     */
+    getAvailableTilts(name: string): Promise<string[]>;
+    /**
+     * Search antennas by criteria
+     *
+     * @param criteria - Search criteria
+     * @returns Array of matching antennas
+     *
+     * @example
+     * const antennas = await store.searchAntennas({
+     *   frequencyMin: 1700,
+     *   frequencyMax: 1900,
+     *   gainMin: 15
+     * });
+     */
+    searchAntennas(criteria: {
+        namePattern?: string;
+        frequencyMin?: number;
+        frequencyMax?: number;
+        gainMin?: number;
+        gainMax?: number;
+    }): Promise<AntennaPattern[]>;
+    /**
+     * Clear cache
+     *
+     * Useful if antenna data is updated in database.
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     *
+     * @returns Cache info
+     */
+    getCacheStats(): {
+        size: number;
+        entries: string[];
+    };
+    /**
+     * Convert database antenna format to AntennaPattern type
+     *
+     * The database stores antennas in one format (from MSI files),
+     * but the coverage calculator needs a specific format.
+     * This function does the conversion.
+     *
+     * @param dbAntenna - Antenna from database
+     * @returns AntennaPattern for coverage calculator
+     */
+    private convertToAntennaPattern;
+    /**
+     * Ensure pattern has exactly 360 values
+     *
+     * Some antenna files might have incomplete data.
+     * This function ensures we always have 360 values.
+     *
+     * @param pattern - Raw pattern data
+     * @returns Pattern with 360 values
+     */
+    private ensurePattern;
+}
+/**
+ * Global antenna store instance
+ *
+ * Use this instead of creating new instances.
+ * Ensures cache is shared across the application.
+ *
+ * @example
+ * import { antennaStore } from './AntennaStore';
+ *
+ * await antennaStore.initialize();
+ * const antenna = await antennaStore.getAntenna("ADU4515R17v06", "3");
+ */
+export declare const antennaStore: AntennaStore;
+/**
+ * Load antenna for a sector configuration
+ *
+ * Convenience function that loads the correct antenna
+ * based on sector configuration.
+ *
+ * @param sectorConfig - Sector configuration (must include antenna name and tilt)
+ * @returns AntennaPattern or null
+ */
+export declare function loadAntennaForSector(sectorConfig: {
+    antenna?: string;
+    antennaModel?: string;
+    electricalTilt: number | string;
+}): Promise<AntennaPattern | null>;