Skip to content

Colossal.Atmosphere.SunMoonData

Assembly: Colossal.Atmosphere
Namespace: Colossal.Atmosphere

Type: struct

Base: System.ValueType

Summary:
SunMoonData provides astronomical calculations for the Sun and Moon used by the atmosphere system: positions (azimuth/altitude), times for sunrise/sunset/dawn/dusk/golden hour, moon position, and moon illumination. It implements commonly used algorithms (Julian date conversions, solar mean anomaly, ecliptic longitude, etc.) and returns results in topocentric/equatorial coordinate types used elsewhere in the engine. The angles returned are mostly in radians.

Fields

  • private static readonly double e
    Provides the obliquity of the ecliptic (Earth's axial tilt) in radians (≈ 23.4397°). Used internally for equatorial/ecliptic conversions.

  • private const double J0
    A small constant (0.0009) used in solar transit calculations.

  • private const double kDayMs
    Constant for number of milliseconds in a day (86400000.0). Present for reference though not directly used publicly.

  • private const double J2000
    Julian date of the epoch J2000 (2451545.0). Used as an offset when converting to/from Julian days.

  • public static readonly double h0
    Sun altitude for official sunrise/sunset threshold in radians (~ -0.833°).

  • public static readonly double h1
    Sun altitude for sunrise/sunset end threshold in radians (~ -0.3°).

  • public static readonly double d0
    Dawn/dusk threshold in radians (-6° for civil twilight).

  • public static readonly double d1
    Nautical dawn/dusk threshold in radians (-12°).

  • public static readonly double d2
    Astronomical night threshold in radians (-18°).

  • public static readonly double g0
    Golden hour threshold in radians (+6°).

(Also contains the nested public struct SunTimes described below.)

Properties

  • None (this struct exposes functionality via methods; results are returned in types such as TopocentricCoordinates, SunTimes, MoonCoordinate, and MoonIllumination).

Constructors

  • public SunMoonData()
    Default value-type constructor. No special initialization required; the type contains only static/read-only constants and methods that operate on input parameters.

Methods

  • private double GetRightAscension(double l, double b)
    Computes right ascension from ecliptic longitude (l) and latitude (b) using the obliquity (e). Internal helper.

  • private double GetDeclination(double l, double b)
    Computes declination from ecliptic longitude and latitude. Internal helper.

  • private double GetAzimuth(double H, double phi, double dec)
    Returns the topocentric azimuth angle (radians) given hour angle H, observer latitude phi, and declination dec. Adds pi to convert to a specific azimuth convention used by the system.

  • private double GetAltitude(double H, double phi, double dec)
    Returns the topocentric altitude angle (radians) given hour angle, latitude and declination.

  • private double GetSiderealTime(double d, double lw)
    Computes sidereal time (in radians) for given days since J2000 (d) and longitude-west lw. Used to compute local hour angle.

  • private double GetAstroRefraction(double h)
    Computes approximate atmospheric refraction correction for altitude h (radians). For negative h values uses zero baseline.

  • private double GetSolarMeanAnomaly(double d)
    Solar mean anomaly (radians) for given days since J2000.

  • private double GetEclipticLongitude(double M)
    Computes the Sun's ecliptic longitude (radians) from the solar mean anomaly M (includes small corrections).

  • private EquatorialCoordinate GetSunCoords(double d)
    Returns the Sun's equatorial coordinates (right ascension and declination) for days since J2000.

  • public TopocentricCoordinates GetSunPosition(JulianDateTime date, double latitude, double longitude)
    Returns the Sun's topocentric coordinates (azimuth and altitude in radians) at the given Julian date and geographic location (latitude, longitude in degrees). Uses the internal ephemeris approximations.

  • private double GetJulianCycle(double d, double lw)
    Helper to compute the Julian cycle used in solar transit calculations.

  • private double GetApproximateSolarTransit(double Ht, double lw, double n)
    Computes an approximate solar transit (in Julian days relative to J2000) given hour angle Ht, longitude-west lw and Julian cycle n.

  • private double GetSolarTransit(double ds, double M, double L)
    Refines the solar transit time (Julian day) using solar mean anomaly M and ecliptic longitude L.

  • private double GetHourAngle(double h, double phi, double d)
    Computes the hour angle for a target altitude h (radians) given observer latitude phi and declination d.

  • private double GetTimeForSunAltitude(double h, double lw, double phi, double dec, double n, double M, double L)
    High-level helper combining hour angle and solar transit to compute the Julian time when the Sun reaches altitude h.

  • public SunTimes GetSunTimes(JulianDateTime date, double latitude, double longitude)
    Returns a SunTimes struct containing a set of important solar events for the given date and location:

  • solarNoon, nadir
  • sunrise, sunset
  • sunriseEnd, sunsetStart
  • dawn, dusk
  • nauticalDawn, nauticalDusk
  • nightEnd, night

  • goldenHourEnd, goldenHour
    Each field is a JulianDateTime. Times are computed using the internal solar algorithms and the altitude thresholds defined by the static fields.

  • private MoonCoords GetMoonCoords(double d)
    Computes approximate lunar equatorial coordinates and distance (in km) for days since J2000. Internal helper.

  • public MoonCoordinate GetMoonPosition(JulianDateTime date, double latitude, double longitude)
    Returns the Moon's topocentric coordinates (azimuth and altitude in radians), distance (km), and parallactic angle for the given date and location. Applies an atmospheric refraction correction to altitude.

  • public MoonIllumination GetMoonIllumination(JulianDateTime date)
    Computes the Moon's illumination data for the date: fraction illuminated (0..1), phase (0..1 where 0/1 = new/full depending on convention used here), and the angle of the bright limb. Uses Sun and Moon equatorial positions and geometric relationships.

Nested types of interest (referenced by methods above) - SunTimes (public nested struct): holds a series of JulianDateTime fields for solar events and overrides ToString() to produce a human-readable block of times. - EquatorialCoordinate, TopocentricCoordinates, MoonCoords, MoonCoordinate, MoonIllumination, JulianDateTime — these are used/returned by SunMoonData methods and are defined elsewhere in the codebase. JulianDateTime appears to support construction from a Julian day double.

Usage Example

// Example usage of SunMoonData to compute sun and moon events/positions.
// Assumes JulianDateTime and coordinate result types exist in the environment.

var sunMoon = new Colossal.Atmosphere.SunMoonData();

// Create a JulianDateTime for the current UTC time (exact constructor depends on the project's API)
JulianDateTime now = new JulianDateTime(DateTime.UtcNow); // adjust if a different ctor/factory is used

double latitude = 40.7128;   // degrees (e.g., New York City)
double longitude = -74.0060; // degrees

// Get Sun position (azimuth/altitude in radians)
TopocentricCoordinates sunPos = sunMoon.GetSunPosition(now, latitude, longitude);
// Example: convert radians to degrees if needed
double sunAzDeg = math.degrees(sunPos.azimuth);
double sunAltDeg = math.degrees(sunPos.altitude);

// Get Sun event times for today at this location
SunMoonData.SunTimes times = sunMoon.GetSunTimes(now, latitude, longitude);
// times.sunrise, times.sunset, times.solarNoon, etc., are JulianDateTime values

// Get Moon position and illumination
MoonCoordinate moonPos = sunMoon.GetMoonPosition(now, latitude, longitude);
MoonIllumination moonIll = sunMoon.GetMoonIllumination(now);

// moonPos.distance is in kilometers (approx), moonIll.fraction is 0..1

// Example debug print
Console.WriteLine($"Sun Azimuth: {sunAzDeg:F2}°, Altitude: {sunAltDeg:F2}°");
Console.WriteLine($"Sunrise: {times.sunrise}, Sunset: {times.sunset}");
Console.WriteLine($"Moon illuminated fraction: {moonIll.fraction:F3}, phase: {moonIll.phase:F3}");

Notes: - All angular results are returned in radians. Convert to degrees (math.degrees) for display. - JulianDateTime creation/formatting depends on the supporting type provided in the engine; adjust constructors/factories accordingly. - Algorithms are approximate and intended for in-game visual timing rather than high-precision astronomical predictions.