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
// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (C) 2026 Vallés Puig, Ramon
//! # Unified Azimuth Computation & Event API
//!
//! ## Scientific scope
//!
//! Topocentric azimuth *A(t)* of a celestial body, expressed in the
//! North‑clockwise convention (`N = 0°`, `E = 90°`). The body's apparent
//! direction comes from the chosen analytical or numerical engine
//! (VSOP87/ELP/JPL DE for solar‑system bodies; ICRS catalogue position
//! plus proper motion for stars), so accuracy and validity match that
//! engine. Azimuth is intrinsically circular in `[0°, 360°)`; this module
//! supports queries that wrap around North by allowing
//! `min_azimuth > max_azimuth`. No atmospheric refraction is modelled.
//!
//! ## Technical scope
//!
//! A clean, user‑friendly API for computing target azimuth vs time and
//! finding events (bearing crossings, azimuth extrema, range periods) for
//! **any** celestial target.
//!
//! ## Module Structure
//!
//! - `types`, Core type definitions (events, query)
//! - `search`, Search options and configuration constants
//! - `events`, Event finding (crossings, extrema, range periods)
//! - `provider`, Trait-based dispatch for bodies
//!
//! ## Public Functions
//!
//! | Function | Purpose |
//! |---|---|
//! | [`azimuth_crossings`] | When azimuth passes a specific bearing |
//! | [`azimuth_extrema`] | All local max/min (northernmost/southernmost) |
//! | [`azimuth_ranges`] | Intervals where azimuth is within `[min, max]` |
//! | [`in_azimuth_range`] | Same as `azimuth_ranges` (convenience alias) |
//! | [`outside_azimuth_range`] | Intervals where azimuth is outside `[min, max]` |
//!
//! All inputs/outputs are typed with `qtty` (`Degrees`, `ModifiedJulianDate`, etc.).
//!
//! ## Time Scale
//!
//! `ModifiedJulianDate` / `Period<ModifiedJulianDate>` values in this API are interpreted on
//! the TT axis (`tempoch` canonical JD(TT) semantics). If your inputs are UTC
//! timestamps, convert them with `ModifiedJulianDate::from_utc(…)` first.
//!
//! ## Azimuth Convention
//!
//! North-clockwise (North = 0°), values in `[0°, 360°)`.
//! A **wrap-around** query, e.g., 350° → 10° passing through North, is
//! expressed by setting `min_azimuth > max_azimuth` in [`AzimuthQuery`].
//!
//! ## Trait-Based API
//!
//! The [`AzimuthProvider`] trait provides a unified interface for computing
//! azimuth quantities for any body. Implementations exist for
//! [`Sun`](crate::bodies::solar_system::Sun),
//! [`Moon`](crate::bodies::solar_system::Moon),
//! [`Star`](crate::bodies::Star), and
//! [`direction::ICRS`](crate::coordinates::spherical::direction::ICRS).
//!
//! ## Example
//!
//! ```rust
//! use siderust::calculus::azimuth::{azimuth_crossings, AzimuthProvider, SearchOpts};
//! use siderust::bodies::Sun;
//! use siderust::coordinates::centers::Geodetic;
//! use siderust::coordinates::frames::ECEF;
//! use siderust::time::{ModifiedJulianDate, Period};
//! use siderust::qtty::*;
//!
//! let site = Geodetic::<ECEF>::new(Degrees::new(0.0), Degrees::new(51.48), Meters::new(0.0));
//! let window = Period::new(ModifiedJulianDate::new(60000.0), ModifiedJulianDate::new(60001.0));
//!
//! // Find when the Sun crosses due-South (180°):
//! let events = azimuth_crossings(&Sun, &site, window, Degrees::new(180.0), SearchOpts::default());
//! for e in &events {
//! println!("Sun crosses South at MJD {:.6} ({:?})", e.mjd.mjd_value(), e.direction);
//! }
//!
//! // Find intervals where azimuth is between East (90°) and West (270°):
//! let query = siderust::calculus::azimuth::AzimuthQuery {
//! observer: site,
//! window,
//! min_azimuth: Degrees::new(90.0),
//! max_azimuth: Degrees::new(270.0),
//! };
//! let eastern_periods = Sun.azimuth_periods(&query);
//! ```
//!
//! ## References
//! None.
// ---------------------------------------------------------------------------
// Re-exports: Types
// ---------------------------------------------------------------------------
pub use ;
// ---------------------------------------------------------------------------
// Re-exports: Search Options
// ---------------------------------------------------------------------------
pub use SearchOpts;
// ---------------------------------------------------------------------------
// Re-exports: Event Finding
// ---------------------------------------------------------------------------
pub use ;
// ---------------------------------------------------------------------------
// Re-exports: Trait & Provider Functions
// ---------------------------------------------------------------------------
pub use ;