d2e2569fe2
Instead of documenting how to calculate phase fraction, just calculate it. Show 'number' instead of 'Number' for numeric types.
API Reference
Astronomy : object
Kind: global namespace
- Astronomy :
object- .Time
- new Time(date)
- .toString() ⇒
string - .AddDays() ⇒
Time
- .Observer
- .IlluminationInfo
- .ElongationEvent
- .Bodies :
Array.<string> - .MakeTime(date) ⇒
Time - .Horizon(date, location, ra, dec) ⇒
Astronomy.HorizontalCoordinates - .MakeObserver(latitude_degrees, longitude_degrees, height_in_meters)
- .SunPosition()
- .SkyPos()
- .Ecliptic()
- .GeoMoon(date) ⇒
Astronomy.Vector - .Illumination(body, date) ⇒
IlluminationInfo - .Elongation(body) ⇒
ElongationEvent - .SearchMaxElongation(body, startDate) ⇒
ElongationEvent - .SearchPeakMagnitude(body, startDate) ⇒
IlluminationInfo
- .Time
Astronomy.Time
Kind: static class of Astronomy
Properties
| Name | Type | Description |
|---|---|---|
| date | Date |
The JavaScript Date object for the given date and time. This Date corresponds to the numeric day value stored in the ut property. |
| ut | number |
Universal Time (UT1/UTC) in fractional days since the J2000 epoch. Universal Time represents time measured with respect to the Earth's rotation, tracking mean solar days. The Astronomy library approximates UT1 and UTC as being the same thing. This gives sufficient accuracy for the 1-arcminute angular resolution requirement of this project. |
| tt | number |
Terrestrial Time in fractional days since the J2000 epoch. TT represents a continuously flowing ephemeris timescale independent of any variations of the Earth's rotation, and is adjusted from UT using historical and predictive models of those variations. |
- .Time
- new Time(date)
- .toString() ⇒
string - .AddDays() ⇒
Time
new Time(date)
The date and time of an astronomical observation.
Objects of this type are used throughout the internals
of the Astronomy library, and are included in certain return objects.
The constructor is not accessible outside the Astronomy library;
outside users should call the MakeTime function
to create a Time object.
| Param | Type | Description |
|---|---|---|
| date | Date | number |
A JavaScript Date object or a numeric UTC value expressed in J2000 days. |
time.toString() ⇒ string
Formats a Time object as an
ISO 8601
date/time string in UTC, to millisecond resolution.
Example:
2018-08-17T17:22:04.050Z
Kind: instance method of Time
time.AddDays() ⇒ Time
Returns a new Time object adjusted by the floating point number of days.
Does NOT modify the original Time object.
Kind: instance method of Time
Astronomy.Observer
Kind: static class of Astronomy
Properties
| Name | Type | Description |
|---|---|---|
| latitude_degrees | number |
The observer's geographic latitude in degrees north of the Earth's equator. The value is negative for observers south of the equator. Must be in the range -90 to +90. |
| longitude_degrees | number |
The observer's geographic longitude in degrees east of the prime meridian passing through Greenwich, England. The value is negative for observers west of the prime meridian. The value should be kept in the range -180 to +180 to minimize floating point errors. |
| height_in_meters | number |
The observer's elevation above mean sea level, expressed in meters. |
new Observer()
Represents the geographic location of an observer on the surface of the Earth.
Astronomy.IlluminationInfo
Kind: static class of Astronomy
Properties
| Name | Type | Description |
|---|---|---|
| time | Time |
The date and time pertaining to the other calculated values in this object. |
| mag | number |
The apparent visual magnitude of the celestial body. |
| phase_angle | number |
The angle in degrees as seen from the center of the celestial body between the Sun and the Earth. The value is always in the range 0 to 180. The phase angle provides a measure of what fraction of the body's face appears illuminated by the Sun as seen from the Earth. When the observed body is the Sun, the phase property is set to 0, although this has no physical meaning because the Sun emits, rather than reflects, light. When the phase is near 0 degrees, the body appears "full". When it is 90 degrees, the body appears "half full". And when it is 180 degrees, the body appears "new" and is very difficult to see because it is both dim and lost in the Sun's glare as seen from the Earth. |
| phase_fraction | number |
The fraction of the body's face that is illuminated by the Sun, as seen from the Earth. Calculated from phase_angle for convenience. |
| helio_dist | number |
The distance between the center of the Sun and the center of the body in Astronomical Units (AU). |
| geo_dist | number |
The distance between the center of the Earth and the center of the body in AU. |
| gc | Astronomy.Vector |
Geocentric coordinates: the 3D vector from the center of the Earth to the center of the body. The components are in expressed in AU and are oriented with respect to the J2000 equatorial plane. |
| hc | Astronomy.Vector |
Heliocentric coordinates: The 3D vector from the center of the Sun to the center of the body. Like gc, hc is expressed in AU and oriented with respect to the J2000 equatorial plane. |
| ring_tilt | number | null |
For Saturn, this is the angular tilt of the planet's rings in degrees away from the line of sight from the Earth. When the value is near 0, the rings appear edge-on from the Earth and are therefore difficult to see. When ring_tilt approaches its maximum value (about 27 degrees), the rings appear widest and brightest from the Earth. Unlike the JPL Horizons online tool, this library includes the effect of the ring tilt angle in the calculated value for Saturn's visual magnitude. For all bodies other than Saturn, the value of ring_tilt is null. |
new IlluminationInfo()
Contains information about the apparent brightness and sunlit phase of a celestial object.
Astronomy.ElongationEvent
Kind: static class of Astronomy
See: Astronomy.Elongation
Properties
| Name | Type | Description |
|---|---|---|
| time | Time |
When the event occurs. |
| visibility | string |
Either "morning" or "evening", indicating when the body is most easily seen. |
| elongation | number |
The angle in degrees, as seen from the center of the Earth, of the apparent separation between the body and the Sun. This angle is measured in 3D space and is not projected onto the ecliptic plane. |
| relative_longitude | number |
The angle in degrees, as seen from the Sun, between the observed body and the Earth. This value is always between 0 and 180. More precisely, relative_longitude is the absolute value of the difference between the heliocentric ecliptic longitudes of the centers of the observed body and the Earth. |
new ElongationEvent()
Represents the visibility of a planet or the Moon relative to the Sun. Includes angular separation from the Sun and whether visibility is best in the morning or the evening.
Astronomy.Bodies : Array.<string>
An array of strings, each a name of a supported astronomical body. Not all bodies are valid for all functions, but any string not in this list is not supported at all.
Kind: static constant of Astronomy
Astronomy.MakeTime(date) ⇒ Time
Given a Date object or a number days since noon (12:00) on January 1, 2000 (UTC), this function creates an Time object. Given an Time object, returns the same object unmodified. Use of this function is not required for any of the other exposed functions in this library, because they all guarantee converting date/time parameters to Astronomy.Time as needed. However, it may be convenient for callers who need to understand the difference between UTC and TT (Terrestrial Time). In some use cases, converting once to Astronomy.Time format and passing the result into multiple function calls may be more efficient than passing in native JavaScript Date objects.
Kind: static method of Astronomy
| Param | Type | Description |
|---|---|---|
| date | Date | number | Time |
A Date object, a number of UTC days since the J2000 epoch (noon on January 1, 2000), or an Astronomy.Time object. See remarks above. |
Astronomy.Horizon(date, location, ra, dec) ⇒ Astronomy.HorizontalCoordinates
Given a date and time, a geographic location of an observer on the Earth, and equatorial coordinates (right ascension and declination) of a celestial object, returns horizontal coordinates (azimuth and altitude angles) for that object as seen by that observer.
Kind: static method of Astronomy
| Param | Type | Description |
|---|---|---|
| date | Date | number | Time |
The date and time for which to find horizontal coordinates. |
| location | Observer |
The location of the observer for which to find horizontal coordinates. |
| ra | number |
Right ascension in sidereal hours of the celestial object, referred to the mean equinox of date for the J2000 epoch. |
| dec | number |
Declination in degrees of the celestial object, referred to the mean equator of date for the J2000 epoch. Positive values are north of the celestial equator and negative values are south. |
Astronomy.MakeObserver(latitude_degrees, longitude_degrees, height_in_meters)
Creates an Observer object.
Kind: static method of Astronomy
| Param | Type | Description |
|---|---|---|
| latitude_degrees | number |
The observer's geographic latitude in degrees north of the Earth's equator. The value is negative for observers south of the equator. Must be in the range -90 to +90. |
| longitude_degrees | number |
The observer's geographic longitude in degrees east of the prime meridian passing through Greenwich, England. The value is negative for observers west of the prime meridian. The value should be kept in the range -180 to +180 to minimize floating point errors. |
| height_in_meters | number |
The observer's elevation above mean sea level, expressed in meters. If omitted, the elevation is assumed to be 0 meters. |
Astronomy.SunPosition()
Returns apparent geocentric true ecliptic coordinates of date for the Sun.
Kind: static method of Astronomy
Astronomy.SkyPos()
Returns equatorial coordinates (right ascension and declination) in two different systems: J2000 and true-equator-of-date.
Kind: static method of Astronomy
Astronomy.Ecliptic()
Given J2000 equatorial Cartesian coordinates, returns J2000 ecliptic latitude, longitude, and cartesian coordinates. You can call Astronomy.GeoVector and use its (x, y, z) return values to pass into this function.
Kind: static method of Astronomy
Astronomy.GeoMoon(date) ⇒ Astronomy.Vector
Calculates the geocentric Cartesian coordinates for the Moon in the J2000 equatorial system. Based on the Nautical Almanac Office's Improved Lunar Ephemeris of 1954, which in turn derives from E. W. Brown's lunar theories. Adapted from Turbo Pascal code from the book Astronomy on the Personal Computer by Montenbruck and Pfleger.
Kind: static method of Astronomy
| Param | Type | Description |
|---|---|---|
| date | Date | number | Time |
The date and time for which to calculate the Moon's geocentric position. |
Astronomy.Illumination(body, date) ⇒ IlluminationInfo
Calculates the phase angle, visual maginitude, and other values relating to the body's illumination at the given date and time, as seen from the Earth.
Kind: static method of Astronomy
| Param | Type | Description |
|---|---|---|
| body | string |
The name of the celestial body being observed. Not allowed to be "Earth". |
| date | Date | number | Time |
The date and time for which to calculate the illumination data for the given body. |
Astronomy.Elongation(body) ⇒ ElongationEvent
Calculates the absolute value of the angle between the centers of the given body and the Sun as seen from the center of the Earth at the given date. The angle is measured along the plane of the Earth's orbit (i.e. the ecliptic) and ranges [0, 180] degrees. This function is helpful for determining how easy it is to view Mercury or Venus away from the Sun's glare on a given date. The function also determines whether the object is visible in the morning or evening; this is more important the smaller the elongation is.
Kind: static method of Astronomy
| Param | Type | Description |
|---|---|---|
| body | string |
The name of the observed body. Not allowed to be "Earth". |
Astronomy.SearchMaxElongation(body, startDate) ⇒ ElongationEvent
Searches for the next maximum elongation event for Mercury or Venus
that occurs after the given start date. Calling with other values
of body will result in an exception.
Maximum elongation occurs when the body has the greatest
angular separation from the Sun, as seen from the Earth.
Returns an ElongationEvent object containing the date and time of the next
maximum elongation, the elongation in degrees, and whether
the body is visible in the morning or evening.
Kind: static method of Astronomy
| Param | Type | Description |
|---|---|---|
| body | string |
either "Mercury" or "Venus" |
| startDate | Date |
the date and time after which to search for the next maximum elongation event |
Astronomy.SearchPeakMagnitude(body, startDate) ⇒ IlluminationInfo
Searches for the date and time Venus will next appear brightest as seen from the Earth.
Kind: static method of Astronomy
| Param | Type | Description |
|---|---|---|
| body | string |
Currently only "Venus" is supported. Mercury's peak magnitude occurs at superior conjunction, when it is virtually impossible to see from Earth, so peak magnitude events have little practical value for this planet. The Moon reaches peak magnitude very close to full moon, which can be found using Astronomy.SearchMoonQuarter or Astronomy.SearchMoonPhase. The other planets reach peak magnitude very close to opposition, which can be found using Astronomy.SearchRelativeLongitude. |
| startDate | Date | number | Time |
The date and time after which to find the next peak magnitude event. |