lib_ephemeris █ PLANETARY EPHEMERIS MASTER LIBRARY
Unified API for calculating planetary positions. Import this single library to access all 11 celestial bodies: Sun, Moon, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto.
Theory: VSOP87 (planets), ELP2000-82 (Moon), Meeus (Pluto)
═══════════════════════════════════════════════════════════════
█ QUICK START
//@version=6
indicator("Planetary Ephemeris Demo")
import BlueprintResearch/lib_ephemeris/1 as eph
// Get all planets
sun = eph.string_to_planet("Sun")
moon = eph.string_to_planet("Moon")
mercury = eph.string_to_planet("Mercury")
venus = eph.string_to_planet("Venus")
mars = eph.string_to_planet("Mars")
jupiter = eph.string_to_planet("Jupiter")
saturn = eph.string_to_planet("Saturn")
uranus = eph.string_to_planet("Uranus")
neptune = eph.string_to_planet("Neptune")
pluto = eph.string_to_planet("Pluto")
// Get longitude for each planet (geocentric)
sun_lon = eph.get_longitude(sun, time, true)
moon_lon = eph.get_longitude(moon, time, true)
mercury_lon = eph.get_longitude(mercury, time, true)
venus_lon = eph.get_longitude(venus, time, true)
mars_lon = eph.get_longitude(mars, time, true)
jupiter_lon = eph.get_longitude(jupiter, time, true)
saturn_lon = eph.get_longitude(saturn, time, true)
uranus_lon = eph.get_longitude(uranus, time, true)
neptune_lon = eph.get_longitude(neptune, time, true)
pluto_lon = eph.get_longitude(pluto, time, true)
// Plot all planets
plot(sun_lon, "Sun", color.yellow)
plot(moon_lon, "Moon", color.silver)
plot(mercury_lon, "Mercury", color.orange)
plot(venus_lon, "Venus", color.green)
plot(mars_lon, "Mars", color.red)
plot(jupiter_lon, "Jupiter", color.purple)
plot(saturn_lon, "Saturn", color.olive)
plot(uranus_lon, "Uranus", color.aqua)
plot(neptune_lon, "Neptune", color.blue)
plot(pluto_lon, "Pluto", color.gray)
═══════════════════════════════════════════════════════════════
█ AVAILABLE FUNCTIONS
Core Data Access:
• string_to_planet(string) → Planet enum
• get_longitude(Planet, time, preferGeo) → degrees [0, 360)
• get_declination(Planet, time) → degrees
• get_speed(Planet, time) → degrees/day
• is_retrograde(Planet, time) → true/false
Planetary Averages:
• get_avg6_geo_lon(time) → 6 outer planets average
• get_avg6_helio_lon(time)
• get_avg8_geo_lon(time) → 8 classical planets average
• get_avg8_helio_lon(time)
Utility:
• normalizeLongitude(lon) → normalize to [0, 360)
═══════════════════════════════════════════════════════════════
█ SUPPORTED PLANET STRINGS
Works with symbols or plain names (case-insensitive):
• "☉︎ Sun" or "Sun"
• "☽︎ Moon" or "Moon"
• "☿ Mercury" or "Mercury"
• "♀ Venus" or "Venus"
• "🜨 Earth" or "Earth"
• "♂ Mars" or "Mars"
• "♃ Jupiter" or "Jupiter"
• "♄ Saturn" or "Saturn"
• "⛢ Uranus" or "Uranus"
• "♆ Neptune" or "Neptune"
• "♇ Pluto" or "Pluto"
═══════════════════════════════════════════════════════════════
█ COORDINATE SYSTEMS
Geocentric: Positions relative to Earth (default for Sun/Moon)
Heliocentric: Positions relative to the Sun
Use the preferGeo parameter in get_longitude():
• true = geocentric
• false = heliocentric
Sun and Moon always return geocentric (heliocentric not applicable).
═══════════════════════════════════════════════════════════════
█ FUTURE PROJECTIONS
Project planetary positions into the future using polylines:
import BlueprintResearch/lib_vsop_core/1 as core
// Get future timestamp (250 bars ahead)
future_time = core.get_future_time(time, 250)
// Calculate future position
future_lon = eph.get_longitude(mars, future_time, true)
Use with polyline.new() to draw projected paths on your chart. See the commented showcase code in this library's source for a complete 250-bar projection example.
═══════════════════════════════════════════════════════════════
█ OPEN SOURCE
This library is part of an open-source planetary ephemeris project.
Free to use with attribution. MIT License.
═══════════════════════════════════════════════════════════════
█ REFERENCES
• Meeus, Jean. "Astronomical Algorithms" (2nd Ed., 1998)
• Bretagnon & Francou. "VSOP87 Solutions" (1988)
• Chapront-Touzé & Chapront. "ELP2000-82" (1983)
═══════════════════════════════════════════════════════════════
© 2025 BlueprintResearch (Javonnii) • 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.
