@smartnet360/svelte-components 0.0.101 → 0.0.103

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

@@ -0,0 +1,252 @@
+/**
+ * Coverage Map System - Type Definitions
+ *
+ * This file contains all TypeScript interfaces and types for the coverage calculation system.
+ * Designed to be AI-ready with structured outputs for future ChatGPT integration.
+ */
+/**
+ * 2D Geographic position (latitude, longitude)
+ */
+export interface Position2D {
+    lat: number;
+    lng: number;
+}
+/**
+ * 3D Position with height above ground
+ */
+export interface Position3D extends Position2D {
+    height: number;
+}
+/**
+ * Geographic bounds (bounding box)
+ */
+export interface GeoBounds {
+    north: number;
+    south: number;
+    east: number;
+    west: number;
+}
+/**
+ * Antenna radiation pattern data
+ * Pattern arrays contain 360 values (one per degree, 0-359)
+ * Values represent attenuation in dB (0 = max gain, higher = more attenuation)
+ */
+export interface AntennaPattern {
+    name: string;
+    model: string;
+    frequency: number;
+    gain_dBd: number;
+    gain_dBi: number;
+    pattern: number[];
+    vertical_pattern: number[];
+    availableTilts: string[];
+    beamwidth_horizontal?: number;
+    beamwidth_vertical?: number;
+}
+/**
+ * RF Parameters for a single antenna/sector
+ */
+export interface RFParameters {
+    position: Position3D;
+    azimuth: number;
+    mechanicalTilt: number;
+    electricalTilt: number;
+    txPower: number;
+    frequency: number;
+    antennaPattern: AntennaPattern;
+}
+/**
+ * Sector configuration (extends RFParameters with metadata)
+ */
+export interface SectorConfig extends RFParameters {
+    sectorId: string;
+    sectorName: string;
+    enabled: boolean;
+    color: string;
+    technology?: string;
+    band?: string;
+}
+/**
+ * Site configuration (collection of sectors)
+ */
+export interface SiteConfiguration {
+    siteId: string;
+    siteName: string;
+    position: Position2D;
+    sectors: SectorConfig[];
+}
+/**
+ * Path loss model types
+ */
+export type PathLossModel = 'free-space' | 'hata-urban' | 'hata-suburban' | 'cost231';
+/**
+ * Grid calculation settings
+ */
+export interface GridSettings {
+    centerPosition: Position2D;
+    cellSizeMeters: number;
+    maxRadiusKm: number;
+    pathLossModel: PathLossModel;
+}
+/**
+ * Signal strength thresholds for coverage zones
+ */
+export interface SignalThresholds {
+    excellent: number;
+    good: number;
+    fair: number;
+    edge: number;
+}
+/**
+ * Coverage calculation configuration
+ */
+export interface CoverageConfig {
+    site: SiteConfiguration;
+    gridSettings: GridSettings;
+    signalThresholds: SignalThresholds;
+    calculateInterference: boolean;
+}
+/**
+ * Signal quality level
+ */
+export type SignalQuality = 'excellent' | 'good' | 'fair' | 'poor' | 'no-signal';
+/**
+ * Single grid cell result
+ */
+export interface GridCell {
+    position: Position2D;
+    signalStrength: number;
+    quality: SignalQuality;
+    dominantSector?: string;
+    sectors: {
+        [sectorId: string]: number;
+    };
+    color: string;
+}
+/**
+ * Complete coverage grid
+ */
+export interface CoverageGrid {
+    centerPosition: Position2D;
+    cellSizeMeters: number;
+    bounds: GeoBounds;
+    rows: number;
+    cols: number;
+    cells: GridCell[][];
+    stats: CoverageStats;
+}
+/**
+ * Coverage statistics and metrics
+ */
+export interface CoverageStats {
+    totalAreaKm2: number;
+    coveredAreaKm2: number;
+    coveragePercentage: number;
+    excellentAreaKm2: number;
+    goodAreaKm2: number;
+    fairAreaKm2: number;
+    poorAreaKm2: number;
+    sectorStats: {
+        [sectorId: string]: {
+            maxRangeKm: number;
+            avgSignalDbm: number;
+            coverageAreaKm2: number;
+        };
+    };
+    overlapAreas?: {
+        sectors: string[];
+        areaKm2: number;
+        avgSignalDifference: number;
+    }[];
+}
+/**
+ * Coverage calculation result (AI-ready format)
+ */
+export interface CoverageResult {
+    config: CoverageConfig;
+    grid: CoverageGrid;
+    timestamp: Date;
+    calculationTimeMs: number;
+    summary: {
+        description: string;
+        issues: string[];
+        metrics: Record<string, number>;
+    };
+}
+/**
+ * Calculation progress callback
+ */
+export interface CalculationProgress {
+    stage: 'initializing' | 'calculating' | 'analyzing' | 'complete';
+    progress: number;
+    message: string;
+    cellsProcessed?: number;
+    totalCells?: number;
+}
+export type ProgressCallback = (progress: CalculationProgress) => void;
+/**
+ * AI analysis request
+ */
+export interface AIAnalysisRequest {
+    coverageResult: CoverageResult;
+    analysisType: 'coverage-quality' | 'optimization' | 'anomaly' | 'comparison' | 'report';
+    context?: Record<string, any>;
+}
+/**
+ * AI analysis response
+ */
+export interface AIAnalysisResponse {
+    type: string;
+    summary: string;
+    recommendations: AIRecommendation[];
+    insights: string[];
+    confidence: number;
+}
+/**
+ * AI recommendation
+ */
+export interface AIRecommendation {
+    sectorId: string;
+    parameter: 'azimuth' | 'tilt' | 'power' | 'height';
+    currentValue: number;
+    suggestedValue: number;
+    reasoning: string;
+    expectedImprovement: string;
+    priority: 'high' | 'medium' | 'low';
+}
+/**
+ * AI tool-callable function signature
+ * These functions will be exposed to ChatGPT for AI integration
+ */
+export interface AIToolFunction {
+    name: string;
+    description: string;
+    parameters: Record<string, any>;
+    execute: (params: any) => Promise<any>;
+}
+/**
+ * Color scheme for heatmap
+ */
+export type ColorScheme = 'heatmap' | 'categorical' | 'single-color';
+/**
+ * Visualization options
+ */
+export interface VisualizationOptions {
+    colorScheme: ColorScheme;
+    opacity: number;
+    showAntennaMarker: boolean;
+    showBeamDirection: boolean;
+    showDistanceRings: boolean;
+    showAzimuthLabels: boolean;
+    showSignalValues: boolean;
+}
+/**
+ * Map integration interface
+ * Allows component to work with or without a map instance
+ */
+export interface MapIntegration {
+    mapInstance?: any;
+    addLayer: (layer: any) => void;
+    removeLayer: (layer: any) => void;
+    fitBounds: (bounds: GeoBounds) => void;
+}

package/dist/core/CoverageMap/types.js

@@ -0,0 +1,7 @@
+/**
+ * Coverage Map System - Type Definitions
+ *
+ * This file contains all TypeScript interfaces and types for the coverage calculation system.
+ * Designed to be AI-ready with structured outputs for future ChatGPT integration.
+ */
+export {};

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

@@ -0,0 +1,223 @@
+/**
+ * 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
+ */
+import type { Position2D, Position3D, GeoBounds } from '../types';
+/**
+ * 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 declare function calculateDistance(point1: Position2D, point2: Position2D): number;
+/**
+ * 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 declare function calculate3DDistance(point1: Position3D, point2: Position2D): number;
+/**
+ * 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 declare function calculateBearing(from: Position2D, to: Position2D): number;
+/**
+ * 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 declare function calculateDestinationPoint(start: Position2D, distanceKm: number, bearingDeg: number): Position2D;
+/**
+ * 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 declare function calculateElevationAngle(antennaPos: Position3D, targetPos: Position2D, targetHeight?: number): number;
+/**
+ * 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 declare function calculateBounds(center: Position2D, radiusKm: number): GeoBounds;
+/**
+ * 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 declare function calculateBoundsArea(bounds: GeoBounds): number;
+/**
+ * Normalize angle to 0-360 range
+ *
+ * @param angle - Angle in degrees (any value)
+ * @returns Normalized angle (0-360)
+ */
+export declare function normalizeAngle(angle: number): number;
+/**
+ * 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 declare function angleDifference(bearing1: number, bearing2: number): number;
+/**
+ * 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 declare function isPointInBounds(point: Position2D, bounds: GeoBounds): boolean;