Airway RouteKit - Aviation Route Calculation and Parsing Library

A high-performance aviation route calculation and parsing library developed in Rust, providing core routing functionality for flight planning systems, flight simulation software, and other aviation applications.

Features

Route Calculation: Find optimal routes between airports with various preferences
Route Parsing: Parse and validate aviation route strings in multiple formats
Geographic Calculations: Accurate great circle distance and bearing calculations
Spatial Search: Find waypoints and navigation aids within specified areas
High Performance: Optimized for real-time aviation applications
Comprehensive Database Support: Works with aviation navigation databases

Installation

Prerequisites

Rust 1.70 or higher
Aviation navigation database (compatible SQLite format)

Build from Source

Clone the repository:

git clone https://github.com/star-reader/Airway_RouteKit.git
cd Airway_RouteKit

Build the library:

cargo build --release

The static and dynamic libraries will be available in the target/release/ directory.

Using as a Rust Dependency

Add to your Cargo.toml:

[dependencies]
airway_routekit = { path = "/path/to/Airway_RouteKit" }

Quick Start

Basic Usage

use routekit::*;

fn main() -> Result<()> {
    // Create RouteKit instance
    let kit = RouteKit::new("path/to/database.s3db")?;

    // Query routes
    let request = RouteRequest {
        departure_icao: "ZBAA".to_string(),
        destination_icao: "ZSPD".to_string(),
        flight_level: Some(FlightLevel::High),
        route_preference: RoutePreference::Balanced,
        max_routes: 3,
    };

    let routes = kit.find_routes(&request)?;
    for route in routes {
        println!("Total route distance: {} nautical miles", route.total_distance_nm);
    }

    Ok(())
}

Route Parsing

use routekit::RouteKit;

let kit = RouteKit::new("database.s3db")?;

// Support multiple formats
let parsed = kit.parse_route("ZBAA SID TEPID G212 VYK STAR ZSPD")?;

if parsed.is_valid {
    println!("Departure: {:?}", parsed.departure);
    println!("Destination: {:?}", parsed.destination);
    println!("Route elements: {}", parsed.elements.len());
}

Geographic Calculations

use routekit::{Coordinate, geo};

let beijing = Coordinate::new(39.9042, 116.4074)?;
let shanghai = Coordinate::new(31.2304, 121.4737)?;

// Calculate great circle distance
let distance = geo::haversine_distance_nm(&beijing, &shanghai);
println!("Distance: {:.2} nautical miles", distance);

// Calculate bearing
let bearing = geo::calculate_bearing(&beijing, &shanghai);
println!("Bearing: {:.2}°", bearing);

Spatial Search

let coord = Coordinate::new(40.0, 116.0)?;

// Find nearest waypoint
if let Some(waypoint) = kit.find_nearest_waypoint(&coord) {
    println!("Nearest waypoint: {}", waypoint.identifier);
}

// Find all waypoints within radius
let nearby = kit.find_waypoints_within_radius(&coord, 50.0);
println!("Found {} waypoints", nearby.len());

Usage from Other Languages

C++ Integration

The library provides C-compatible bindings for C++ integration:

#include <iostream>
#include "routekit_c.h"

int main() {
    // Initialize RouteKit
    RouteKit* kit = routekit_new("database.s3db");
    if (!kit) {
        std::cerr << "Failed to initialize RouteKit" << std::endl;
        return 1;
    }

    // Create route request
    RouteRequest request = {};
    request.departure_icao = "ZBAA";
    request.destination_icao = "ZSPD";
    request.flight_level = FL_HIGH;
    request.route_preference = ROUTE_BALANCED;
    request.max_routes = 3;

    // Find routes
    RouteResponse* response = routekit_find_routes(kit, &request);
    if (response) {
        for (int i = 0; i < response->route_count; i++) {
            std::cout << "Route " << i << ": " 
                      << response->routes[i].total_distance_nm 
                      << " NM" << std::endl;
        }
        routekit_free_response(response);
    }

    // Cleanup
    routekit_destroy(kit);
    return 0;
}

Compile with:

g++ -o example example.cpp -L./target/release -lroutekit -I./include

Go Integration

Use cgo to integrate with the Rust library:

package main

/*
#cgo LDFLAGS: -L./target/release -lroutekit
#cgo CFLAGS: -I./include
#include "routekit_c.h"
*/
import "C"
import (
    "fmt"
    "unsafe"
)

func main() {
    // Initialize RouteKit
    dbPath := C.CString("database.s3db")
    defer C.free(unsafe.Pointer(dbPath))
  
    kit := C.routekit_new(dbPath)
    if kit == nil {
        fmt.Println("Failed to initialize RouteKit")
        return
    }
    defer C.routekit_destroy(kit)

    // Create route request
    request := C.RouteRequest{
        departure_icao:   C.CString("ZBAA"),
        destination_icao: C.CString("ZSPD"),
        flight_level:     C.FL_HIGH,
        route_preference: C.ROUTE_BALANCED,
        max_routes:       3,
    }
    defer C.free(unsafe.Pointer(request.departure_icao))
    defer C.free(unsafe.Pointer(request.destination_icao))

    // Find routes
    response := C.routekit_find_routes(kit, &request)
    if response != nil {
        defer C.routekit_free_response(response)
      
        routes := (*[1 << 28]C.Route)(unsafe.Pointer(response.routes))[:response.route_count:response.route_count]
        for i, route := range routes {
            fmt.Printf("Route %d: %.2f NM\n", i, route.total_distance_nm)
        }
    }
}

Build with:

go build -o example example.go

API Documentation

Core Components

RouteKit: Main library interface for route operations
RouteRequest: Configuration for route queries
RouteResponse: Contains calculated route information
Coordinate: Geographic coordinate representation
Waypoint: Navigation waypoint data structure

Route Preferences

Direct: Shortest distance route
Balanced: Balance between distance and efficiency
Economic: Fuel-efficient routing
Time: Time-optimized routing

Flight Levels

Low: Below FL245
High: FL245 and above
Custom: Specific flight level

Database Requirements

This library requires an aviation navigation database to function properly. The database should include:

Airport information (ICAO/IATA codes, coordinates, runways)
Waypoints and navigation aids
Airway structures and connections
Standard Instrument Departures (SIDs)
Standard Terminal Arrival Routes (STARs)

Note: Ensure you have proper licensing and legal access to aviation navigation databases.

Performance

Optimized for real-time route calculations
Efficient spatial indexing for waypoint searches
Minimal memory footprint
Thread-safe operations

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

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

Disclaimer

This library is intended for educational and simulation purposes. It can't use in real flight! For aviation applications, ensure compliance with relevant aviation authorities and regulations.

star-reader/Airway_RouteKit