Metadata-Version: 2.1
Name: flight_sun
Version: 0.1.0
Summary: Calculate the sun position during a flight
Author-email: James Baird <j.baird94@gmail.com>
License: MIT License
        
        Copyright (c) 2023 James Baird
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: repository, https://github.com/bairdj/flight_sun
Description-Content-Type: text/markdown
License-File: LICENSE

# Flight Sun

Flight Sun is a Python package designed to calculate the proportion of a flight
that will be in sunlight.

The sunrise and sunset times of the origin and destination airports are easily obtainable,
so for short flights, it can usually be assumed whether a flight is a day or night flight.

However, for long flights, especially those travelling longitudinally, this calculation can
be more difficult. For example, a 17-hour flight from London to Perth, Australia can take off
and land in daylight, but spend the majority of the flight in darkness.

This package breaks a flight path into segments of day and night, allowing the proportion of
a flight that is in sunlight to be calculated.

## Features

- GeoJSON rendering of flight path with feature properties for whether the segment is in sunlight
- Integrated IATA and ICAO airport lookups (using airportsdata package). This retrieves the coordinates and local time
zones of airports.

## Assumptions

- The flight path is a direct great circle route between the origin and destination airports
- The aircraft flies at a constant speed
- Flight altitude is not considered

## Installation

Flight Sun can be installed using pip:

    pip install flight_sun

## Usage
    from flight_sun.flight import Flight
    from flight_sun.visualisation import generate_geojson
    from datetime import datetime
    import json
    
    take_off_time = datetime.fromisoformat("2023-02-11 11:50:00")
    landing_time = datetime.fromisoformat("2023-02-12 12:25:00")
    flight = Flight.from_iata_codes("LHR", "PER", take_off_time, landing_time)
    
    # Get sunlight proportion
    print(f"Sunlight proportion: {flight.proportion_in_sunlight():.2%}")
    
    # Get sunlight segments
    print("Sunlight segments:")
    for segment in flight.light_segments:
        print(f"Sunlight: {segment.sun_up}, start: {segment.start}, end: {segment.end}")
    
    # Render to GeoJSON
    geojson = generate_geojson(flight.light_segments)
    with open("flight.geojson", "w") as f:
        json.dump(geojson, f)

### Example output
    
    Sunlight proportion: 45.23%
    Sunlight segments:
    Sunlight: True, start: 2023-02-11 11:50:00+00:00, end: 2023-02-11 14:58:00+00:00
    Sunlight: False, start: 2023-02-11 14:58:00+00:00, end: 2023-02-12 00:03:00+00:00
    Sunlight: True, start: 2023-02-12 00:03:00+00:00, end: 2023-02-12 04:25:00+00:00

## Future ideas

- Add support for more complex flight paths (e.g. via waypoints)
- Use real-world flight data to create a better time-distance interpolation function
- Consider the position of the sun in relation to the aircraft i.e. which side of the aircraft is in sunlight
