solunatus 0.6.0

High-precision astronomical calculation library and CLI for sun/moon positions, rise/set times, and lunar phases
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

//! Cached data types for the TUI.
//!
//! These types cache expensive astronomical calculations to avoid
//! recomputation on every frame render.

use crate::astro::moon::LunarPosition;
use crate::astro::planets::{Planet, PlanetEvent, PlanetPosition};
use crate::astro::sun::SolarPosition;
use crate::astro::{Location, moon, planets, sun};
use chrono::DateTime;
use chrono_tz::Tz;

// ============================================================================
// Cached Events
// ============================================================================

/// Cached astronomical events for the event window.
#[derive(Debug, Clone)]
pub struct CachedEvents {
    /// Reference time when this cache was generated
    pub reference: DateTime<Tz>,
    /// List of (timestamp, event_name) tuples
    pub entries: Vec<(DateTime<Tz>, &'static str)>,
}

// ============================================================================
// Cached Positions
// ============================================================================

/// Cached sun and moon positions.
#[derive(Debug, Clone, Copy)]
pub struct CachedPositions {
    /// Timestamp when positions were calculated
    pub timestamp: DateTime<Tz>,
    /// Sun position data
    pub sun: SolarPosition,
    /// Moon position data
    pub moon: LunarPosition,
}

impl CachedPositions {
    /// Create new cached positions for the given location and time.
    pub fn new(location: &Location, timestamp: &DateTime<Tz>) -> Self {
        Self {
            timestamp: *timestamp,
            sun: sun::solar_position(location, timestamp),
            moon: moon::lunar_position(location, timestamp),
        }
    }
}

// ============================================================================
// Cached Planets
// ============================================================================

/// Position and rise/set times for one planet.
#[derive(Debug, Clone, Copy)]
pub struct CachedPlanet {
    /// Which planet this entry describes
    pub planet: Planet,
    /// Apparent position and brightness
    pub position: PlanetPosition,
    /// Rise time on the local day, if any
    pub rise: Option<DateTime<Tz>>,
    /// Set time on the local day, if any
    pub set: Option<DateTime<Tz>>,
}

/// Cached planet positions and rise/set times for the planets panel.
#[derive(Debug, Clone)]
pub struct CachedPlanets {
    /// Timestamp when the entries were calculated
    pub timestamp: DateTime<Tz>,
    /// One entry per supported planet, in distance order from the sun
    pub entries: Vec<CachedPlanet>,
}

impl CachedPlanets {
    /// Compute positions and rise/set times for all supported planets.
    pub fn new(location: &Location, timestamp: &DateTime<Tz>) -> Self {
        let entries = Planet::ALL
            .iter()
            .map(|&planet| CachedPlanet {
                planet,
                position: planets::planet_position(planet, location, timestamp),
                rise: planets::planet_event_time(planet, location, timestamp, PlanetEvent::Rise),
                set: planets::planet_event_time(planet, location, timestamp, PlanetEvent::Set),
            })
            .collect();
        Self {
            timestamp: *timestamp,
            entries,
        }
    }
}

// ============================================================================
// Moon Altitude Trend
// ============================================================================

/// Simple visibility indicator for the Moon.
#[derive(Debug, Clone, Copy)]
pub enum MoonAltitudeTrend {
    /// Moon center altitude < 0° (not visible).
    Down,
    /// Moon center altitude ≥ 0° (visible).
    Up,
}

// ============================================================================
// Cached Moon Details
// ============================================================================

/// Cached moon details including trend information.
#[derive(Debug, Clone, Copy)]
pub struct CachedMoonDetails {
    /// Timestamp when details were calculated
    pub timestamp: DateTime<Tz>,
    /// Moon position data
    pub moon: LunarPosition,
    /// Whether moon is above or below horizon
    pub altitude_trend: MoonAltitudeTrend,
}

impl CachedMoonDetails {
    /// Create moon details from cached positions.
    pub fn from_positions(location: &Location, positions: &CachedPositions) -> Self {
        let altitude_trend = determine_moon_trend(location, &positions.timestamp, positions.moon);
        Self {
            timestamp: positions.timestamp,
            moon: positions.moon,
            altitude_trend,
        }
    }
}

/// Determine if moon is above or below the horizon.
fn determine_moon_trend(
    _location: &Location,
    _timestamp: &DateTime<Tz>,
    base: LunarPosition,
) -> MoonAltitudeTrend {
    if base.altitude >= 0.0 {
        MoonAltitudeTrend::Up
    } else {
        MoonAltitudeTrend::Down
    }
}