Skip to content

Colossal.Atmosphere.SunCalculator

Assembly: Assembly-CSharp (game)
Namespace: Colossal.Atmosphere

Type: public class

Base: System.Object

Summary:
SunCalculator provides astronomical calculations for the Sun used by the atmosphere/lighting system. It can compute the sun's topocentric position (azimuth and altitude) for a given date/time and location, and it can compute daily events such as dawn, sunrise, transit (solar noon), sunset and dusk as well as twilight ranges (astronomical, nautical, civil). The class exposes public nested structs to represent time frames and day information and relies on Julian date conversions and standard solar position algorithms.

Fields

  • private static readonly double J2000
    Contains the Julian date of the epoch J2000.0 (2451545.0). Used as a reference for many astronomical calculations.

  • private static readonly double h0
    Apparent solar altitude threshold for sunrise/sunset, including atmospheric refraction and solar disk radius (converted to radians, -0.83°).

  • private static readonly double d0
    Approximate angular radius of the Sun (in radians, 0.53°). Used for refined sunrise/sunset computations.

  • private static readonly double h1
    Solar altitude threshold for civil twilight (in radians, -6°).

  • private static readonly double h2
    Solar altitude threshold for nautical twilight (in radians, -12°).

  • private static readonly double h3
    Solar altitude threshold for astronomical twilight (in radians, -18°).

  • private static readonly double P
    Argument used in ecliptic longitude calculation (planetary/perihelion constant, converted to radians).

  • private static readonly double e
    Obliquity of the Earth's axis (approx. 23.45°, in radians).

  • private static readonly double th0
    Base sidereal time constant (in radians).

  • private static readonly double th1
    Sidereal time rate (degrees per Julian day converted to radians).

  • private static readonly double M0
    Solar mean anomaly base (in radians).

  • private static readonly double M1
    Solar mean anomaly rate per day (in radians).

  • private static readonly double C1
    Coefficients used for the equation of center (first-order).

  • private static readonly double C2
    Coefficients used for the equation of center (second-order).

  • private static readonly double C3
    Coefficients used for the equation of center (third-order).

  • private static readonly double J0
    Julian transit constant used when computing Julian cycle / approximate transit.

  • private static readonly double J1
    Correction term added to approximate solar transit.

  • private static readonly double J2
    Second order correction term for solar transit.

  • public struct Twiligth
    Represents three TimeFrame values for twilights (astronomical, nautical, civil). Note: spelled "Twiligth" in source.

  • public struct TimeFrame
    Represents a time interval with DateTime start and end. Overrides ToString() to show Start and End.

  • public struct DayInfo
    Contains dawn, sunrise (TimeFrame), transit (solar noon), sunset (TimeFrame), dusk, morningTwilight (Twiligth), nightTwilight (Twiligth), and an override ToString() that summarizes these values.

Properties

  • None (SunCalculator exposes only methods and nested types; no public properties).

Constructors

  • public SunCalculator()
    No explicit constructor is defined in source. The class is used as a static utility style type (most methods are static); you do not need to instantiate it to use the provided static methods.

Methods

  • public static DayInfo GetDayInfo(DateTime date, float latitude, float longitude)
    Computes detailed sun event times for the specified date and geographic location. Input latitude and longitude are expected in degrees. The returned DayInfo contains:
  • dawn (DateTime)
  • sunrise (TimeFrame with start/end)
  • transit (solar noon, DateTime)
  • sunset (TimeFrame with start/end)
  • dusk (DateTime)
  • morningTwilight and nightTwilight (Twiligth structures with astronomical/nautical/civil TimeFrames)

Implementation notes: - Internally converts the provided date to a Julian date using ConvertToJulianDateTime (extension/helper presumed available in the project). - Uses a set of standard astronomical formulas (solar mean anomaly, equation of center, ecliptic longitude, declination, hour angles, solar transit) to compute the times. - All internal angle math uses radians (Unity.Mathematics.math helpers).

  • public static TopocentricCoordinates GetSunPosition(DateTime date, float latitude, float longitude)
    Returns the topocentric coordinates (azimuth and altitude) of the Sun for the specified date/time and location. Inputs latitude and longitude are in degrees. The resulting TopocentricCoordinates (defined in Colossal.Atmosphere.Internal) contains:
  • azimuth (radians)
  • altitude (radians)

Implementation notes: - Converts the given DateTime to a Julian date and calls the private GetSunPosition(J, lw, phi) overload. - Longitude is negated and converted to radians before internal use (lw = -radians(longitude)). - Latitude is converted to radians.

The class also contains multiple private helper methods used by the public APIs:

  • private static double GetEclipticLongitude(double M, double C)
    Returns ecliptic longitude of the Sun given mean anomaly (M) and the equation of center (C).

  • private static double GetHourAngle(double h, double phi, double d)
    Computes hour angle for a given solar altitude threshold h, observer latitude phi and Sun declination d. Returns an absolute hour angle (radians) via acos.

  • private static double GetSunDeclination(double Lsun)
    Returns the declination of the Sun given ecliptic longitude Lsun.

  • private static double GetSolarMeanAnomaly(double Js)
    Computes the solar mean anomaly from a given Julian date Js.

  • private static double GetEquationOfCenter(double M)
    Computes the equation of center for the Sun from mean anomaly M (small corrections to elliptical orbit).

  • private static double GetJulianCycle(double J, double lw)
    Computes the Julian cycle (n) used to find the day's solar transit.

  • private static double GetSolarTransit(double Js, double M, double Lsun)
    Computes the corrected solar transit (solar noon) from approximate values.

  • private static double GetApproxSolarTransit(double Ht, double lw, double n)
    Returns the approximate solar transit J value used as the starting point for corrections.

  • private static double GetSunsetJulianDate(double w0, double M, double Lsun, double lw, double n)
    Computes the Julian date of sunset for a given hour angle w0 and other parameters by computing the corrected solar transit.

  • private static double GetSunriseJulianDate(double Jtransit, double Jset)
    Given transit and set Julian dates, returns the corresponding sunrise Julian date (assuming symmetric around transit).

  • private static double GetRightAscension(double Lsun)
    Computes the Sun's right ascension from its ecliptic longitude.

  • private static double GetSiderealTime(double J, double lw)
    Computes the sidereal time at the given Julian date and longitude.

  • private static double GetAzimuth(double th, double a, double phi, double d)
    Computes the topocentric azimuth (radians) from sidereal time (th), right ascension (a), latitude (phi), and declination (d).

  • private static double GetAltitude(double th, double a, double phi, double d)
    Computes the topocentric altitude (radians) from sidereal time (th), right ascension (a), latitude (phi), and declination (d).

  • private static TopocentricCoordinates GetSunPosition(double J, double lw, double phi)
    Internal overload that computes azimuth and altitude from a Julian date (J), longitude westwards (lw, radians, negative east-longitude), and latitude (phi, radians).

Notes on outputs: - Times returned in DayInfo are DateTime values in the same timezone/format as provided/produced by the ConvertToDateTime helper used in the code. The code uses Julian date conversion helpers (ConvertToJulianDateTime / ConvertToDateTime) which are external to this file — ensure these extensions are available and behave as expected (UTC vs local interpretation). - Azimuth and altitude are returned in radians. Convert to degrees for readability where required (math.degrees or (float)(radians * (180.0 / Math.PI))).

Usage Example

// Example: query sun events and position for Oslo on 2025-06-21 12:00 UTC
DateTime dt = new DateTime(2025, 6, 21, 12, 0, 0, DateTimeKind.Utc);
float latitude = 59.9139f;  // Oslo latitude in degrees
float longitude = 10.7522f; // Oslo longitude in degrees

// Get day information (dawn, sunrise, transit, sunset, dusk, twilights)
Colossal.Atmosphere.SunCalculator.DayInfo day = Colossal.Atmosphere.SunCalculator.GetDayInfo(dt, latitude, longitude);
Console.WriteLine(day.ToString());

// Get sun position (azimuth, altitude) at a specific time and place
Colossal.Atmosphere.Internal.TopocentricCoordinates pos = Colossal.Atmosphere.SunCalculator.GetSunPosition(dt, latitude, longitude);

// Convert radians to degrees for display
double azimuthDeg = pos.azimuth * (180.0 / Math.PI);
double altitudeDeg = pos.altitude * (180.0 / Math.PI);
Console.WriteLine($"Azimuth: {azimuthDeg:F2}°, Altitude: {altitudeDeg:F2}°");

{{ Additional notes: - The nested struct name "Twiligth" contains a typo and is spelled that way in the source; be careful when referencing it. - The implementation assumes availability of ConvertToJulianDateTime() and ConvertToDateTime() helpers/extensions for DateTime <-> Julian conversions (not included in this file). - All internal angle math uses radians (Unity.Mathematics.math), so convert units where appropriate for UI or debugging. - This class is suitable for modding uses where realistic daylight/twilight intervals and sun directions are needed for atmosphere, lighting, or gameplay events. }}