From c689bdd0a0f4b96a2a10fb4c88d502c7c00d27be Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Thu, 20 Feb 2014 15:52:15 +0100 Subject: info: solar position MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- info/blueshift.texinfo | 92 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 91 insertions(+), 1 deletion(-) diff --git a/info/blueshift.texinfo b/info/blueshift.texinfo index 91f42e0..0ef6134 100644 --- a/info/blueshift.texinfo +++ b/info/blueshift.texinfo @@ -601,9 +601,99 @@ use Python's time API. @code{periodically} will never be invoked with fake time. Just do not mix as you could theoretically get on two different seconds, minutes, hours, or even days, months or -years, the delay between Blueshifts time measure +years, the delay between Blueshift's timestamp and yours could overlap an increase in the second. +Blueshift includes a simple way to get the Sun's +position. The function @code{sun(latitude, longitude)} +returns the visibility of the Sun as an [0, 1] floating +point. It has three optional parameters: + +@table @code +@item t = None +The time in Julian Centuries. + +@item low = -6.0 +The suns elevation at the limit to high night, that +is, the highest possible position (measured in degrees) +of the sun before it becomes visible. + +@item high = 3.0 +The suns elevation at the limit to high day, that is, +the lowest possible position (measured in degrees) of +the before it starts becoming less visible (twilight.) +@end table + +To convert a time to Julian Centuries, you can use +the function @code{epoch_to_julian_centuries}. It takes +one argument, the local POSIX time, that is, the number of +seconds that have elapsed since 1970-(01)Jan-01 00:00:00 +local time, not counting leap seconds. + +A set of functions that are used to calculate the Sun's +are provided: + +@table @code +@item julian_day_to_epoch(t) +Converts a Julian Day timestamp to a POSIX time timestamp. + +@item epoch_to_julian_day(t) +Converts a POSIX time timestamp to a Julian Day timestamp. + +@item julian_day_to_julian_centuries(t) +Converts a Julian Day timestamp to a Julian Centuries timestamp. + +@item julian_centuries_to_julian_day(t) +Converts a Julian Centuries timestamp to a Julian Day timestamp. + +@item epoch_to_julian_centuries(t) +Converts a POSIX time timestamp to a Julian Centuries timestamp. + +@item julian_centuries_to_epoch(t) +Converts a Julian Centuries timestamp to a POSIX time timestamp. + +@item epoch() +Returns the current time in POSIX time. + +@item julian_day() +Returns the current time in Julian Day time. + +@item julian_centuries() +Returns the current time in Julian Centuries time. + +@item radians(deg) +Converts from degrees to radians. + +@item degrees(rad) +Converts from radians to degrees. + +@c TODO : these could be documented (in the source code as well) +@item sun_geometric_mean_longitude(t) +@item sun_geometric_mean_anomaly(t) +@item earth_orbit_eccentricity(t) +@item sun_equation_of_centre(t) +@item sun_real_longitude(t) +@item sun_apparent_longitude(t) +@item mean_ecliptic_obliquity(t) +@item corrected_mean_ecliptic_obliquity(t) +@item solar_declination(t) +@item equation_of_time(t) +@item hour_angle_from_elevation(latitude, declinaton, elevation) +@item elevation_from_hour_angle(latitude, declinaton, hour_angle) +@item time_of_solar_noon(t, longitude) +@item time_of_solar_elevation(t, noon, latitude, longitude, elevation) +@item solar_elevation_from_time(t, latitude, longitude) +@item solar_elevation(latitude, longitude, t = None) +Does the same thing as @code{solar_elevation_from_time}, +except the time is optional and defaults to the current time. +@end table + +For all functions beneath @code{degrees}, @code{t} is the +time in Julian Centuries. All parameters are floating point +and may not be @code{None}, except for in @code{solar_elevation}, +as specified. + + @node GNU Free Documentation License @appendix GNU Free Documentation License -- cgit v1.2.3-70-g09d2