class SunTimes::SunTime

Defined in:

sun_times.cr

Constant Summary

CORRECTION_ECCENTRICITY = 0.00534
CORRECTION_OBLIQUITY = 0.00692
DAILY_MOTION = 0.98564736
DEG2RAD = Math::PI / 180.0
EARTH_PERIHELION_LONG = 102.9373
EQUATION_CENTER_COEFF_1 = 1.9148

Equation of center coefficients (Meeus 1998)

EQUATION_CENTER_COEFF_2 = 0.0200
EQUATION_CENTER_COEFF_3 = 0.0003
JULIAN_BASE_OFFSET = 1524.5
JULIAN_EPOCH_J2000 = 2451545.0
JULIAN_EPOCH_OFFSET = 4716
JULIAN_MIDNIGHT_FIX = 0.5
JULIAN_MONTH_FACTOR = 30.6001
JULIAN_UNIX_EPOCH = 2440587.5
JULIAN_YEAR_DAYS = 365.25
MEAN_ANOMALY_AT_EPOCH = 357.5291
OBLIQUITY = 23.43929111
RAD2DEG = 180.0 / Math::PI
SECONDS_PER_DAY = 86400.0
SUN_ALTITUDE_ASTRONOMICAL = -18.0
SUN_ALTITUDE_CIVIL = -6.0
SUN_ALTITUDE_NAUTICAL = -12.0
SUN_ALTITUDE_RISE_SET = -0.8333

Constructors

Instance Method Summary

Constructor Detail

def self.new(latitude : Float64, longitude : Float64) #

Initializes a SunTime calculator for the given latitude and longitude.

#latitude - Degrees north (negative for south) #longitude - Degrees east (negative for west)

Example:

SunTimes::SunTime.new(48.87, 2.67)   # Paris
SunTimes::SunTime.new({48.87, 2.67}) # Paris

[View source]
def self.new(coords : Tuple(Float64, Float64)) #

Initializes a SunTime calculator for the given latitude and longitude.

#latitude - Degrees north (negative for south) #longitude - Degrees east (negative for west)

Example:

SunTimes::SunTime.new(48.87, 2.67)   # Paris
SunTimes::SunTime.new({48.87, 2.67}) # Paris

[View source]

Instance Method Detail

def astronomical_dawn(date : Time, location : Time::Location | Nil = nil) : Time #

Returns the time of astronomical dawn (beginning of astronomical twilight). Astronomical twilight occurs when the sun is 18° below the horizon. During this period, the sky is dark enough for astronomical observations.

Arguments:

  • date - Time (date portion is used; time of day ignored)
  • location - Optional Time::Location for local conversion

Returns: Time in UTC or converted to the provided location.

Raises: CalculationError if there is no astronomical dawn (polar night or polar day).

Example:

sun.astronomical_dawn(Time.local(2025, 11, 2), paris)
=> 2025-11-02 06:37:00 UTC

[View source]
def astronomical_dawn?(date : Time, location : Time::Location | Nil = nil) : Time | Nil #

[View source]
def astronomical_dusk(date : Time, location : Time::Location | Nil = nil) : Time #

Returns the time of astronomical dusk (end of astronomical twilight).

See #astronomical_dawn for details about astronomical twilight.


[View source]
def astronomical_dusk?(date : Time, location : Time::Location | Nil = nil) : Time | Nil #

[View source]
def civil_dawn(date : Time, location : Time::Location | Nil = nil) : Time #

Returns the time of civil dawn (beginning of civil twilight). Civil twilight occurs when the sun is 6° below the horizon. During this period, there is enough light for most outdoor activities.

Arguments:

  • date - Time (date portion is used; time of day ignored)
  • location - Optional Time::Location for local conversion

Returns:

Time in UTC or converted to the provided location.

Raises:

CalculationError if there is no civil dawn (polar night or polar day).

Example:

sun.civil_dawn(Time.local(2025, 11, 2), paris)
=> 2025-11-02 06:37:00 UTC

[View source]
def civil_dawn?(date : Time, location : Time::Location | Nil = nil) : Time | Nil #

[View source]
def civil_dusk(date : Time, location : Time::Location | Nil = nil) : Time #

Returns the time of civil dusk (end of civil twilight).

See #civil_dawn for details about civil twilight.


[View source]
def civil_dusk?(date : Time, location : Time::Location | Nil = nil) : Time | Nil #

[View source]
def daylight_length(date : Time, location : Time::Location | Nil = nil) : Time::Span #

Returns the duration of daylight (time between sunrise and sunset) for the given date and location.

Arguments:

  • date - Time (only date portion is used)
  • location - Optional Time::Location for local conversion

Returns:

Time::Span representing total daylight duration.

Returns Time::Span.zero if there is no sunrise/sunset (polar night or polar day).

Example:

sun.daylight_length(Time.local(2025, 11, 2), paris)
=> 9 hours, 50 minutes (approx)

[View source]
def events(date : Time, location : Time::Location | Nil = nil) #

Returns all solar events for the given date and location as a NamedTuple.

Arguments:

  • date - Time (only date portion is used)
  • location - Optional Time::Location for local conversion

Returns:

NamedTuple with all solar events:

Example:

sun.events(Time.local(2025, 11, 2), paris)
=> {astronomical_dawn: ..., nautical_dawn: ..., ...}

[View source]
def latitude : Float64 #

[View source]
def longitude : Float64 #

[View source]
def nautical_dawn(date : Time, location : Time::Location | Nil = nil) : Time #

Returns the time of nautical dawn (beginning of nautical twilight). Nautical twilight occurs when the sun is 12° below the horizon. During this period, the horizon is still visible for navigation.

Arguments:

  • date - Time (date portion is used; time of day ignored)
  • location - Optional Time::Location for local conversion

Returns:

Time in UTC or converted to the provided location.

Raises:

CalculationError if there is no nautical dawn (polar night or polar day).

Example:

sun.nautical_dawn(Time.local(2025, 11, 2), paris)
=> 2025-11-02 06:37:00 UTC

[View source]
def nautical_dawn?(date : Time, location : Time::Location | Nil = nil) : Time | Nil #

[View source]
def nautical_dusk(date : Time, location : Time::Location | Nil = nil) : Time #

Returns the time of nautical dusk (end of nautical twilight). See #nautical_dawn for details about nautical twilight.


[View source]
def nautical_dusk?(date : Time, location : Time::Location | Nil = nil) : Time | Nil #

[View source]
def solar_noon(date : Time, location : Time::Location | Nil = nil) : Time #

Returns the UTC or local time of solar noon (Sun's highest point) for the given date.

Solar noon corresponds to the moment when the Sun crosses the local meridian. This method uses the same underlying model as sunrise/sunset calculations.

Arguments:

  • date - Time (only the date portion is used)
  • location - Optional Time::Location for local conversion

Returns:

Time of local solar noon (UTC by default)

Example:

sun.solar_noon(Time.local(2025, 11, 2), paris)
=> 2025-11-02 12:32:50 +01:00

[View source]
def sunrise(date : Time, location : Time::Location | Nil = nil) : Time #

Returns the UTC time of sunrise for the given date.

Arguments:

  • date - Time (date portion is used; time of day ignored)
  • location - Optional Time::Location for local conversion

Returns:

Time in UTC or converted to the provided location.

Raises:

CalculationError if there is no sunrise (polar night or polar day).

Example:

sun.sunrise(Time.local(2025, 11, 2))
=> 2025-11-02 06:37:00 UTC

[View source]
def sunrise?(date : Time, location : Time::Location | Nil = nil) : Time | Nil #

Non-raising convenience variants that return nil when the event does not occur.


[View source]
def sunset(date : Time, location : Time::Location | Nil = nil) : Time #

Returns the UTC time of sunset for the given date.

Arguments and behavior are identical to #sunrise.

Raises:

CalculationError if there is no sunset (polar night or polar day).

Example:

sun.sunset(Time.local(2025, 11, 2))
=> 2025-11-02 16:47:00 UTC

[View source]
def sunset?(date : Time, location : Time::Location | Nil = nil) : Time | Nil #

[View source]