astronoby 0.9.0 → 0.10.0

data/lib/astronoby/angle.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angle with radians as its internal representation.
+  # Provides conversions between radians, degrees, hours, and sexagesimal
+  # formats (DMS and HMS), as well as trigonometric operations.
+  #
+  # @example Create an angle from degrees
+  #   angle = Astronoby::Angle.from_degrees(180)
+  #   angle.radians  # => Math::PI
+  #
+  # @example Create an angle from hours, minutes, seconds
+  #   angle = Astronoby::Angle.from_hms(12, 30, 0)
+  #
   class Angle
     include Comparable
 
@@ -8,29 +19,42 @@ module Astronoby
     FORMATS = %i[dms hms].freeze
 
     class << self
+      # @return [Astronoby::Angle] a zero angle
       def zero
         new(0)
       end
 
+      # @param radians [Numeric] the angle in radians
+      # @return [Astronoby::Angle] a new Angle, normalized to (-2π, 2π)
       def from_radians(radians)
         normalized_radians = radians.remainder(Constants::RADIANS_PER_CIRCLE)
         new(normalized_radians)
       end
 
+      # @param degrees [Numeric] the angle in degrees
+      # @return [Astronoby::Angle] a new Angle
       def from_degrees(degrees)
         radians = degrees / Constants::PI_IN_DEGREES * Math::PI
         from_radians(radians)
       end
 
+      # @param arcseconds [Numeric] the angle in arcseconds
+      # @return [Astronoby::Angle] a new Angle
       def from_degree_arcseconds(arcseconds)
         from_dms(0, 0, arcseconds)
       end
 
+      # @param hours [Numeric] the angle in hour-angle hours
+      # @return [Astronoby::Angle] a new Angle
       def from_hours(hours)
         radians = hours * Constants::RADIAN_PER_HOUR
         from_radians(radians)
       end
 
+      # @param hour [Numeric] hours component
+      # @param minute [Numeric] minutes component
+      # @param second [Numeric] seconds component
+      # @return [Astronoby::Angle] a new Angle
       def from_hms(hour, minute, second)
         hours = hour +
           minute / Constants::MINUTES_PER_HOUR +
@@ -38,89 +62,118 @@ module Astronoby
         from_hours(hours)
       end
 
+      # @param degree [Numeric] degrees component (sign determines overall sign)
+      # @param minute [Numeric] arcminutes component
+      # @param second [Numeric] arcseconds component
+      # @return [Astronoby::Angle] a new Angle
       def from_dms(degree, minute, second)
         sign = degree.negative? ? -1 : 1
         degrees = degree.abs +
-          minute / Constants::MINUTES_PER_HOUR +
-          second / Constants::SECONDS_PER_HOUR
+          minute / Constants::ARCMINUTES_PER_DEGREE +
+          second / Constants::ARCSECONDS_PER_DEGREE
         from_degrees(sign * degrees)
       end
 
+      # @param ratio [Numeric] the sine value (-1..1)
+      # @return [Astronoby::Angle] the arcsine
       def asin(ratio)
         radians = Math.asin(ratio)
         from_radians(radians)
       end
 
+      # @param ratio [Numeric] the cosine value (-1..1)
+      # @return [Astronoby::Angle] the arccosine
       def acos(ratio)
         radians = Math.acos(ratio)
         from_radians(radians)
       end
 
+      # @param ratio [Numeric] the tangent value
+      # @return [Astronoby::Angle] the arctangent
       def atan(ratio)
         radians = Math.atan(ratio)
         from_radians(radians)
       end
     end
 
+    # @return [Numeric] the angle in radians
     attr_reader :radians
 
+    # @param radians [Numeric] the angle in radians
     def initialize(radians)
       @radians = radians
       freeze
     end
 
+    # @return [Float] the angle in degrees
     def degrees
       @radians * Constants::PI_IN_DEGREES / Math::PI
     end
 
+    # @return [Float] the angle in milliarcseconds
     def degree_milliarcseconds
       degrees * Constants::MILLIARCSECONDS_PER_DEGREE
     end
 
+    # @return [Float] the angle in hour-angle hours
     def hours
       @radians / Constants::RADIAN_PER_HOUR
     end
 
+    # @param other [Astronoby::Angle] angle to add
+    # @return [Astronoby::Angle] the sum
     def +(other)
       self.class.from_radians(radians + other.radians)
     end
 
+    # @param other [Astronoby::Angle] angle to subtract
+    # @return [Astronoby::Angle] the difference
     def -(other)
       self.class.from_radians(@radians - other.radians)
     end
 
+    # @return [Astronoby::Angle] the negated angle
     def -@
       self.class.from_radians(-@radians)
     end
 
+    # @return [Float] the sine of the angle
     def sin
       Math.sin(radians)
     end
 
+    # @return [Float] the cosine of the angle
     def cos
       Math.cos(radians)
     end
 
+    # @return [Float] the tangent of the angle
     def tan
       Math.tan(radians)
     end
 
+    # @return [Boolean] true if the angle is positive
     def positive?
       radians > 0
     end
 
+    # @return [Boolean] true if the angle is negative
     def negative?
       radians < 0
     end
 
+    # @return [Boolean] true if the angle is zero
     def zero?
       radians.zero?
     end
 
+    # @return [Integer] hash value
     def hash
       [radians, self.class].hash
     end
 
+    # @param other [Astronoby::Angle] angle to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
     def <=>(other)
       return unless other.is_a?(self.class)
 
@@ -128,6 +181,12 @@ module Astronoby
     end
     alias_method :eql?, :==
 
+    # Formats the angle as a string in the given format.
+    #
+    # @param format [Symbol] :dms or :hms
+    # @param precision [Integer] decimal places for seconds
+    # @return [String] the formatted angle
+    # @raise [Astronoby::UnsupportedFormatError] if format is not :dms or :hms
     def str(format, precision: 4)
       case format
       when :dms then to_dms.format(precision: precision)
@@ -139,6 +198,7 @@ module Astronoby
       end
     end
 
+    # @return [Astronoby::Dms] the angle in degrees, arcminutes, arcseconds
     def to_dms
       sign = degrees.negative? ? "-" : "+"
       absolute_degrees = degrees.abs
@@ -156,6 +216,7 @@ module Astronoby
       Dms.new(sign, deg, minutes, seconds)
     end
 
+    # @return [Astronoby::Hms] the angle in hours, minutes, seconds
     def to_hms
       absolute_hours = hours.abs
       hrs = absolute_hours.floor

data/lib/astronoby/angles/dms.rb

@@ -1,9 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angle in degrees, arcminutes, arcseconds (DMS) notation.
   class Dms
-    attr_reader :sign, :degrees, :minutes, :seconds
+    # @return [String] "+" or "-"
+    attr_reader :sign
 
+    # @return [Integer] degrees component
+    attr_reader :degrees
+
+    # @return [Integer] arcminutes component
+    attr_reader :minutes
+
+    # @return [Float] arcseconds component
+    attr_reader :seconds
+
+    # @param sign [String] "+" or "-"
+    # @param degrees [Integer] degrees component
+    # @param minutes [Integer] arcminutes component
+    # @param seconds [Float] arcseconds component
     def initialize(sign, degrees, minutes, seconds)
       @sign = sign
       @degrees = degrees
@@ -11,6 +26,8 @@ module Astronoby
       @seconds = seconds
     end
 
+    # @param precision [Integer] decimal places for the seconds component
+    # @return [String] the formatted DMS string (e.g., "+45° 30′ 15.0000″")
     def format(precision: 4)
       "#{sign}#{degrees}° #{minutes}′ #{seconds.floor(precision)}″"
     end

data/lib/astronoby/angles/hms.rb

@@ -1,15 +1,28 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angle in hours, minutes, seconds (HMS) notation.
   class Hms
-    attr_reader :hours, :minutes, :seconds
+    # @return [Integer] hours component
+    attr_reader :hours
 
+    # @return [Integer] minutes component
+    attr_reader :minutes
+
+    # @return [Float] seconds component
+    attr_reader :seconds
+
+    # @param hours [Integer] hours component
+    # @param minutes [Integer] minutes component
+    # @param seconds [Float] seconds component
     def initialize(hours, minutes, seconds)
       @hours = hours
       @minutes = minutes
       @seconds = seconds
     end
 
+    # @param precision [Integer] decimal places for the seconds component
+    # @return [String] the formatted HMS string (e.g., "12h 30m 45.0000s")
     def format(precision: 4)
       "#{hours}h #{minutes}m #{seconds.floor(precision)}s"
     end

data/lib/astronoby/angular_velocity.rb

@@ -1,18 +1,25 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angular velocity with radians per second as its internal
+  # representation. Used primarily for stellar proper motion.
   class AngularVelocity
     include Comparable
 
     class << self
+      # @return [Astronoby::AngularVelocity] a zero angular velocity
       def zero
         new(0)
       end
 
+      # @param radians_per_second [Numeric] the angular velocity in rad/s
+      # @return [Astronoby::AngularVelocity] a new AngularVelocity
       def from_radians_per_second(radians_per_second)
         new(radians_per_second)
       end
 
+      # @param mas_per_year [Numeric] the angular velocity in mas/yr
+      # @return [Astronoby::AngularVelocity] a new AngularVelocity
       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
@@ -20,52 +27,66 @@ module Astronoby
       end
     end
 
+    # @return [Numeric] the angular velocity in radians per second
     attr_reader :radians_per_second
     alias_method :rps, :radians_per_second
 
+    # @param radians_per_second [Numeric] the angular velocity in rad/s
     def initialize(radians_per_second)
       @radians_per_second = radians_per_second
       freeze
     end
 
+    # @return [Float] the angular velocity in milliarcseconds per year
     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
 
+    # @param other [Astronoby::AngularVelocity] angular velocity to add
+    # @return [Astronoby::AngularVelocity] the sum
     def +(other)
       self.class.from_radians_per_second(
         @radians_per_second + other.radians_per_second
       )
     end
 
+    # @param other [Astronoby::AngularVelocity] angular velocity to subtract
+    # @return [Astronoby::AngularVelocity] the difference
     def -(other)
       self.class.from_radians_per_second(
         @radians_per_second - other.radians_per_second
       )
     end
 
+    # @return [Astronoby::AngularVelocity] the negated angular velocity
     def -@
       self.class.from_radians_per_second(-@radians_per_second)
     end
 
+    # @return [Boolean] true if the angular velocity is positive
     def positive?
       @radians_per_second > 0
     end
 
+    # @return [Boolean] true if the angular velocity is negative
     def negative?
       @radians_per_second < 0
     end
 
+    # @return [Boolean] true if the angular velocity is zero
     def zero?
       @radians_per_second.zero?
     end
 
+    # @return [Integer] hash value
     def hash
       [@radians_per_second, self.class].hash
     end
 
+    # @param other [Astronoby::AngularVelocity] angular velocity 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/bodies/deep_sky_object.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents a deep-sky object (star, galaxy, nebula, etc.) with optional
+  # proper motion and parallax data.
   class DeepSkyObject
+    include Body
+
     # @param equatorial_coordinates [Astronoby::Coordinates::Equatorial]
     #   Equatorial coordinates at epoch J2000.0
     # @param proper_motion_ra [Astronoby::AngularVelocity, nil] Proper motion in
@@ -37,7 +41,8 @@ module Astronoby
         proper_motion_ra: @proper_motion_ra,
         proper_motion_dec: @proper_motion_dec,
         parallax: @parallax,
-        radial_velocity: @radial_velocity
+        radial_velocity: @radial_velocity,
+        deep_sky_object: self
       )
     end
   end

data/lib/astronoby/bodies/deep_sky_object_position.rb

@@ -1,20 +1,33 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents the computed position of a deep-sky object at a specific
+  # instant, providing astrometric, apparent, and topocentric reference frames.
   class DeepSkyObjectPosition
+    include Position
+
     DEFAULT_DISTANCE = Distance.from_parsecs(1e9)
 
-    attr_reader :instant, :apparent
+    # @return [Astronoby::Instant] the time instant
+    attr_reader :instant
+
+    # @return [Astronoby::Apparent] the apparent reference frame
+    attr_reader :apparent
+
+    # @return [Astronoby::DeepSkyObject, nil] the body definition
+    attr_reader :body
 
     # @param instant [Astronoby::Instant] Instant of the observation
     # @param equatorial_coordinates [Astronoby::Coordinates::Equatorial]
     #   Equatorial coordinates at epoch J2000.0
+    # @param ephem [::Ephem::SPK, nil] Ephemeris data source for Earth position
     # @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
+    # @param deep_sky_object [Astronoby::DeepSkyObject, nil] the body definition
     def initialize(
       instant:,
       equatorial_coordinates:,
@@ -22,7 +35,8 @@ module Astronoby
       proper_motion_ra: nil,
       proper_motion_dec: nil,
       parallax: nil,
-      radial_velocity: nil
+      radial_velocity: nil,
+      deep_sky_object: nil
     )
       @instant = instant
       @initial_equatorial_coordinates = equatorial_coordinates
@@ -30,6 +44,7 @@ module Astronoby
       @proper_motion_dec = proper_motion_dec
       @parallax = parallax
       @radial_velocity = radial_velocity
+      @body = deep_sky_object
       if ephem
         @earth_geometric = Earth.geometric(ephem: ephem, instant: @instant)
       end
@@ -42,24 +57,24 @@ module Astronoby
         instant: @instant,
         position: astrometric_position,
         velocity: astrometric_velocity,
-        center_identifier: SolarSystemBody::EARTH,
-        target_body: self
-      )
-    end
-
-    def observed_by(observer)
-      Topocentric.build_from_apparent(
-        apparent: @apparent,
-        observer: observer,
-        instant: @instant,
-        target_body: self
+        center: Center.geocentric,
+        target_body: body
       )
     end
 
     private
 
     def astrometric_position
-      @astrometric_position ||= if use_stellar_propagation?
+      @astrometric_position ||=
+        if @earth_geometric
+          barycentric_position - @earth_geometric.position
+        else
+          barycentric_position
+        end
+    end
+
+    def barycentric_position
+      if use_stellar_propagation?
         stellar_propagation.position
       else
         astronomical_distance = DEFAULT_DISTANCE.meters
@@ -103,7 +118,7 @@ module Astronoby
           instant: @instant,
           target_astrometric: astrometric,
           earth_geometric: @earth_geometric,
-          target_body: self
+          target_body: body
         )
       else
         precession_matrix = Precession.matrix_for(@instant)
@@ -118,8 +133,8 @@ module Astronoby
           position: corrected_position,
           velocity: corrected_velocity,
           instant: @instant,
-          center_identifier: SolarSystemBody::EARTH,
-          target_body: self
+          center: Center.geocentric,
+          target_body: body
         )
       end
     end

data/lib/astronoby/bodies/earth.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents the Earth. Provides ephemeris segments for computing Earth's
+  # geometric position.
   class Earth < SolarSystemBody
+    ORBITAL_PERIOD = 365.256
+
+    # @param ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(ephem_source)
       if ephem_source == ::Ephem::SPK::JPL_DE
         [
@@ -15,52 +21,9 @@ module Astronoby
       end
     end
 
+    # @return [nil] Earth has no phase angle as seen from itself
     def phase_angle
       nil
     end
-
-    private
-
-    # Attributes that require Sun data like phase angle or magnitude are not
-    # applicable for Earth.
-    def requires_sun_data?
-      true
-    end
-
-    def compute_astrometric(_ephem)
-      Astrometric.new(
-        position: Vector[
-          Distance.zero,
-          Distance.zero,
-          Distance.zero
-        ],
-        velocity: Vector[
-          Velocity.zero,
-          Velocity.zero,
-          Velocity.zero
-        ],
-        instant: @instant,
-        center_identifier: EARTH,
-        target_body: self.class
-      )
-    end
-
-    def compute_mean_of_date(_ephem)
-      MeanOfDate.new(
-        position: Vector[
-          Distance.zero,
-          Distance.zero,
-          Distance.zero
-        ],
-        velocity: Vector[
-          Velocity.zero,
-          Velocity.zero,
-          Velocity.zero
-        ],
-        instant: @instant,
-        center_identifier: EARTH,
-        target_body: self.class
-      )
-    end
   end
 end

data/lib/astronoby/bodies/jupiter.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Jupiter.
   class Jupiter < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(71_492_000)
     ABSOLUTE_MAGNITUDE = -9.395
+    ORBITAL_PERIOD = 4332.59
 
+    # @return [Boolean] true; Jupiter is a superior planet
+    def self.superior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, JUPITER_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end

data/lib/astronoby/bodies/mars.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Mars.
   class Mars < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(3_396_200)
     ABSOLUTE_MAGNITUDE = -1.601
+    ORBITAL_PERIOD = 686.98
 
+    # @return [Boolean] true; Mars is a superior planet
+    def self.superior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, MARS_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end

data/lib/astronoby/bodies/mercury.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Mercury.
   class Mercury < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(2_439_700)
     ABSOLUTE_MAGNITUDE = -0.613
+    ORBITAL_PERIOD = 87.969
 
+    # @return [Boolean] true; Mercury is an inferior planet
+    def self.inferior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, MERCURY_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end