voruby 1.0.1

data/lib/voruby/spacetime/spacetime.rb

@@ -0,0 +1,607 @@
+require 'voruby/spacetime/loader'
+
+module VORuby
+  
+  module SpaceTime
+  
+    class SpatialPosition
+      attr_accessor :axis1, :axis2, :axis3
+    
+      def initialize(x, y, z)
+        self.axis1 = x
+        self.axis2 = y
+        self.axis3 = z
+      end
+    end
+    class TemporalPosition
+      attr_accessor :time
+    
+      def initialize(t)
+        self.time = t
+      end
+    end
+  
+    class Event
+      attr_accessor :spatial_position, :temporal_position
+    
+      # Create a space-time even with the given spatial and temporal parts.
+      def initialize(spatial, temporal)
+        raise Exception::NotASpatialPosition.new(spatial) if !spatial.is_a?(SpatialPosition)
+        raise Exception::NotATemporalPosition.new(temporal) if !temporal.is_a?(TemporalPosition)
+      
+        self.spatial_position = spatial
+        self.temporal_position = temporal
+      end
+    
+      def to_s
+        "#{self.spatial_position}, #{self.temporal_position}"
+      end
+    end
+  
+    module Exception
+      class NotASpatialPosition < RuntimeError
+        def initialize(value)
+          super("#{value} is not a SpatialPosition")
+        end
+      end
+    
+      class NotATemporalPosition < RuntimeError
+        def initialize(value)
+          super("#{value} is not a TemporalPosition")
+        end
+      end
+    end
+  
+  end
+
+  module CoordinateSystems
+  
+    class CoordinateOutOfRangeException < RuntimeError
+      def initialize(coord_name, value, start_range, end_range)
+        super("#{coord_name} of #{value} out of allowed range.  Must be between #{start_range} and #{end_range}.")
+      end
+    end
+
+    class NotACoordinateException < RuntimeError
+      def initialize(value, intended_name)
+        super("'#{value}' (#{value.class}) is not (or can't be converted to) a #{intended_name} object.")
+      end
+    end
+  
+    class NotATimeException < NotACoordinateException
+      def initialize(value)
+        super(value, 'Time')
+      end
+    end
+  
+    class InvalidTimeOffsetException < RuntimeError
+      def initialize(value)
+        super("Offset '#{value}' not recognized.  Try a number with s, m, h or d appended.")
+      end
+    end
+  
+    class StandardTime < SpaceTime::TemporalPosition
+      attr_reader :value
+    
+      # Create a StandardTime object from Ruby's core Time object.
+      def initialize(time)
+        self.value = time
+      
+        super(self.value)
+      end
+    
+      def value=(time)
+        raise NotATimeException.new(time) if !time.is_a?(Time)
+        @value = time
+      end
+    
+      # Returns an ISO 8601 compliant string representing the UTC time.
+      def to_utc_s
+        self.value.getutc.strftime("%Y-%m-%dT%H:%M:%SZ")
+      end
+    
+      # Returns an ISO 8601 compliant string representing the local time.
+      def to_local_s
+        utc_offset_hrs = self.value.getlocal.utc_offset / (60.0 * 60.0)
+        utc_offset_min = ((utc_offset_hrs - utc_offset_hrs.floor) * 60.0).to_i
+        utc_offset = sprintf("%+03d:%02d", utc_offset_hrs.floor, utc_offset_min)
+
+        self.value.getlocal.strftime("%Y-%m-%dT%H:%M:%S#{utc_offset}")
+      end
+    
+      def extract_time(time_s)
+        matches = time_s.match(/^(\d+(\.\d+)?)([smhd])?$/)
+        raise InvalidTimeOffsetException.new(time_s) if !matches
+      
+        return calculate_time(matches[1].to_f, matches[3])
+      end
+    
+      def calculate_time(value, unit)
+        case unit
+          when 's' then return value
+          when 'm' then return value * 60.0
+          when 'h' then return value * 60.0 * 60.0
+          when 'd' then return value * 24.0 * 60.0 * 60.0
+          else return value
+        end
+      end
+    
+      # Returns a StandardTime object projected forward the specified
+      # amount of time.  Input maybe be:
+      # 1) a decimal number of seconds
+      # 2) a string with a decimal number followed by a modifier specifying the unit.
+      #    The unit may be s = seconds, m = minutes, h = hours, d = days
+      #    i.e. 12.3h for 12.3 hours
+      def +(time_s)
+        new_time = nil
+        (time_s.kind_of?(Numeric))? new_time = self.value + time_s: new_time = self.value + extract_time(time_s)
+        return StandardTime.new(new_time)
+      end
+    
+      # Add the specified number of seconds to the time.
+      def increment(seconds)
+        self.value = (self + seconds).value
+      end
+    
+      # Returns a StandardTime object projected backward the specified
+      # amount of time.  Input maybe be:
+      # 1) a decimal number of seconds
+      # 2) a string with a decimal number followed by a modifier specifying the unit.
+      #    The unit may be s = seconds, m = minutes, h = hours, d = days
+      #    i.e. '12.3h' for 12.3 hours
+      def -(time_s)
+        new_time = nil
+        (time_s.kind_of?(Numeric))? new_time = self.value + time_s: new_time = self.value - extract_time(time_s)
+        return StandardTime.new(new_time)
+      end
+    
+      # Subtract the specified number of seconds to the time.
+      def decrement(seconds)
+        self.value = (self - seconds).value
+      end
+    
+      # Compare two StandardTimes.
+      # if timeA before timeB, returns -1
+      # if timeA == timeB, returns 0
+      # if timeA after timeB, returns 1
+      def <=>(time)
+        self.value <=> time.value
+      end
+    
+      def ==(time)
+        self.value.eql?(time.value)
+      end
+    
+      def to_s
+        self.to_utc_s
+      end
+    
+      private :extract_time, :calculate_time
+    end
+  
+    module Equatorial
+ 
+      module Exception
+        class RAOutOfRange < CoordinateOutOfRangeException
+          def initialize(value)
+            super("Right ascension", value, 0, 360)
+          end
+        end
+    
+        class DecOutOfRange < CoordinateOutOfRangeException
+          def initialize(value)
+            super("Declination", value, -90, 90)
+          end
+        end
+    
+        class InvalidSexigesimalFormat < RuntimeError
+          def initialize(value)
+            super("Sexigesimal value of #{value} in a format that is not understood.  Try NN:NN:NN.NN.")
+          end
+        end
+      
+        class NotARightAscension < NotACoordinateException
+          def initialize(value)
+            super(value, 'RightAscension')
+          end
+        end
+      
+        class NotADeclination < NotACoordinateException
+          def initialize(value)
+            super(value, 'Declination')
+          end
+        end
+      end
+    
+      # Returns true if the provided string looks like it's
+      # in standard sexigesimal format.
+      def self.looks_like_sexigesimal?(sexig, sep='(:|(\s)+)')
+         return true if sexig.match(/^[+-]?\d+#{sep}\d+#{sep}\d+/)
+         return false
+      end
+     
+      # Returns true if the provided string looks like it's
+      # in standard decimal format.
+      def self.looks_like_decimal?(decimal)
+        return true if decimal.to_s.match(/^[+-]?\d+(\.\d*)?$/)
+        return false
+      end
+    
+      # Default is to J2000.0 (i.e. equinox2=2000.0, system=:fk5)
+      def self.precession_matrix(equinox1, equinox2=2000.0, system=:fk5)
+        a, b, c = (system == :fk4)? Equatorial::fk4_rotation_angles(equinox1, equinox2): Equatorial::fk5_rotation_angles(equinox1, equinox2)
+      
+        sina = Math.sin(a)
+        sinb = Math.sin(b)
+        sinc = Math.sin(c)
+      
+        cosa = Math.cos(a)
+        cosb = Math.cos(b)
+        cosc = Math.cos(c)
+      
+        Matrix.rows([
+          [cosa*cosb*cosc-sina*sinb, sina*cosb+cosa*sinb*cosc,  cosa*sinc],
+          [-cosa*sinb-sina*cosb*cosc, cosa*cosb-sina*sinb*cosc, -sina*sinc],
+          [-cosb*sinc, -sinb*sinc, cosc]
+        ])
+      end
+    
+      def self.fk5_rotation_angles(equinox1, equinox2=2000.0)
+        deg_to_rad = Math::PI / 180.0
+        sec_to_rad = deg_to_rad / 3600.0
+        t = 0.001 * (equinox2 - equinox1)
+        st = 0.001 * (equinox1 - 2000.0)
+      
+        a = sec_to_rad * t *
+          (23062.181 +
+            st * (139.656 + 0.0139 * st) +
+            t * (30.188 - 0.344 * st + 17.998))
+        b = sec_to_rad * t * t * (79.280 + 0.410 * st + 0.205 * t) + a
+        c = sec_to_rad * t *
+          (20043.109 -
+            st * (85.33 + 0.217 * st) +
+            t * (-42.665 - 0.217 * st - 41.833 * t))
+          
+        return [a, b, c]
+      end
+    
+      def self.fk4_rotation_angles(equinox1, equinox2=2000.0)
+        deg_to_rad = Math::PI / 180.0
+        sec_to_rad = deg_to_rad / 3600.0
+        t = 0.001 * (equinox2 - equinox1)
+        st = 0.001 * (equinox1 - 1900.0)
+      
+        a = sec_to_rad * t *
+          (23042.53 +
+            st * (139.75 + 0.06 * st) +
+            t * (30.23 - 0.27 * st + 18.0 * t))
+        b = sec_to_rad * t * t * (79.27 + 0.66 * st + 0.32 * t) + a
+        c = sec_to_rad * t *
+          (20046.85 -
+            st * (85.33 + 0.37 * st) +
+            t * (-42.67 - 0.37 * st - 41.8 * t))
+          
+        return [a, b, c]
+      end
+
+      class RightAscension
+        attr_reader :value
+      
+        MIN_ALLOWED_VALUE = 0.0
+        MAX_ALLOWED_VALUE = 360.0
+      
+        # Create a RightAscenson object.
+        def initialize(ra)
+          self.value = ra
+        end
+      
+        def value=(ra)
+          if ra.is_a?(Numeric) or Equatorial::looks_like_decimal?(ra)
+            @value = ra.to_f
+          elsif ra.is_a?(String)
+            if Equatorial::looks_like_sexigesimal?(ra)
+              @value = RightAscension.from_sexigesimal(ra).value
+            else
+              raise Exception::InvalidSexigesimalFormat.new(ra)
+            end
+          else
+            raise Exception::NotARightAscension.new(ra)
+          end
+        
+          raise Exception::RAOutOfRange.new(ra) if !RightAscension::in_range?(@value)
+        end
+
+        # Is the supplied number in the correct range for a right ascension
+        # (i.e between 0 and 360 degrees)?
+        def self.in_range?(ra)
+          (MIN_ALLOWED_VALUE..MAX_ALLOWED_VALUE) === ra
+        end
+      
+        # Create a RightAscension object from a string in sexigesimal format.
+        # Numerical values may be separated by a space or colon (but not both).
+        def self.from_sexigesimal(ra)
+          raise Exception::InvalidSexigesimalFormat.new(ra) if !Equatorial::looks_like_sexigesimal?(ra)
+        
+          hours_s, minutes_s, seconds_s = ra.split(/:|\s+/)
+
+          hours = hours_s.to_f
+          minutes = minutes_s.to_f
+          seconds = seconds_s.to_f
+
+          ra_degrees = 15.0 * (hours + (minutes + seconds.to_f / 60.0) / 60.0)
+          return RightAscension.new(ra_degrees)
+        end
+      
+        # Return the value of the ra as a string in sexigesimal format.
+        def to_sexigesimal(sep=':')
+          rah = (self.value / 15.0).to_i()
+          ram = ((self.value - 15.0 * rah) * (60.0 / 15.0)).to_i()
+          ras = self.value - (rah * 15.0) - (ram / (60.0 / 15.0))
+          ras = ras * (60.0 * 60.0 / 15.0)
+        
+          return sprintf("%02u#{sep}%02u#{sep}%0.2f", rah, ram, ras)
+        end
+      
+        # Returns a RightAscension object projected forward the specified
+        # number of degrees.
+        def +(degrees)
+          new_degrees = self.value + degrees
+          new_degrees = new_degrees - MAX_ALLOWED_VALUE if new_degrees > MAX_ALLOWED_VALUE
+        
+          RightAscension.new(new_degrees)
+        end
+      
+        # Add the specified number of degrees to the ra.
+        def increment(degrees)
+          new_degrees = self + degrees
+          self.value = new_degrees.value
+        end
+      
+        # Returns a RightAscension object projected backward the specified
+        # number of degrees.
+        def -(degrees)
+          new_degrees = self.value - degrees
+          new_degrees = MAX_ALLOWED_VALUE + new_degrees if new_degrees < MIN_ALLOWED_VALUE
+        
+          RightAscension.new(new_degrees)
+        end
+      
+        # Subtract the specified number of degrees from the ra.
+        def decrement(degrees)
+          new_degrees = self - degrees
+          self.value = new_degrees.value
+        end
+      
+        def <=>(ra)
+          self.value <=> ra.value
+        end
+      
+        def ==(ra)
+          self.value == ra.value
+        end
+      
+        def to_s
+          "#{self.to_sexigesimal}"
+        end
+      end
+    
+      class Declination
+        attr_reader :value
+      
+        MIN_ALLOWED_VALUE = -90.0
+        MAX_ALLOWED_VALUE = 90.0
+      
+        # Create a Declination object from a decimal number.
+        def initialize(dec)
+          self.value = dec
+        end
+      
+        def value=(dec)
+          if dec.is_a?(Numeric) or Equatorial::looks_like_decimal?(dec)
+             @value = dec.to_f
+           elsif dec.is_a?(String)
+             if Equatorial::looks_like_sexigesimal?(dec)
+               @value = Declination.from_sexigesimal(dec).value
+             else
+               raise Exception::InvalidSexigesimalFormat.new(dec)
+             end
+           else
+             raise Exception::NotADeclinationAscension.new(dec)
+           end
+         
+           raise Exception::DecOutOfRange.new(dec) if !Declination::in_range?(@value)
+        end
+      
+        # Is the supplied number in the correct range for a declination
+        # (i.e between -90 and 90 degrees)?
+        def self.in_range?(dec)
+          (MIN_ALLOWED_VALUE..MAX_ALLOWED_VALUE) === dec
+        end
+      
+        # Create a Declination object from a string in sexigesimal format.
+        # Numerical values may be separated by a space or colon (but not both).
+        def self.from_sexigesimal(dec)
+          raise Exception::InvalidSexigesimalFormat.new(dec) if !Equatorial::looks_like_sexigesimal?(dec)
+        
+          degree, arcmin, arcsec = dec.split(/:|\s+/)
+          degree_f = degree.to_f()
+          arcmin_f = (arcmin.to_f() / 60.0)
+          arcsec_f = (arcsec.to_f() / (60.0 * 60.0))
+        
+          return Declination.new(degree_f - arcmin_f - arcsec_f) if degree_f < 0
+          return Declination.new(degree_f + arcmin_f + arcsec_f)
+        end
+      
+        # Return the value of the dec as a string in sexigesimal format.
+        def to_sexigesimal(sep=':')
+           degrees = self.value  
+           decsign = '+'
+           if degrees < 0
+             decsign = '-'
+             degrees = -degrees
+           end
+           decd = degrees.to_i()
+           decm = ((degrees - decd) * 60.0).to_i()
+           decs = degrees - decd - (decm / 60.0)
+           decs = decs * 60.0 * 60.0
+         
+           return sprintf("%s%02u#{sep}%02u#{sep}%0.2f", decsign, decd, decm, decs)
+         end
+       
+         # Returns a declination object projected forward the specified
+         # number of degrees.  Note that if the new object will have a
+         # value greater than 90 degrees, the declination will be assumed
+         # to be exactly 90 degrees, and similarly for -90 degrees.
+         def +(degrees)
+           new_degrees = self.value + degrees
+           new_degrees = MAX_ALLOWED_VALUE if new_degrees > MAX_ALLOWED_VALUE
+           new_degrees = MIN_ALLOWED_VALUE if new_degrees < MIN_ALLOWED_VALUE
+         
+           Declination.new(new_degrees)
+         end
+       
+         # Add the specified number of degrees to the dec.
+         def increment(degrees)
+           new_degrees = self + degrees
+           self.value = new_degrees.value
+         end
+       
+         # Returns a declination object projected backwards the specified
+         # number of degrees.  Note that if the new object will have a
+         # value greater less than -90 degrees, the declination will be assumed
+         # to be exactly -90 degrees.
+         def -(degrees)
+           new_degrees = self.value - degrees
+           new_degrees = MIN_ALLOWED_VALUE if new_degrees < MIN_ALLOWED_VALUE
+         
+           Declination.new(new_degrees)
+         end
+       
+         # Subtract the specified number of degrees from the dec.
+         def decrement(degrees)
+           new_degrees = self - degrees
+           self.value = new_degrees.value
+         end
+       
+         def <=>(dec)
+           self.value <=> dec.value
+         end
+
+         def ==(dec)
+           self.value == dec.value
+         end
+
+         def to_s
+           "#{self.to_sexigesimal}"
+         end
+      end
+    
+      class RADecPosition < SpaceTime::SpatialPosition
+        attr_reader :ra, :dec, :distance
+        attr_accessor :equinox, :system
+      
+        # Create a Position object.  ra and dec may be:
+        #   1) RightAscension or Declination objects
+        #   2) Sexigesimal strings in standard format
+        #   3) Strings that looks like decimals
+        #   4) Degrees in decimal format.
+        def initialize(ra, dec, distance=nil, equinox=2000.0, system=:fk5)
+          self.ra = ra
+          self.dec = dec
+          self.distance = distance
+          self.equinox = equinox
+          self.system = system
+        
+          super(self.ra, self.dec, self.distance)
+        end
+      
+        def ra=(ra)
+          (ra.is_a?(RightAscension))? @ra = ra: @ra = RightAscension.new(ra)
+        end
+      
+        def dec=(dec)
+          (dec.is_a?(Declination))? @dec = dec: @dec = Declination.new(dec)
+        end
+      
+        def distance=(dist)
+          @distance = dist
+        end
+      
+        # Returns the angular separation between two positions in degrees.
+        def angular_separation(position)
+          # Convert to radians
+          ra1 = self.ra.value * (Math::PI / 180.0)
+          dec1 = self.dec.value * (Math::PI / 180.0)
+          ra2 = position.ra.value * (Math::PI / 180.0)
+          dec2 = position.dec.value * (Math::PI / 180.0)
+        
+          ninety = 90.0 * (Math::PI / 180) # One quarter of a circle (90 degrees) in radians
+        
+          sep = Math.acos(
+            Math.cos(ninety - dec1) * Math.cos(ninety - dec2) +
+            Math.sin(ninety - dec1) * Math.sin(ninety - dec2) * Math.cos(ra1 - ra2)
+          )
+
+          return sep * (180.0 / Math::PI)
+        end
+      
+        def ==(position)
+            # Precess the new position object into the same equinox as the receiver.
+            position = position.precess(self.equinox, self.system) if position.equinox != self.equinox and position.system != self.system
+            self.ra == position.ra && self.dec == position.dec && self.distance == position.distance
+        end
+      
+        # Precess the position to the specified equinox.
+        # The constants for the precession matrix and general algorithm are taken from the IDL astro routines PREMAT and PRECESS.
+        # Notes: Accuracy of precession decreases for declination values near 90 degrees.
+        # Should not be used more than 2.5 centuries from 2000 on the FK5 system (1950.0 on the FK4 system).
+        def precess(to_equinox=2000.0, system=:fk5)
+          if self.equinox != to_equinox or self.system != system
+            deg_to_rad = Math::PI / 180.0
+        
+            from_components = Matrix.row_vector(RADecPosition::equatorial_to_rectangular(self.ra.value, self.dec.value))
+            precession_matrix = Equatorial::precession_matrix(self.equinox, to_equinox, system)
+            to_components = from_components * precession_matrix
+            ra, dec = RADecPosition::rectangular_to_equatorial(to_components[0, 0], to_components[0, 1], to_components[0, 2])
+        
+            return RADecPosition.new(ra, dec, self.distance, to_equinox, system)
+          else
+            return self
+          end
+        end
+      
+        def to_s
+          coords = "#{self.ra}, #{self.dec}"
+          coords << ", #{self.distance}" if self.distance
+        
+          coords
+        end
+      
+        # Convert RA and Dec in decimal degrees to rectangular coordinates.
+        def self.equatorial_to_rectangular(ra, dec)
+          deg_to_rad = Math::PI / 180.0
+
+          x = Math.cos(ra * deg_to_rad) * Math.cos(dec * deg_to_rad)
+          y = Math.sin(ra * deg_to_rad) * Math.cos(dec * deg_to_rad)
+          z = Math.sin(dec * deg_to_rad)
+
+          return [x, y, z]
+        end
+      
+        # Convert rectangular coordinates to equatorial coordinates in degrees.
+        def self.rectangular_to_equatorial(x, y, z)
+          rad_to_deg = 180.0 / Math::PI
+        
+          ra_rad = Math.atan(y/x)
+          dec_rad = Math.asin(z)
+        
+          ra_rad = ra_rad + 2 * Math::PI if ra_rad < 0.0
+        
+          [ra_rad * rad_to_deg, dec_rad * rad_to_deg]
+        end
+      end
+    end
+
+  end
+end
+