          /\,%,_
          \%%%/,\       In silence drift, through void unknown,
        _.-"%%|//%      A mapless path your screen has shown.
      .'  .-"  /%%%
  _.-'_.-" 0)   \%%%    Coordinates fade, the stars align,
 /.\.'           \%%%   To whispers lost beyond defined.
 \ /      _,      %%%
  `"---"~`\   _,*'\%%'   _,--""""-,%%,
           )*^     `""~~`         \%%%,
         _/                         \%%%
     _.-`/       uncharted           |%%,___
 _.-"   /    worlds await your       |%%   .`\
/\     /    gaze, their secrets      \%'   \ /
\ \ _,/     shine in stellar haze.    \`""~~`
 `"` /-.,_/                            \
     \___,'                       \.-"`/      
                                   `--'
           Navigate shadows, chart the spark,
             Secrets found in deepest dark.

Space Navigation System

A comprehensive 3D celestial navigation system with advanced pathfinding, coordinate transformations, and collision detection for space simulation environments.

Overview

Space Navigation System is a high-performance Rust library designed for accurate interplanetary navigation calculations with realistic physics considerations. It implements optimized bidirectional A* search with pre-computed visibility graphs, quaternion-based coordinate transformations, and sophisticated collision detection algorithms.

Features

Advanced Pathfinding: Bidirectional A* search algorithm with optimized performance for interplanetary routes
Obstacle Avoidance: Automatically detects celestial bodies in the path and calculates optimal detour routes
Quaternion-based Rotations: Precise coordinate transformations between global and local reference frames
Planetary Rotation: Accounts for planetary rotation when calculating surface coordinates
Path Complexity Analysis: Categorizes routes based on complexity and provides detailed navigation instructions
Efficient Caching: Implements smart caching for expensive coordinate transformations
JSON Data Loading: Loads celestial object data and points of interest from structured JSON files
Travel Time Estimation: Calculates realistic travel times with acceleration and deceleration profiles
Quantum Travel Support: Special handling for both subluminal and quantum (FTL) travel mechanics

Installation

Add this to your Cargo.toml:

[dependencies]
space-navigation-system = "0.1.0"

Quick Start

use space_navigation_system::{SpaceNavigationSystem, types::StaticAstronomicalData};

fn main() {
    // Load navigation data (containers and points of interest)
    let data = StaticAstronomicalData::new(pois, containers);
    
    // Create navigation system
    let mut nav_system = SpaceNavigationSystem::new(data);
    
    // Set current position (can be in local or global coordinates)
    nav_system.set_position_local("Hurston", -328.91, -785.98, 564.17);
    
    // Plan navigation to a destination
    let plan = nav_system.plan_navigation("Shubin Mining Facility SCD-1");
    
    if let Some(plan) = plan {
        // Get human-readable navigation instructions
        let instructions = nav_system.format_navigation_instructions(&plan);
        println!("{}", instructions);
    }
}

Architecture

The navigation system is built with a modular architecture:

┌─────────────────────────────────────┐
│       SpaceNavigationSystem         │
└───────────────┬─────────────────────┘
                │
                ▼
┌─────────────────────────────────────┐
│         NavigationPlanner           │
└───────────────┬─────────────────────┘
                │
        ┌───────┴───────┐
        ▼               ▼
┌───────────────┐ ┌─────────────────────┐
│ NavigationCore│ │CoordinateTransformer│
└───────────────┘ └─────────────────────┘
        ▲               ▲
        └───────┬───────┘
                │
                ▼
┌─────────────────────────────────────┐
│    AstronomicalDataProvider         │
└─────────────────────────────────────┘

Core Components

CoordinateTransformer

Specialized utility for transforming coordinates between global and local reference frames with caching for expensive calculations.

let transformer = CoordinateTransformer::new();
let global_coords = transformer.transform_coordinates(
    &local_coords,
    &container,
    TransformDirection::ToGlobal
);

NavigationCore

Provides core navigation functionality including position tracking, vector calculations, and closest point determination.

let nav_core = NavigationCore::new(data_provider);
nav_core.set_position(x, y, z);
let nav_data = nav_core.get_navigation_data();

NavigationPlanner

Advanced pathfinding system with bidirectional A* search and pre-computed visibility graphs for efficient route calculation.

let planner = NavigationPlanner::new(data_provider);
let plan = planner.plan_route("Lorville", "Shubin Mining Facility SCD-1");

Data Loading

Load celestial objects and points of interest from JSON files.

let containers = load_containers("data/containers.json")?;
let pois = load_pois("data/pois.json")?;

Navigation Plan Example

When executing a navigation plan, the system provides detailed instructions:

NAVIGATION PLAN
===============

ORIGIN: Hurston

SUMMARY:
Distance: 43,854,328 km
Estimated Travel Time: 14m 22s
Path Complexity: MultiJump

ROUTE SEGMENTS:

[1] Lorville → Hurston OM-1
    Distance: 1,500.00 km
    Travel Mode: Sublight
    Time: 5m 10s

[2] Hurston OM-1 → Daymar OM-6
    Distance: 19,204,875.23 km
    Travel Mode: Quantum
    Time: 5m 32s
    Align: Pitch -1.4°, Yaw 223.7°

[3] Daymar OM-6 → Shubin Mining Facility SCD-1
    Distance: 305.88 km
    Travel Mode: Sublight
    Time: 3m 40s

Data Models

The system uses several specialized data structures:

ObjectContainer: Represents celestial bodies (planets, moons, space stations)
PointOfInterest: Locations on or near celestial bodies
Vector3: 3D vector representation
Quaternion: For precise rotational calculations
NavigationPlan: Complete route with multiple segments
PathSegment: Individual segments in a navigation route

Performance Considerations

The system implements several performance optimizations:

Caching: Coordinate transformations are cached with automatic pruning
Pre-computed Visibility: Navigation nodes use pre-computed visibility graphs
Optimized Pathfinding: Bidirectional A* search algorithm reduces search space
Lazy Initialization: Navigation markers are created on-demand

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

The quaternion implementation is inspired by modern aerospace navigation systems
Pathfinding algorithms derived from advanced graph theory research
Special thanks to all contributors and testers

Note: This navigation system is designed for simulation environments and should not be used for real-world space navigation.

starnav 0.2.2