lunar_phase.hpp

Go to the documentation of this file.

#pragma once
 
#include "altitude.hpp"
#include "coordinates.hpp"
#include "ffi_core.hpp"
#include "time.hpp"
#include <ostream>
#include <vector>
 
namespace siderust {
 
// ============================================================================
// Phase enumerations
// ============================================================================
 
enum class PhaseKind : int32_t {
  NewMoon = 0,
  FirstQuarter = 1,
  FullMoon = 2,
  LastQuarter = 3,
};
 
enum class MoonPhaseLabel : int32_t {
  NewMoon = 0,
  WaxingCrescent = 1,
  FirstQuarter = 2,
  WaxingGibbous = 3,
  FullMoon = 4,
  WaningGibbous = 5,
  LastQuarter = 6,
  WaningCrescent = 7,
};
 
// ============================================================================
// Phase event / geometry types
// ============================================================================
 
struct MoonPhaseGeometry {
  qtty::Radian phase_angle;    
  double illuminated_fraction; 
  qtty::Radian elongation;     
  bool waxing;                 
 
  static MoonPhaseGeometry from_c(const siderust_moon_phase_geometry_t &c) {
    return {qtty::Radian(c.phase_angle_rad), c.illuminated_fraction, qtty::Radian(c.elongation_rad),
            static_cast<bool>(c.waxing)};
  }
};
 
struct PhaseEvent {
  Time<TT, MJD> time; 
  PhaseKind kind;     
 
  static PhaseEvent from_c(const siderust_phase_event_t &c) {
    return {Time<TT, MJD>(c.mjd), static_cast<PhaseKind>(c.kind)};
  }
};
 
// ============================================================================
// Internal helpers
// ============================================================================
namespace detail {
 
inline std::vector<PhaseEvent> phase_events_from_c(siderust_phase_event_t *ptr, uintptr_t count) {
  std::vector<PhaseEvent> result;
  result.reserve(count);
  for (uintptr_t i = 0; i < count; ++i) {
    result.push_back(PhaseEvent::from_c(ptr[i]));
  }
  siderust_phase_events_free(ptr, count);
  return result;
}
 
inline std::vector<Period<TT, MJD>> illum_periods_from_c(tempoch_period_mjd_t *ptr,
                                                         uintptr_t count) {
  std::vector<Period<TT, MJD>> result;
  result.reserve(count);
  for (uintptr_t i = 0; i < count; ++i) {
    result.push_back(
        Period<TT, MJD>(Time<TT, MJD>(ptr[i].start_mjd), Time<TT, MJD>(ptr[i].end_mjd)));
  }
  siderust_periods_free(ptr, count);
  return result;
}
 
} // namespace detail
 
// ============================================================================
// Lunar phase namespace
// ============================================================================
 
namespace moon {
 
inline MoonPhaseGeometry phase_geocentric(const Time<TT, JD> &jd) {
  siderust_moon_phase_geometry_t out{};
  check_status(siderust_moon_phase_geocentric(jd.value(), &out), "moon::phase_geocentric");
  return MoonPhaseGeometry::from_c(out);
}
 
inline MoonPhaseGeometry phase_topocentric(const Time<TT, JD> &jd, const Geodetic &site) {
  siderust_moon_phase_geometry_t out{};
  check_status(siderust_moon_phase_topocentric(jd.value(), site.to_c(), &out),
               "moon::phase_topocentric");
  return MoonPhaseGeometry::from_c(out);
}
 
inline MoonPhaseLabel phase_label(const MoonPhaseGeometry &geom) {
  siderust_moon_phase_geometry_t c{geom.phase_angle.value(), geom.illuminated_fraction,
                                   geom.elongation.value(), static_cast<uint8_t>(geom.waxing)};
  siderust_moon_phase_label_t out{};
  check_status(siderust_moon_phase_label(c, &out), "moon::phase_label");
  return static_cast<MoonPhaseLabel>(out);
}
 
inline std::vector<PhaseEvent> find_phase_events(const Period<TT, MJD> &window,
                                                 const SearchOptions &opts = {}) {
  siderust_phase_event_t *ptr = nullptr;
  uintptr_t count = 0;
  check_status(siderust_find_phase_events(window.c_inner(), opts.to_c(), &ptr, &count),
               "moon::find_phase_events");
  return detail::phase_events_from_c(ptr, count);
}
 
inline std::vector<Period<TT, MJD>> illumination_above(const Period<TT, MJD> &window, double k_min,
                                                       const SearchOptions &opts = {}) {
  tempoch_period_mjd_t *ptr = nullptr;
  uintptr_t count = 0;
  check_status(siderust_moon_illumination_above(window.c_inner(), k_min, opts.to_c(), &ptr, &count),
               "moon::illumination_above");
  return detail::illum_periods_from_c(ptr, count);
}
 
inline std::vector<Period<TT, MJD>> illumination_below(const Period<TT, MJD> &window, double k_max,
                                                       const SearchOptions &opts = {}) {
  tempoch_period_mjd_t *ptr = nullptr;
  uintptr_t count = 0;
  check_status(siderust_moon_illumination_below(window.c_inner(), k_max, opts.to_c(), &ptr, &count),
               "moon::illumination_below");
  return detail::illum_periods_from_c(ptr, count);
}
 
inline std::vector<Period<TT, MJD>> illumination_range(const Period<TT, MJD> &window, double k_min,
                                                       double k_max,
                                                       const SearchOptions &opts = {}) {
  tempoch_period_mjd_t *ptr = nullptr;
  uintptr_t count = 0;
  check_status(
      siderust_moon_illumination_range(window.c_inner(), k_min, k_max, opts.to_c(), &ptr, &count),
      "moon::illumination_range");
  return detail::illum_periods_from_c(ptr, count);
}
 
} // namespace moon
 
// ============================================================================
// Convenience helpers (pure C++, no FFI)
// ============================================================================
 
inline double illuminated_percent(const MoonPhaseGeometry &geom) {
  return geom.illuminated_fraction * 100.0;
}
 
inline bool is_waxing(MoonPhaseLabel label) {
  switch (label) {
  case MoonPhaseLabel::WaxingCrescent:
  case MoonPhaseLabel::FirstQuarter:
  case MoonPhaseLabel::WaxingGibbous:
    return true;
  default:
    return false;
  }
}
 
inline bool is_waning(MoonPhaseLabel label) {
  switch (label) {
  case MoonPhaseLabel::WaningGibbous:
  case MoonPhaseLabel::LastQuarter:
  case MoonPhaseLabel::WaningCrescent:
    return true;
  default:
    return false;
  }
}
 
// ============================================================================
// Stream operators
// ============================================================================
 
inline std::ostream &operator<<(std::ostream &os, PhaseKind kind) {
  switch (kind) {
  case PhaseKind::NewMoon:
    return os << "new moon";
  case PhaseKind::FirstQuarter:
    return os << "first quarter";
  case PhaseKind::FullMoon:
    return os << "full moon";
  case PhaseKind::LastQuarter:
    return os << "last quarter";
  }
  return os << "unknown";
}
 
inline std::ostream &operator<<(std::ostream &os, MoonPhaseLabel label) {
  switch (label) {
  case MoonPhaseLabel::NewMoon:
    return os << "new moon";
  case MoonPhaseLabel::WaxingCrescent:
    return os << "waxing crescent";
  case MoonPhaseLabel::FirstQuarter:
    return os << "first quarter";
  case MoonPhaseLabel::WaxingGibbous:
    return os << "waxing gibbous";
  case MoonPhaseLabel::FullMoon:
    return os << "full moon";
  case MoonPhaseLabel::WaningGibbous:
    return os << "waning gibbous";
  case MoonPhaseLabel::LastQuarter:
    return os << "last quarter";
  case MoonPhaseLabel::WaningCrescent:
    return os << "waning crescent";
  }
  return os << "unknown";
}
 
} // namespace siderust