This document provides an in-depth look at the technical aspects, algorithms, and logic used in the SatMap project, current as of Version 3.0.

1. Project Core Objective
2. Key Technologies (V3.0)
3. Orbital Mechanics & Satellite Propagation
   • Satellite.js Library
   • Two-Line Element Sets (TLEs)
   • Beacon Satellite TLE Generation
   • Propagation Process
4. Communication Simulation (V3.0 Logic)
   • Iridium Constellation
   • Beacon and Iridium Antenna Cones & FOV
   • Line-of-Sight (Earth Occultation) Check
   • Cone Intersection Check
5. Simulation Engine Logic (simulationEngine.ts)
   • Time Stepping
   • Handshake Logic (V3.0 Definition)
   • Blackout Period Calculation
   • Simulation Outputs for UI
6. User Interface and Visualization (SatSimUI - V3.0 Features)
   • App.tsx (Main Controller)
   • OrbitInputForm.tsx (Simulation Configuration)
   • SimulationResultsDisplay.tsx (Key Metrics Display)
   • SatVisualization.tsx (2D Map View)
   • SatVisualization3D.tsx (3D Globe View - V3.0 Core)
   • SidePanel.tsx & CurrentConnectionsPanel.tsx (Interactive Info Panels)
   • ConsolePanel.tsx (Log Output)
   • PlaybackControls.tsx (Simulation Playback & Time Range)
7. Coordinate Systems
8. Source Code Structure Highlights
9. Version History & Feature Evolution
   • Version 1.0 (Hackathon MVP)
   • Version 2.0 (RelV2.0) - Delivered Features (Enhanced 2D & UX)
   • Version 3.0 (RelV3.0) - Delivered Features (3D Visualization & Viewports)
10. V3.x Future Enhancements & Long-Term Aspirations
    • Immediate Next Steps (V3.x)
    • Long-Term Aspirations (Post-V3.x)

The primary goal is to simulate a custom "Beacon" satellite orbiting Earth and determine its communication handshakes with the Iridium satellite constellation over a configurable period. The simulation calculates total communication blackout duration, percentage of time in communication, logs detailed handshake events, and visualizes the process on interactive 2D and 3D maps. The project originated from the Space Handshakes Hackathon.

• Core Logic (SatCore): TypeScript, satellite.js (orbital mechanics).
• Frontend (SatSimUI): React, TypeScript.
• 2D Data Visualization: react-simple-maps.
• 3D Data Visualization: three.js, @react-three/fiber, @react-three/drei.
• HTTP Requests: axios (for fetching Iridium TLEs from CelesTrak).
• Build Tool: Create React App.
• Styling: CSS (global styles, component-specific CSS Modules), supporting a Dark Theme.

Relies on satellite.js for SGP4/SDP4 propagation. Custom type definitions (src/types/satellite.d.ts) are used due to the lack of official @types/satellite.js.

Standard format for orbital data.

• Iridium TLEs: Fetched from CelesTrak via tleService.ts. Users can select between "active", "next", or "all" Iridium datasets.
• Beacon TLE: Dynamically generated by src/utils/orbitCalculation.ts based on user inputs (orbit type, altitude, LSTN/inclination, etc.).

Logic in src/utils/orbitCalculation.ts creates valid TLEs from user-defined parameters (SSO or Non-Polar LEO), calculating epoch, mean motion, inclination (direct or SSO-derived), RAAN (direct or LST_DN-derived), and assuming near-circular orbits (e=0.0001, argPerigee=0, meanAnomaly=0). Checksums are calculated.

1. satellite.twoline2satrec() parses TLEs into SatRec objects.
2. satellite.propagate(satrec, date) predicts ECI position/velocity at each time step.
3. satellite.eciToGeodetic(eciPosition, gmst) converts ECI to Geodetic (lat, lon, alt) for WGS84.

Models each Iridium satellite as a potential communication partner.

Communication capabilities are modeled using conical Fields of View (FOV):

• Iridium Satellite: Nadir-pointing (downward) cone. FOV half-angle is user-configurable.
• Beacon Satellite: Uses horizon-aligned antenna cones for bi-directional mode. FOV half-angle is also user-configurable.
• Geometric Functions: createIridiumCone (for nadir) and createHorizonAlignedAntennaCones (for horizon-scanning) in src/utils/geometry.ts define these cones.

The isLineOfSightClear(point1Eci, point2Eci) function in src/utils/geometry.ts checks if the direct path between two points (e.g., Beacon and an Iridium satellite) is obstructed by the Earth. This is crucial for realistic link assessment.

The isPointInCone(pointEci, cone) function in src/utils/geometry.ts determines if a target satellite (its ECI position) falls within the defined communication cone of another satellite.

The runSimulation function in src/simulationEngine.ts orchestrates the simulation based on a SimulationConfig object (Beacon params, FOVs, duration, time step, handshake mode, etc.).

Iterates through the simulation duration at user-defined time steps. In each step: Beacon and Iridium satellites are propagated, and communication checks are performed.

Definition of a Handshake: A handshake is counted as one continuous communication session initiated with a specific Iridium satellite. The simulation counts the number of such unique, new sessions over the simulation period.

• One-Way Mode ("Beacon Directly Overhead"): Communication occurs if the Beacon is within an Iridium satellite's nadir-pointing cone AND there is clear Line of Sight (LoS).
• Bi-Directional Mode ("Mutual Horizon Scanning"): Communication occurs if the Beacon is within an Iridium satellite's horizon-aligned cone, AND the Iridium satellite is within the Beacon's horizon-aligned cone, AND there is clear LoS between them.
• Tracking: previousConnectedIridiumSatIds (Set of Iridium IDs connected in the prior timestep) and currentConnectedIridiumSatIdsThisStep (Set for the current timestep) are used.
• New Handshake Condition: A handshake with IridiumX is registered if IridiumX is in currentConnectedIridiumSatIdsThisStep BUT was NOT in previousConnectedIridiumSatIds.
• The simulation logs each handshake event with details (timestamp, satellites involved).

A blackout occurs when the Beacon is not in communication (LoS + cone conditions not met) with any Iridium satellite. The logic calculates start, end, and duration for each blackout period, stored in blackoutPeriods.

The SimulationResults object (returned by runSimulation) includes:

• totalHandshakes: Total count of new link establishments.
• handshakeLog: HandshakeEvent[]: Detailed log of each handshake (timestamp, Beacon pos, Iridium sat, Iridium pos, etc.).
• activeLinksLog: Array<Set<string>>: An array where each index represents a time step. The Set at each index contains IDs of Iridium satellites actively linked to the Beacon at that moment.
• blackoutPeriods: BlackoutPeriod[]: List of blackout events with start, end, duration.
• totalBlackoutDuration: Total duration (in seconds) the Beacon is not in communication.
• averageBlackoutDuration: Average length of a single blackout period (in seconds).
• numberOfBlackouts: Total count of distinct blackout periods.
• beaconTrack: SatellitePosition[], iridiumTracks: { [satelliteId: string]: SatellitePosition[] }: Full positional data for visualization.
• (Note: The percentage of time in communication is derived in the UI (SimulationResultsDisplay.tsx) using totalBlackoutDuration and the simulationDurationHours from the input SimulationConfig.)

Manages overall application state (input parameters, simulation results, UI states like loading/error, selected time range, playback states). Triggers simulations, passes data to visualization components (SatVisualization.tsx, SatVisualization3D.tsx), SidePanel.tsx, and SimulationResultsDisplay.tsx.

Form for users to input:

• Beacon Orbit: Type (SSO/Non-Polar), Altitude, LSTDN (SSO) or Inclination & RAAN (Non-Polar).
• Simulation Timing: Start Date/Time (UTC, optional), Duration (hours), Time Step (seconds).
• Communication: Handshake Mode (One-Way/Bi-Directional - Bi-Directional default), Iridium FOV, Beacon FOV.
• Iridium Dataset: Selection (Active, Next, All).
• Styled for dark theme consistency (e.g., #simulationStartTime input).

This component, part of the main dashboard, presents key summary statistics from the completed simulation. It receives the SimulationResults and the SimulationConfig used for the run. Displayed metrics include:

• Total Handshakes.
• Percentage of Time in Communication (calculated from total blackout duration and simulation duration).
• Number of Blackouts.
• Total Blackout Duration (seconds).
• Average Blackout Duration (seconds).

• Renders interactive 2D map using react-simple-maps.
• Displays satellite ground tracks (Beacon, Iridium), handshake markers (small circles/dots at Beacon's location), and active communication links (lines).
• Time Range Filtering: Visual elements (trails, markers) are filtered based on the selectedTimeRange from PlaybackControls. The trailLength input is disabled if a time range is active.
• Defaults: Trails are OFF by default. Map can be panned/zoomed. Satellite names/icons displayed.

• Renders interactive 3D globe using three.js, @react-three/fiber, @react-three/drei.
• Displays Earth globe, satellite positions (markers), orbital paths (trails), active communication links (lines between satellites), communication cones, and Iridium nadir cone Earth footprints (circles).
• Time Range Filtering: Trails and handshake markers (small gold spheres at Beacon's handshake location) are filtered by selectedTimeRange.
• Toggleable Features: Satellite trails (default OFF), communication cones (default ON), satellite labels.
• Camera Controls: Standard orbit controls; labels are larger for readability.
• Default View: Shows a blank Earth globe before simulation.

• CurrentConnectionsPanel.tsx: Displays a list of currently active Beacon-Iridium links, updating with simulation playback. Clicking an Iridium satellite opens its details in SidePanel.tsx.
• SidePanel.tsx: Draggable/minimizable panel. Shows detailed info for a selected satellite (Beacon or Iridium) or details of a selected historical handshake event. Includes an "Active Link Status" section for ongoing connections and historical handshake log.

A panel (default disabled, can be enabled) to show simulation log messages and event details. Useful for debugging or deeper insight.

• Standard Controls: Play/Pause, Reset simulation view.
• Speed Control: Selectable playback speed (1x, 2x, 4x, 8x).
• Timelapse Mode: Fast playback (e.g., 16x speed).
• Realtime Mode: Advances simulation one time step per simulationTimeStepSec (e.g., if step is 60s, advances 1 sim minute per 1 real second).
• Time Range Selector: Two <input type="range"> sliders for Start and End of a time window. Filters data shown in both 2D and 3D views (trails, handshake markers).
• Timestamp Display: Shows the current simulation timestamp, formatted.

• ECI (Earth-Centered Inertial): Used for orbital propagation and core geometric calculations (cone checks, LoS). satellite.js outputs positions in ECI (km).
• Geodetic (LLA): Latitude, Longitude, Altitude. Used for displaying positions on maps (2D and 3D). Conversion from ECI via satellite.eciToGeodetic.
• Screen Coordinates: For UI element positioning and interaction on the 2D map.

• src/components/: React components for UI elements.
• src/services/: Services like tleService.ts for fetching external data.
• src/simulation/: Core simulation logic, including simulationEngine.ts.
• src/utils/: Utility functions for orbital math (orbitCalculation.ts), geometry (geometry.ts), TLE generation, etc.
• src/types/: TypeScript type definitions, including custom satellite.d.ts.
• src/constants/: Application-wide constants (e.g., physical constants, default settings).

• Basic Beacon TLE generation (SSO only, limited parameterization).
• Core SGP4 propagation for Beacon and fetched Iridium TLEs.
• Simple 2D map visualization using react-simple-maps.
• Rudimentary one-way handshake logic (Beacon in Iridium nadir cone, no LoS check).
• Basic UI for inputs and results display.
• Focus on demonstrating the core concept for the Space Handshakes Hackathon.

• UI/UX Overhaul: Modernized dark theme, improved layout, interactive panels (SidePanel, CurrentConnectionsPanel, ConsolePanel).
• Advanced 2D Simulation Controls: Playback speed, timelapse, realtime mode, reset.
• Time Range Selector (2D): Filtering of 2D map trails and markers.
• Refined Simulation Configuration: Choice of Iridium datasets, bi-directional handshake as default option, user-defined simulation start time & timezone awareness, explicit FOV inputs.
• Core Logic Enhancements:
  • Line of Sight (Earth Occultation): Integrated isLineOfSightClear into simulation.
  • Bi-Directional Handshake Logic: Implemented mutual horizon scanning cone checks for Beacon and Iridium.
  • Generalized Cone Creation: createHorizonAlignedAntennaCones for flexible use.
  • Improved Handshake Logging: More detailed HandshakeEvent structure.
• Dynamic TLE Generation: Support for Non-Polar LEO Beacon orbits in addition to SSO.
• Code Quality: Increased TypeScript adoption and code organization.

• Core 3D Visualization (SatVisualization3D.tsx):
  • Switchable 3D map mode with an interactive Earth globe (three.js, R3F).
  • 3D rendering of satellites (markers), orbital paths (trails), and active communication links (lines).
  • Visualization of communication cones (Beacon horizon-aligned, Iridium nadir) in 3D space (toggleable, default ON).
  • Projection of Iridium nadir cone footprints onto the 3D Earth's surface.
  • Consistent Earth textures between 2D and 3D views.
  • Default blank 3D Earth globe view pre-simulation.
• Feature Parity & Enhancements in 3D View:
  • Full playback suite (play/pause, speed, timelapse, realtime) functional in 3D.
  • Time Range Selector fully operational for 3D trails and handshake markers (small gold spheres).
  • 3D satellite trails (toggleable, default OFF).
  • Enlarged 3D satellite labels for readability.
• Specialized Viewport Controls (Enhanced Camera Focus):
  • Functionality allowing camera to focus/zoom on selected satellites (Beacon or Iridium) to better inspect cones and relative positions in the 3D scene (achieved via camera manipulation rather than distinct viewport components).
• Configuration & Defaults for V3.0:
  • User-defined simulation start time input robustly styled and functional.
  • Bi-directional handshake mode remains the default.
  • Trails OFF by default in 3D view, FOV cones ON by default in 3D view.
  • Lowered default Beacon altitude (e.g., 550km) in OrbitInputForm.tsx.

• UI/UX Refinements: Explore subtle Glassmorphic UI elements for panels/modals to enhance the modern aesthetic, maintaining overall dark theme consistency.
• Introduction/How-To-Use Guide: Develop an integrated "Getting Started" modal or a brief tutorial overlay explaining key UI elements and workflow for new users.
• Performance & Technical Improvements: Implement a TLE Cache Toggle in the UI. This would allow the application to store and reuse fetched Iridium TLE data (e.g., in localStorage or IndexedDB) for a certain period, reducing API calls to CelesTrak, especially useful for developers or users running similar simulations frequently.

• Public API Development: Design and implement a public API (e.g., RESTful or GraphQL) allowing external applications or scripts to programmatically run simulations and retrieve results.
• Advanced 3D Satellite Models: Allow users to import or select more detailed 3D models for satellites (e.g., .gltf, .fbx) instead of the current generic markers/spheres.
• Full-Screen Mode: Implement a toggle for full-screen display of the 2D/3D visualization area.
• Basic Orbit Insertion/Maneuver Simulation: Introduce capabilities to simulate simplified orbital insertion phases or basic propulsive maneuvers for the Beacon satellite.
• Enhanced Simulation Logic:
  • More sophisticated antenna pattern modeling (e.g., using gain patterns instead of simple cones).
  • Basic modeling of atmospheric signal attenuation or interference.
  • Calculation and display of Doppler shift for active links.
• Data Export Capabilities: Provide options for users to export simulation results (handshake logs, blackout data, satellite tracks) in common formats like CSV, JSON, or KML.
• User Accounts & Saved Configurations: Allow users to create accounts to save, load, and manage their preferred simulation configurations and possibly past results.
• Enhanced Earth Visualizations (3D): Higher resolution Earth textures, dynamic weather layers (clouds), city lights on the night side of the globe.
• WebAssembly (WASM) for Performance: Explore migrating computationally intensive parts of the simulation engine (e.g., propagation loops) to WebAssembly for potential performance gains in the browser.

This document is intended to provide a high-level technical overview. For precise implementation details, please refer to the source code.