1 throw new Error("Description for built in functions. Must not be included!");
  2 /**
  3  * @fileOverview
  4  *    Documentation of Sun class built into dimctrl.
  5  */
  6 
  7 /**
  8  * @namespace
  9  *
 10  * Namespace for functions returning astrometry information about the Sun.
 11  *
 12  * @author <a href="mailto:thomas.bretz@epfl.ch">Thomas Bretz</a>
 13  */
 14 var Sun = { };
 15 
 16 /**
 17  * Calculate sun rise, set and transit times.
 18  *
 19  * Calculates the sun's rise and set time, above and below horizon,
 20  * and the time of culmination (transit time) for the given time.
 21  * As a second argument the angle abov or below horizon of interest
 22  * can be provided. The calculation is done using libnova's
 23  * ln_get_solar_rst_horizon and is always performed for the FACT
 24  * site at La Palma.
 25  *
 26  * @param {Number,String} [angle=null]
 27  *    Angle above (positive) or below (negative) horizon. The
 28  *    angle can be given as Number in degree or as string referring to
 29  *    "horizon" (0deg), "civil" (-6deg), "nautical" (-12deg),
 30  *    "fact" (-15deg), "astronomical" (-18deg). Strings can be abbreviated
 31  *    down to "h", "c", "n", "f" and "a". If the argument is omitted or
 32  *    null, a value referring to the appearance or the disappearance of
 33  *    the Sun's disk at horizon is chosen (~-0.8deg).
 34  *
 35  * @param {Date} [time=new Date()]
 36  *    Date for which the times should be calculated. Note that the date
 37  *    is converted to UTC and the times are calculated such that the
 38  *    Date (yy/mm/dd) is identical for all returned values.
 39  *
 40  * @type {Object}
 41  *
 42  * @returns
 43  *    An object with the following properties is returned: time {Date}
 44  *    the provided time; rise, transit, set {Date} times of rise, set and
 45  *    transit; horizon {Number} the angle used for the calculation;
 46  *    isUp {Boolean} whether the sun is above or below the given horizon
 47  *    at th given time. If the sun does not rise or set, the properties
 48  *    rise, transit and set will be undefined, isUp will refer to
 49  *    the fact whether the sun is the whole day above or below the
 50  *    horizon (0deg).
 51  *
 52  * @example
 53  *    var date = new Date("2012-10-25 16:30 GMT"); // Date in UTC
 54  *    console.out(JSON.stringify(Sun.horizon());
 55  *    console.out(JSON.stringify(Sun.horizon("astro"));
 56  *    console.out(JSON.stringify(Sun.horizon(-12, date); // nautical
 57  */
 58 Sun.horizon = function() { /* [native code] */ }
 59