astral

Documentation

Index

• Constants
• Variables
• func Azimuth(observer Observer, dateandtime time.Time) float64
• func BlueHour(observer Observer, date time.Time, direction SunDirection) (time.Time, time.Time, error)
• func Dawn(observer Observer, date time.Time, depression float64) (time.Time, error)
• func Daylight(observer Observer, date time.Time) (time.Time, time.Time, error)
• func Dusk(observer Observer, date time.Time, depression float64) (time.Time, error)
• func Elevation(observer Observer, dateandtime time.Time, with_refraction bool) float64
• func GoldenHour(observer Observer, date time.Time, direction SunDirection) (time.Time, time.Time, error)
• func Midnight(observer Observer, date time.Time) time.Time
• func MoonPhase(date time.Time) float64
• func MoonPhaseDescription(x float64) (string, error)
• func Night(observer Observer, date time.Time) (time.Time, time.Time, error)
• func Noon(observer Observer, date time.Time) time.Time
• func Sunrise(observer Observer, date time.Time) (time.Time, error)
• func Sunset(observer Observer, date time.Time) (time.Time, error)
• func TimeAtElevation(observer Observer, elevation float64, date time.Time, direction SunDirection) (time.Time, error)
• func Twilight(observer Observer, date time.Time, direction SunDirection) (time.Time, time.Time, error)
• func Zenith(observer Observer, dateandtime time.Time, with_refraction bool) float64
• func ZenithAndAzimuth(observer Observer, dateandtime time.Time, with_refraction bool) (float64, float64)
• type Observer
• type SunDirection

Constants

const (
	DepressionCivil        float64 = 6.0
	DepressionNautical     float64 = 12.0
	DepressionAstronomical float64 = 18.0
)

Variables

var (
	ErrAlwaysBelow = errors.New("sun is always below the horizon on this day, at this location")
	ErrAlwaysAbove = errors.New("sun is always above the horizon on this day, at this location")
)

Functions

func Azimuth

func Azimuth(observer Observer, dateandtime time.Time) float64

Calculate the azimuth angle of the sun. Args:

observer:    Observer to calculate the solar azimuth for
dateandtime: The date and time for which to calculate the angle.

Returns:

The azimuth angle in degrees clockwise from North.

func BlueHour

func BlueHour(observer Observer, date time.Time, direction SunDirection) (time.Time, time.Time, error)

Raises:

ValueError: if the sun does not transit the elevations -4 & -6 degrees

func Dawn

func Dawn(observer Observer, date time.Time, depression float64) (time.Time, error)

Calculate dawn time. Args:

observer:   Observer to calculate dawn for
date:       Date to calculate for.
depression: Number of degrees below the horizon to use to calculate dawn.
            Default is for Civil dawn i.e. 6.0
tzinfo:     Timezone to return times in. Default is UTC.

Returns:

Date and time at which dawn occurs.

func Daylight

func Daylight(observer Observer, date time.Time) (time.Time, time.Time, error)

Calculate daylight start and end times. Args:

observer Observer to calculate daylight for
date:     Date to calculate for.
tzinfo:   Timezone to return times in. Default is UTC.

Returns:

A tuple of the date and time at which daylight starts and ends.

Raises:

ValueError: if the sun does not rise or does not set

func Dusk

func Dusk(observer Observer, date time.Time, depression float64) (time.Time, error)

if isinstance(tzinfo, str) {
	tzinfo = pytz.timezone(tzinfo)
}

if date.IsZero() {
	date := today(tzinfo)
}

func Elevation

func Elevation(observer Observer, dateandtime time.Time, with_refraction bool) float64

Calculate the sun's angle of elevation. Args:

observer:    Observer to calculate the solar elevation for
dateandtime: The date and time for which to calculate the angle.
with_refraction: If True adjust elevation to take refraction into account

Returns:

The elevation angle in degrees above the horizon.

func GoldenHour

func GoldenHour(observer Observer, date time.Time, direction SunDirection) (time.Time, time.Time, error)

Returns the start and end times of the Golden Hour when the sun is traversing in the specified direction. This method uses the definition from PhotoPills i.e. the golden hour is when the sun is between 4 degrees below the horizon and 6 degrees above. Args:

observer:  Observer to calculate the golden hour for
date:      Date for which to calculate the times.

direction: Determines whether the time is for the sun rising or setting.
              Use ``SunDirectionRising`` or ``SunDirectionSetting``.
tzinfo:    Timezone to return times in. Default is UTC.

Returns:

A tuple of the date and time at which the Golden Hour starts and ends.

Raises:

ValueError: if the sun does not transit the elevations -4 & +6 degrees

func Midnight

func Midnight(observer Observer, date time.Time) time.Time

Calculate solar midnight time. Note:

This calculates the solar midnight that is closest
to 00:00:00 of the specified date i.e. it may return a time that is on
the previous day.

Args:

observer: An observer viewing the sun at a specific, latitude, longitude and elevation
date:     Date to calculate for. Default is today for the specified tzinfo.

Returns:

Date and time at which midnight occurs.

func MoonPhase

func MoonPhase(date time.Time) float64

Calculates the phase of the moon on the specified date. Args:

date: The date to calculate the phase for. Dates are always in the UTC timezone.
      If not specified then today's date is used.

Returns:

A number designating the phase.
============  ==============
0 .. 6.99     New moon
7 .. 13.99    First quarter
14 .. 20.99   Full moon
21 .. 27.99   Last quarter
============  ==============

func MoonPhaseDescription

func MoonPhaseDescription(x float64) (string, error)

MoonPhaseDescription returns the description of the given moon phase.

func Night

func Night(observer Observer, date time.Time) (time.Time, time.Time, error)

Calculate night start and end times. Night is calculated to be between astronomical dusk on the date specified and astronomical dawn of the next day. Args:

observer Observer to calculate night for
date:     Date to calculate for. Default is today's date for the
          specified tzinfo.
tzinfo:   Timezone to return times in. Default is UTC.

Returns:

A tuple of the date and time at which night starts and ends.

Raises:

ValueError: if dawn does not occur on the specified date or
            dusk on the following day

func Noon

func Noon(observer Observer, date time.Time) time.Time

Calculate solar noon time when the sun is at its highest point. Args:

observer: An observer viewing the sun at a specific, latitude, longitude and elevation
date:     Date to calculate for. Default is today for the specified tzinfo.

Returns:

Date and time at which noon occurs.

func Sunrise

func Sunrise(observer Observer, date time.Time) (time.Time, error)

Calculate sunrise time. Args:

observer Observer to calculate sunrise for
date:     Date to calculate for.
tzinfo:   Timezone to return times in. Default is UTC.

Returns:

Date and time at which sunrise occurs.

func Sunset

func Sunset(observer Observer, date time.Time) (time.Time, error)

Calculate sunset time. Args:

observer Observer to calculate sunset for
date:     Date to calculate for.
tzinfo:   Timezone to return times in. Default is UTC.

Returns:

Date and time at which sunset occurs.

Raises:

    ValueError: if the sun does not reach the horizon

	if isinstance(tzinfo, str) {
		tzinfo = pytz.timezone(tzinfo)
	}
	if date.IsZero() {
		date := today(tzinfo)
	}

func TimeAtElevation

func TimeAtElevation(observer Observer, elevation float64, date time.Time, direction SunDirection) (time.Time, error)

Calculates the time when the sun is at the specified elevation on the specified date. Note:

This method uses positive elevations for those above the horizon.
Elevations greater than 90 degrees are converted to a setting sun
i.e. an elevation of 110 will calculate a setting sun at 70 degrees.

Args:

elevation: Elevation of the sun in degrees above the horizon to calculate for.
observer:  Observer to calculate for
date:      Date to calculate for.
direction: Determines whether the calculated time is for the sun rising or setting.
           Use ``SunDirectionRising`` or ``SunDirectionSetting``. Default is rising.

Returns:

Date and time at which the sun is at the specified elevation.

func Twilight

func Twilight(observer Observer, date time.Time, direction SunDirection) (time.Time, time.Time, error)

Returns the start and end times of Twilight when the sun is traversing in the specified direction. This method defines twilight as being between the time when the sun is at -6 degrees and sunrise/sunset. Args:

observer:  Observer to calculate twilight for
date:      Date for which to calculate the times.

direction: Determines whether the time is for the sun rising or setting.
              Use ``astral.SunDirectionRising`` or ``astral.SunDirectionSetting``.
tzinfo:    Timezone to return times in. Default is UTC.

Returns:

A tuple of the date and time at which twilight starts and ends.

Raises:

ValueError: if the sun does not rise or does not set

func Zenith

func Zenith(observer Observer, dateandtime time.Time, with_refraction bool) float64

Returns:

The zenith angle in degrees.

func ZenithAndAzimuth

func ZenithAndAzimuth(observer Observer, dateandtime time.Time, with_refraction bool) (float64, float64)

Types

type Observer

type Observer struct {
	Latitude  float64
	Longitude float64
	Elevation float64
}

type SunDirection

type SunDirection int

const (
	SunDirectionRising  SunDirection = 1
	SunDirectionSetting SunDirection = -1
)