ephem 0.4.1 → 0.5.0

data/lib/ephem/core/orientation.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Ephem
+  module Core
+    # The orientation of a body, expressed as the three Euler angles that rotate
+    # a reference frame (e.g. J2000/ICRF) into the body-fixed frame, optionally
+    # with their time derivatives.
+    #
+    # For binary PCK orientation kernels the angles are the classical 3-1-3
+    # (Z-X-Z) sequence: +phi+ and +theta+ orient the pole and +psi+ is the
+    # rotation about it (the prime meridian). Angles are in radians and rates,
+    # when present, in radians per day — matching ephem's per-day rate
+    # convention for SPK velocities (divide by 86400 for radians per second).
+    class Orientation
+      # @return [Numeric] first Euler angle (radians)
+      attr_reader :phi
+
+      # @return [Numeric] second Euler angle (radians)
+      attr_reader :theta
+
+      # @return [Numeric] third Euler angle (radians)
+      attr_reader :psi
+
+      # @return [Array<Numeric>, nil] [phi, theta, psi] rates (radians/day),
+      #   or nil when the orientation carries no rates
+      attr_reader :rates
+
+      # @param phi [Numeric] first Euler angle (radians)
+      # @param theta [Numeric] second Euler angle (radians)
+      # @param psi [Numeric] third Euler angle (radians)
+      # @param rates [Array<Numeric>, nil] optional [phi, theta, psi] rates
+      #   (radians/day)
+      # @raise [Ephem::InvalidInputError] if any angle or rate is not numeric
+      def initialize(phi, theta, psi, rates: nil)
+        unless phi.is_a?(Numeric) && theta.is_a?(Numeric) && psi.is_a?(Numeric)
+          raise InvalidInputError, "Orientation angles must be numeric"
+        end
+
+        unless rates.nil? || valid_rates?(rates)
+          raise InvalidInputError, "Orientation rates must be three numerics"
+        end
+
+        @phi = phi
+        @theta = theta
+        @psi = psi
+        @rates = rates&.freeze
+        freeze
+      end
+
+      def self.[](phi, theta, psi, rates: nil)
+        new(phi, theta, psi, rates: rates)
+      end
+
+      # @return [Boolean] whether this orientation carries rates
+      def rates?
+        !@rates.nil?
+      end
+
+      # @return [Array<Numeric>] the three Euler angles [phi, theta, psi]
+      def to_a
+        [phi, theta, psi]
+      end
+
+      # The rotation matrix that maps the reference frame into the body-fixed
+      # frame, built from the 3-1-3 (Z-X-Z) Euler angles:
+      # +M = Rz(psi) * Rx(theta) * Rz(phi)+. Rates are ignored.
+      #
+      # @return [Array<Array<Float>>] a 3x3 rotation matrix
+      def to_matrix
+        Rotation.multiply(
+          Rotation.about_z(psi),
+          Rotation.about_x(theta),
+          Rotation.about_z(phi)
+        )
+      end
+
+      # @param index [Integer] 0 for phi, 1 for theta, 2 for psi
+      # @return [Numeric] the angle at the given index
+      # @raise [Ephem::IndexError] if index is not 0, 1, or 2
+      def [](index)
+        case index
+        when 0 then phi
+        when 1 then theta
+        when 2 then psi
+        else raise IndexError, "Invalid index: #{index}"
+        end
+      end
+
+      def inspect
+        body = "phi: #{phi}, theta: #{theta}, psi: #{psi}"
+        body += ", rates: #{rates}" if rates?
+        "Orientation[#{body}]"
+      end
+      alias_method :to_s, :inspect
+
+      def hash
+        [phi, theta, psi, rates, self.class].hash
+      end
+
+      def ==(other)
+        unless other.is_a?(self.class)
+          raise InvalidInputError, "Can only compare with another Orientation"
+        end
+
+        to_a == other.to_a && rates == other.rates
+      end
+      alias_method :eql?, :==
+
+      private
+
+      def valid_rates?(rates)
+        rates.is_a?(Array) &&
+          rates.size == 3 &&
+          rates.all?(Numeric)
+      end
+    end
+  end
+end

data/lib/ephem/core/rotation.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Ephem
+  module Core
+    # Builds and applies 3x3 rotation matrices. Kernel-agnostic: callers choose
+    # the axis sequence and order that matches their frame convention.
+    #
+    # The elementary rotations use the coordinate-frame (passive) convention:
+    # they express a fixed vector in a frame rotated by +angle about the axis
+    module Rotation
+      # @param angle [Numeric] rotation angle in radians
+      # @return [Array<Array<Float>>] rotation about the X axis
+      def self.about_x(angle)
+        cosine = Math.cos(angle)
+        sine = Math.sin(angle)
+        [
+          [1.0, 0.0, 0.0],
+          [0.0, cosine, sine],
+          [0.0, -sine, cosine]
+        ]
+      end
+
+      # @param angle [Numeric] rotation angle in radians
+      # @return [Array<Array<Float>>] rotation about the Y axis
+      def self.about_y(angle)
+        cosine = Math.cos(angle)
+        sine = Math.sin(angle)
+        [
+          [cosine, 0.0, -sine],
+          [0.0, 1.0, 0.0],
+          [sine, 0.0, cosine]
+        ]
+      end
+
+      # @param angle [Numeric] rotation angle in radians
+      # @return [Array<Array<Float>>] rotation about the Z axis
+      def self.about_z(angle)
+        cosine = Math.cos(angle)
+        sine = Math.sin(angle)
+        [
+          [cosine, sine, 0.0],
+          [-sine, cosine, 0.0],
+          [0.0, 0.0, 1.0]
+        ]
+      end
+
+      # Product of rotation matrices in the given order, as standard matrix
+      # multiplication: +multiply(a, b, c)+ returns +a * b * c+.
+      #
+      # @param matrices [Array<Array<Array<Float>>>] one or more 3x3 matrices
+      # @return [Array<Array<Float>>] the combined rotation matrix
+      def self.multiply(*matrices)
+        matrices.reduce { |product, matrix| multiply_pair(product, matrix) }
+      end
+
+      # Applies a rotation matrix to a vector.
+      #
+      # @param matrix [Array<Array<Float>>] a 3x3 rotation matrix
+      # @param vector [Core::Vector, Array<Numeric>] the vector to rotate
+      # @return [Core::Vector] the rotated vector
+      def self.apply(matrix, vector)
+        x, y, z = vector.to_a
+        Vector.new(
+          matrix[0][0] * x + matrix[0][1] * y + matrix[0][2] * z,
+          matrix[1][0] * x + matrix[1][1] * y + matrix[1][2] * z,
+          matrix[2][0] * x + matrix[2][1] * y + matrix[2][2] * z
+        )
+      end
+
+      def self.multiply_pair(left, right)
+        Array.new(3) do |row|
+          Array.new(3) do |column|
+            left[row][0] * right[0][column] +
+              left[row][1] * right[1][column] +
+              left[row][2] * right[2][column]
+          end
+        end
+      end
+      private_class_method :multiply_pair
+    end
+  end
+end

data/lib/ephem/core/state.rb

@@ -51,6 +51,11 @@ module Ephem
         )
       end
 
+      def inspect
+        "State[position: #{position}, velocity: #{velocity}]"
+      end
+      alias_method :to_s, :inspect
+
       # Converts the state vectors to arrays.
       #
       # @return [Array<Array<Numeric>>] Array containing position and velocity

data/lib/ephem/download.rb

@@ -11,6 +11,8 @@ module Ephem
   class Download
     JPL_BASE_URL = "https://ssd.jpl.nasa.gov/ftp/eph/planets/bsp/"
     IMCCE_BASE_URL = "https://ftp.imcce.fr/pub/ephem/planets/"
+    NAIF_PCK_BASE_URL =
+      "https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/"
 
     JPL_KERNELS = %w[
       de102.bsp
@@ -59,6 +61,11 @@ module Ephem
       de441.bsp
     ].freeze
 
+    NAIF_PCK_KERNELS = %w[
+      moon_pa_de421_1900-2050.bpc
+      moon_pa_de440_200625.bpc
+    ].freeze
+
     IMCCE_KERNELS = {
       "inpop10b.bsp" => "inpop10b_TDB_m100_p100_spice.bsp",
       "inpop10b_large.bsp" => "inpop10b_TDB_m1000_p1000_spice.bsp",
@@ -90,7 +97,8 @@ module Ephem
       "inpop21a_large.bsp" => "inpop21a/inpop21a_TDB_m1000_p1000_spice.tar.gz"
     }.freeze
 
-    SUPPORTED_KERNELS = (JPL_KERNELS + IMCCE_KERNELS.keys).freeze
+    SUPPORTED_KERNELS =
+      (JPL_KERNELS + NAIF_PCK_KERNELS + IMCCE_KERNELS.keys).freeze
 
     def self.call(name:, target:)
       new(name, target).call
@@ -104,12 +112,22 @@ module Ephem
 
     def call
       FileUtils.mkdir_p(@target_path.dirname)
-      jpl_kernel? ? download_jpl : download_imcce
+      download_kernel
       true
     end
 
     private
 
+    def download_kernel
+      if jpl_kernel?
+        download_jpl
+      elsif pck_kernel?
+        download_naif_pck
+      else
+        download_imcce
+      end
+    end
+
     def validate_requested_kernel!
       unless SUPPORTED_KERNELS.include?(@name)
         raise UnsupportedError,
@@ -121,8 +139,20 @@ module Ephem
       JPL_KERNELS.include?(@name)
     end
 
+    def pck_kernel?
+      NAIF_PCK_KERNELS.include?(@name)
+    end
+
     def download_jpl
-      uri = URI.join(JPL_BASE_URL, @name)
+      download_direct(JPL_BASE_URL)
+    end
+
+    def download_naif_pck
+      download_direct(NAIF_PCK_BASE_URL)
+    end
+
+    def download_direct(base_url)
+      uri = URI.join(base_url, @name)
       @target_path.open("wb") do |file|
         stream_http_to_file(uri, file)
       end

data/lib/ephem/excerpt.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Ephem
-  # The Excerpt class creates SPK file excerpts with reduced time spans and
-  # target bodies. This is useful for creating smaller files that focus only on
-  # the data needed for specific applications.
+  # The Excerpt class creates DAF excerpts (SPK or binary PCK) with reduced time
+  # spans and bodies. This is useful for creating smaller files that focus only
+  # on the data needed for specific applications.
   #
   # @example Create an excerpt with specific time range and bodies
   #   spk = Ephem::SPK.open("de421.bsp")
@@ -19,11 +19,11 @@ module Ephem
     J2000_EPOCH = Core::Constants::Time::J2000_EPOCH
     RECORD_SIZE = 1024
 
-    # @param spk [Ephem::SPK] The SPK object to create an excerpt from
-    def initialize(spk)
-      @spk = spk
-      @daf = spk.instance_variable_get(:@daf)
-      @binary_reader = @daf.instance_variable_get(:@binary_reader)
+    # @param kernel [Ephem::SPK, Ephem::PCK] The kernel to excerpt from
+    def initialize(kernel)
+      @kernel = kernel
+      @daf = kernel.daf
+      @binary_reader = @daf.binary_reader
     end
 
     # Creates an excerpt of the SPK file
@@ -31,11 +31,12 @@ module Ephem
     # @param output_path [String] Path where the excerpt will be written
     # @param start_jd [Float] Start time as Julian Date
     # @param end_jd [Float] End time as Julian Date
-    # @param target_ids [Array<Integer>, nil] Optional list of target IDs to
-    #   include
+    # @param target_ids [Array<Integer>, nil] Optional list of target/body IDs
+    #   to include
     # @param debug [Boolean] Whether to print debug information
     #
-    # @return [Ephem::SPK] A new SPK instance for the excerpt file
+    # @return [Ephem::SPK, Ephem::PCK] A new instance for the excerpt file,
+    #   matching the source kernel kind
     def extract(output_path:, start_jd:, end_jd:, target_ids: nil, debug: false)
       start_seconds = seconds_since_j2000(start_jd)
       end_seconds = seconds_since_j2000(end_jd)
@@ -46,11 +47,15 @@ module Ephem
       process_segments(writer, start_seconds, end_seconds, target_ids, debug)
       output_file.close
 
-      SPK.open(output_path)
+      reopen(output_path)
     end
 
     private
 
+    def reopen(path)
+      (@daf.file_type == :pck) ? PCK.open(path) : SPK.open(path)
+    end
+
     def seconds_since_j2000(jd)
       (jd - J2000_EPOCH) * S_PER_DAY
     end

data/lib/ephem/io/binary_reader.rb

@@ -4,6 +4,8 @@ module Ephem
   module IO
     class BinaryReader
       RECORD_SIZE = 1024
+      ENDIANNESS_DOUBLE_FORMATS = {little: "E", big: "G"}.freeze
+      ENDIANNESS_UINT32_FORMATS = {little: "V", big: "N"}.freeze
 
       def initialize(file_object)
         validate_file_object(file_object)
@@ -81,20 +83,20 @@ module Ephem
       def read_and_pad_record
         data = @file.read(RECORD_SIZE)
         raise IOError, "Failed to read record" unless data
+
         data.ljust(RECORD_SIZE, "\0")
       end
 
       def read_array_data(length, endianness)
         data = @file.read(8 * length)
         raise IOError, "Failed to read array" unless data
+
         data.unpack("#{endianness_format(endianness)}#{length}")
       end
 
       def endianness_format(endianness)
-        case endianness
-        when :little then "E"
-        when :big then "G"
-        else raise ArgumentError, "Invalid endianness: #{endianness}"
+        ENDIANNESS_DOUBLE_FORMATS.fetch(endianness) do
+          raise ArgumentError, "Invalid endianness: #{endianness}"
         end
       end
     end

data/lib/ephem/io/daf.rb

@@ -3,7 +3,7 @@
 module Ephem
   module IO
     class DAF
-      attr_reader :record_data, :endianness
+      attr_reader :binary_reader, :record_data, :endianness
 
       def initialize(file_object)
         @binary_reader = BinaryReader.new(file_object)
@@ -15,6 +15,11 @@ module Ephem
         @comments ||= load_comments
       end
 
+      # @return [Symbol, nil]
+      def file_type
+        @file_type ||= detect_file_type
+      end
+
       def summaries(&block)
         return enum_for(:summaries) unless block_given?
 
@@ -36,6 +41,18 @@ module Ephem
 
       private
 
+      def detect_file_type
+        case @record_data.locator_identifier
+        when "DAF/SPK" then :spk
+        when "DAF/PCK" then :pck
+        else
+          case @record_data.integer_count
+          when 6 then :spk
+          when 5 then :pck
+          end
+        end
+      end
+
       def setup_file_format
         file_record = @binary_reader.read_record(1)
         endianness_info = EndiannessManager.new(file_record).detect_endianness

data/lib/ephem/io/record_parser.rb

@@ -43,11 +43,11 @@ module Ephem
       end
 
       def endian_uint32
-        (@endianness == :little) ? "V" : "N"
+        BinaryReader::ENDIANNESS_UINT32_FORMATS[@endianness]
       end
 
       def endian_double
-        (@endianness == :little) ? "E" : "G"
+        BinaryReader::ENDIANNESS_DOUBLE_FORMATS[@endianness]
       end
     end
   end

data/lib/ephem/io/summary_manager.rb

@@ -57,6 +57,7 @@ module Ephem
         @record_data = record_data
         @binary_reader = binary_reader
         @endianness = endianness
+        @record_parser = RecordParser.new(endianness: @endianness)
         setup_summary_format
       end
 
@@ -125,10 +126,10 @@ module Ephem
 
       def iterate_summary_chain(record_number)
         while record_number != 0
-          process_summary_record(record_number) do |name, values|
-            yield name, values
-          end
-          record_number = get_next_record(record_number)
+          record_number =
+            process_summary_record(record_number) do |name, values|
+              yield name, values
+            end
         end
       end
 
@@ -145,13 +146,14 @@ module Ephem
         ) do |name, values|
           yield name, values
         end
+
+        control[:next_record]
       end
 
       def parse_control_data(data)
-        control_data = data[0, RecordParser::SUMMARY_CONTROL_SIZE]
-        RecordParser
-          .new(endianness: @endianness)
-          .parse_summary_control(control_data)
+        @record_parser.parse_summary_control(
+          data[0, RecordParser::SUMMARY_CONTROL_SIZE]
+        )
       end
 
       def extract_summary_data(data)
@@ -169,25 +171,22 @@ module Ephem
 
       def extract_values(data)
         return [] if data.nil? || data.empty?
+
         data.unpack(@summary_format)
       end
 
       def extract_name(data)
         return "" if data.nil? || data.empty?
-        data.strip
-      end
 
-      def get_next_record(record_number)
-        data = @binary_reader.read_record(record_number)
-        parse_control_data(data)[:next_record]
+        data.strip
       end
 
       def endian_double
-        (@endianness == :little) ? "E" : "G"
+        BinaryReader::ENDIANNESS_DOUBLE_FORMATS[@endianness]
       end
 
       def endian_uint32
-        (@endianness == :little) ? "V" : "N"
+        BinaryReader::ENDIANNESS_UINT32_FORMATS[@endianness]
       end
     end
   end

data/lib/ephem/pck.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Ephem
+  # Reads a binary PCK (+DAF/PCK+) orientation kernel: the orientation of one or
+  # more body frames over time, expressed as Euler angles.
+  class PCK
+    # Index of the data type within a PCK summary descriptor
+    # ([start, end, body, reference_frame, data_type, start_i, end_i]).
+    DATA_TYPE_IDENTIFIER = 4
+
+    attr_reader :daf, :segments
+
+    # @param daf [Ephem::IO::DAF] DAF containing PCK data
+    # @raise [ArgumentError] if the DAF is nil
+    def initialize(daf:)
+      raise ArgumentError, "DAF cannot be nil" if daf.nil?
+
+      @daf = daf
+      @segments = load_segments
+      @bodies = build_bodies
+    end
+
+    # Opens a binary PCK file.
+    #
+    # @param path [String] Path to the PCK (+.bpc+) file
+    # @return [PCK]
+    # @raise [ArgumentError] if the file is not a binary PCK or cannot be read
+    def self.open(path)
+      daf = IO::DAF.new(File.open(path, "rb"))
+      unless daf.file_type == :pck
+        raise ArgumentError, "#{path} is not a binary PCK (DAF/PCK) file"
+      end
+
+      new(daf: daf)
+    rescue Errno::EACCES => e
+      raise ArgumentError, "File permission denied: #{path} (#{e.message})"
+    rescue
+      daf&.close
+      raise
+    end
+
+    # @return [void]
+    def close
+      @daf&.close
+      @segments&.each(&:clear_data)
+    end
+
+    # Retrieves the orientation source for a body frame.
+    #
+    # @param body [Integer] NAIF frame ID of the oriented body
+    # @return [Segments::OrientationSegment, Segments::OrientationGroup] a
+    #   single segment, or a group routing each query to the covering segment
+    #   when the body spans several time intervals
+    # @raise [KeyError] if no segment is found for the given body
+    def [](body)
+      @bodies.fetch(body) do
+        raise KeyError, "No orientation segment found for body: #{body}"
+      end
+    end
+
+    # @return [String] the comments stored in the PCK file
+    def comments
+      @daf.comments
+    end
+
+    # @yieldparam segment [Segments::OrientationSegment]
+    # @return [Enumerator] if no block is given
+    def each_segment(&block)
+      return enum_for(:each_segment) unless block_given?
+
+      @segments.each(&block)
+    end
+
+    # @return [String] a description of the PCK file and its segments
+    def to_s
+      <<~DESCRIPTION
+        PCK file with #{@segments.size} segments:
+        #{@segments.join("\n")}
+      DESCRIPTION
+    end
+
+    def excerpt(output_path:, start_jd:, end_jd:, target_ids: nil, debug: false)
+      Excerpt
+        .new(self)
+        .extract(
+          output_path: output_path,
+          start_jd: start_jd,
+          end_jd: end_jd,
+          target_ids: target_ids,
+          debug: debug
+        )
+    end
+
+    private
+
+    def load_segments
+      @daf.summaries.map do |source, descriptor|
+        build_segment(source: source, descriptor: descriptor)
+      end
+    end
+
+    def build_bodies
+      @segments.group_by(&:body).transform_values do |segments|
+        Segments::OrientationGroup.wrap(segments)
+      end
+    end
+
+    def build_segment(source:, descriptor:)
+      data_type = descriptor[DATA_TYPE_IDENTIFIER]
+      segment_class = Segments::Registry.lookup(:pck, data_type)
+      unless segment_class
+        raise UnsupportedError, "Unsupported PCK data type: #{data_type}"
+      end
+
+      segment_class.new(daf: @daf, source: source, descriptor: descriptor)
+    end
+  end
+end

data/lib/ephem/segments/base_segment.rb

@@ -38,6 +38,10 @@ module Ephem
       attr_reader :center
       # @return [String] the source of the segment
       attr_reader :source
+      # @return [Float] start of coverage as a Julian Date
+      attr_reader :start_jd
+      # @return [Float] end of coverage as a Julian Date
+      attr_reader :end_jd
 
       # Initialize a new segment
       #
@@ -55,14 +59,7 @@ module Ephem
       def initialize(daf:, source:, descriptor:)
         @daf = daf
         @source = source
-        @start_second,
-          @end_second,
-          @target,
-          @center,
-          @frame,
-          @data_type,
-          @start_i,
-          @end_i = descriptor
+        parse_descriptor(descriptor)
         @start_jd = compute_julian_date(@start_second)
         @end_jd = compute_julian_date(@end_second)
       end
@@ -97,6 +94,15 @@ module Ephem
         DESCRIPTION
       end
 
+      # Whether the given time falls within this segment's coverage.
+      #
+      # @param tdb [Numeric] time in TDB Julian Date
+      # @param tdb2 [Numeric] optional fractional part of the TDB date
+      # @return [Boolean]
+      def covers?(tdb, tdb2 = 0.0)
+        (tdb + tdb2).between?(@start_jd, @end_jd)
+      end
+
       def compute(_tdb, _tdb2 = 0.0)
         raise NotImplementedError,
           "#{self.class} has not implemented compute() for data type #{@data_type}"
@@ -113,6 +119,17 @@ module Ephem
 
       private
 
+      def parse_descriptor(descriptor)
+        @start_second,
+          @end_second,
+          @target,
+          @center,
+          @frame,
+          @data_type,
+          @start_i,
+          @end_i = descriptor
+      end
+
       def compute_julian_date(seconds)
         Time::J2000_EPOCH + seconds / Time::SECONDS_PER_DAY
       end