astronoby 0.7.0 → 0.9.0

data/docs/reference_frames.md

@@ -0,0 +1,138 @@
+# Reference Frames
+
+A given body at a given time can be perceived at different positions, depending
+on the reference frame and the corrections applied.
+
+Astronoby provides five reference frames for each celestial body:
+
+* Geometric
+* Astrometric
+* Mean of date
+* Apparent
+* Topocentric
+
+All reference frames provide this common interface:
+
+* `#position`: Vector of position as x,y,z `Astronoby::Distance` objects
+* `#velocity`: Vector of velocity as x,y,z `Astronoby::Velocity` objects
+* `#distance`: Distance from the centre (`Astronoby::Distance`)
+* `#equatorial`: Equatorial coordinates (`Astronoby::Coordinates::Equatorial`)
+* `#ecliptic`: Ecliptic coordinates (`Astronoby::Coordinates::Ecliptic`)
+
+## Geometric
+
+Also called "mean J2000", this reference frame is related to the mean ecliptic
+or terrestrial equator and the mean equinox of the reference date (J2000). It is
+the strict position computed from the ephemeris file in a reference frame
+centered on the Solar System barycentre, with no corrections applied.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+geometric = moon.geometric
+# => #<Astronoby::Geometric:0x000000011e7ffd40
+
+geometric.distance.au
+# => 1.0095091198501744
+
+geometric.equatorial.right_ascension.str(:hms, precision: 0)
+# => "20h 13m 52s"
+```
+
+## Astrometric
+
+Also called "astrometric J2000", this reference frame is related to the ecliptic
+or the mean terrestrial equator and the mean equinox of the reference date
+(J2000). It applies light-time correction between the celestial body and the
+observer. The frame is centred on the Earth's centre, as are all the following
+reference frames.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+astrometric = moon.astrometric
+
+astrometric.distance.km.round
+# => 371187
+
+astrometric.equatorial.right_ascension.str(:hms, precision: 0)
+# => "1h 54m 27s"
+```
+
+## Mean of date
+
+This reference frame is related to the ecliptic or the mean equator and the mean
+equinox of the date. It provides the geometric position corrected for the
+precessional motion of the Earth's rotation axis (precession and nutation).
+
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+mean_of_date = moon.mean_of_date
+
+mean_of_date.equatorial.right_ascension.str(:hms, precision: 0)
+# => "1h 52m 29s"
+```
+
+## Apparent
+
+This reference frame is related to the true ecliptic or equator and the true
+equinox of the date. It is the actual position in the sky of a celestial object
+as seen from the centre of the Earth. It applies several corrections to the
+astrometric position:the deflection of light, the aberration, the precession and
+the nutation.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+apparent = moon.apparent
+
+apparent.equatorial.right_ascension.str(:hms, precision: 0)
+# => "1h 52m 28s"
+```
+
+## Topocentric
+
+This reference frame is the final transformation of a position. It provides the
+apparent position of a celestial body as seen from a location on Earth. It can
+only be produced given an observer (`Astronoby::Observer`). It provides another
+set of coordinates: horizontal (`Astronoby::Coordinates::Horizontal`).
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48.838),
+  longitude: Astronoby::Angle.from_degrees(2.4843)
+)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+topocentric = moon.observed_by(observer)
+
+topocentric.horizontal.azimuth.str(:dms, precision: 0)
+# => "+90° 14′ 19″"
+```
+
+You can learn more about observers on the [Observer page].
+
+## See also
+- [Coordinates](coordinates.md) - for understanding coordinate systems
+- [Observer](observer.md) - for location setup
+- [Solar System Bodies](solar_system_bodies.md) - for object positions
+- [Ephemerides](ephem.md) - for data sources
+
+[Observer page]: observer.md

data/docs/rise_transit_set_times.md

@@ -0,0 +1,119 @@
+# Rise, Transit and Set Times
+
+Astronoby provides a calculator to compute all the rise, transit and set times
+that will happen for a celestial body as observed from Earth during a period
+of time: `Astronoby::RiseTransitSetCalculator`.
+
+## Initialization
+
+Once instantiated, the calculator doesn't do anything yet, it waits for your
+instruction.
+
+It takes as key arguments:
+* `body` (`Astronoby::SolarSystemBody` or `Astronoby::DeepSkyObject`): any
+  supported celestial body, e.g. `Astronoby::Sun`
+* `observer` (`Astronoby::Observer`): location on Earth of the observer
+* `ephem`: ephemeris to provide the initial raw data
+
+You can learn more about [Solar System bodies] and [ephemerides].
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(41.0082),
+  longitude: Astronoby::Angle.from_degrees(28.9784),
+  elevation: Astronoby::Distance.from_meters(40)
+)
+
+calculator = Astronoby::RiseTransitSetCalculator.new(
+  body: Astronoby::Saturn,
+  observer: observer,
+  ephem: ephem
+)
+```
+
+You can learn more about observers on the
+[Observer page](https://github.com/rhannequin/astronoby/wiki/Observer).
+
+## `#events_between`
+
+This is the main method of the calculator. It provides all the rising, transit
+and setting times that will happen between two dates. It returns a
+`Astronoby::RiseTransitSetEvents` object which exposes the methods
+`#rising_times`, `#transit_times` and `#setting_times`.
+
+```rb
+events = calculator.events_between(
+  Time.utc(2025, 5, 1),
+  Time.utc(2025, 5, 3)
+)
+
+events.rising_times
+# => [2025-05-01 01:28:48 UTC, 2025-05-02 01:25:07 UTC]
+
+events.transit_times
+# => [2025-05-01 07:21:34 UTC, 2025-05-02 07:18:01 UTC]
+
+events.setting_times
+# => [2025-05-01 13:14:24 UTC, 2025-05-02 13:10:59 UTC]
+```
+
+## `#events_on`
+
+You can call `#events_on` to compute the event times that will happen during a
+civil day. You can provide a UTC offset to specify the boundaries of the civil
+day for your location.
+
+This method also returns a `Astronoby::RiseTransitSetEvents` object because some
+celestial bodies could occasionally have the same event happen multiple times in
+a single day. This is the case for the Moon, for example, which can seem to rise
+twice in the same civil day because of its quick motion around the Earth.
+
+```rb
+events = calculator.events_on(Date.new(2025, 5, 1))
+
+events.rising_times
+# => [2025-05-01 01:28:48 UTC]
+
+events.transit_times
+# => [2025-05-01 07:21:34 UTC]
+
+events.setting_times
+# => [2025-05-01 13:14:24 UTC]
+```
+
+## `#event_on`
+
+For convenience, `Astronoby::RiseTransitSetCalculator` also exposes a
+`#event_on` method that behaves the same way as `#events_on` but returns the
+first time of rising, transit and setting for the civil date, as these events
+only happen once in most cases. It returns a `Astronoby::RiseTransitSetEvent`
+which exposes the instance methods `#rising_time`, `#transit_time` and
+`#setting_time`.
+
+```rb
+utc_offset = "+03:00"
+event = calculator.event_on(
+  Date.new(2025, 5, 1),
+  utc_offset: utc_offset
+)
+
+event.rising_time.localtime(utc_offset)
+# => 2025-05-01 04:28:48 +0300
+
+event.transit_time.localtime(utc_offset)
+# => 2025-05-01 10:21:34 +0300
+
+event.setting_time.localtime(utc_offset)
+# => 2025-05-01 16:14:24 +0300
+```
+
+[Solar System bodies]: solar_system_bodies.md
+[ephemerides]: ephem.md
+
+## See also
+- [Twilight Times](twilight_times.md) - for sun-related events
+- [Solar System Bodies](solar_system_bodies.md) - for object information
+- [Observer](observer.md) - for location setup
+- [Ephemerides](ephem.md) - for data sources

data/docs/solar_system_bodies.md

@@ -0,0 +1,107 @@
+# Solar System Bodies
+
+Currently, Astronoby only supports the following major bodies of the Solar
+System:
+* the Sun (`Astronoby::Sun`)
+* planets from Mercury to Neptune, including the Earth (`Astronoby::Earth`, ...)
+* the Moon (`Astronoby::Moon`)
+
+Given an ephemeris (`Astronoby::Ephem`) and an instant object
+(`Astronoby::Instant`), these classes enable you to get instances which provide
+positions in different reference frames.
+
+You can learn more about [ephemerides] and [reference frames].
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(2021, 7, 8)
+instant = Astronoby::Instant.from_time(time)
+
+venus = Astronoby::Venus.new(ephem: ephem, instant: instant)
+apparent_position = venus.apparent.position
+
+apparent_position.x.km.round
+# => -148794622
+```
+
+Each of these bodies also provides its own equatorial radius
+(`Astronoby::Distance`).
+
+```rb
+Astronoby::Venus::EQUATORIAL_RADIUS.meters
+# => 6051800
+```
+
+## Attributes of planets
+
+For all Solar System bodies, except the Sun and the Earth, the following
+attributes are available. Note that dynamic values are accessible through
+instance methods, while absolute values are accessible through class methods.
+
+### `#angular_diameter`
+
+Size of the body in the sky. Returns a `Astronoby::Angle` object.
+
+```rb
+venus.angular_diameter.str(:dms)
+# => "+0° 0′ 11.4587″"
+```
+
+### `#constellation`
+
+Constellation where the body appears in the sky as seen from Earth. Returns
+a `Astronoby::Constellation` object.
+
+```rb
+venus.constellation.name
+# => "Cancer"
+
+venus.constellation.abbreviation
+# => "Cnc"
+```
+
+### `#phase_angle`
+
+"Sun-object-Earth" angle. Returns a `Astronoby::Angle` object.
+
+```rb
+venus.phase_angle.degrees.round
+# => 40
+```
+
+### `#illuminated_fraction`
+
+Fraction of the object's disk illuminated as seen from Earth. Returns a `Float`
+between `0` and `1`.
+
+```rb
+venus.illuminated_fraction.round(2)
+# => 0.88
+```
+
+### `#apparent_magnitude`
+
+Apparent brightness of the body. Returns a `Float`.
+
+```rb
+venus.apparent_magnitude.round(2)
+# => -3.89
+```
+
+### `::absolute_magnitude`
+
+Absolute brightness of the body. Returns a `Float`.
+
+```rb
+Astronoby::Venus.absolute_magnitude
+# => -4.384
+```
+
+[ephemerides]: ephem.md
+[reference frames]: reference_frames.md
+
+## See also
+- [Ephemerides](ephem.md) - for understanding data sources
+- [Reference Frames](reference_frames.md) - for coordinate systems
+- [Observer](observer.md) - for setting up observation locations
+- [Angles](angles.md) - for working with angular measurements

data/docs/twilight_times.md

@@ -0,0 +1,123 @@
+# Twilight times
+
+In astronomy, twilight is a period of time when the Sun is already set but
+some of its light still illuminates the atmosphere, making the sky brighter than
+during full night.
+
+We usually define 4 moments when talking about twilight:
+* sunrise/sunset: right when the Sun goes above the horizon or right after it
+  goes below the horizon. The Sun's horizon angle is 0°.
+* civil twilight: when the horizon angle is between 0° and -6°. Usually, during
+  this time, artificial light is not needed yet.
+* nautical twilight: when the horizon angle is between -6° and -12°. When the
+  nautical twilight starts, the difference between the horizon at sea and the
+  sky cannot be seen clearly anymore.
+* astronomical twilight: when the horizon angle is between -12° and -18°. Some
+  stars can be seen during this time.
+
+These moments change every day and depend on the observer's location. They can
+be computed using `Astronoby::TwilightCalculator`.
+
+## Initialization
+
+Once instantiated, the calculator doesn't do anything yet, it waits for your
+instruction.
+
+It takes as key arguments:
+* `observer` (`Astronoby::Observer`): location on Earth of the observer
+* `ephem`: ephemeris to provide the initial raw data
+
+You can learn more about ephemerides on the [Ephem page].
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(41.0082),
+  longitude: Astronoby::Angle.from_degrees(28.9784),
+  elevation: Astronoby::Distance.from_meters(40)
+)
+
+calculator = Astronoby::TwilightCalculator.new(
+  observer: observer,
+  ephem: ephem
+)
+```
+
+You can learn more about observers on the [Observer page].
+
+## `events_between`
+
+This is the main method of the calculator. It provides all the twilight times
+that will happen between two dates.
+
+It returns a `Astronoby::TwilightEvents` object which exposes the 6 following
+instance methods:
+* `#morning_astronomical_twilight_times`: when the rising Sun reaches 18° below
+  the horizon
+* `#morning_nautical_twilight_times`: when the rising Sun reaches 12° below the
+  horizon
+* `#morning_civil_twilight_times`: when the rising Sun reaches 6° below the
+  horizon
+* `#evening_civil_twilight_times`: when the setting Sun reaches 6° below the
+  horizon
+* `#evening_nautical_twilight_times`: when the setting Sun reaches 12° below the
+  horizon
+* `#evening_astronomical_twilight_times`: when the setting Sun reaches 18° below
+  the horizon
+
+```rb
+events = calculator.events_between(
+  Time.utc(2025, 8, 1),
+  Time.utc(2025, 8, 8)
+)
+
+events.morning_civil_twilight_times
+# =>
+# [2025-08-01 02:29:17 UTC,
+#  2025-08-02 02:30:21 UTC,
+#  2025-08-03 02:31:26 UTC,
+#  2025-08-04 02:32:30 UTC,
+#  2025-08-05 02:33:35 UTC,
+#  2025-08-06 02:34:40 UTC,
+#  2025-08-07 02:35:45 UTC]
+```
+
+## `#event_on`
+
+The calculator exposes the instance method `#event_on` to compute the twilight
+times for a given `date` (`Date`) parameter.
+
+It returns a `Astronoby::TwilightEvent` object which exposes the 6 following
+instance methods: `#morning_astronomical_twilight_time`,
+`#morning_nautical_twilight_time`, `#morning_civil_twilight_time`,
+`#evening_civil_twilight_time`, `#evening_nautical_twilight_time` and
+`#evening_astronomical_twilight_time`.
+
+```rb
+event = calculator.event_on(Date.new(2025, 5, 1))
+
+event.morning_astronomical_twilight_time
+# => 2025-05-01 01:17:18 UTC
+
+event.morning_nautical_twilight_time
+# => 2025-05-01 01:56:48 UTC
+
+event.evening_civil_twilight_time
+# => 2025-05-01 17:29:41 UTC
+
+event.evening_nautical_twilight_time
+# => 2025-05-01 18:06:08 UTC
+
+event.evening_astronomical_twilight_time
+# => 2025-05-01 18:45:38 UTC
+```
+
+[Ephem page]: ephem.md
+[Observer page]: observer.md
+
+## See also
+- [Rise, Transit and Set Times](rise_transit_set_times.md) - for sun and moon events
+- [Observer](observer.md) - for location setup
+- [Ephemerides](ephem.md) - for data sources
+- [Moon Phases](moon_phases.md) - for lunar events

data/lib/astronoby/angle.rb

@@ -73,6 +73,10 @@ module Astronoby
       @radians * Constants::PI_IN_DEGREES / Math::PI
     end
 
+    def degree_milliarcseconds
+      degrees * Constants::MILLIARCSECONDS_PER_DEGREE
+    end
+
     def hours
       @radians / Constants::RADIAN_PER_HOUR
     end
@@ -139,10 +143,10 @@ module Astronoby
       sign = degrees.negative? ? "-" : "+"
       absolute_degrees = degrees.abs
       deg = absolute_degrees.floor
-      decimal_minutes = Constants::MINUTES_PER_DEGREE *
+      decimal_minutes = Constants::ARCMINUTES_PER_DEGREE *
         (absolute_degrees - deg)
       absolute_decimal_minutes = (
-        Constants::MINUTES_PER_DEGREE * (absolute_degrees - deg)
+        Constants::ARCMINUTES_PER_DEGREE * (absolute_degrees - deg)
       ).abs
       minutes = decimal_minutes.floor
       seconds = Constants::SECONDS_PER_MINUTE * (

data/lib/astronoby/angular_velocity.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class AngularVelocity
+    include Comparable
+
+    class << self
+      def zero
+        new(0)
+      end
+
+      def from_radians_per_second(radians_per_second)
+        new(radians_per_second)
+      end
+
+      def from_milliarcseconds_per_year(mas_per_year)
+        angle = Angle.from_degree_arcseconds(mas_per_year / 1000.0)
+        radians_per_second = angle.radians / Constants::SECONDS_PER_JULIAN_YEAR
+        new(radians_per_second)
+      end
+    end
+
+    attr_reader :radians_per_second
+    alias_method :rps, :radians_per_second
+
+    def initialize(radians_per_second)
+      @radians_per_second = radians_per_second
+      freeze
+    end
+
+    def milliarcseconds_per_year
+      angle = Angle.from_radians(@radians_per_second)
+      angle.degree_milliarcseconds * Constants::SECONDS_PER_JULIAN_YEAR
+    end
+    alias_method :mas_per_year, :milliarcseconds_per_year
+
+    def +(other)
+      self.class.from_radians_per_second(
+        @radians_per_second + other.radians_per_second
+      )
+    end
+
+    def -(other)
+      self.class.from_radians_per_second(
+        @radians_per_second - other.radians_per_second
+      )
+    end
+
+    def -@
+      self.class.from_radians_per_second(-@radians_per_second)
+    end
+
+    def positive?
+      @radians_per_second > 0
+    end
+
+    def negative?
+      @radians_per_second < 0
+    end
+
+    def zero?
+      @radians_per_second.zero?
+    end
+
+    def hash
+      [@radians_per_second, self.class].hash
+    end
+
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      @radians_per_second <=> other.radians_per_second
+    end
+    alias_method :eql?, :==
+  end
+end

data/lib/astronoby/bodies/deep_sky_object.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class DeepSkyObject
+    # @param equatorial_coordinates [Astronoby::Coordinates::Equatorial]
+    #   Equatorial coordinates at epoch J2000.0
+    # @param proper_motion_ra [Astronoby::AngularVelocity, nil] Proper motion in
+    #   right ascension
+    # @param proper_motion_dec [Astronoby::AngularVelocity, nil] Proper motion
+    #   in declination
+    # @param parallax [Astronoby::Angle, nil] Parallax angle
+    # @param radial_velocity [Astronoby::Velocity, nil] Radial velocity
+    def initialize(
+      equatorial_coordinates:,
+      proper_motion_ra: nil,
+      proper_motion_dec: nil,
+      parallax: nil,
+      radial_velocity: nil
+    )
+      @initial_equatorial_coordinates = equatorial_coordinates
+      @proper_motion_ra = proper_motion_ra
+      @proper_motion_dec = proper_motion_dec
+      @parallax = parallax
+      @radial_velocity = radial_velocity
+    end
+
+    # @param instant [Astronoby::Instant] Instant of the observation
+    # @param ephem [Astronoby::Ephemeris, nil] Ephemeris to use for Earth
+    #   position calculation
+    # @return [Astronoby::DeepSkyObjectPosition] Position of the deep-sky object
+    #   at the given instant
+    def at(instant, ephem: nil)
+      DeepSkyObjectPosition.new(
+        instant: instant,
+        equatorial_coordinates: @initial_equatorial_coordinates,
+        ephem: ephem,
+        proper_motion_ra: @proper_motion_ra,
+        proper_motion_dec: @proper_motion_dec,
+        parallax: @parallax,
+        radial_velocity: @radial_velocity
+      )
+    end
+  end
+end