Skip to content

README.md

Latest commit

 

History

History
289 lines (209 loc) · 7.23 KB

README.md

File metadata and controls

289 lines (209 loc) · 7.23 KB
Raw

Quick Start

Download an ephemeris

You only need to run this once, it will download and store an ephemeris on your file system.

Ephem::IO::Download.call(name: "de421.bsp", target: "tmp/de421.bsp")

Ephemerides can be large files, but Astronoby provides a tool to drastically reduce the size to your needs. You can learn more about ephemerides on the Ephem page.

Load an ephemeris

ephem = Astronoby::Ephem.load("tmp/de421.bsp")

Define a time and create an Instant object from it

time = Time.utc(2025, 6, 19, 12, 0, 0)
instant = Astronoby::Instant.from_time(time)

You can learn more about time scales on the Instant page.

Instantiate a Solar System body object

jupiter = Astronoby::Jupiter.new(instant: instant, ephem: ephem)

You can learn more about planets and bodies on the Solar System Bodies page.

Define an observer from geographic coordinates

observer = Astronoby::Observer.new(
  latitude: Astronoby::Angle.from_degrees(48.83661378408946),
  longitude: Astronoby::Angle.from_degrees(2.3366748126024466),
  elevation: Astronoby::Distance.from_meters(65)
)

You can learn more about angles on the Angles page, and about observers on the Observer page.

Compute the topocentric position of the body as seen from the observer

topocentric = jupiter.observed_by(observer)

You can learn more about reference frames and positions on the Reference Frames page.

Get the horizontal coordinates from the position

topocentric.horizontal.azimuth.str(:dms)
# => "+175° 34′ 33.2353″"

topocentric.horizontal.altitude.str(:dms)
# => "+64° 22′ 58.229″"

You can learn more about coordinates on the Coordinates page.

Get the rising, transit and setting times between two times

calculator = Astronoby::RiseTransitSetCalculator.new(
  body: Astronoby::Jupiter,
  observer: observer,
  ephem: ephem
)

events = calculator.events_between(
  Time.utc(2025, 5, 1),
  Time.utc(2025, 5, 3),
)

events.rising_times
# => [2025-05-01 06:35:35 UTC, 2025-05-02 06:32:26 UTC]

events.transit_times
# => [2025-05-01 14:34:34 UTC, 2025-05-02 14:31:31 UTC]

events.setting_times
# => [2025-05-01 22:33:37 UTC, 2025-05-02 22:30:39 UTC]

You can learn more about this calculator on the Rise, transit and setting times page.

Get the twilight times of the day

calculator = Astronoby::TwilightCalculator.new(
  observer: observer,
  ephem: ephem
)

event = calculator.event_on(Date.new(2025, 5, 1))

event.morning_astronomical_twilight_time
# => 2025-05-01 02:17:07 UTC

event.morning_nautical_twilight_time
# => 2025-05-01 03:09:44 UTC

event.morning_civil_twilight_time
# => 2025-05-01 03:54:38 UTC

event.evening_civil_twilight_time
# => 2025-05-01 19:41:51 UTC

event.evening_nautical_twilight_time
# => 2025-05-01 20:26:56 UTC

event.evening_astronomical_twilight_time
# => 2025-05-01 21:19:57 UTC

You can learn more about this calculator on the Twilight times page.

Moon phases

You can either get all the major Moon phases that will happen in a month, or get information about the current Moon phase.

may_2024_phases = Astronoby::Events::MoonPhases.phases_for(year: 2024, month: 5)

may_2024_phases.each { puts "#{_1.phase}: #{_1.time}" }
# last_quarter: 2024-05-01 11:27:15 UTC
# new_moon: 2024-05-08 03:21:56 UTC
# first_quarter: 2024-05-15 11:48:02 UTC
# full_moon: 2024-05-23 13:53:12 UTC
# last_quarter: 2024-05-30 17:12:42 UTC
time = Time.utc(2025, 5, 15)
instant = Astronoby::Instant.from_time(time)
moon = Astronoby::Moon.new(ephem: ephem, instant: instant)

moon.illuminated_fraction.round(2)
# => 0.95

moon.current_phase_fraction.round(2)
# => 0.59

You can learn more about phases on the Moon phases page.

Lunar observation

time = Time.utc(2025, 3, 1)
instant = Astronoby::Instant.from_time(time)
moon = Astronoby::Moon.new(ephem: ephem, instant: instant)

moon.libration.longitude.str(:dms)
# => "-2° 5′ 4.4219″"

moon.libration.latitude.str(:dms)
# => "+0° 28′ 45.9616″"

moon.position_angle_of_axis.str(:dms)
# => "-21° 48′ 46.657″"

moon.bright_limb_position_angle.str(:dms)
# => "+248° 1′ 57.9467″"

You can learn more about libration, axis and limb angles on the Lunar observation page.

Lunar eclipses

eclipses = Astronoby::Moon.eclipse_events(
  ephem: ephem,
  start_time: Time.utc(2025, 1, 1),
  end_time: Time.utc(2026, 1, 1)
)

eclipses.map { |eclipse| [eclipse.instant.to_time, eclipse.kind] }
# => [[2025-03-14 06:58:47 UTC, :total], [2025-09-07 18:11:49 UTC, :total]]

You can learn more about umbral and penumbral magnitudes, phases and contact times on the Lunar eclipses page.

Equinox and solstice times

Astronoby::EquinoxSolstice.march_equinox(2025, ephem)
# => 2025-03-20 09:01:29 UTC

Astronoby::EquinoxSolstice.june_solstice(2025, ephem)
# => 2025-06-21 02:42:16 UTC

Astronoby::EquinoxSolstice.september_equinox(2025, ephem)
# => 2025-09-22 18:19:21 UTC

Astronoby::EquinoxSolstice.december_solstice(2025, ephem)
# => 2025-12-21 15:03:05 UTC

You can learn more about equinoxes and solstices on the Equinoxes and solstices times page.

Planetary phenomena

Astronoby::Mars.opposition_events(
  ephem: ephem,
  start_time: Time.utc(2025, 1, 1),
  end_time: Time.utc(2026, 1, 1)
).first.instant.to_time
# => 2025-01-16 02:38:35 UTC

Astronoby::Venus.greatest_elongation_events(
  ephem: ephem,
  start_time: Time.utc(2025, 1, 1),
  end_time: Time.utc(2026, 1, 1)
).first.angle.degrees.round(1)
# => 47.2

You can learn more about conjunctions, oppositions and greatest elongations on the Planetary phenomena page.

Deep-sky objects

It is possible to manipulate any deep-sky possible, given equatorial coordinates from a catalogue at J2000 epoch.

time = Time.utc(2025, 10, 1)
instant = Astronoby::Instant.from_time(time)

vega_j2000 = Astronoby::Coordinates::Equatorial.new(
  right_ascension: Astronoby::Angle.from_hms(18, 36, 56.33635),
  declination: Astronoby::Angle.from_dms(38, 47, 1.2802),
  epoch: Astronoby::JulianDate::J2000
)

# Build the body for star Vega
vega = Astronoby::DeepSkyObject.new(equatorial_coordinates: vega_j2000)

# Build the position of star Vega for a given instant
vega_position = vega.at(instant)

vega_position.apparent.equatorial.right_ascension.str(:hms)
# => "18h 37m 48.2804s"

You can learn more about deep-sky objects on the Deep-sky Bodies page.

See also