skymap 0.4.0 → 0.5.0

data/lib/skymap/context.rb

@@ -2,22 +2,55 @@
 
 module Skymap
   class Context
-    attr_reader :observer, :instant, :canvas
+    MAX_ANGLE_FROM_VIEW_COSINE = Math.cos(150 * Math::PI / 180)
+    STAR_POSITION_TOLERANCE = 0.005
+    SHIFT_SLACK = 1e-6
+    SECONDS_PER_JULIAN_YEAR = Astronoby::Constants::SECONDS_PER_JULIAN_YEAR
+    ASTRONOMICAL_UNIT = 149_597_870_700.0
+    SPEED_OF_LIGHT = 299_792_458.0
+    PROPER_MOTION_ROUNDING = 1e-15
+    POSITION_ANGLE_STEP = 1e-4
+    PRECESSION_ARCSECONDS_PER_YEAR = 50.3
+    FASTEST_PROPER_MOTION_ARCSECONDS_PER_YEAR = 10.4
+    NUTATION_AND_ABERRATION_ARCSECONDS = 60.0
+    private_constant :PRECESSION_ARCSECONDS_PER_YEAR,
+      :FASTEST_PROPER_MOTION_ARCSECONDS_PER_YEAR,
+      :NUTATION_AND_ABERRATION_ARCSECONDS, :STAR_POSITION_TOLERANCE,
+      :SHIFT_SLACK, :SECONDS_PER_JULIAN_YEAR, :ASTRONOMICAL_UNIT,
+      :SPEED_OF_LIGHT, :PROPER_MOTION_ROUNDING, :POSITION_ANGLE_STEP
 
-    def initialize(observer:, instant:, canvas:)
+    attr_reader :observer, :instant, :canvas, :view
+
+    def initialize(observer:, instant:, canvas:, view: nil)
       @observer = observer
       @instant = instant
       @canvas = canvas
+      @view = view
       @transformation = Astronoby::HorizontalTransformation.new(
         observer: observer,
         instant: instant
       )
       @horizontal = {}
+      @star_horizontals = {}.compare_by_identity
+      @catalog_horizontals = {}.compare_by_identity
+      @star_shifts = {}.compare_by_identity
       @projections = {}
     end
 
     def horizontal(star)
-      horizontal_coordinates(star.equatorial_coordinates)
+      @star_horizontals[star] ||= star_horizontal(star)
+    end
+
+    def possibly_visible?(star, margin = 0)
+      catalog = catalog_horizontal(star)
+      shift = star_shift(star) + SHIFT_SLACK
+      return false if catalog.altitude.radians < -shift
+      return true if full_sky?
+
+      reach = view_reach(margin) + shift
+      return true if reach >= Math::PI
+
+      cosine_from_view(catalog) >= Math.cos(reach)
     end
 
     def horizontal_coordinates(coordinates)
@@ -27,7 +60,13 @@ module Skymap
         coordinates.epoch
       ]
 
-      @horizontal[key] ||= @transformation.apply(coordinates)
+      @horizontal[key] ||= convert(coordinates)
+    end
+
+    def to_horizontal(position)
+      return position unless position.is_a?(Astronoby::Coordinates::Equatorial)
+
+      horizontal_coordinates(position)
     end
 
     def position(star)
@@ -39,13 +78,292 @@ module Skymap
       projection(radius).project(altitude: altitude, azimuth: azimuth)
     end
 
+    def span(angle, altitude:, azimuth:, radius: @canvas.radius)
+      projection(radius).scale_at(altitude: altitude, azimuth: azimuth) *
+        angle.radians
+    end
+
+    def rotation_at(coordinates, position_angle:)
+      center = project_horizontal(horizontal_coordinates(coordinates))
+      toward = project_horizontal(
+        convert(step_toward(coordinates, position_angle))
+      )
+
+      Astronoby::Angle.from_radians(
+        Math.atan2(toward.y - center.y, toward.x - center.x)
+      )
+    end
+
+    def scale_at_point(point, radius: @canvas.radius)
+      projection(radius).scale_at_point(point)
+    end
+
+    def disk_radius(default, angular_diameter:, altitude:, azimuth:)
+      return default if full_sky?
+
+      [
+        default,
+        span(angular_diameter, altitude: altitude, azimuth: azimuth) / 2
+      ].max
+    end
+
+    def full_sky?
+      @view.nil?
+    end
+
+    def cone
+      return if full_sky?
+
+      @cone ||= Cone.new(
+        center: view_equatorial,
+        radius: Astronoby::Angle.from_radians(
+          [view_reach(StarSize::MAX_RADIUS_RATIO * @canvas.radius) +
+            cone_drift, Math::PI].min
+        )
+      )
+    end
+
+    def in_view?(point, margin = 0)
+      return true if full_sky?
+
+      distance = Math.hypot(point.x - @canvas.center.x,
+        point.y - @canvas.center.y)
+      distance <= @canvas.radius + margin
+    end
+
+    def crosses_view?(points)
+      return true if full_sky?
+
+      return in_view?(points.first) if points.size == 1
+
+      points.each_cons(2).any? do |from, to|
+        distance_to_segment(@canvas.center, from, to) <= @canvas.radius
+      end
+    end
+
+    def reachable?(horizontal)
+      return true if full_sky?
+
+      cosine_from_view(horizontal) > MAX_ANGLE_FROM_VIEW_COSINE
+    end
+
     private
 
-    def projection(radius)
-      @projections[radius] ||= Projection::Stereographic.new(
-        center: @canvas.center,
-        radius: radius
+    def view_equatorial
+      center = @view.center
+      unless center.is_a?(Astronoby::Coordinates::Horizontal)
+        return Astronoby::Coordinates::Equatorial.new(
+          right_ascension: center.right_ascension,
+          declination: center.declination,
+          epoch: Astronoby::JulianDate::J2000
+        )
+      end
+
+      latitude = @observer.latitude
+      altitude = center.altitude
+      azimuth = center.azimuth
+      hour_angle = Math.atan2(
+        -azimuth.sin * altitude.cos,
+        altitude.sin * latitude.cos - altitude.cos * latitude.sin * azimuth.cos
+      )
+
+      Astronoby::Coordinates::Equatorial.new(
+        right_ascension: Astronoby::Angle.from_radians(
+          (Astronoby::Angle.from_hours(sidereal_time).radians - hour_angle) %
+            (2 * Math::PI)
+        ),
+        declination: Astronoby::Angle.from_radians(
+          Math.asin(
+            (altitude.sin * latitude.sin +
+              altitude.cos * latitude.cos * azimuth.cos).clamp(-1, 1)
+          )
+        ),
+        epoch: Astronoby::JulianDate::J2000
+      )
+    end
+
+    def cone_drift
+      arcseconds = elapsed_years * (
+        PRECESSION_ARCSECONDS_PER_YEAR +
+        FASTEST_PROPER_MOTION_ARCSECONDS_PER_YEAR
+      ) + NUTATION_AND_ABERRATION_ARCSECONDS
+
+      Astronoby::Angle.from_degree_arcseconds(arcseconds).radians
+    end
+
+    def project_horizontal(horizontal)
+      project(altitude: horizontal.altitude, azimuth: horizontal.azimuth)
+    end
+
+    def step_toward(coordinates, position_angle)
+      right_ascension = coordinates.right_ascension
+      declination = coordinates.declination
+      east = [-right_ascension.sin, right_ascension.cos, 0.0]
+      north = [
+        -declination.sin * right_ascension.cos,
+        -declination.sin * right_ascension.sin,
+        declination.cos
+      ]
+      point = [
+        declination.cos * right_ascension.cos,
+        declination.cos * right_ascension.sin,
+        declination.sin
+      ]
+      nearby = Geometry.normalize(
+        point.each_index.map do |axis|
+          point[axis] + POSITION_ANGLE_STEP * (
+            position_angle.sin * east[axis] + position_angle.cos * north[axis]
+          )
+        end
       )
+
+      Astronoby::Coordinates::Equatorial.new(
+        right_ascension: Astronoby::Angle.from_radians(
+          Math.atan2(nearby[1], nearby[0]) % (2 * Math::PI)
+        ),
+        declination: Astronoby::Angle.from_radians(
+          Math.asin(nearby[2].clamp(-1, 1))
+        ),
+        epoch: coordinates.epoch
+      )
+    end
+
+    def star_horizontal(star)
+      catalog = catalog_horizontal(star)
+      shift = star_shift(star)
+      return catalog if shift.zero?
+
+      scale = projection(@canvas.radius)
+        .scale_at(altitude: catalog.altitude, azimuth: catalog.azimuth)
+      return catalog if shift * scale < STAR_POSITION_TOLERANCE
+
+      convert(star.coordinates_at(@instant))
+    end
+
+    def catalog_horizontal(star)
+      @catalog_horizontals[star] ||= convert(star.equatorial_coordinates)
+    end
+
+    def star_shift(star)
+      @star_shifts[star] ||= compute_star_shift(star)
+    end
+
+    def compute_star_shift(star)
+      return 0.0 if star.proper_motion_ra.nil? || elapsed_years.zero?
+
+      rate = Math.hypot(
+        proper_motion_bound(star.proper_motion_ra),
+        proper_motion_bound(star.proper_motion_dec)
+      ) * SECONDS_PER_JULIAN_YEAR
+      velocity = (star.radial_velocity&.meters_per_second || 0).abs
+      seconds = elapsed_years * SECONDS_PER_JULIAN_YEAR
+      parallax = star.parallax&.radians || 0
+      slack = velocity / SPEED_OF_LIGHT +
+        velocity * seconds * parallax / ASTRONOMICAL_UNIT
+      return Float::INFINITY if slack >= 0.5
+
+      rate * elapsed_years / (1 - slack)
+    end
+
+    def proper_motion_bound(proper_motion)
+      rate = proper_motion.radians_per_second
+
+      rate.negative? ? -rate + PROPER_MOTION_ROUNDING : rate
+    end
+
+    def elapsed_years
+      @elapsed_years ||= (@instant.tt - Astronoby::JulianDate::J2000).abs /
+        Astronoby::Constants::DAYS_PER_JULIAN_YEAR
+    end
+
+    def view_reach(margin)
+      quarter = @view.field_of_view.radians / 4.0
+
+      2 * Math.atan(Math.tan(quarter) * (1 + margin / @canvas.radius))
+    end
+
+    def cosine_from_view(horizontal)
+      east, north, up = view_direction
+
+      horizontal.altitude.cos *
+        (horizontal.azimuth.cos * east + horizontal.azimuth.sin * north) +
+        horizontal.altitude.sin * up
+    end
+
+    def convert(coordinates)
+      case coordinates.epoch
+      when Astronoby::JulianDate::J2000
+        @transformation.apply(coordinates)
+      when @instant.tt
+        horizontal_of_date(coordinates)
+      else
+        raise ArgumentError,
+          "coordinates must be at J2000 or at the date of the chart"
+      end
+    end
+
+    def horizontal_of_date(coordinates)
+      Astronoby::Coordinates::Equatorial.new(
+        right_ascension: coordinates.right_ascension,
+        declination: coordinates.declination,
+        hour_angle: Astronoby::Angle.from_hours(
+          (sidereal_time - coordinates.right_ascension.hours) %
+            Astronoby::Constants::HOURS_PER_DAY
+        ),
+        epoch: coordinates.epoch
+      ).to_horizontal(time: @instant.to_time, observer: @observer)
+    end
+
+    def sidereal_time
+      @sidereal_time ||= Astronoby::LocalApparentSiderealTime.from_utc(
+        @instant.to_time,
+        longitude: @observer.longitude
+      ).time
+    end
+
+    def projection(radius)
+      @projections[radius] ||= if full_sky?
+        Projection::Stereographic.new(center: @canvas.center, radius: radius)
+      else
+        center = view_center
+        Projection::ObliqueStereographic.new(
+          center: @canvas.center,
+          radius: radius,
+          altitude: center.altitude,
+          azimuth: center.azimuth,
+          field_of_view: @view.field_of_view,
+          orientation: @view.orientation,
+          pole: celestial_pole,
+          rotation: @view.rotation,
+          mirrored: @view.mirrored
+        )
+      end
+    end
+
+    def view_center
+      @view_center ||= to_horizontal(@view.center)
+    end
+
+    def celestial_pole
+      latitude = @observer.latitude
+
+      [latitude.cos, 0.0, latitude.sin]
+    end
+
+    def view_direction
+      @view_direction ||= Horizon.direction([view_center])
+    end
+
+    def distance_to_segment(point, from, to)
+      dx = to.x - from.x
+      dy = to.y - from.y
+      length = dx * dx + dy * dy
+      return Math.hypot(from.x - point.x, from.y - point.y) if length.zero?
+
+      along = (((point.x - from.x) * dx + (point.y - from.y) * dy) / length)
+        .clamp(0, 1)
+
+      Math.hypot(from.x + along * dx - point.x, from.y + along * dy - point.y)
     end
   end
 end

data/lib/skymap/deep_sky_object.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Skymap
+  DeepSkyObject = Data.define(
+    :designation,
+    :name,
+    :type,
+    :equatorial_coordinates,
+    :magnitude,
+    :magnitude_band,
+    :major_axis,
+    :minor_axis,
+    :position_angle
+  ) do
+    def initialize(
+      designation:,
+      type:,
+      equatorial_coordinates:,
+      name: nil,
+      magnitude: nil,
+      magnitude_band: nil,
+      major_axis: nil,
+      minor_axis: nil,
+      position_angle: nil
+    )
+      unless non_blank_string?(designation)
+        raise ArgumentError, "designation must be a non-blank String"
+      end
+
+      unless name.nil? || non_blank_string?(name)
+        raise ArgumentError, "name must be a non-blank String or nil"
+      end
+
+      unless DeepSkyObject::TYPES.include?(type)
+        raise ArgumentError,
+          "type must be one of #{DeepSkyObject::TYPES.join(", ")}"
+      end
+
+      unless equatorial_coordinates.is_a?(Astronoby::Coordinates::Equatorial) &&
+          equatorial_coordinates.epoch == Astronoby::JulianDate::J2000
+        raise ArgumentError,
+          "equatorial_coordinates must be Astronoby::Coordinates::Equatorial " \
+          "at J2000"
+      end
+
+      unless magnitude?(magnitude)
+        raise ArgumentError, "magnitude must be a finite Numeric or nil"
+      end
+
+      unless DeepSkyObject::MAGNITUDE_BANDS.include?(magnitude_band) ||
+          magnitude_band.nil?
+        raise ArgumentError,
+          "magnitude_band must be one of " \
+          "#{DeepSkyObject::MAGNITUDE_BANDS.join(", ")} or nil"
+      end
+
+      if magnitude_band && magnitude.nil?
+        raise ArgumentError, "magnitude_band must come with a magnitude"
+      end
+
+      unless axis?(major_axis)
+        raise ArgumentError,
+          "major_axis must be an Astronoby::Angle above 0 or nil"
+      end
+
+      unless axis?(minor_axis)
+        raise ArgumentError,
+          "minor_axis must be an Astronoby::Angle above 0 or nil"
+      end
+
+      if minor_axis && major_axis.nil?
+        raise ArgumentError, "minor_axis must come with a major_axis"
+      end
+
+      if minor_axis && minor_axis > major_axis
+        raise ArgumentError, "minor_axis must not be larger than major_axis"
+      end
+
+      unless position_angle?(position_angle)
+        raise ArgumentError, "position_angle must be an Astronoby::Angle or nil"
+      end
+
+      super
+    end
+
+    def messier?
+      designation.match?(/\AM\d+\z/)
+    end
+
+    alias_method :given_minor_axis, :minor_axis
+    private :given_minor_axis
+
+    def minor_axis
+      given_minor_axis || major_axis
+    end
+
+    alias_method :given_magnitude_band, :magnitude_band
+    private :given_magnitude_band
+
+    def magnitude_band
+      given_magnitude_band || (:visual unless magnitude.nil?)
+    end
+
+    private
+
+    def non_blank_string?(value)
+      value.is_a?(String) && !value.strip.empty?
+    end
+
+    def magnitude?(value)
+      value.nil? ||
+        (value.is_a?(Numeric) && value.real? && value.finite?)
+    end
+
+    def position_angle?(value)
+      value.nil? ||
+        (value.is_a?(Astronoby::Angle) && value.radians.finite?)
+    end
+
+    def axis?(value)
+      value.nil? ||
+        (value.is_a?(Astronoby::Angle) &&
+          value.radians.finite? && value.positive?)
+    end
+  end
+
+  DeepSkyObject::MAGNITUDE_BANDS = %i[visual blue].freeze
+
+  DeepSkyObject::TYPES = %i[
+    galaxy
+    open_cluster
+    globular_cluster
+    planetary_nebula
+    nebula
+    supernova_remnant
+    asterism
+    double_star
+    other
+  ].freeze
+end

data/lib/skymap/eyepiece.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Skymap
+  Eyepiece = Data.define(:focal_length_mm, :apparent_field_of_view) do
+    def initialize(focal_length_mm:, apparent_field_of_view:)
+      unless focal_length_mm.is_a?(Numeric) && focal_length_mm.real? &&
+          focal_length_mm.finite? && focal_length_mm > 0
+        raise ArgumentError, "focal_length_mm must be a number above 0"
+      end
+
+      unless apparent_field_of_view.is_a?(Astronoby::Angle) &&
+          apparent_field_of_view.positive? &&
+          apparent_field_of_view.radians <= Math::PI
+        raise ArgumentError,
+          "apparent_field_of_view must be an Astronoby::Angle " \
+          "above 0 and up to 180 degrees"
+      end
+
+      super
+    end
+  end
+end

data/lib/skymap/field.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Skymap
+  Field = Data.define(:true_field, :label) do
+    def initialize(true_field:, label:)
+      unless true_field.is_a?(Astronoby::Angle) && true_field.positive? &&
+          true_field.radians <= Math::PI
+        raise ArgumentError,
+          "true_field must be an Astronoby::Angle " \
+          "above 0 and up to 180 degrees"
+      end
+
+      unless label.is_a?(String) && !label.strip.empty?
+        raise ArgumentError, "label must be a string that is not blank"
+      end
+
+      super
+    end
+  end
+end

data/lib/skymap/geometry.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Skymap
+  module Geometry
+    module_function
+
+    def dot(a, b)
+      a.zip(b).sum { |x, y| x * y }
+    end
+
+    def direction(right_ascension, declination)
+      [
+        Math.cos(declination) * Math.cos(right_ascension),
+        Math.cos(declination) * Math.sin(right_ascension),
+        Math.sin(declination)
+      ]
+    end
+
+    def cross(a, b)
+      [
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0]
+      ]
+    end
+
+    def normalize(vector)
+      length = Math.sqrt(dot(vector, vector))
+
+      vector.map { |component| component / length }
+    end
+
+    def away_from(reference, forward)
+      along = dot(reference, forward)
+
+      reference.zip(forward).map { |r, f| r - along * f }
+    end
+
+    def frame(forward)
+      axis = (0..2).min_by { |index| forward[index].abs }
+      reference = Array.new(3) { |index| (index == axis) ? 1.0 : 0.0 }
+      up = normalize(away_from(reference, forward))
+
+      [forward, cross(up, forward), up]
+    end
+  end
+end

data/lib/skymap/horizon.rb

@@ -38,13 +38,43 @@ module Skymap
           crossing_point(context, from, to) + [position(context, to)]
         end
 
+      runs_of(context, path)
+    end
+
+    def line(context)
+      azimuths = (0...360).map do |degrees|
+        Astronoby::Coordinates::Horizontal.new(
+          altitude: Astronoby::Angle.zero,
+          azimuth: Astronoby::Angle.from_degrees(degrees),
+          observer: context.observer
+        )
+      end
+      path = (azimuths + azimuths.first(1)).map do |horizontal|
+        next unless context.reachable?(horizontal)
+
+        context.project(
+          altitude: horizontal.altitude,
+          azimuth: horizontal.azimuth
+        )
+      end
+
+      joined(runs_of(context, path))
+    end
+
+    def joined(runs)
+      return runs unless runs.size > 1 && runs.first.first == runs.last.last
+
+      [runs.last + runs.first.drop(1)] + runs[1...-1]
+    end
+
+    def runs_of(context, path)
       path.chunk { |point| !point.nil? }.filter_map do |visible, points|
-        points if visible && points.size > 1
+        points if visible && points.size > 1 && context.crosses_view?(points)
       end
     end
 
     def position(context, horizontal)
-      return if below?(horizontal)
+      return if below?(horizontal) || !context.reachable?(horizontal)
 
       context.project(
         altitude: horizontal.altitude,
@@ -68,6 +98,6 @@ module Skymap
       horizontal.altitude.negative?
     end
 
-    private_class_method :position, :crossing_point, :below?
+    private_class_method :position, :below?
   end
 end