/************************************************************************ * Copyright (C) 1996-2008, International Business Machines Corporation * * and others. All Rights Reserved. * ************************************************************************ * 2003-nov-07 srl Port from Java */ #ifndef ASTRO_H #define ASTRO_H #include "unicode/utypes.h" #if !UCONFIG_NO_FORMATTING #include "gregoimp.h" // for Math #include "unicode/unistr.h" U_NAMESPACE_BEGIN /** * <code>CalendarAstronomer</code> is a class that can perform the calculations to * determine the positions of the sun and moon, the time of sunrise and * sunset, and other astronomy-related data. The calculations it performs * are in some cases quite complicated, and this utility class saves you * the trouble of worrying about them. * <p> * The measurement of time is a very important part of astronomy. Because * astronomical bodies are constantly in motion, observations are only valid * at a given moment in time. Accordingly, each <code>CalendarAstronomer</code> * object has a <code>time</code> property that determines the date * and time for which its calculations are performed. You can set and * retrieve this property with {@link #setDate setDate}, {@link #getDate getDate} * and related methods. * <p> * Almost all of the calculations performed by this class, or by any * astronomer, are approximations to various degrees of accuracy. The * calculations in this class are mostly modelled after those described * in the book * <a href="http://www.amazon.com/exec/obidos/ISBN=0521356997" target="_top"> * Practical Astronomy With Your Calculator</a>, by Peter J. * Duffett-Smith, Cambridge University Press, 1990. This is an excellent * book, and if you want a greater understanding of how these calculations * are performed it a very good, readable starting point. * <p> * <strong>WARNING:</strong> This class is very early in its development, and * it is highly likely that its API will change to some degree in the future. * At the moment, it basically does just enough to support {@link IslamicCalendar} * and {@link ChineseCalendar}. * * @author Laura Werner * @author Alan Liu * @internal */ class U_I18N_API CalendarAstronomer : public UMemory { public: // some classes public: /** * Represents the position of an object in the sky relative to the ecliptic, * the plane of the earth's orbit around the Sun. * This is a spherical coordinate system in which the latitude * specifies the position north or south of the plane of the ecliptic. * The longitude specifies the position along the ecliptic plane * relative to the "First Point of Aries", which is the Sun's position in the sky * at the Vernal Equinox. * <p> * Note that Ecliptic objects are immutable and cannot be modified * once they are constructed. This allows them to be passed and returned by * value without worrying about whether other code will modify them. * * @see CalendarAstronomer.Equatorial * @see CalendarAstronomer.Horizon * @internal */ class U_I18N_API Ecliptic : public UMemory { public: /** * Constructs an Ecliptic coordinate object. * <p> * @param lat The ecliptic latitude, measured in radians. * @param lon The ecliptic longitude, measured in radians. * @internal */ Ecliptic(double lat = 0, double lon = 0) { latitude = lat; longitude = lon; } /** * Setter for Ecliptic Coordinate object * @param lat The ecliptic latitude, measured in radians. * @param lon The ecliptic longitude, measured in radians. * @internal */ void set(double lat, double lon) { latitude = lat; longitude = lon; } /** * Return a string representation of this object * @internal */ UnicodeString toString() const; /** * The ecliptic latitude, in radians. This specifies an object's * position north or south of the plane of the ecliptic, * with positive angles representing north. * @internal */ double latitude; /** * The ecliptic longitude, in radians. * This specifies an object's position along the ecliptic plane * relative to the "First Point of Aries", which is the Sun's position * in the sky at the Vernal Equinox, * with positive angles representing east. * <p> * A bit of trivia: the first point of Aries is currently in the * constellation Pisces, due to the precession of the earth's axis. * @internal */ double longitude; }; /** * Represents the position of an * object in the sky relative to the plane of the earth's equator. * The <i>Right Ascension</i> specifies the position east or west * along the equator, relative to the sun's position at the vernal * equinox. The <i>Declination</i> is the position north or south * of the equatorial plane. * <p> * Note that Equatorial objects are immutable and cannot be modified * once they are constructed. This allows them to be passed and returned by * value without worrying about whether other code will modify them. * * @see CalendarAstronomer.Ecliptic * @see CalendarAstronomer.Horizon * @internal */ class U_I18N_API Equatorial : public UMemory { public: /** * Constructs an Equatorial coordinate object. * <p> * @param asc The right ascension, measured in radians. * @param dec The declination, measured in radians. * @internal */ Equatorial(double asc = 0, double dec = 0) : ascension(asc), declination(dec) { } /** * Setter * @param asc The right ascension, measured in radians. * @param dec The declination, measured in radians. * @internal */ void set(double asc, double dec) { ascension = asc; declination = dec; } /** * Return a string representation of this object, with the * angles measured in degrees. * @internal */ UnicodeString toString() const; /** * Return a string representation of this object with the right ascension * measured in hours, minutes, and seconds. * @internal */ //String toHmsString() { //return radToHms(ascension) + "," + radToDms(declination); //} /** * The right ascension, in radians. * This is the position east or west along the equator * relative to the sun's position at the vernal equinox, * with positive angles representing East. * @internal */ double ascension; /** * The declination, in radians. * This is the position north or south of the equatorial plane, * with positive angles representing north. * @internal */ double declination; }; /** * Represents the position of an object in the sky relative to * the local horizon. * The <i>Altitude</i> represents the object's elevation above the horizon, * with objects below the horizon having a negative altitude. * The <i>Azimuth</i> is the geographic direction of the object from the * observer's position, with 0 representing north. The azimuth increases * clockwise from north. * <p> * Note that Horizon objects are immutable and cannot be modified * once they are constructed. This allows them to be passed and returned by * value without worrying about whether other code will modify them. * * @see CalendarAstronomer.Ecliptic * @see CalendarAstronomer.Equatorial * @internal */ class U_I18N_API Horizon : public UMemory { public: /** * Constructs a Horizon coordinate object. * <p> * @param alt The altitude, measured in radians above the horizon. * @param azim The azimuth, measured in radians clockwise from north. * @internal */ Horizon(double alt=0, double azim=0) : altitude(alt), azimuth(azim) { } /** * Setter for Ecliptic Coordinate object * @param alt The altitude, measured in radians above the horizon. * @param azim The azimuth, measured in radians clockwise from north. * @internal */ void set(double alt, double azim) { altitude = alt; azimuth = azim; } /** * Return a string representation of this object, with the * angles measured in degrees. * @internal */ UnicodeString toString() const; /** * The object's altitude above the horizon, in radians. * @internal */ double altitude; /** * The object's direction, in radians clockwise from north. * @internal */ double azimuth; }; public: //------------------------------------------------------------------------- // Assorted private data used for conversions //------------------------------------------------------------------------- // My own copies of these so compilers are more likely to optimize them away static const double PI; /** * The average number of solar days from one new moon to the next. This is the time * it takes for the moon to return the same ecliptic longitude as the sun. * It is longer than the sidereal month because the sun's longitude increases * during the year due to the revolution of the earth around the sun. * Approximately 29.53. * * @see #SIDEREAL_MONTH * @internal * @deprecated ICU 2.4. This class may be removed or modified. */ static const double SYNODIC_MONTH; //------------------------------------------------------------------------- // Constructors //------------------------------------------------------------------------- /** * Construct a new <code>CalendarAstronomer</code> object that is initialized to * the current date and time. * @internal */ CalendarAstronomer(); /** * Construct a new <code>CalendarAstronomer</code> object that is initialized to * the specified date and time. * @internal */ CalendarAstronomer(UDate d); /** * Construct a new <code>CalendarAstronomer</code> object with the given * latitude and longitude. The object's time is set to the current * date and time. * <p> * @param longitude The desired longitude, in <em>degrees</em> east of * the Greenwich meridian. * * @param latitude The desired latitude, in <em>degrees</em>. Positive * values signify North, negative South. * * @see java.util.Date#getTime() * @internal */ CalendarAstronomer(double longitude, double latitude); /** * Destructor * @internal */ ~CalendarAstronomer(); //------------------------------------------------------------------------- // Time and date getters and setters //------------------------------------------------------------------------- /** * Set the current date and time of this <code>CalendarAstronomer</code> object. All * astronomical calculations are performed based on this time setting. * * @param aTime the date and time, expressed as the number of milliseconds since * 1/1/1970 0:00 GMT (Gregorian). * * @see #setDate * @see #getTime * @internal */ void setTime(UDate aTime); /** * Set the current date and time of this <code>CalendarAstronomer</code> object. All * astronomical calculations are performed based on this time setting. * * @param aTime the date and time, expressed as the number of milliseconds since * 1/1/1970 0:00 GMT (Gregorian). * * @see #getTime * @internal */ void setDate(UDate aDate) { setTime(aDate); } /** * Set the current date and time of this <code>CalendarAstronomer</code> object. All * astronomical calculations are performed based on this time setting. * * @param jdn the desired time, expressed as a "julian day number", * which is the number of elapsed days since * 1/1/4713 BC (Julian), 12:00 GMT. Note that julian day * numbers start at <em>noon</em>. To get the jdn for * the corresponding midnight, subtract 0.5. * * @see #getJulianDay * @see #JULIAN_EPOCH_MS * @internal */ void setJulianDay(double jdn); /** * Get the current time of this <code>CalendarAstronomer</code> object, * represented as the number of milliseconds since * 1/1/1970 AD 0:00 GMT (Gregorian). * * @see #setTime * @see #getDate * @internal */ UDate getTime(); /** * Get the current time of this <code>CalendarAstronomer</code> object, * expressed as a "julian day number", which is the number of elapsed * days since 1/1/4713 BC (Julian), 12:00 GMT. * * @see #setJulianDay * @see #JULIAN_EPOCH_MS * @internal */ double getJulianDay(); /** * Return this object's time expressed in julian centuries: * the number of centuries after 1/1/1900 AD, 12:00 GMT * * @see #getJulianDay * @internal */ double getJulianCentury(); /** * Returns the current Greenwich sidereal time, measured in hours * @internal */ double getGreenwichSidereal(); private: double getSiderealOffset(); public: /** * Returns the current local sidereal time, measured in hours * @internal */ double getLocalSidereal(); /** * Converts local sidereal time to Universal Time. * * @param lst The Local Sidereal Time, in hours since sidereal midnight * on this object's current date. * * @return The corresponding Universal Time, in milliseconds since * 1 Jan 1970, GMT. */ //private: double lstToUT(double lst); /** * * Convert from ecliptic to equatorial coordinates. * * @param ecliptic The ecliptic * @param result Fillin result * @return reference to result */ Equatorial& eclipticToEquatorial(Equatorial& result, const Ecliptic& ecliptic); /** * Convert from ecliptic to equatorial coordinates. * * @param eclipLong The ecliptic longitude * @param eclipLat The ecliptic latitude * * @return The corresponding point in equatorial coordinates. * @internal */ Equatorial& eclipticToEquatorial(Equatorial& result, double eclipLong, double eclipLat); /** * Convert from ecliptic longitude to equatorial coordinates. * * @param eclipLong The ecliptic longitude * * @return The corresponding point in equatorial coordinates. * @internal */ Equatorial& eclipticToEquatorial(Equatorial& result, double eclipLong) ; /** * @internal */ Horizon& eclipticToHorizon(Horizon& result, double eclipLong) ; //------------------------------------------------------------------------- // The Sun //------------------------------------------------------------------------- /** * The longitude of the sun at the time specified by this object. * The longitude is measured in radians along the ecliptic * from the "first point of Aries," the point at which the ecliptic * crosses the earth's equatorial plane at the vernal equinox. * <p> * Currently, this method uses an approximation of the two-body Kepler's * equation for the earth and the sun. It does not take into account the * perturbations caused by the other planets, the moon, etc. * @internal */ double getSunLongitude(); /** * TODO Make this public when the entire class is package-private. */ /*public*/ void getSunLongitude(double julianDay, double &longitude, double &meanAnomaly); /** * The position of the sun at this object's current date and time, * in equatorial coordinates. * @param result fillin for the result * @internal */ Equatorial& getSunPosition(Equatorial& result); public: /** * Constant representing the vernal equinox. * For use with {@link #getSunTime getSunTime}. * Note: In this case, "vernal" refers to the northern hemisphere's seasons. * @internal */ // static double VERNAL_EQUINOX(); /** * Constant representing the summer solstice. * For use with {@link #getSunTime getSunTime}. * Note: In this case, "summer" refers to the northern hemisphere's seasons. * @internal */ static double SUMMER_SOLSTICE(); /** * Constant representing the autumnal equinox. * For use with {@link #getSunTime getSunTime}. * Note: In this case, "autumn" refers to the northern hemisphere's seasons. * @internal */ // static double AUTUMN_EQUINOX(); /** * Constant representing the winter solstice. * For use with {@link #getSunTime getSunTime}. * Note: In this case, "winter" refers to the northern hemisphere's seasons. * @internal */ static double WINTER_SOLSTICE(); /** * Find the next time at which the sun's ecliptic longitude will have * the desired value. * @internal */ UDate getSunTime(double desired, UBool next); /** * Returns the time (GMT) of sunrise or sunset on the local date to which * this calendar is currently set. * * NOTE: This method only works well if this object is set to a * time near local noon. Because of variations between the local * official time zone and the geographic longitude, the * computation can flop over into an adjacent day if this object * is set to a time near local midnight. * * @internal */ UDate getSunRiseSet(UBool rise); //------------------------------------------------------------------------- // The Moon //------------------------------------------------------------------------- /** * The position of the moon at the time set on this * object, in equatorial coordinates. * @internal * @return const reference to internal field of calendar astronomer. Do not use outside of the lifetime of this astronomer. */ const Equatorial& getMoonPosition(); /** * The "age" of the moon at the time specified in this object. * This is really the angle between the * current ecliptic longitudes of the sun and the moon, * measured in radians. * * @see #getMoonPhase * @internal */ double getMoonAge(); /** * Calculate the phase of the moon at the time set in this object. * The returned phase is a <code>double</code> in the range * <code>0 <= phase < 1</code>, interpreted as follows: * <ul> * <li>0.00: New moon * <li>0.25: First quarter * <li>0.50: Full moon * <li>0.75: Last quarter * </ul> * * @see #getMoonAge * @internal */ double getMoonPhase(); class U_I18N_API MoonAge : public UMemory { public: MoonAge(double l) : value(l) { } void set(double l) { value = l; } double value; }; /** * Constant representing a new moon. * For use with {@link #getMoonTime getMoonTime} * @internal */ static const MoonAge NEW_MOON(); /** * Constant representing the moon's first quarter. * For use with {@link #getMoonTime getMoonTime} * @internal */ // static const MoonAge FIRST_QUARTER(); /** * Constant representing a full moon. * For use with {@link #getMoonTime getMoonTime} * @internal */ static const MoonAge FULL_MOON(); /** * Constant representing the moon's last quarter. * For use with {@link #getMoonTime getMoonTime} * @internal */ // static const MoonAge LAST_QUARTER(); /** * Find the next or previous time at which the Moon's ecliptic * longitude will have the desired value. * <p> * @param desired The desired longitude. * @param next <tt>true</tt> if the next occurrance of the phase * is desired, <tt>false</tt> for the previous occurrance. * @internal */ UDate getMoonTime(double desired, UBool next); UDate getMoonTime(const MoonAge& desired, UBool next); /** * Returns the time (GMT) of sunrise or sunset on the local date to which * this calendar is currently set. * @internal */ UDate getMoonRiseSet(UBool rise); //------------------------------------------------------------------------- // Interpolation methods for finding the time at which a given event occurs //------------------------------------------------------------------------- // private class AngleFunc : public UMemory { public: virtual double eval(CalendarAstronomer&) = 0; virtual ~AngleFunc(); }; friend class AngleFunc; UDate timeOfAngle(AngleFunc& func, double desired, double periodDays, double epsilon, UBool next); class CoordFunc : public UMemory { public: virtual void eval(Equatorial& result, CalendarAstronomer&) = 0; virtual ~CoordFunc(); }; friend class CoordFunc; double riseOrSet(CoordFunc& func, UBool rise, double diameter, double refraction, double epsilon); //------------------------------------------------------------------------- // Other utility methods //------------------------------------------------------------------------- private: /** * Return the obliquity of the ecliptic (the angle between the ecliptic * and the earth's equator) at the current time. This varies due to * the precession of the earth's axis. * * @return the obliquity of the ecliptic relative to the equator, * measured in radians. */ double eclipticObliquity(); //------------------------------------------------------------------------- // Private data //------------------------------------------------------------------------- private: /** * Current time in milliseconds since 1/1/1970 AD * @see java.util.Date#getTime */ UDate fTime; /* These aren't used yet, but they'll be needed for sunset calculations * and equatorial to horizon coordinate conversions */ double fLongitude; double fLatitude; double fGmtOffset; // // The following fields are used to cache calculated results for improved // performance. These values all depend on the current time setting // of this object, so the clearCache method is provided. // double julianDay; double julianCentury; double sunLongitude; double meanAnomalySun; double moonLongitude; double moonEclipLong; double meanAnomalyMoon; double eclipObliquity; double siderealT0; double siderealTime; void clearCache(); Equatorial moonPosition; UBool moonPositionSet; /** * @internal */ // UDate local(UDate localMillis); }; U_NAMESPACE_END struct UHashtable; U_NAMESPACE_BEGIN /** * Cache of month -> julian day * @internal */ class CalendarCache : public UMemory { public: static int32_t get(CalendarCache** cache, int32_t key, UErrorCode &status); static void put(CalendarCache** cache, int32_t key, int32_t value, UErrorCode &status); virtual ~CalendarCache(); private: CalendarCache(int32_t size, UErrorCode& status); static void createCache(CalendarCache** cache, UErrorCode& status); /** * not implemented */ CalendarCache(); UHashtable *fTable; }; U_NAMESPACE_END #endif #endif