HyPlan

An open-source Python library for planning airborne remote sensing campaigns.

HyPlan helps scientists and engineers design flight missions for hyperspectral, multispectral, lidar, and radar remote sensing. It handles flight line generation, sensor modeling, swath coverage, solar glint prediction, cloud analysis, terrain-aware calculations, and mission logistics including airport selection and aircraft performance.

Tip

HyPlan modules are classified as Stable or Experimental. Stable APIs will not change in backward-incompatible ways within a major version. See API Stability for details.

Getting Started

• Installation
  • From source (pip)
  • From source (conda/mamba)
  • Optional extras
  • Versioning
  • Library logging
  • Building the documentation
• Concepts
  • Altitude: MSL vs AGL
  • Sensor hierarchy
  • Flight planning workflow
  • Pattern model
  • Aircraft speed profiles
  • Imports
  • Units
• Architecture
  • Data flow
  • Subsystems
  • Supporting modules
  • Units
• Aircraft Calibration
  • What “calibrated” means
  • Calibration status
  • Methodology
  • Operational vs aircraft-intrinsic numbers
  • Deferred calibrations
  • Conventions
• API Stability
  • What the levels mean
  • Module stability levels
  • Deprecation policy
• HyPlan Tutorial: End-to-End Airborne Campaign Planning
  • What You Will Learn
  • High-Level Workflow
  • What This Notebook Produces
  • 1. Define the Instrument and Aircraft
  • 2. Define the Study Area
  • 3. Generate Flight Lines
  • 4. Check Solar Illumination
  • 5. Find Nearby Airports
  • 6. Optimize Flight Line Sequence
  • 7. Compute the Flight Plan
  • 8. Visualize
  • 9. Create Individual Flight Lines
  • 10. Unit Conversions
  • Summary
  • Operational Takeaways
  • Common Pitfalls
  • Next Steps

API Reference

Flight planning

• Flight Lines
  • FlightLine class
  • Utilities
• Waypoint
  • Waypoint
  • Helper functions
• Flight Box
  • Box generators
  • Altitude helpers
• Pattern
  • Pattern class
• Flight Patterns
  • Pattern generators
  • Multi-aircraft coordination
  • Utilities
• Flight Plan
  • Plan computation
  • Record builders
• Isochrone
  • Modes
  • Compute
  • Helpers
  • See also
• Flight Optimizer
  • Graph construction
  • Optimization

Aircraft & navigation

• Aircraft
  • Base class
  • Pre-configured aircraft
• Airports
  • Data source
  • Airport
  • initialize_data()
  • find_nearest_airport()
  • find_nearest_airports()
  • airports_within_radius()
  • get_airports()
  • get_runways()
  • get_airport_details()
  • get_longest_runway()
  • generate_geojson()
  • get_runway_details()
• Dubins Path Planning
  • DubinsPath2D

Instruments

• Instruments
  • Base class
  • Line scanners
  • LVIS lidar
  • Profiling lidars
  • Doppler wind lidar
  • Radar
  • Frame camera
  • Factory function
• Profiling Lidars
  • Base class
  • NASA Langley HSRL-2
  • NASA Langley HALO
  • NASA Goddard CPL
  • References
• AWP Profiling
  • Instrument model
  • Planning helpers

Winds & atmosphere

• Winds
  • Wind field classes
  • Factory function
• Atmosphere
  • temperature_at()
  • pressure_at()
  • density_at()
  • speed_of_sound()
  • cas_to_tas()
  • tas_to_cas()
  • mach_to_tas()
  • tas_to_mach()

Terrain & swath

• Terrain
  • Assumptions and limitations
  • Terrain references
  • DEMGrid
  • get_cache_root()
  • clear_cache()
  • clear_localdem_cache()
  • build_tile_index()
  • download_dem_files()
  • merge_tiles()
  • generate_demfile()
  • load_dem()
  • get_elevations()
  • get_elevations_from_grid()
  • get_min_max_elevations()
  • ray_terrain_intersection()
  • terrain_elevation_along_track()
  • terrain_aspect_azimuth()
  • surface_normal_at()
• Swath
  • Swath generation
  • Coverage analysis
  • Export

Environment & timing

• Sun Position
  • Sun references
  • sunpos()
  • solar_threshold_times()
  • solar_azimuth()
  • solar_position_increments()
  • plot_solar_positions()
  • Data and attribution
• Solar Glint
  • Glint references
  • GlintArc
  • glint_angle()
  • calculate_target_and_glint_vectorized()
  • compute_glint_vectorized()
  • compute_glint_arc()
  • fraction_exceeding_glint_threshold()
• Cloud Cover
  • get_binary_cloud()
  • calculate_cloud_fraction()
  • create_date_ranges()
  • create_cloud_data_array_with_limit()
  • simulate_visits()
  • plot_yearly_cloud_fraction_heatmaps_with_visits()
  • OpenMeteoCloudFraction
  • fetch_cloud_fraction()
  • summarize_cloud_fraction_by_doy()
  • plot_doy_cloud_fraction()
  • OpenMeteoCloudForecast
  • fetch_cloud_forecast()
  • fetch_cloud_fraction_spatial()
  • plot_cloud_forecast()
  • plot_cloud_fraction_spatial()
• Vegetation Phenology
  • fetch_phenology()
  • fetch_phenology_spatial()
  • summarize_phenology_by_doy()
  • extract_phenology_stages()
  • plot_seasonal_profile()
  • plot_phenology_calendar()
  • plot_year_over_year_heatmap()
  • plot_cloud_phenology_combined()
• Satellites
  • Satellite references
  • SatelliteInfo
  • get_satellite()
  • fetch_tle()
  • clear_tle_cache()
  • compute_ground_track()
  • compute_swath_footprint()
  • find_overpasses()
  • find_all_overpasses()
  • compute_overpass_overlap()
  • overpasses_to_kml()
• Airspace
  • Data model
  • Conflict detection
  • Severity and schedule helpers
  • Data sources
  • Cache management
  • Parsing helpers

Mission management

• Campaign
  • Folder structure
  • What changed in the pattern-aware campaign model
  • Common workflow
  • Campaign class
• Exports
  • Functions
• Plotting
  • Maps
  • Flight plan visualization
  • Airspace visualization
  • Isochrone visualization
  • Terrain

Internals

• Geometry
  • Geometry references
  • wrap_to_180()
  • wrap_to_360()
  • get_timezone()
  • calculate_geographic_mean()
  • get_utm_crs()
  • get_utm_transforms()
  • haversine()
  • random_points_in_polygon()
  • minimum_rotated_rectangle()
  • rotated_rectangle()
  • rectangle_dimensions()
  • translate_polygon()
  • buffer_polygon_along_azimuth()
  • process_linestring()
  • magnetic_declination()
  • true_to_magnetic()
  • dd_to_ddm()
  • dd_to_ddms()
  • dd_to_nddmm()
  • dd_to_foreflight_oneline()
• Units
  • magnitude_in()
  • convert_distance()
  • convert_speed()
  • convert_angle()
  • convert_time()
  • altitude_to_flight_level()
• Download
  • download_file()
• Exceptions
  • HyPlanError
  • HyPlanValueError
  • HyPlanTypeError
  • HyPlanRuntimeError

Developer Guide

• Developer Guide
  • Package layout
  • Re-export pattern
  • Extending HyPlan
  • Where future refactors should land
  • Testing conventions
  • CI workflows
• Module Map
  • Decision tree: which function do I want?
  • Package layout
  • Cross-cutting concerns
  • See also