astronoby 0.9.0 → 0.11.0

data/lib/astronoby/constants.rb

@@ -36,6 +36,7 @@ module Astronoby
 
     # WGS84 Earth Constants
     WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS = 6378137
+    IAU_MOON_RADIUS_IN_METERS = 0.2725076 * WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS
     WGS84_INVERSE_FLATTENING = 298.257223563
     WGS84_FLATTENING = 1.0 / WGS84_INVERSE_FLATTENING
     WGS84_ECCENTICITY_SQUARED = 2.0 * WGS84_FLATTENING - WGS84_FLATTENING * WGS84_FLATTENING
@@ -45,7 +46,5 @@ module Astronoby
     EARTH_FLATTENING_CORRECTION = 0.996647
 
     EARTH_ANGULAR_VELOCITY_RAD_PER_S = 7.2921159e-5
-
-    TAI_TT_OFFSET = 32.184
   end
 end

data/lib/astronoby/constellation.rb

@@ -1,9 +1,17 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an IAU constellation with its full name and standard
+  # three-letter abbreviation.
   class Constellation
-    attr_reader :name, :abbreviation
+    # @return [String] the constellation name (e.g., "Orion")
+    attr_reader :name
 
+    # @return [String] the IAU three-letter abbreviation (e.g., "Ori")
+    attr_reader :abbreviation
+
+    # @param name [String] the constellation name
+    # @param abbreviation [String] the IAU abbreviation
     def initialize(name, abbreviation)
       @name = name
       @abbreviation = abbreviation

data/lib/astronoby/constellations/data.rb

@@ -31,7 +31,7 @@ module Astronoby
       end
 
       def self.read_file(filename)
-        File.readlines(data_path(filename)).map(&:strip)
+        File.readlines(data_path(filename), encoding: "UTF-8").map(&:strip)
       end
 
       def self.data_path(filename)

data/lib/astronoby/coordinates/ecliptic.rb

@@ -2,14 +2,23 @@
 
 module Astronoby
   module Coordinates
+    # Ecliptic coordinate system (latitude and longitude relative to the
+    # ecliptic plane).
     class Ecliptic
-      attr_reader :latitude, :longitude
+      # @return [Astronoby::Angle] ecliptic latitude
+      attr_reader :latitude
 
+      # @return [Astronoby::Angle] ecliptic longitude
+      attr_reader :longitude
+
+      # @param latitude [Astronoby::Angle] ecliptic latitude
+      # @param longitude [Astronoby::Angle] ecliptic longitude
       def initialize(latitude:, longitude:)
         @latitude = latitude
         @longitude = longitude
       end
 
+      # @return [Astronoby::Coordinates::Ecliptic] zero coordinates
       def self.zero
         new(latitude: Angle.zero, longitude: Angle.zero)
       end

data/lib/astronoby/coordinates/equatorial.rb

@@ -2,9 +2,24 @@
 
 module Astronoby
   module Coordinates
+    # Equatorial coordinate system (right ascension and declination).
     class Equatorial
-      attr_reader :declination, :right_ascension, :hour_angle, :epoch
+      # @return [Astronoby::Angle] declination
+      attr_reader :declination
 
+      # @return [Astronoby::Angle] right ascension
+      attr_reader :right_ascension
+
+      # @return [Astronoby::Angle, nil] hour angle, if set
+      attr_reader :hour_angle
+
+      # @return [Numeric] the Julian Date epoch
+      attr_reader :epoch
+
+      # @param declination [Astronoby::Angle] declination
+      # @param right_ascension [Astronoby::Angle] right ascension
+      # @param hour_angle [Astronoby::Angle, nil] hour angle
+      # @param epoch [Numeric] Julian Date epoch (default: J2000.0 = 2451545.0)
       def initialize(
         declination:,
         right_ascension:,
@@ -17,12 +32,23 @@ module Astronoby
         @epoch = epoch
       end
 
-      def self.zero
-        new(declination: Angle.zero, right_ascension: Angle.zero)
+      # @param epoch [Numeric] Julian Date epoch the coordinates are referred to
+      # @return [Astronoby::Coordinates::Equatorial] zero coordinates
+      def self.zero(epoch: JulianDate::DEFAULT_EPOCH)
+        new(
+          declination: Angle.zero,
+          right_ascension: Angle.zero,
+          epoch: epoch
+        )
       end
 
-      def self.from_position_vector(position)
-        return zero if position.zero?
+      # Derives equatorial coordinates from a position vector.
+      #
+      # @param position [Astronoby::Vector<Astronoby::Distance>] position vector
+      # @param epoch [Numeric] Julian Date epoch the vector is referred to
+      # @return [Astronoby::Coordinates::Equatorial] equatorial coordinates
+      def self.from_position_vector(position, epoch: JulianDate::DEFAULT_EPOCH)
+        return zero(epoch: epoch) if position.zero?
 
         term1 = position.z.m
         term2 = position.magnitude.m
@@ -38,9 +64,18 @@ module Astronoby
             angle
           )
 
-        new(declination: declination, right_ascension: right_ascension)
+        new(
+          declination: declination,
+          right_ascension: right_ascension,
+          epoch: epoch
+        )
       end
 
+      # Computes the hour angle for a given time and observer longitude.
+      #
+      # @param time [Time] the UTC time
+      # @param longitude [Astronoby::Angle] the observer's longitude
+      # @return [Astronoby::Angle] the hour angle
       def compute_hour_angle(time:, longitude:)
         last = LocalApparentSiderealTime.from_utc(time.utc, longitude: longitude)
         ha = (last.time - @right_ascension.hours)
@@ -49,6 +84,11 @@ module Astronoby
         Angle.from_hours(ha)
       end
 
+      # Converts to horizontal coordinates for a given observer and time.
+      #
+      # @param time [Time] the UTC time
+      # @param observer [Astronoby::Observer] the observer
+      # @return [Astronoby::Coordinates::Horizontal] horizontal coordinates
       def to_horizontal(time:, observer:)
         latitude = observer.latitude
         longitude = observer.longitude
@@ -74,25 +114,32 @@ module Astronoby
         )
       end
 
+      # Converts to ecliptic coordinates.
+      #
       # Source:
       #  Title: Celestial Calculations
       #  Author: J. L. Lawrence
       #  Edition: MIT Press
       #  Chapter: 4 - Orbits and Coordinate Systems
-      def to_ecliptic(instant:)
-        mean_obliquity = MeanObliquity.at(instant)
-
+      #
+      # @param instant [Astronoby::Instant] the time instant for the obliquity
+      # @param obliquity [Astronoby::Angle] the obliquity of the ecliptic to
+      #   rotate by. Defaults to the mean obliquity of date; pass the true
+      #   obliquity when the equatorial coordinates already include nutation
+      #   (true-of-date apparent and topocentric places).
+      # @return [Astronoby::Coordinates::Ecliptic] ecliptic coordinates
+      def to_ecliptic(instant:, obliquity: MeanObliquity.at(instant))
         y = Angle.from_radians(
-          @right_ascension.sin * mean_obliquity.cos +
-          @declination.tan * mean_obliquity.sin
+          @right_ascension.sin * obliquity.cos +
+          @declination.tan * obliquity.sin
         )
         x = Angle.from_radians(@right_ascension.cos)
         r = Angle.atan(y.radians / x.radians)
         longitude = Util::Trigonometry.adjustement_for_arctangent(y, x, r)
 
         latitude = Angle.asin(
-          @declination.sin * mean_obliquity.cos -
-          @declination.cos * mean_obliquity.sin * @right_ascension.sin
+          @declination.sin * obliquity.cos -
+          @declination.cos * obliquity.sin * @right_ascension.sin
         )
 
         Ecliptic.new(
@@ -100,6 +147,25 @@ module Astronoby
           longitude: longitude
         )
       end
+
+      # Position angle of another point as seen from this one, measured
+      # eastward (counterclockwise) from the direction of the north celestial
+      # pole. Both points must be expressed in the same frame.
+      #
+      # @param other [Astronoby::Coordinates::Equatorial] the target point
+      # @return [Astronoby::Angle] position angle, between -180 and 180 degrees
+      def position_angle_to(other)
+        delta_right_ascension = other.right_ascension - @right_ascension
+
+        Angle.from_radians(
+          Math.atan2(
+            other.declination.cos * delta_right_ascension.sin,
+            other.declination.sin * @declination.cos -
+              other.declination.cos * @declination.sin *
+                delta_right_ascension.cos
+          )
+        )
+      end
     end
   end
 end

data/lib/astronoby/coordinates/geodetic.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Astronoby
+  module Coordinates
+    # Geodetic coordinate system (WGS-84 latitude, longitude, and elevation).
+    #
+    # Geodetic coordinates describe a position on or above the Earth's surface
+    # using the WGS-84 reference ellipsoid, the same system used by GPS.
+    #
+    # The reverse conversion from ECEF (Earth-Centered Earth-Fixed) Cartesian
+    # coordinates uses Bowring's iterative method, which converges in 2-3
+    # iterations for typical satellite altitudes.
+    class Geodetic
+      SEMI_MINOR_AXIS =
+        Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS *
+        (1 - Constants::WGS84_FLATTENING)
+      SECOND_ECCENTRICITY_SQUARED =
+        (Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS**2 -
+          SEMI_MINOR_AXIS**2) /
+        SEMI_MINOR_AXIS**2
+      MAX_ITERATIONS = 10
+      CONVERGENCE_THRESHOLD = 1e-12
+
+      # @return [Astronoby::Angle] geodetic latitude
+      attr_reader :latitude
+
+      # @return [Astronoby::Angle] geodetic longitude
+      attr_reader :longitude
+
+      # @return [Astronoby::Distance] elevation above the WGS-84 ellipsoid
+      attr_reader :elevation
+
+      # @param latitude [Astronoby::Angle] geodetic latitude
+      # @param longitude [Astronoby::Angle] geodetic longitude
+      # @param elevation [Astronoby::Distance] elevation above the WGS-84
+      #   ellipsoid
+      def initialize(latitude:, longitude:, elevation:)
+        @latitude = latitude
+        @longitude = longitude
+        @elevation = elevation
+      end
+
+      # Converts ECEF Cartesian coordinates to geodetic coordinates using
+      # Bowring's iterative method.
+      #
+      # Source:
+      #  Title: Transformation from Spatial to Geographical Coordinates
+      #  Author: B. R. Bowring
+      #  Edition: Survey Review, Vol. 23, No. 181, 1976
+      #
+      # @param position [Astronoby::Vector<Astronoby::Distance>] ECEF position
+      # @return [Astronoby::Coordinates::Geodetic] geodetic coordinates
+      def self.from_ecef(position)
+        x = position.x.m
+        y = position.y.m
+        z = position.z.m
+
+        a = Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS
+        e2 = Constants::WGS84_ECCENTICITY_SQUARED
+
+        p = Math.sqrt(x * x + y * y)
+        longitude = Math.atan2(y, x)
+
+        theta = Math.atan2(z * a, p * SEMI_MINOR_AXIS)
+        latitude = Math.atan2(
+          z + SECOND_ECCENTRICITY_SQUARED * SEMI_MINOR_AXIS *
+            Math.sin(theta)**3,
+          p - e2 * a * Math.cos(theta)**3
+        )
+
+        MAX_ITERATIONS.times do
+          prev_latitude = latitude
+          theta = Math.atan2(
+            (1 - Constants::WGS84_FLATTENING) * Math.sin(latitude),
+            Math.cos(latitude)
+          )
+          latitude = Math.atan2(
+            z + SECOND_ECCENTRICITY_SQUARED * SEMI_MINOR_AXIS *
+              Math.sin(theta)**3,
+            p - e2 * a * Math.cos(theta)**3
+          )
+          break if (latitude - prev_latitude).abs < CONVERGENCE_THRESHOLD
+        end
+
+        sin_lat = Math.sin(latitude)
+        n = a / Math.sqrt(1 - e2 * sin_lat * sin_lat)
+
+        elevation = if Math.cos(latitude).abs > 1e-10
+          p / Math.cos(latitude) - n
+        else
+          z / sin_lat - n * (1 - e2)
+        end
+
+        new(
+          latitude: Angle.from_radians(latitude),
+          longitude: Angle.from_radians(longitude),
+          elevation: Distance.from_meters(elevation)
+        )
+      end
+    end
+  end
+end

data/lib/astronoby/coordinates/horizontal.rb

@@ -2,9 +2,21 @@
 
 module Astronoby
   module Coordinates
+    # Horizontal coordinate system (azimuth and altitude) for a specific
+    # observer.
     class Horizontal
-      attr_reader :azimuth, :altitude, :observer
+      # @return [Astronoby::Angle] azimuth (measured from north, clockwise)
+      attr_reader :azimuth
 
+      # @return [Astronoby::Angle] altitude above the horizon
+      attr_reader :altitude
+
+      # @return [Astronoby::Observer] the observer
+      attr_reader :observer
+
+      # @param azimuth [Astronoby::Angle] azimuth
+      # @param altitude [Astronoby::Angle] altitude
+      # @param observer [Astronoby::Observer] the observer
       def initialize(
         azimuth:,
         altitude:,

data/lib/astronoby/delta_t.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "iers"
+
+module Astronoby
+  module DeltaT
+    class << self
+      # @param instant [Numeric, Time, Date, DateTime] a Julian Date, or a date
+      #   and time. Any time scale will do.
+      # @return [Numeric] ΔT in seconds
+      # @raise [Astronoby::IncompatibleArgumentsError] if the instant is not a
+      #   Numeric, Time, Date or DateTime
+      def at(instant)
+        case instant
+        when Numeric
+          IERS::DeltaT.at(jd: instant).delta_t
+        when ::Time, ::Date, ::DateTime
+          IERS::DeltaT.at(instant).delta_t
+        else
+          raise IncompatibleArgumentsError,
+            "Expected a Numeric, Time, Date or DateTime object, got #{instant.class}"
+        end
+      rescue IERS::OutOfRangeError => error
+        outside_available_range(error)
+      end
+
+      private
+
+      # IERS covers 1800 up to the end of its EOP series, and refuses anything
+      # outside. Rather than propagate that, we answer with the closest value
+      # we have: 0 before 1800, where ΔT is small next to the uncertainty on
+      # it, and the last measured value after the series, which drifts slowly
+      # enough to beat any extrapolation we could invent.
+      def outside_available_range(error)
+        last_measured = IERS::Data.finals_entries.last
+        return 0 if last_measured.nil?
+        return 0 if error.requested_mjd.nil?
+        return 0 if error.requested_mjd < last_measured.mjd
+
+        IERS::DeltaT.at(mjd: last_measured.mjd).delta_t
+      end
+    end
+  end
+end

data/lib/astronoby/distance.rb

@@ -1,93 +1,128 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents a distance with meters as its internal representation.
+  # Provides conversions between meters, kilometers, astronomical units,
+  # and parsecs.
+  #
+  # @example Create a distance from astronomical units
+  #   distance = Astronoby::Distance.from_au(1.0)
+  #   distance.km  # => 149597870.7
+  #
   class Distance
     include Comparable
 
     class << self
+      # @return [Astronoby::Distance] a zero distance
       def zero
         new(0)
       end
 
+      # @param meters [Numeric] the distance in meters
+      # @return [Astronoby::Distance] a new Distance
       def from_meters(meters)
         new(meters)
       end
       alias_method :from_m, :from_meters
 
+      # @param kilometers [Numeric] the distance in kilometers
+      # @return [Astronoby::Distance] a new Distance
       def from_kilometers(kilometers)
         meters = kilometers * Constants::KILOMETER_IN_METERS
         from_meters(meters)
       end
       alias_method :from_km, :from_kilometers
 
+      # @param astronomical_units [Numeric] the distance in AU
+      # @return [Astronoby::Distance] a new Distance
       def from_astronomical_units(astronomical_units)
         meters = astronomical_units * Constants::ASTRONOMICAL_UNIT_IN_METERS
         from_meters(meters)
       end
       alias_method :from_au, :from_astronomical_units
 
+      # @param parsecs [Numeric] the distance in parsecs
+      # @return [Astronoby::Distance] a new Distance
       def from_parsecs(parsecs)
         meters = parsecs * Constants::PARSEC_IN_METERS
         from_meters(meters)
       end
       alias_method :from_pc, :from_parsecs
 
+      # @param array [Array<Numeric>] array of meter values
+      # @return [Astronoby::Vector<Astronoby::Distance>] a vector of Distances
       def vector_from_meters(array)
         Vector.elements(array.map { from_meters(_1) })
       end
       alias_method :vector_from_m, :vector_from_meters
     end
 
+    # @return [Numeric] the distance in meters
     attr_reader :meters
     alias_method :m, :meters
 
+    # @param meters [Numeric] the distance in meters
     def initialize(meters)
       @meters = meters
       freeze
     end
 
+    # @return [Float] the distance in kilometers
     def kilometers
       @meters / Constants::KILOMETER_IN_METERS.to_f
     end
     alias_method :km, :kilometers
 
+    # @return [Float] the distance in astronomical units
     def astronomical_units
       @meters / Constants::ASTRONOMICAL_UNIT_IN_METERS.to_f
     end
     alias_method :au, :astronomical_units
 
+    # @param other [Astronoby::Distance] distance to add
+    # @return [Astronoby::Distance] the sum
     def +(other)
       self.class.from_meters(meters + other.meters)
     end
 
+    # @param other [Astronoby::Distance] distance to subtract
+    # @return [Astronoby::Distance] the difference
     def -(other)
       self.class.from_meters(@meters - other.meters)
     end
 
+    # @return [Astronoby::Distance] the negated distance
     def -@
       self.class.from_meters(-@meters)
     end
 
+    # @return [Boolean] true if the distance is positive
     def positive?
       meters > 0
     end
 
+    # @return [Boolean] true if the distance is negative
     def negative?
       meters < 0
     end
 
+    # @return [Boolean] true if the distance is zero
     def zero?
       meters.zero?
     end
 
+    # @return [Numeric] the square of the distance in meters
     def abs2
       meters**2
     end
 
+    # @return [Integer] hash value
     def hash
       [meters, self.class].hash
     end
 
+    # @param other [Astronoby::Distance] distance to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
     def <=>(other)
       return unless other.is_a?(self.class)
 

data/lib/astronoby/duration.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Duration
+    include Comparable
+
+    class << self
+      # @return [Astronoby::Duration] a zero duration
+      def zero
+        new(0)
+      end
+
+      # @param seconds [Numeric] the duration in seconds
+      # @return [Astronoby::Duration] a new Duration
+      def from_seconds(seconds)
+        new(seconds)
+      end
+
+      # @param minutes [Numeric] the duration in minutes
+      # @return [Astronoby::Duration] a new Duration
+      def from_minutes(minutes)
+        seconds = minutes * Constants::SECONDS_PER_MINUTE
+        from_seconds(seconds)
+      end
+
+      # @param hours [Numeric] the duration in hours
+      # @return [Astronoby::Duration] a new Duration
+      def from_hours(hours)
+        seconds = hours * Constants::SECONDS_PER_HOUR
+        from_seconds(seconds)
+      end
+
+      # @param days [Numeric] the duration in days
+      # @return [Astronoby::Duration] a new Duration
+      def from_days(days)
+        seconds = days * Constants::SECONDS_PER_DAY
+        from_seconds(seconds)
+      end
+    end
+
+    # @return [Numeric] the duration in seconds
+    attr_reader :seconds
+
+    # @param seconds [Numeric] the duration in seconds
+    def initialize(seconds)
+      @seconds = seconds
+      freeze
+    end
+
+    # @return [Float] the duration in minutes
+    def minutes
+      @seconds / Constants::SECONDS_PER_MINUTE
+    end
+
+    # @return [Float] the duration in hours
+    def hours
+      @seconds / Constants::SECONDS_PER_HOUR
+    end
+
+    # @return [Float] the duration in days
+    def days
+      @seconds / Constants::SECONDS_PER_DAY
+    end
+
+    # @param other [Astronoby::Duration] duration to add
+    # @return [Astronoby::Duration] the sum
+    def +(other)
+      self.class.from_seconds(@seconds + other.seconds)
+    end
+
+    # @param other [Astronoby::Duration] duration to subtract
+    # @return [Astronoby::Duration] the difference
+    def -(other)
+      self.class.from_seconds(@seconds - other.seconds)
+    end
+
+    # @return [Astronoby::Duration] the negated duration
+    def -@
+      self.class.from_seconds(-@seconds)
+    end
+
+    # @return [Astronoby::Duration] the absolute duration
+    def abs
+      self.class.from_seconds(@seconds.abs)
+    end
+
+    # @return [Boolean] true if the duration is positive
+    def positive?
+      @seconds > 0
+    end
+
+    # @return [Boolean] true if the duration is negative
+    def negative?
+      @seconds < 0
+    end
+
+    # @return [Boolean] true if the duration is zero
+    def zero?
+      @seconds.zero?
+    end
+
+    # @return [Integer] hash value
+    def hash
+      [@seconds, self.class].hash
+    end
+
+    # @param other [Astronoby::Duration] duration to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      seconds <=> other.seconds
+    end
+    alias_method :eql?, :==
+  end
+end