voruby 1.0.1

data/lib/voruby/simple/parameters.rb

@@ -0,0 +1,196 @@
+require 'uri'
+
+module VORuby
+
+  module Simple
+
+    # Classes representing the different sorts of parameters commonly used
+    # in the REST-based services like SIAP, SSAP and SCS.
+    module Parameters
+
+      # Represents a search radius.
+      class Radius
+        def initialize(radius)
+  	      @radius = radius(radius)
+        end
+
+        def radius(radius=nil)
+  	      if radius == nil
+  	        return @radius
+  	      else
+  	        @radius = radius.to_f()
+  	      end
+        end
+
+        def to_s
+  	      URI.escape(sprintf("SR=%.2f", @radius))
+        end
+      end
+    
+      # Represents astronomical longitude.
+      class RightAscension
+        def initialize(ra)
+  	      ra(ra)
+        end
+
+        def ra(ra=nil)
+  	      if ra == nil
+  	        return @ra
+  	      else
+  	        if ra.instance_of?(String)
+  	          if ra =~ /[-+]\d+:\d+:\d+(\.\d+)?/
+  	            @ra = RightAscension.convert_to_decimal_degrees(ra)
+  	          else
+  	            @ra = ra.to_f()
+  	          end
+  	        else
+  	          @ra = ra.to_f()
+  	        end
+  	      end
+        end
+
+        def to_s
+  	      URI.escape(sprintf("RA=%.3f", @ra))
+        end
+      
+        # Convert an RA in h:m:s format to decimal degrees.
+        def self.convert_to_decimal_degrees(ra)
+  	      hours, min, sec = ra.split(':')
+	
+  	      degrees =
+  	        (hours.to_f() * 15.0) +
+  	        (min.to_f() * 15.0 / 60.0) +
+  	        (sec.to_f() * 15.0 / (60.0 * 60.0))
+	
+  	        return degrees
+        end
+      end
+    
+      # Represents astronomical latitude.
+      class Declination
+        def initialize(dec)
+  	      dec(dec)
+        end
+
+        def dec(dec=nil)
+  	      if dec == nil
+  	        return @dec
+  	      else
+  	        if dec.instance_of?(String)
+  	          @dec = Declination.convert_to_decimal_degrees(dec)
+  	        else
+  	          @dec = dec.to_f()
+  	        end
+  	      end
+        end
+
+        def to_s
+  	      URI.escape(sprintf("DEC=%.3f", @dec))
+        end
+
+        # Convert a Dec in d:m:s format to decimal degrees.
+        def self.convert_to_decimal_degrees(dec)
+  	      degree, arcmin, arcsec = dec.split(':')
+	
+  	      degree_f = degree.to_f()
+  	      arcmin_f = (arcmin.to_f() / 60.0)
+  	      arcsec_f = (arcsec.to_f() / (60.0 * 60.0))
+	
+  	      return (degree_f - arcmin_f - arcsec_f) if degree_f < 0
+  	      return degree_f + arcmin_f + arcsec_f
+        end
+      end
+    
+      # Represents an angular size on the sky.
+      class Size
+        def initialize(ra_width, dec_width=nil)
+  	      if dec_width == nil
+  	        ra_width(ra_width)
+  	        dec_width(ra_width)
+  	      else
+  	        ra_width(ra_width)
+  	        dec_width(dec_width)
+  	      end
+        end
+      
+        # Set or get the value of the RA width.
+        # The width is specifed in decimal degrees.
+        def ra_width(ra_width=nil)
+  	      if ra_width == nil
+  	        return @ra_width
+  	      else
+  	        @ra_width = ra_width.to_f()
+  	      end
+        end
+      
+        # Set or get the value of the declination width.
+        # The width is specified in decimal degrees.
+        def dec_width(dec_width=nil)
+  	      if dec_width == nil
+        	  return @dec_width
+        	else
+        	  @dec_width = dec_width.to_f()
+        	end
+        end
+      
+        #  Convert the size to its SIAP-compliant form.
+        def to_s
+        	if @ra_width == @dec_width
+        	  # size = 0 is a special case--it test whether
+        	  # the given point is in an image.
+        	  if @ra_width == 0.0
+        	    return URI.escape("SIZE=0")
+        	  else
+        	    return URI.escape(sprintf("SIZE=%.4f", @ra_width))
+        	  end
+        	else
+        	  return URI.escape(sprintf("SIZE=%.4f,%.4f", @ra_width, @dec_width))
+        	end
+        end
+      end
+    
+      # Represents a position on the sky.
+      class Position
+        def initialize(ra, dec)
+  	      ra(ra)
+  	      dec(dec)
+        end
+      
+        # Set or get the value of the right ascension. 
+        # The RA may be a decimal or a string in standard sexigesimal format.
+        def ra(ra=nil)
+  	      if ra == nil
+  	        return @ra
+  	      else
+  	        if ra.instance_of?(RightAscension)
+  	          @ra = ra
+  	        else
+  	          @ra = RightAscension.new(ra)
+  	        end
+  	      end
+        end
+      
+        # Set or get the value of the declination.
+        # The declination may be a decimal or a string in standard sexigesimal format.
+        def dec(dec=nil)
+  	      if dec == nil
+  	        return @dec
+  	      else
+  	        if dec.instance_of?(Declination)
+  	          @dec = dec
+  	        else
+  	          @dec = Declination.new(dec)
+  	        end
+  	      end
+        end
+			
+        #  Convert the position to its SIAP-compliant form.
+        def to_s
+  	      URI.escape(sprintf("POS=%.3f,%.3f", @ra.ra(), @dec.dec()))
+        end
+      end
+    
+    end
+  end
+  
+end

data/lib/voruby/simple/sap.rb

@@ -0,0 +1,446 @@
+require 'voruby/simple/loader'
+
+module VORuby
+  # A number of classes for dealing with standard VO protocols like SIAP, SSAP and
+  # SCS.
+  module Simple
+    # Executes a series of queries, each in its own thread.
+    # Typical use might be something like this:
+    #   # Convert the query results into an object representation.
+    #   objectifier = Proc.new { |query|
+    #      query.marshall().votable().votable()
+    #   }
+    #
+    #   # Prepare a SIAP query
+    #   nsa_siap = Simple::ImageAccess.new('http://archive.noao.edu/nvo/sim/voquery.php',
+    #	  	         '23:00:00, 2:00:00', 7, nil, 30, 'rexml')
+    #
+    #   # Prepare a SSAP query
+    #   iso_ssap = Simple::SpectralAccess.new('http://pma.iso.vilspa.esa.es:8080/aio/jsp/siap.jsp',
+    #			       '53.084, -27.873', 10, {:format => 'votable'}, 30, 'rexml')
+    #   # Prepare a cone search query
+    #   mast_cone = Simple::ConeSearch.new('http://archive.stsci.edu/hst/search.php',
+    #		 		   53.084, -27.873, 0.01, nil, 30, 'rexml')
+    #
+    #   # Execute the queries asynchronously.
+    #   Simple::QueryExecutor.new([nsa_siap, iso_ssap, mast_cone], objectifier).results().each do |query, votable|
+    #     # Just to prove things are working, output the list of field UCDs for each table.
+    #     puts "#{query.to_s()}..."
+    #     votable.fields().each do |field|
+    #       puts "#{field.id()}, #{field.name()}, #{field.ucd().value() if field.ucd() != nil}"
+    #     end
+    #
+    #     votable.rows().each do |row|
+    #       puts row
+    #     end
+    #
+    #     puts "\n"
+    #   end
+    class QueryExecutor
+      attr_accessor :queries, :converter
+      attr_reader :results
+
+      # [_queries_:]
+      #    A list of valid query objects.  Good examples of these are:
+      #    * Simple::SpectralAccess (Simple Spectral Access Protocol queries)
+      #    * Simple::ImageAccess (Simple Image Access Protocol queries)
+      #    * Simple::ConeSearch (Simple Cone Search queries)
+      # [_converter_:]
+      #    An anonymous subroutine that can be used to convert the result of a
+      #    query into another form--often a VOTABLE::VOTable for our purposes.
+      #    By default, it simply returns the completed query. 
+      # [_abort_on_exeception_:]
+      #     A flag which indicates whether or not if one query fails, the other queries
+      #     should abort, too.
+      # Each query must also have a _fetch_ method.  One way to get this is to mixin
+      # the Simple::HTTPGetQuery module.
+      def initialize(queries=[], converter=Proc.new{|qo| qo}, abort_on_exception=false)
+        @queries = queries
+        @converter = converter
+        Thread::abort_on_exception = abort_on_exception
+    
+        @results = {}
+        begin_queries()
+      end
+
+      # Kick off each query into its own thread.
+      def begin_queries
+        threads = []
+
+        # Place each query in its own thread.
+        queries.each do |query|
+  		    threads << Thread.new(query){ |the_query|
+  	  		  the_query.fetch()
+  	  		  # Convert the query into something (maybe itself).
+  	  		  @results[the_query] = converter.call(the_query)
+  		    }
+        end
+
+        # Make sure each thread finishes before the program
+        # exits.
+        threads.each{ |thread| thread.join() }
+      end
+    end
+
+    # Mixin a generic GET-type HTTP query.
+    # Requires that the main object has a query_uri() method defined
+    # that returns a valid URI as a string.
+    module HTTPGetQuery
+      # Using an HTTP get, fetch the response that corresponds to the
+      # query parameters.
+      def fetch
+        uri = URI.parse(query_uri())
+      
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.read_timeout = query_timeout()
+      
+        uri_params = required_parameters()
+        # Other parameters
+        parameters().each do |param, value|
+  		    uri_params.push(URI.escape("#{param.to_s().upcase()}=#{value}"))
+        end
+      
+        res = http.start {|http|
+          http.get(uri.path + '?' + uri_params.join('&'))
+        }
+        self.response = res.body
+      end
+
+      # Convert to a form suitable for use in a URL.  The required_parameters
+      # and parameters methods must exist.
+      def query_uri
+        uri_params = required_parameters()
+
+        # Other parameters
+        parameters().each do |param, value|
+  		    uri_params.push(URI.escape("#{param.to_s().upcase()}=#{value}"))
+        end
+      
+        "#{uri()}?" + uri_params.join('&')
+      end
+    end
+
+    # Mixin a method that converts an XML VOTable into an object using
+    # a VOTABLE::TreeParsedVOTable.
+    module VOTableMarshaller
+      # Interpret the response into an object.
+      def marshall
+        tmp_file = Tempfile.new('response_') # Open a temporary file.
+
+        # Write the response.
+        tmp_file.write(response())
+        tmp_file.flush()
+
+        # Create the votable
+        votable = VORuby::VOTables::VOTable::TreeParsedVOTable.new(tmp_file.path(), parser())
+
+        tmp_file.close()
+
+        votable
+      end
+    end
+
+    # Represents a query to a cone search server.
+    #     mast_cone =  Simple::ConeSearch.new('http://archive.stsci.edu/hst/search.php',
+    #						53.084, -27.873, 0.01, nil, 30, 'rexml')
+    #     mast_cone.fetch()
+    #     votable = mast_cone.marshall()
+    class ConeSearch
+      include HTTPGetQuery
+      include VOTableMarshaller
+
+      attr_accessor :uri, :parameters, :query_timeout, :parser, :response
+
+  	# [_uri_:]
+  	#   The base URI of the cone service.
+  	# [_ra_:]
+  	#   The right ascension search center of the query.  May be a floating
+  	#   point number (in degrees), or a full Simple::Parameters::RightAscension
+  	#   object.
+  	# [_dec_:]
+  	#   The declination search center of the query.  May be a floating
+  	#   point number (in degrees), or a full Simple::Parameters::Declination
+  	#   object.
+  	# [_radius_:]
+  	#    The size of the search radius in degrees.
+  	# [_parameters_:]
+  	#   A hash of extra parameters to pass to the cone service.  Typically
+  	#   this list is empty, but some cone servers permit "extra" parameters
+  	#   to be used.
+  	# [_:query_timeout_:]
+  	#   Period of time to wait until the remote host don't respond.
+  	# [_parser_:]
+  	#   A string representing the underlying XML parser to use.  Choices
+  	#   right now are 'rexml' and 'libxml'.  rexml ships with Ruby, but is
+  	#   slow.  libxml is much faster, but of course must be installed
+  	#   separately.
+      def initialize(uri, ra, dec, radius, parameters={}, query_timeout=30, parser='rexml')
+        parameters ||= {}
+      
+        @uri = uri
+        ra(ra)
+        dec(dec)
+        radius(radius)
+        @parameters = parameters
+        @query_timeout = query_timeout
+        @parser = parser
+
+        @response = nil
+      end
+
+      # Set or get the value of the RA.
+      # Allows a lazy mode where a string representing
+      # the right ascension is passed in instead of a full
+      # Simple::Parameters::RightAscension object.
+      def ra(ra=nil)
+      	if ra == nil
+  			return @ra
+        	else
+  			if ra.instance_of?(Parameters::RightAscension)
+  	  			@ra = ra
+  			elsif ra.instance_of?(String) or ra.instance_of?(Float) or ra.instance_of?(Fixnum)
+  	  			@ra = Parameters::RightAscension.new(ra)
+  			else
+  	  			raise "Right ascension must be RightAscension object or an interparable string."
+  			end  
+        	end
+      end
+
+      # Set or get the value of the dec.
+      # Allows a lazy mode where a string representing
+      # the declination is passed in instead of a full
+      # Simple::Parameters::Declination object.
+      def dec(dec=nil)
+        if dec == nil
+  		return @dec
+        else
+  		if dec.instance_of?(Parameters::Declination)
+  	  		@dec = dec
+  		elsif dec.instance_of?(String) or dec.instance_of?(Float) or dec.instance_of?(Fixnum)
+  	  		@dec = Parameters::Declination.new(dec)
+  		else
+  	  		raise "Declination must be a Declination object or an interparable string."
+  		end
+        end
+      end
+
+      # Set or get the value of the search radius (in degrees).
+      # Allows a lazy mode where an integer representing the radius
+      # is passed in instead of a full
+      # Simple::Parameters::Radius object.
+      def radius(radius=nil)
+        if radius == nil
+  		return @radius
+        else
+  		if radius.instance_of?(Parameters::Radius)
+  	  		@radius = radius
+  		else
+  	  		@radius = Parameters::Radius.new(radius)
+  		end
+        end
+      end
+
+  	# Retrieve the list of required parameters.  In this case: ra, dec and radius.
+      def required_parameters
+        [@ra.to_s(), @dec.to_s(), @radius.to_s()]
+      end
+
+  	# Convert the query into a valid URL.
+      def to_s
+        query_uri()
+      end
+    end
+
+    # Represents a query to single SSAP server.
+    #   iso_ssap = Simple::SpectralAccess.new('http://pma.iso.vilspa.esa.es:8080/aio/jsp/siap.jsp',
+    #			                           '53.084, -27.873', 10, {:format => 'votable'},
+    #			                           30, 'rexml')
+    #   iso_ssap.fetch()
+    #   votable = iso_ssap.marshall()
+    class SpectralAccess
+      include HTTPGetQuery
+      include VOTableMarshaller
+
+      attr_accessor :uri, :parameters, :query_timeout, :parser, :response
+    
+      # [_uri_:]
+      #   The base URI of the SSAP service.
+      # [_pos_:]
+      #   The RA and dec position of the search center for the query. May be a string
+      #   of the form '53.084, -27.873', or a full Simple::Parameters::Position
+      #   object.
+      # [_size_:]
+      #    The size (in degrees) of the search area.
+      # [_parameters_:]
+      #    A hash of additional parameters to pass to the SSAP service.
+      # [_:query_timeout_:]
+  	  #   Period of time to wait until the remote host don't respond.
+      # [_parser_:]
+      #   A string representing the underlying XML parser to use.  Choices
+  	  #   right now are 'rexml' and 'libxml'.  rexml ships with Ruby, but is
+  	  #   slow.  libxml is much faster, but of course must be installed
+  	  #   separately.
+      def initialize(uri, pos, size, parameters={}, query_timeout=30, parser='rexml')
+        parameters ||= {}
+      
+        @uri = uri
+        pos(pos)
+        size(size)
+        @parameters = parameters
+        @query_timeout = query_timeout
+        @parser = parser
+
+        @response = nil
+      end
+    
+      # Set or get the value of the position.
+      # Allows a lazy mode where a string representing
+      # the position like '53.084, -27.873'is passed in
+      # instead of a full Position object.
+      def pos(pos=nil)
+        if pos == nil
+  		return @pos
+        else
+  	  	# Position.  Allow a lazy mode where a string representing
+  	  	# the position is passed in instead of a full Position object.
+  		if pos.instance_of?(Parameters::Position)
+  	  		@pos = pos
+  		elsif pos.instance_of?(String)
+  	  		ra_dec, dec_dec = pos.split(/\s*,\s*/)
+  	  		@pos = Parameters::Position.new(ra_dec, dec_dec)
+  		else
+  	  	raise "Position must be a Position object or a string like " +
+  	    	"'ra_in_decimal_degrees, dec_in_decimal_degrees'"
+  		end
+        end
+      end
+    
+      # Set or get the value of the angular size.
+      # Allows a lazy mode where a floating point number representing
+      # the size is passed in instead of a full Size object.
+      def size(size=nil)
+        if size == nil
+  		return @size
+        else
+  		if size.instance_of?(Parameters::Size)
+  	  		@size = size
+  		elsif size.instance_of?(String)
+  	  		ra_width, dec_width = size.split(/\s*,\s*/)
+  	  		@size = Parameters::Size.new(ra_width, dec_width)
+  		elsif size.instance_of?(Float) or size.instance_of?(Fixnum)
+  	  		@size = Parameters::Size.new(size.to_f())
+  		else
+  	  		raise "Size must be a Size object or a string like " +
+  	    		"'ra_width_in_decimal_degrees, dec_width_in_decimal_degrees'"
+  		end
+        end
+      end
+
+  	# Retrieve the list of required parameters.  In this case: pos and size.
+      def required_parameters
+        [@pos.to_s(), @size.to_s()]
+      end
+    
+      # Convert the query into a valid URL.
+      def to_s
+        query_uri()
+      end
+    end
+	
+    # Represents a query to single SIAP server.
+    #   nsa_siap = Simple::ImageAccess.new('http://archive.noao.edu/nvo/sim/voquery.php',
+    #                                    '23:00:00, 2:00:00', 7, nil, 30, 'rexml')
+    #   nsa_siap.fetch()
+    #   votable = nsa_siap.marshall()
+    class ImageAccess
+      include HTTPGetQuery
+      include VOTableMarshaller
+
+      attr_accessor :uri, :parameters, :query_timeout, :parser, :response
+    
+      # [_uri_:]
+      #   The base URI of the SIAP service.
+      # [_pos_:]
+      #   The RA and dec position of the search center for the query. May be a string
+      #   of the form '53.084, -27.873', or a full Simple::Parameters::Position
+      #   object.
+      # [_size_:]
+      #    The size (in degrees) of the search area.
+      # [_parameters_:]
+      #    A hash of additional parameters to pass to the SIAP service.
+      # [_:query_timeout_:]
+  	#   Period of time to wait until the remote host don't respond.
+      # [_parser_:]
+      #   A string representing the underlying XML parser to use.  Choices
+  	#   right now are 'rexml' and 'libxml'.  rexml ships with Ruby, but is
+  	#   slow.  libxml is much faster, but of course must be installed
+  	#   separately.
+      def initialize(uri, pos, size, parameters={}, query_timeout=30, parser='rexml')
+        parameters ||= {}
+
+        @uri = uri
+        pos(pos)
+        size(size)
+        @parameters = parameters
+        @query_timeout = query_timeout
+        @parser = parser
+
+        @response = nil
+      end
+    
+      # Set or get the value of the position.
+      # Allows a lazy mode where a string representing
+      # the position like '53.084, -27.873'is passed in
+      # instead of a full Position object.
+      def pos(pos=nil)
+        if pos == nil
+  		return @pos
+        else
+  	  	# Position.  Allow a lazy mode where a string representing
+  	  	# the position is passed in instead of a full Position object.
+  		if pos.instance_of?(Parameters::Position)
+  	  		@pos = pos
+  		elsif pos.instance_of?(String)
+  	  		ra_dec, dec_dec = pos.split(/\s*,\s*/)
+  	  		@pos = Parameters::Position.new(ra_dec, dec_dec)
+  		else
+  	  		raise "Position must be a Position object or a string like " +
+  	    		"'ra_in_decimal_degrees, dec_in_decimal_degrees'"
+  		end
+        end
+      end
+		
+      # Set or get the value of the angular size.
+      # Allows a lazy mode where a floating point number representing
+      # the size is passed in instead of a full Size object.
+      def size(size=nil)
+        if size == nil
+  		return @size
+        else
+  		if size.instance_of?(Parameters::Size)
+  	  		@size = size
+  		elsif size.instance_of?(String)
+  	  		ra_width, dec_width = size.split(/\s*,\s*/)
+  	  		@size = Parameters::Size.new(ra_width, dec_width)
+  		elsif size.instance_of?(Float) or size.instance_of?(Fixnum)
+  	  		@size = Parameters::Size.new(size.to_f())
+  		else
+  	  		raise "Size must be a Size object or a string like " +
+  	    		"'ra_width_in_decimal_degrees, dec_width_in_decimal_degrees'"
+  		end
+        end
+      end
+
+      # Retrieve the list of required parameters.  In this case: pos and size.
+      def required_parameters
+        [@pos.to_s(), @size.to_s()]
+      end
+    
+      # Convert the query into a valid URL.
+      def to_s
+        query_uri()
+      end
+    end
+  
+  end
+end

data/lib/voruby/spacetime/loader.rb

@@ -0,0 +1,3 @@
+require 'voruby/loader'
+
+require 'matrix'