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 [-90, +90]
• 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 [-90, +90] 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.