Name Picker Malfunction

    astronomy-bundle
    TypeScript icon, indicating that this package has built-in type declarations

    7.5.3 • Public • Published

    Astronomy Bundle

    This library provides tools and methods for astronomical calculations. With this bundle it is possible to calculate the position of moon, sun and planets and several coordinate systems. For a higher accuracy, several corrections, like nutation and precision, were taken into account. It is also possible to calculate rise, set and culmination events for celestial objects. For a detailed see the table of contents.

    Most of the calculations base on Jean Meeus 'Astronomical Algorithms' book and the VSOP87 theory.

    Table of Contents

    1. Installation
    2. Angle Utils
    3. Time of Interest
      1. Create Time Of Interest
      2. Calendar methods
      3. Julian Day, Centuries and Millennia
      4. Greenwich and Local Sidereal Time
      5. Delta T
    4. Location
      1. Distance between two locations
    5. Astronomical Objects
      1. Coordinates
    6. Earth
      1. Position of the Earth
      2. Nutation in Longitude and Obliquity
      3. Obliquity of Ecliptic
    7. Sun
      1. Position of the Sun
      2. Distance to Earth and Diameter
      3. Sunrise, Sunset and Transit
    8. Moon
      1. Position of the Moon
      2. Distance to Earth and Diameter
      3. Moonrise, Moonset and Transit
      4. Phases
      5. Apparent Magnitude
      6. Physical Observation
      7. Libration
      8. Golden Handle, Lunar X and V
    9. Planets
      1. Position of Planets
      2. Distance to Earth and Diameter
      3. Phases
      4. Apparent Magnitude
      5. Physical Observation
      6. Conjunction
    10. Stars
    11. Position of Stars
    12. Solar Eclipse
    13. Solar Eclipse exists
    14. Greatest Eclipse
    15. Observational Circumstances
    16. Satellites
    17. Two Line Elements

    Installation

    You can install the astronomy-bundle using npm:

    npm i astronomy-bundle
    

    or yarn:

    yarn add astronomy-bundle
    

    Angle Utils

    The angle util provides helper methods to convert an angle into different formats.

    Example 1: Convert decimal angle

    import {angleCalc} from 'astronomy-bundle/utils';
    
    const angleInDeg = 132.6029282;
    
    const angleStr = angleCalc.deg2angle(angleInDeg);
    const timeStr = angleCalc.deg2time(angleInDeg);

    The result of the calculation should be:
    Angle: 132° 36' 10.542"
    Time: 8h 50m 24.703s

    Example 2: Convert time into decimal format

    import {angleCalc} from 'astronomy-bundle/utils';
    
    const timeStr = '8h 50m 24.703s';
    
    const angleInDeg = angleCalc.time2deg(timeStr);

    The result of the calculation should be:
    Angle: 132.602929°

    Time of Interest

    The TimeOfInterest (TOI) object represents the time for which all the astronomical calculations are done. For that reason it is the most important object in this library.

    Create the TimeOfInterest object

    There are several ways to initialize the TOI object.

    Example 1: Initialize the TimeOfInterest object for the date 02 July 2017 at 15:30:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    
    // Create from time
    const toi = createTimeOfInterest.fromTime(2017, 7, 2, 15, 30, 0);
    
    // Create from Date object
    const date = new Date('2017-07-02 15:30:00');
    const toi = createTimeOfInterest.fromDate(date);
    
    // Create from Julian Day
    const jd = 2457937.1458333;
    const toi = createTimeOfInterest.fromJulianDay(jd);
    
    // Create from Julian Centuries since J2000
    const T = 0.17500741501255;
    const toi = createTimeOfInterest.fromJulianCenturiesJ2000(T);

    The result will be always: 2017-07-02 15:30:00

    Example 2: Create the TOI object for the current date and time in UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    
    const toi = createTimeOfInterest.fromCurrentTime();

    Calendar methods

    Legend for day of the week:

    Value Day of week
    0 Sunday
    1 Monday
    2 Tuesday
    3 Wednesday
    4 Thursday
    5 Friday
    6 Saturday

    Example: Get day of year, day of week and leap year for 02 July 2017 at 13:37 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    
    const toi = createTimeOfInterest.fromTime(2017, 7, 2, 13, 37, 0);
    
    const dayOfYear = toi.getDayOfYear();
    const dayOfWeek = toi.getDayOfWeek();
    const isLeapYear = toi.isLeapYear();

    The result of the calculation should be:
    Day of year: 183
    Day of week: 0 (Sunday)
    Is leap year: false

    Julian Day, Julian Centuries and Julian Millennia

    Example: Get Julian Day, Julian Centuries and Julian Millennia for 02 July 2017 at 13:37 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    
    const toi = createTimeOfInterest.fromTime(2017, 7, 2, 13, 37, 0);
    
    const jd = toi.getJulianDay();
    const jd0 = toi.getJulianDay0();
    const T = toi.getJulianCenturiesJ2000();
    const t = toi.getJulianMillenniaJ2000();

    The result of the calculation should be:
    Julian Day: 2457937.0673611
    Julian Day 0: 2457936.5
    Julian Centuries J2000: 0.1750052666
    Julian Millennia J2000: 0.0175005267

    Greenwich Sidereal Time and Local Sidereal Time

    Example 1: Get Greenwich Sidereal Time for 02 July 2017 at 13:37 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    
    const toi = createTimeOfInterest.fromTime(2017, 7, 2, 13, 37, 0);
    
    const GMST = toi.getGreenwichMeanSiderealTime();
    const GAST = toi.getGreenwichApparentSiderealTime();
    
    // To express the angle in time format use angleCalc.deg2time(GMST)

    The result of the calculation should be:
    GMST: 5h 44m 46.48s
    GAST: 5h 44m 45.47s

    Example 2: Get Local Sidereal Time for 02 July 2017 at 13:37 UTC in Berlin, Germany

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createLocation} from 'astronomy-bundle/earth';
    
    const toi = createTimeOfInterest.fromTime(2017, 7, 2, 13, 37, 0);
    const location = createLocation(52.52, 13.41);
    
    const LMST = toi.getLocalMeanSiderealTime(location);
    const LAST = toi.getLocalApparentSiderealTime(location);
    
    // To express the angle in time format use angleCalc.deg2time(LMST)

    The result of the calculation should be:
    LMST: 9h 13m 46.798s
    LAST: 9h 13m 46.232s

    Delta T

    Example: Get Delta T for 20 May 2000 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    
    const toi = createTimeOfInterest.fromTime(2000, 5, 20, 0, 0, 0);
    
    const deltaT = toi.getDeltaT();

    The result of the calculation should be:
    Delta T: 64

    Location

    Distance between two locations

    Example: Calculate the distance between the Eiffel Tower and the Washington Monument in km

    import {createLocation} from 'astronomy-bundle/earth';
    
    const locationParis = createLocation(48.858272, 2.29447);
    const locationWashingtonDc = createLocation(38.889514, -77.035193);
    
    const distanceInKm = locationParis.getDistanceToInKm(locationWashingtonDc);

    The result of the calculation should be: 6177.93 km

    Astronomical Objects

    An astronomical object should be initialized with the TOI. If you don't pass the TOI in the constructor, the current time is chosen.

    Example 1: Create an astronomical object with TOI

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromCurrentTime();
    
    const moon = createMoon(toi);

    Example 2: Create an astronomical object without TOI. The chosen TOI corresponds to the current time

    import {createMoon} from 'astronomy-bundle/moon';
    
    const moon = createMoon();

    Coordinates of Astronomical Objects

    Explanation of different Coordinate Systems used

    Center of coordinate system

    • Heliocentric (Sun is center of coordinate system)
    • Geocentric (Earth is center of coordinate system)
    • Topocentric (Observer's location is center of coordinate system)

    Coordinate system type

    • Ecliptic Rectangular (x, y, z)
    • Ecliptic Spherical (lon, lat, radiusVector)
    • Equatorial Spherical (rightAscension, declination, radiusVector)
    • Horizontal (azimuth, altitude, radiusVector)

    Usable Methods in objects

    Each object (e.g. Moon, Sun, Venus, Jupiter, ...) provides the following methods to get their coordinates in space:

    Heliocentric coordinates
    getHeliocentricEclipticRectangularJ2000Coordinates()
    getHeliocentricEclipticRectangularDateCoordinates()
    getHeliocentricEclipticSphericalJ2000Coordinates()
    getHeliocentricEclipticSphericalDateCoordinates()
    Geocentric coordinates
    getGeocentricEclipticRectangularJ2000Coordinates()
    getGeocentricEclipticRectangularDateCoordinates()
    getGeocentricEclipticSphericalJ2000Coordinates()
    getGeocentricEclipticSphericalDateCoordinates()
    getGeocentricEquatorialSphericalJ2000Coordinates()
    getGeocentricEquatorialSphericalDateCoordinates()
    getApparentGeocentricRectangularCoordinates() // Corrected by light time, abberation & nutation
    getApparentGeocentricEclipticSphericalCoordinates() // Corrected by light time, abberation & nutation
    getApparentGeocentricEquatorialSphericalCoordinates() // Corrected by light time, abberation & nutation
    Topocentric coordinates
    getTopocentricEquatorialSphericalCoordinates(location)
    getTopocentricHorizontalCoordinates(location)
    getApparentTopocentricHorizontalCoordinates(location) // Corrected by atmospheric refraction

    Earth

    This library uses the VSOP87 theory to calculate precise planetary positions. Each calculation uses terms with a heavy file size of several kilobytes. For that reason all VSOP87 calculations will load asynchronous and only when they are used. All coordinate methods do return a Promise.

    Position of the Earth

    Example: Calculate the heliocentric position (J2000) of the Earth for 10 December 2017 at 00:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createEarth} from 'astronomy-bundle/earth';
    
    const toi = createTimeOfInterest.fromTime(2017, 12, 10, 0, 0, 0);
    const earth = createEarth(toi);
    
    const {x, y, z} = await earth.getHeliocentricEclipticRectangularJ2000Coordinates();
    const {lon, lat, radiusVector} = await earth.getHeliocentricEclipticSphericalJ2000Coordinates();

    The result of the calculation should be:

    x: 0.2070104
    y: 0.96282379
    z: -0.00004247

    Longitude: 77° 51' 57.357"
    Latitude: -0° 00' 08.895"
    Radius Vector: 0.98482636

    Nutation in Longitude and Obliquity

    Example: Get nutation in Longitude and Obliquity for 01 August 2020 at 16:51:54 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createEarth} from 'astronomy-bundle/earth';
    
    const toi = createTimeOfInterest.fromTime(2020, 8, 1, 16, 51, 54);
    const earth = createEarth(toi);
    
    const phi = earth.getNutationInLongitude();
    const e = earth.getNutationInObliquity();
    
    // To express the angle in string format use angleCalc.deg2angle(p)

    The result of the calculation should be:

    Nutation in Longitude: -0° 00' 15.807"
    Nutation in Obliquity: 0° 00' 00.395"

    Obliquity of Ecliptic

    Example: Get Mean and True Obliquity of Ecliptic for 01 August 2020 at 16:51:54 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createEarth} from 'astronomy-bundle/earth';
    
    const toi = createTimeOfInterest.fromTime(2020, 8, 1, 16, 51, 54);
    const earth = createEarth(toi);
    
    const eps0 = earth.getMeanObliquityOfEcliptic();
    const eps = earth.getTrueObliquityOfEcliptic();
    
    // To express the angle in string format use angleCalc.deg2angle(eps)

    The result of the calculation should be:

    Mean Obliquity of Ecliptic: 23° 26' 11.813"
    True Obliquity of Ecliptic: 23° 26' 12.208"

    Sun

    This library uses the VSOP87 theory to calculate precise planetary positions. Each calculation uses terms with a heavy file size of several kilobytes. For that reason all VSOP87 calculations will load asynchronous and only when they are used. All coordinate methods do return a Promise.

    Position of the Sun

    Example: Get the position of the Sun (Date) for 10 October 2020 at 06:15 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createSun} from 'astronomy-bundle/sun';
    
    const toi = createTimeOfInterest.fromTime(2020, 10, 10, 6, 15, 0);
    const sun = createSun(toi);
    
    const geoEclCoords = await sun.getGeocentricEclipticSphericalDateCoordinates();
    const geoAppEquCoords = await sun.getApparentGeocentricEquatorialSphericalCoordinates()

    The result should be:

    Longitude: 209.31555315°
    Latitude: -0.00014017°
    Radius Vector: 0.99514386

    Right Ascension: 207.25282342°
    Declination: -11.22796087°
    Radius Vector: 0.99514386

    Distance to Earth and diameter of the Sun

    Example 1: Get distance and diameter of the sun for the current date and time

    import {createSun} from 'astronomy-bundle/sun';
    
    const sun = createSun();
    
    const distance = await sun.getDistanceToEarth();
    const delta = await sun.getAngularDiameter();

    The result should be:
    The distance is between 147.1 mio and 152.1 mio kilometers.
    The angular diameter is about 32'

    Example 2: Get the distance and diameter of the Sun for 05 June 2017 at 20:30 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createSun} from 'astronomy-bundle/createSun';
    
    const toi = createTimeOfInterest.fromTime(2017, 6, 5, 20, 30, 0);
    const sun = createSun(toi);
    
    const distance = await sun.getDistanceToEarth();
    const delta = await sun.getAngularDiameter();

    The result should be:

    Distance: 151797423.98 km
    Diameter: 0° 31' 32.43"

    Sunrise, Sunset and Transit

    The used standard altitudes for sunset and sunrise consider the effect of atmospheric refraction and are given as:

    • Sun's center: -0.583°
    • Sun's upper limb: -0.833°

    Example: Get the rise, set and transit of the Sun on 20. November 2020 in Berlin, Germany

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createSun} from 'astronomy-bundle/sun';
    
    const location = {
        lat: 52.519,
        lon: 13.408,
    };
    
    const toi = createTimeOfInterest.fromTime(2020, 11, 20, 0, 0, 0);
    const sun = createSun(toi);
    
    const toiRiseUpperLimb = await sun.getRiseUpperLimb(location);
    const toiRiseCenter = await sun.getRise(location);
    const toiTransit = await sun.getTransit(location);
    const toiSetCenter = await sun.getSet(location);
    const toiSetUpperLimb = await sun.getSetUpperLimb(location);

    The result should be:

    Sunrise (upper limb): 06:37:31 UTC
    Sunrise (disk's center): 06:39:28 UTC
    Transit: 11:52:04 UTC
    Sunset (disk's center): 15:04:10 UTC
    Sunset (upper limb): 15:06:07 UTC

    Moon

    This library uses the VSOP87 theory to calculate precise planetary positions. Each calculation uses terms with a heavy file size of several kilobytes. For that reason all VSOP87 calculations will load asynchronous and only when they are used. All coordinate methods do return a Promise.

    Position of the Moon

    Example 1: Calculate the geocentric position of the Moon for 12 April 1992 at 00:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(1992, 4, 12, 0, 0, 0);
    const moon = createMoon(toi);
    
    const {x, y, z} = await moon.getGeocentricEclipticRectangularDateCoordinates();
    const {lon, lat, radiusVector} = await moon.getGeocentricEclipticSphericalDateCoordinates();
    const {rightAscension, declination, radiusVector} = await moon.getGeocentricEquatorialSphericalDateCoordinates();

    The result of the calculation should be:

    x: -0.001682
    y: -0.001701
    z: 0.000586

    Longitude: 133.17°
    Latitude: -3.23°
    Radius Vector: 0.002463

    Right Ascension: 134.69°
    Declination: 13.77°
    Radius Vector: 0.002463

    Distance to earth and diameter

    Example 1: Calculate the distance of the Moon in kilometers for the current time

    import {createMoon} from 'astronomy-bundle/moon';
    
    const moon = createMoon();
    
    const distance = await moon.getDistanceToEarth();
    const delta = await moon.getAngularDiameter();

    The result should be between 363300 km and 405500 km.
    The angular diameter is about 32'

    Example 2: Get the distance of the Moon for 05 June 2017 at 20:30 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(2017, 6, 5, 20, 30, 0);
    const moon = createMoon(toi);
    
    const distance = await moon.getDistanceToEarth();

    The result should be: 402937.61 km

    Moonrise, Moonset and Transit

    The used standard altitude for moonset and moonrise is 0.125 which considers the effect of atmospheric refraction.

    Example: Get the rise, set and transit of the Moon on 20. November 2020 in Berlin, Germany

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const location = {
        lat: 52.519,
        lon: 13.408,
    };
    
    const toi = createTimeOfInterest.fromTime(2020, 11, 20, 0, 0, 0);
    const moon = createMoon(toi);
    
    const toiRise = await moon.getRise(location);
    const toiTransit = await moon.getTransit(location);
    const toiSet = await moon.getSet(location);

    The result should be:

    Moonrise: 12:02:52 UTC
    Transit: 16:03:43 UTC
    Moonset: 20:11:42 UTC

    Phases of the Moon

    Example 1: Get the illuminated fraction of the Moon for 12 April 1992 at 00:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(1992, 4, 12, 0, 0, 0);
    const moon = createMoon(toi);
    
    const k = await moon.getIlluminatedFraction();
    const isWaxing = await moon.isWaxing();

    The result of the calculation should be:
    Illumination: 0.679 (67.9%)
    Is waxing: true

    Example 2: Get upcoming first quarter and next full moon in November 2020

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(2020, 11, 1, 0, 0, 0);
    const moon = createMoon(toi);
    
    const toiUpcomingFirstQuarter = moon.getUpcomingFirstQuarter();
    const toiUpcomingFullMoon = moon.getUpcomingFullMoon();

    The result of the calculation should be:
    Upcoming first quarter: 2020-11-22 04:46:35 UTC
    Upcoming full moon: 2020-11-30 09:31:22 UTC

    Apparent magnitude of the Moon

    Example: Get the apparent Magnitude of the Moon for 07 November 2020 at 01:20 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(2020, 11, 7, 1, 20, 0);
    const moon = createMoon(toi);
    
    const V = await moon.getApparentMagnitude();

    The result of the calculation should be: -10.71m

    Physical Observation of the Moon

    Example 1: Get the geocentric Physical Observation of the Moon for 07 November 2020 at 01:20 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(2020, 11, 7, 1, 20, 0);
    const moon = createMoon(toi);
    
    const phi = await moon.getElongation();
    const i = await moon.getPhaseAngle();
    const chi = await moon.getPositionAngleOfBrightLimb();

    The result of the calculation should be:
    Elongation from Sun: 108.26°
    Phase Angle: 71.6°
    Position Angle of bright Limb: 100.29°

    Example 2: Get the topocentric Physical Observation of the Moon for 07 November 2020 at 01:20 UTC for Berlin, Germany

    import {createLocation} from 'astronomy-bundle/earth';
    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const location = createLocation(52.52, 13.41, 30);
    
    const toi = createTimeOfInterest.fromTime(2020, 11, 7, 1, 20, 0);
    const moon = createMoon(toi);
    
    const phi = await moon.getTopocentricElongation(location);
    const i = await moon.getTopocentricPhaseAngle(location);
    const chi = await moon.getTopocentricPositionAngleOfBrightLimb(location);

    The result of the calculation should be:
    Elongation from Sun: 107.81°
    Phase Angle: 72.05°
    Position Angle of bright Limb: 100.58°

    Libration of the moon

    The libration is the wagging or wavering of the Moon perceived by Earth-bound observers.

    Example 1: Get the libration (selenographic position of the earth on the moons surface) on 12th of April 1992 (See Meeus Example 53.a)

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(1992, 4, 12, 0, 0, 0);
    const moon = createMoon(toi);
    
    const {lon, lat} = await moon.getGeocentricLibration();
    const {lon, lat} = await moon.getSelenographicLocationOfEarth(); // same as getGeocentricLibration()

    The result of the calculation should be:
    Longitude: -1.23121°
    Latitude: 4.1998°

    Example 2: Get the selenographic position of the sun on the moons surface on 12th of April 1992 (See Meeus Example 53.b)

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(1992, 4, 12, 0, 0, 0);
    const moon = createMoon(toi);
    
    const {lon, lat} = await moon.getSelenographicLocationOfSun();

    The result of the calculation should be:
    Longitude: 67.89894°
    Latitude: 1.4615°

    Golden Handle, Lunar X and V

    The Golden Handle occurs about 4 days before the Full Moon. The Jura Mountains catch the sunlight while Sinus Iridum below remains in shadow.

    Example 1: Get the time of the Golden Handle for April 2022.

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(2022, 4, 1, 0, 0, 0);
    const moon = createMoon(toi);
    
    const goldenHandle = moon.getGoldenHandle();
    
    const toiStart = await goldenHandle.getStartTime();
    const toiMax = await goldenHandle.getMaximum();
    const toiEnd = await goldenHandle.getEndTime();

    The result of the calculation should be:
    Start of visibility: 2022-04-11 18:19:36 UT
    Maximum visibility: 2022-04-11 21:19:36 UT
    End of visibility: 2022-04-12 03:19:36 UT

    The Lunar X is a clair-obscur effect in which light and shadow creates the appearance of a letter 'X' on the rim of the Blanchinus, La Caille and Purbach craters.

    Example 2: Get the time of the Lunar X for April 2022.

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(2022, 4, 1, 0, 0, 0);
    const moon = createMoon(toi);
    
    const lunarX = moon.getLunarX();
    
    const toiStart = await lunarX.getStartTime();
    const toiMax = await lunarX.getMaximum();
    const toiEnd = await lunarX.getEndTime();

    The result of the calculation should be:
    Start of visibility: 2022-04-08 20:02:32 UT
    Maximum visibility: 2022-04-08 21:32:32 UT
    End of visibility: 2022-04-08 23:02:32 UT

    The Lunar V is another effect such as the Lunar X. The Lunar V is longer visible than the Lunar X and can be seen even 10 hour after it reached his highest contrast.

    Example 3: Get the time of the Lunar V for April 2022.

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMoon} from 'astronomy-bundle/moon';
    
    const toi = createTimeOfInterest.fromTime(2022, 4, 1, 0, 0, 0);
    const moon = createMoon(toi);
    
    const lunarV = moon.getLunarV();
    
    const toiStart = await lunarV.getStartTime();
    const toiMax = await lunarV.getMaximum();
    const toiEnd = await lunarV.getEndTime();

    The result of the calculation should be:
    Start of visibility: 2022-04-08 19:09:03 UT
    Maximum visibility: 2022-04-08 22:09:03 UT
    End of visibility: 2022-04-09 06:09:03 UT

    Planets

    This library uses the VSOP87 theory to calculate precise planetary positions. Each calculation uses terms with a heavy file size of several kilobytes. For that reason all VSOP87 calculations will load asynchronous and only when they are used. All coordinate methods do return a Promise.

    Position of Planets

    Example 1: Calculate the heliocentric position for equinox J2000 of Venus for 04 November 2020 at 00:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createVenus} from 'astronomy-bundle/planets';
    
    const toi = createTimeOfInterest.fromTime(2020, 11, 4, 0, 0, 0);
    const venus = createVenus(toi);
    
    const coordsRec = await venus.getHeliocentricEclipticRectangularJ2000Coordinates();
    const coordsSph = await venus.getHeliocentricEclipticSphericalJ2000Coordinates();

    The result of the calculation should be:

    Heliocentric Rectangular (J2000)
    x: -0.53523555
    y: 0.477793213
    z: 0.037443275

    Heliocentric Spherical (J2000)
    Longitude: 138° 14' 43.437"
    Latitude: 2° 59' 14.774"
    Radius Vector: 0.71844655

    Example 2: Calculate the geocentric position for current date of Jupiter for 04 November 2020 at 00:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createJupiter} from 'astronomy-bundle/planets';
    
    const toi = createTimeOfInterest.fromTime(2020, 11, 4, 0, 0, 0);
    const jupiter = createJupiter(toi);
    
    const coordsRec = await jupiter.getGeocentricEclipticRectangularDateCoordinates();
    const coordsSph = await jupiter.getGeocentricEclipticSphericalDateCoordinates();

    The result of the calculation should be:

    Geocentric Rectangular
    x: 4.1719826
    y: 1.966573890
    z: -0.101817535

    Geocentric Spherical
    Longitude: 25° 14' 17.091"
    Latitude: -1° 15' 52.651"
    Radius Vector: 4.613373871

    Distance to Earth and diameter

    Example: Get the distance and diameter of Venus for 02 October 2008 at 00:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createVenus} from 'astronomy-bundle/planets';
    
    const toi = createTimeOfInterest.fromTime(2008, 10, 2, 0, 0, 0);
    const venus = createVenus(toi);
    
    const d = await venus.getDistanceToEarth();
    const delta = await venus.getAngularDiameter();

    The result of the calculation should be:
    Distance to Earth: 206 930 461.4 km
    Diameter: 0° 00' 12.065"

    Phases of a Planet

    Example: Get the illumination of the Mars for 20 Match 2019 at 02:55 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createMars} from 'astronomy-bundle/planets';
    
    const toi = createTimeOfInterest.fromTime(2019, 3, 20, 2, 55, 0);
    const mars = createMars(toi);
    
    const k = await mars.getIlluminatedFraction();
    const isWaxing = await mars.isWaxing();

    The result of the calculation should be:
    Illumination: 0.929 (92.9%)
    Is waxing: true

    Apparent magnitude of a Planet

    Example: Get the apparent magnitude of Jupiter for 05 January 2012 at 00:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createJupiter} from 'astronomy-bundle/planets';
    
    const toi = createTimeOfInterest.fromTime(2012, 1, 5, 0, 0, 0);
    const jupiter = createJupiter(toi);
    
    const V = await jupiter.getApparentMagnitude();

    The result of the calculation should be: -2.52m

    Physical Observation of Planets

    Example: Get the geocentric Physical Observation of Venus for 30 July 2020 at 22:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createVenus} from 'astronomy-bundle/planets';
    
    const toi = createTimeOfInterest.fromTime(2020, 7, 30, 22, 0, 0);
    const venus = createVenus(toi);
    
    const phi = await venus.getElongation();
    const i = await venus.getPhaseAngle();
    const chi = await venus.getPositionAngleOfBrightLimb();

    The result of the calculation should be:
    Elongation from Sun: 45.09°
    Phase Angle: 98.85°
    Position Angle of bright Limb: 83.08°

    Conjunction of two Planets

    Example 1: Check if there is a conjunction between Jupiter and Saturn on 04 June 2018

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createJupiter, Saturn} from 'astronomy-bundle/planets';
    
    const toi = createTimeOfInterest.fromTime(2018, 6, 4, 0, 0, 0);
    const jupiter = createJupiter(toi);
    
    const {toi} = await jupiter.getConjunctionInRightAscensionTo(Saturn);

    This code will throw an error: No conjunction possible for given objects at 2458273.5

    Example 2: Check if there is a conjunction between Jupiter and Saturn on 21 December 2020

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createJupiter, Saturn} from 'astronomy-bundle/planets';
    
    const toi = createTimeOfInterest.fromTime(2020, 12, 21, 0, 0, 0);
    const jupiter = createJupiter(toi);
    
    const {toi, position, angularDistance} = await jupiter.getConjunctionInRightAscensionTo(Saturn);

    Result of the calculation:
    There is a conjunction on 21 December 2020 at 13:24 UTC
    And Jupiter is 06' 15.164" north of Saturn

    Stars

    Position of Stars

    Example 1: Given are the equatorial coordinates of epoch J2000.
    Right Ascension: 2h 44m 11.986s
    Declination: 49° 13' 42.48"
    Proper motion in Right Ascension: 0.03425"
    Proper motion in Declination: -0.0895"
    Calculate the apparent position for 04 November 2028 at 00:00 UTC

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createStar} from 'astronomy-bundle/stars';
    
    const toi = createTimeOfInterest.fromTime(2028, 11, 13, 0, 0, 0);
    
    const coordsJ2000 = {
        rightAscension: 41.04994167,
        declination: 49.22846667,
        radiusVector: 1,
    };
    
    const properMotion = {
        rightAscension: 0.0001427083,
        declination: -0.000024861,
    };
    
    const star = createStar.byEquatorialCoordinates(coordsJ2000, toi, properMotion);
    
    const coords = await star.getApparentGeocentricEquatorialSphericalCoordinates();

    The result of the calculation should be:

    Right Ascension: 2h 46m 14.548s
    Declination: 49° 21' 05.617"

    Example 2: You may pass the epoch in Julian Days to the constructor, in case the coordinates of a star are given for another epoch than J2000.

    import {createTimeOfInterest, EPOCH_J1950} from 'astronomy-bundle/time';
    import {createStar} from 'astronomy-bundle/stars';
    
    const toi = createTimeOfInterest.fromTime(2028, 11, 13, 0, 0, 0);
    
    const coordsJ1950 = {
        rightAscension: 41.04994167,
        declination: 49.22846667,
        radiusVector: 1,
    };
    
    const properMotion = {
        rightAscension: 0.0001427083,
        declination: -0.000024861,
    };
    
    const star = createStar.byEquatorialCoordinates(coordsJ1950, toi, properMotion, EPOCH_J1950);

    Solar Eclipse

    You can create a new Solar Eclipse object by using Besselian Elements or a given date using the TimeOfInterest object. This bundle contains all Besselian Elements from the year 1500 to 2500. To reduce the bundle size the createSolarEclipse.fromTimeOfInterest() function will load the Besselian Elements asynchronous.

    Example 1: Create the Solar Eclipse for 14 December 2020 using the TimeOfInterest object

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createSolarEclipse} from 'astronomy-bundle/solarEclipse';
    
    const toi = createTimeOfInterest.fromTime(2020, 12, 14, 0, 0, 0);
    
    const solarEclipse = await createSolarEclipse.fromTimeOfInterest(toi);

    Example 2: Create the Solar Eclipse for 14 December 2020 using the Besselian Elements
    Data source: https://eclipse.gsfc.nasa.gov/SEsearch/SEdata.php?Ecl=20201214

    import {createSolarEclipse} from 'astronomy-bundle/solarEclipse';
    
    const besselianElements = {
       tMax: 2459198.177,
       t0: 16,
       dT: 72.1,
       x: [-0.181824, 0.5633567, 0.0000216, -0.000009],
       y: [-0.269645, -0.0858122, 0.0001884, 0.0000015],
       d: [-23.2577591, -0.001986, 0.000006, 0],
       l1: [0.543862, 0.000097, -0.0000126, 0],
       l2: [-0.002265, 0.0000965, -0.0000125, 0],
       mu: [61.265911, 14.9965, 0, 0],
       tanF1: 0.0047502,
       tanF2: 0.0047266,
       latGreatestEclipse: -40.3,
       lonGreatestEclipse: -67.9,
    };
    
    const solarEclipse = createSolarEclipse.fromBesselianElements(besselianElements);

    Check if solar eclipse exists

    Example 1: Check if there is a Solar Eclipse on 15 January 2019

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {solarEclipseExists} from 'astronomy-bundle/solarEclipse';
    
    const toi = createTimeOfInterest.fromTime(2019, 1, 15, 0, 0, 0);
    const exists = solarEclipseExists(toi);

    Result of the calculation: There is no solar eclipse

    Example 2: Check if there is a Solar Eclipse on 21 August 2017

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {solarEclipseExists} from 'astronomy-bundle/solarEclipse';
    
    const toi = createTimeOfInterest.fromTime(2017, 8, 21, 0, 0, 0);
    const exists = solarEclipseExists(toi);

    Result of the calculation: Yes, there is a solar eclipse

    Greatest Eclipse

    Example: Get the location of the greatest eclipse for the total solar eclipse on 14 December 2020

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createSolarEclipse} from 'astronomy-bundle/solarEclipse';
    
    const toi = createTimeOfInterest.fromTime(2020, 12, 14, 0, 0, 0);
    const solarEclipse = await createSolarEclipse.fromTimeOfInterest(toi);
    
    const location = solarEclipse.getLocationOfGreatestEclipse();

    Result of the calculation:
    Lat: -40.3°
    Lon: -67.9°

    Observational Solar Eclipse Circumstances

    Observational circumstances are circumstances which are dependent on the location of the observer and the exact time. Some events during an eclipse are special:

    • C1: First contact of the moon and the sun. Beginning of the solar eclipse
    • C2: Beginning of totality or annularity (Only during total or annular eclipse)
    • Max: Maximum obscuration of the sun
    • C3: End of totality or annularity (Only during total or annular eclipse)
    • C4: Last contact of the moon and the sun. End of the solar eclipse

    Hint for examples: All examples below are using the following data:
    Eclipse date: 14 December 2020
    Location of the observer: -40.04842°, -70.07593° (Piedra del Águila, Argentina, elevation: 500 meters)

    Example 1: Get the observational circumstances for all contacts and the maximum eclipse.

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createSolarEclipse} from 'astronomy-bundle/solarEclipse';
    import {createLocation} from 'astronomy-bundle/earth';
    
    const toi = createTimeOfInterest.fromTime(2020, 12, 14, 0, 0, 0);
    const location = createLocation(-40.04842, -70.07593, 500);
    
    const solarEclipse = await createSolarEclipse.fromTimeOfInterest(toi);
    
    const localCircumstances = solarEclipse.getLocalCircumstances(location);
    
    const obsCircumstancesC1 = localCircumstances.getObservationalCircumstancesForC1();
    const obsCircumstancesC2 = localCircumstances.getObservationalCircumstancesForC2();
    const obsCircumstancesMax = localCircumstances.getObservationalCircumstancesForMaxEclipse();
    const obsCircumstancesC3 = localCircumstances.getObservationalCircumstancesForC3();
    const obsCircumstancesC4 = localCircumstances.getObservationalCircumstancesForC4();

    Example 2: Get the eclipse type, magnitude, moon-sun ratio and obscuration of the maximum eclipse for the given location.

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createSolarEclipse} from 'astronomy-bundle/solarEclipse';
    import {createLocation} from 'astronomy-bundle/earth';
    
    const toi = createTimeOfInterest.fromTime(2020, 12, 14, 0, 0, 0);
    const location = createLocation(-40.04842, -70.07593, 500);
    
    const solarEclipse = await createSolarEclipse.fromTimeOfInterest(toi);
    
    const obsCircumstances = solarEclipse
            .getLocalCircumstances(location)
            .getObservationalCircumstancesForMaxEclipse();
    
    const eclipseType = obsCircumstances.getEclipseType();
    const magnitude = obsCircumstances.getMagnitude();
    const moonSunRatio = obsCircumstances.getMoonSunRatio();
    const obscuration = obsCircumstances.getObscuration();

    Result of the calculation:
    Eclipse type: 3 (0 = none, 1 = partial, 2 = annular, 3 = total)
    Magnitude: 1.00633
    Moon-Sun ratio: 1.02535
    Obscuration: 100%

    In other words: The observer will see a total solar eclipse where to moon covers the sun 100%.

    Example 3: Get the eclipse type, magnitude, moon-sun ratio and obscuration of the maximum eclipse for an observer outside of the path of totality. Location: -37.47010, -72.36141

    import {createTimeOfInterest} from 'astronomy-bundle/time';
    import {createSolarEclipse} from 'astronomy-bundle/solarEclipse';
    import {createLocation} from 'astronomy-bundle/earth';
    
    const toi = createTimeOfInterest.fromTime(2020, 12, 14, 0, 0, 0);
    const location = createLocation(-37.47010, -72.36141, 135);
    
    const solarEclipse = await createSolarEclipse.fromTimeOfInterest(toi);
    
    const obsCircumstances = solarEclipse
            .getLocalCircumstances(location)
            .getObservationalCircumstancesForMaxEclipse();
    
    const eclipseType = obsCircumstances.getEclipseType();
    const magnitude = obsCircumstances.getMagnitude();
    const moonSunRatio = obsCircumstances.getMoonSunRatio();
    const obscuration = obsCircumstances.getObscuration();

    Result of the calculation:
    Eclipse type: 1 (0 = none, 1 = partial, 2 = annular, 3 = total)
    Magnitude: 0.96144
    Moon-Sun ratio: 1.02547
    Obscuration: 95.76%

    In other words: The observer will see a partial solar eclipse with a maximum obscuration of 95.8%.

    Satellites

    Two Line Elements

    Example: Parse Two Line Elements for the ISS

    import {parseTwoLineElement} from 'astronomy-bundle/satellites';
    
    const tleString = `
            ISS(ZARYA)
            1 25544U 98067A   06040.85138889  .00012260  00000-0  86027-4 0  3194
            2 25544  51.6448 122.3522 0008835 257.3473 251.7436 15.74622749413094
        `;
    
    const tle = parseTwoLineElement(tleString);

    Install

    npm i astronomy-bundle

    DownloadsWeekly Downloads

    524

    Version

    7.5.3

    License

    MIT

    Unpacked Size

    5.14 MB

    Total Files

    2651

    Last publish

    Collaborators

    • andrmoel