@smartnet360/svelte-components 0.0.101 → 0.0.103

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

@@ -0,0 +1,434 @@
+/**
+ * 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
+ */
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/**
+ * 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 const DBD_TO_DBI = 2.15;
+// ============================================================================
+// dB CONVERSIONS AND ARITHMETIC
+// ============================================================================
+/**
+ * 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 function dBmToWatts(dBm) {
+    // Step 1: Convert dBm to milliwatts using inverse log
+    const milliwatts = Math.pow(10, dBm / 10);
+    // Step 2: Convert milliwatts to watts
+    const watts = milliwatts / 1000;
+    return watts;
+}
+/**
+ * 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 function wattsTodBm(watts) {
+    // Convert watts to milliwatts
+    const milliwatts = watts * 1000;
+    // Convert to dBm using logarithm
+    const dBm = 10 * Math.log10(milliwatts);
+    return dBm;
+}
+/**
+ * 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 function dBdTodBi(dBd) {
+    return dBd + DBD_TO_DBI;
+}
+/**
+ * Convert dBi to dBd
+ *
+ * @param dBi - Gain in dBi
+ * @returns Gain in dBd
+ */
+export function dBiTodBd(dBi) {
+    return dBi - DBD_TO_DBI;
+}
+/**
+ * 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 function addPowersdB(dB1, dB2) {
+    // Convert to linear scale
+    const linear1 = Math.pow(10, dB1 / 10);
+    const linear2 = Math.pow(10, dB2 / 10);
+    // Add in linear domain
+    const totalLinear = linear1 + linear2;
+    // Convert back to dB
+    const totaldB = 10 * Math.log10(totalLinear);
+    return totaldB;
+}
+/**
+ * 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 function subtractPowersdB(dB1, dB2) {
+    const linear1 = Math.pow(10, dB1 / 10);
+    const linear2 = Math.pow(10, dB2 / 10);
+    if (linear1 <= linear2) {
+        return -Infinity; // Can't subtract more than we have
+    }
+    const diffLinear = linear1 - linear2;
+    const diffdB = 10 * Math.log10(diffLinear);
+    return diffdB;
+}
+// ============================================================================
+// EIRP CALCULATIONS
+// ============================================================================
+/**
+ * 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 function calculateEIRP(txPowerdBm, antennaGaindBi, cableLossdB = 0.5) {
+    // In dB domain, this is simple addition/subtraction
+    const eirp = txPowerdBm + antennaGaindBi - cableLossdB;
+    return eirp;
+}
+/**
+ * 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 function calculateEffectiveEIRP(maxEIRP, patternAttenuation) {
+    return maxEIRP - patternAttenuation;
+}
+// ============================================================================
+// LINK BUDGET CALCULATIONS
+// ============================================================================
+/**
+ * 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 function calculateReceivedPower(eirp, pathLoss, rxGain = 0, rxLosses = 3) {
+    // Link budget equation in dB domain
+    const receivedPower = eirp - pathLoss + rxGain - rxLosses;
+    return receivedPower;
+}
+/**
+ * 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 function calculateMaxRange(eirp, frequencyMHz, threshold, rxGain = 0, rxLosses = 3) {
+    // Calculate allowed path loss
+    // This is how much loss we can tolerate before signal drops below threshold
+    const allowedPathLoss = eirp - threshold + rxGain - rxLosses;
+    // Use FSPL model: FSPL = 32.45 + 20log₁₀(d_km) + 20log₁₀(f_MHz)
+    // Solve for d_km:
+    const frequencyTerm = 20 * Math.log10(frequencyMHz);
+    const exponent = (allowedPathLoss - 32.45 - frequencyTerm) / 20;
+    const maxRangeKm = Math.pow(10, exponent);
+    return maxRangeKm;
+}
+// ============================================================================
+// ANTENNA PATTERN UTILITIES
+// ============================================================================
+/**
+ * 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 function attenuationToGain(maxGain, attenuation) {
+    return maxGain - attenuation;
+}
+/**
+ * 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 function interpolatePattern(pattern, angle) {
+    // Normalize angle to 0-360 range
+    angle = ((angle % 360) + 360) % 360;
+    // Get floor and ceiling indices
+    const idx1 = Math.floor(angle);
+    const idx2 = Math.ceil(angle) % 360;
+    // If angle is integer, return exact value
+    if (idx1 === idx2) {
+        return pattern[idx1];
+    }
+    // Linear interpolation
+    const fraction = angle - idx1;
+    const value1 = pattern[idx1];
+    const value2 = pattern[idx2];
+    return value1 + (value2 - value1) * fraction;
+}
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+/**
+ * Classify signal quality based on received power
+ *
+ * @param rssi - Received signal strength in dBm
+ * @returns Quality category
+ */
+export function classifySignalQuality(rssi) {
+    if (rssi >= -70)
+        return 'excellent';
+    if (rssi >= -85)
+        return 'good';
+    if (rssi >= -95)
+        return 'fair';
+    if (rssi >= -105)
+        return 'poor';
+    return '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 function calculateSNR(signalPower, noisePower) {
+    return signalPower - noisePower;
+}
+/**
+ * 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 function calculateNoiseFloor(bandwidthHz, noiseFigure = 7) {
+    const thermalNoise = -174; // dBm/Hz
+    const bandwidthTerm = 10 * Math.log10(bandwidthHz);
+    return thermalNoise + bandwidthTerm + noiseFigure;
+}

package/dist/core/CoverageMap/visualization/ColorSchemes.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Color Schemes
+ *
+ * This module defines color schemes for coverage visualization.
+ * Supports multiple visualization styles:
+ * - Heatmap: Gradient from strong to weak signal
+ * - Categorical: Discrete quality levels
+ * - Single color: Opacity-based (for sector identification)
+ *
+ * All colors designed to be:
+ * - Colorblind-friendly (where possible)
+ * - Print-friendly
+ * - Intuitive (red = strong, blue = weak for heatmap)
+ */
+import type { SignalQuality, SignalThresholds } from '../types';
+export interface ColorStop {
+    value: number;
+    color: string;
+}
+export interface ColorScheme {
+    name: string;
+    description: string;
+    stops: ColorStop[];
+    noSignalColor: string;
+}
+/**
+ * Heatmap - Red to Blue gradient
+ *
+ * Classic heatmap where:
+ * - Red = Excellent signal (hot)
+ * - Orange/Yellow = Good signal (warm)
+ * - Green = Fair signal (cool)
+ * - Blue = Poor signal (cold)
+ * - Gray = No signal
+ *
+ * This is intuitive for most users.
+ */
+export declare const HEATMAP_RED_BLUE: ColorScheme;
+/**
+ * Heatmap - Green to Red (inverted)
+ *
+ * Alternative where:
+ * - Green = Excellent (good status)
+ * - Yellow = Fair (warning)
+ * - Red = Poor (problem)
+ *
+ * More intuitive for traffic light metaphor.
+ */
+export declare const HEATMAP_GREEN_RED: ColorScheme;
+/**
+ * Categorical - Discrete quality levels
+ *
+ * Uses distinct colors for each quality level.
+ * No gradients - clear boundaries.
+ * Good for presentations and reports.
+ */
+export declare const CATEGORICAL: ColorScheme;
+/**
+ * Viridis-inspired (colorblind-friendly)
+ *
+ * Based on matplotlib's viridis colormap.
+ * Optimized for colorblind users and grayscale printing.
+ */
+export declare const VIRIDIS: ColorScheme;
+/**
+ * Plasma-inspired (high contrast)
+ *
+ * High contrast colormap for visibility.
+ */
+export declare const PLASMA: ColorScheme;
+/**
+ * All available color schemes
+ */
+export declare const COLOR_SCHEMES: Record<string, ColorScheme>;
+/**
+ * Default color scheme
+ */
+export declare const DEFAULT_COLOR_SCHEME: ColorScheme;
+/**
+ * Interpolate color for a specific signal strength
+ *
+ * Uses linear interpolation between color stops to create
+ * smooth gradients.
+ *
+ * Process:
+ * 1. Find two nearest color stops
+ * 2. Calculate interpolation factor
+ * 3. Interpolate RGB components
+ * 4. Convert back to hex
+ *
+ * @param signalDbm - Signal strength in dBm
+ * @param scheme - Color scheme to use
+ * @returns Hex color string
+ *
+ * @example
+ * const color = interpolateColor(-75, HEATMAP_RED_BLUE);
+ * // Returns color between -70 (orange-red) and -80 (orange)
+ * // e.g., "#FF7400"
+ */
+export declare function interpolateColor(signalDbm: number, scheme: ColorScheme): string;
+/**
+ * Get color for categorical quality level
+ *
+ * Returns discrete color based on quality level without interpolation.
+ *
+ * @param quality - Signal quality level
+ * @param scheme - Color scheme (optional, defaults to categorical)
+ * @returns Hex color string
+ */
+export declare function getCategoricalColor(quality: SignalQuality, scheme?: ColorScheme): string;
+/**
+ * Get color based on signal thresholds
+ *
+ * Convenience function that combines threshold checking and coloring.
+ *
+ * @param signalDbm - Signal strength in dBm
+ * @param thresholds - Signal quality thresholds
+ * @param scheme - Color scheme to use
+ * @returns Hex color string
+ */
+export declare function getColorForSignal(signalDbm: number, thresholds: SignalThresholds, scheme?: ColorScheme): string;
+/**
+ * Add opacity to hex color
+ *
+ * Converts hex to rgba with specified opacity.
+ *
+ * @param hex - Hex color
+ * @param opacity - Opacity (0-1)
+ * @returns RGBA color string
+ *
+ * @example
+ * const semi = addOpacity("#FF0000", 0.5);
+ * // Returns: "rgba(255, 0, 0, 0.5)"
+ */
+export declare function addOpacity(hex: string, opacity: number): string;
+/**
+ * Create legend entries for a color scheme
+ *
+ * Generates legend data for UI display.
+ *
+ * @param scheme - Color scheme
+ * @param thresholds - Signal thresholds
+ * @returns Array of legend entries
+ */
+export declare function createLegend(scheme: ColorScheme, thresholds: SignalThresholds): Array<{
+    label: string;
+    color: string;
+    range: string;
+}>;