lib_ephemerisLibrary "lib_ephemeris"
Unified API for all planetary positions. Imports all planetary libraries
and provides simplified access functions, planetary averages, and
retrograde detection. Your primary interface for ephemeris data.
@author BlueprintResearch (Javonnii)
@license MIT License - Free to use with attribution
@theory Aggregates VSOP87, ELP2000-82, and Meeus algorithms
@accuracy Varies by planet - see individual library documentation
@time_scale Handles time conversion automatically based on celestial body
@reference Meeus, Jean. "Astronomical Algorithms" (2nd Ed., 1998)
Bretagnon & Francou. "VSOP87 Solutions" (1988)
Chapront-Touzé & Chapront. "ELP2000-82" (1983)
@showcase Includes commented showcase code with 250-bar future projection.
Uncomment to display unified planetary data with polyline projections.
@open_source This library is part of an open-source alternative to
proprietary astronomical libraries. Study, modify, and
share freely. We believe knowledge of the cosmos belongs
to everyone.
════════════════════════════════════════════════════════════════
© 2025 BlueprintResearch / Javonnii
Licensed under MIT License
════════════════════════════════════════════════════════════════
@version=6
normalizeLongitude(lon)
Normalizes any longitude value to the range [0, 360) degrees.
Parameters:
lon (float) : (float) Longitude in degrees (can be any value, including negative or >360).
Returns: (float) Normalized longitude in range [0, 360).
string_to_planet(planetStr)
Converts a planet string identifier to Planet enum value.
Parameters:
planetStr (string) : (string) Planet name (case-insensitive). Supports formats: "Sun", "☉︎ Sun", "sun", "SUN"
Returns: (Planet) Corresponding Planet enum. Returns Planet.Sun if string not recognized.
@note Supported planet strings: Sun, Moon, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto
get_longitude(p, t, preferGeo)
Returns planetary longitude with automatic coordinate system selection.
Parameters:
p (series Planet) : (Planet) Planet to query.
t (float) : (float) Unix timestamp in milliseconds (use built-in 'time' variable).
preferGeo (bool) : (bool) If true, return geocentric; if false, return heliocentric.
Returns: (float) Longitude in degrees, normalized to range [0, 360).
@note Sun and Moon always return geocentric regardless of preference (heliocentric not applicable).
get_declination(p, t)
Returns planetary geocentric equatorial declination.
Parameters:
p (series Planet) : (Planet) Planet to query.
t (float) : (float) Unix timestamp in milliseconds (use built-in 'time' variable).
Returns: (float) Geocentric declination in degrees, range where positive is north.
@note Declination is always geocentric (no heliocentric equivalent in library).
get_speed(p, t)
Returns planetary geocentric longitude speed (rate of change).
Parameters:
p (series Planet) : (Planet) Planet to query.
t (float) : (float) Unix timestamp in milliseconds (use built-in 'time' variable).
Returns: (float) Geocentric longitude speed in degrees per day. Negative values indicate retrograde motion. Returns na for Moon.
@note Speed is always geocentric (no heliocentric equivalent in library). Moon speed calculation not implemented.
get_avg6_geo_lon(t)
get_avg6_geo_lon
@description Returns the arithmetic average of the geocentric longitudes for the six outer planets: Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Parameters:
t (float) : (float) Time in Unix timestamp (milliseconds).
Returns: (float) Average geocentric longitude of the six outer planets in degrees, range [0, 360).
get_avg6_helio_lon(t)
get_avg6_helio_lon
@description Returns the arithmetic average of the heliocentric longitudes for the six outer planets: Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Parameters:
t (float) : (float) Time in Unix timestamp (milliseconds).
Returns: (float) Average heliocentric longitude of the six outer planets in degrees, range [0, 360).
get_avg8_geo_lon(t)
get_avg8_geo_lon
@description Returns the arithmetic average of the geocentric longitudes for all eight classical planets: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Parameters:
t (float) : (float) Time in Unix timestamp (milliseconds).
Returns: (float) Average geocentric longitude of all eight classical planets in degrees, range [0, 360).
get_avg8_helio_lon(t)
get_avg8_helio_lon
@description Returns the arithmetic average of the heliocentric longitudes for all eight classical planets: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Parameters:
t (float) : (float) Time in Unix timestamp (milliseconds).
Returns: (float) Average heliocentric longitude of all eight classical planets in degrees, range [0, 360).
is_retrograde(p, t)
Returns true if the planet is currently in retrograde motion (geocentric speed < 0) == 0 = stationary.
Parameters:
p (series Planet) : The planet to check.
t (float) : Time in Unix timestamp (milliseconds).
Returns: true if the planet is in retrograde, false otherwise.
Geocentric
Astro: Planetary Aspects v2.0I have updated the excellent script originally written by @BarefootJoey with additional functionality as listed below the script's original description:
@BarefootJoey:
In astrology, planetary aspects refer to the angles formed between two or more planets in a horoscope or birth chart. These angles are created by the positions of the planets in the sky and are thought to represent a particular energy or influence that can impact events on Earth.
The most common planetary aspects are the conjunction (when two planets are in the same position in the zodiac), the opposition (when two planets are direct across from each other in the zodiac), the trine (when two planets are 120 degrees apart in the zodiac), and the square (when two planets are 90 degrees apart in the zodiac).
This oscillator plots the current geocentric/heliocentric aspect for up to two planets and features a customizable precision of degree (up to +/- 15 degrees) for each aspect.
Additional functionality added in by @Yevolution:
1. Overlay the indicator plot on top of the main chart, with the indicator's scale placed on the left - I found it easier to spot price reactions at a given planetary aspect vs seeing the plot in a separate frame
2. Add options to plot a vertical bar for every occurrence of chosen aspects
The script source code has remained open and additional comments have been added by me to explain the changes where relevant.
When I get some more spare time I will add a function to enable future planetary aspect events to also be displayed on the chart to make forecasting using this data easier.
