ruby-avm-library 0.0.1

data/.autotest

@@ -0,0 +1,5 @@
+Autotest.add_hook :initialize do |at|
+  at.add_mapping(%r{^spec/sample_files/([^/]+)/.*}, true) { |_, m|
+    "spec/avm/#{m[1]}_spec.rb"
+  }
+end

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.quickfix.txt

data/.rspec

@@ -0,0 +1,5 @@
+-c
+--require ./spec/quick_fix_formatter.rb
+--format progress
+--format RSpec::Core::Formatters::QuickFixFormatter
+--out .quickfix.txt

data/Gemfile

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in ruby-avm-library.gemspec
+gemspec
+
+group :test do
+  gem 'autotest'
+end
+
+group :mac do
+  gem 'autotest-fsevent'
+  gem 'autotest-growl'
+end
+

data/README.md

@@ -0,0 +1,56 @@
+## The Ruby AVM Library
+
+The Astronomy Visualization Metadata (AVM) standard is an extension of the Adobe XMP format. This
+extension adds information to an astronomical image that describes the scientific data and methods
+of collection that went in to producing the image. This Ruby library assists in reading the metadata from
+XMP documents and writing out AVM data as a new XMP file.
+
+## Installing the library
+
+### From Bundler
+
+In your Gemfile:
+
+    gem 'ruby-avm-library'
+
+To use the current development version:
+
+    gem 'ruby-avm-library', :git => 'git://github.com/johnbintz/ruby-avm-library.git'
+
+### From RubyGems
+
+    gem install ruby-avm-library
+
+## Basic usage
+
+### Reading an XMP file
+
+    require 'avm/image'
+    
+    image = AVM::Image.from_xml(File.read('my-file.xmp'))
+    
+    puts image.title #=> "The title of the image"
+
+### Writing XML data
+
+    image.to_xml #=> <xmp data in xml format />
+
+### Creating an Image from scratch
+
+    image = AVM::Image.new
+    image.title = "The title of the image"
+    
+    observation = image.create_observation(:instrument => 'HST', :color_assignment => 'Green')
+    contact = image.creator.create_contact(:name => 'John Bintz')
+
+## Command line tool
+
+`avm2avm` currently performs one function: take an XMP file from stdin and pretty print the image as a Hash:
+
+    avm2avm < my-file.xmp
+
+## More resources
+
+* RDoc: [http://rdoc.info/github/johnbintz/ruby-avm-library/frames](http://rdoc.info/github/johnbintz/ruby-avm-library/frames)
+* AVM Standard: [http://www.virtualastronomy.org/avm_metadata.php](http://www.virtualastronomy.org/avm_metadata.php)
+

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/autotest/discover.rb

@@ -0,0 +1,2 @@
+Autotest.add_discovery { "rspec2" }
+

data/bin/avm2avm

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'thor'
+require 'avm/cli'
+
+AVM::CLI.start
+

data/lib/avm/cli.rb

@@ -0,0 +1,18 @@
+require 'thor'
+require 'avm/image'
+require 'pp'
+
+module AVM
+  # The CLI interface
+  class CLI < ::Thor
+    default_task :convert
+
+    desc 'convert', "Convert a file from one format to another"
+    def convert
+      data = $stdin.read
+
+      pp AVM::Image.from_xml(data).to_h
+    end
+  end
+end
+

data/lib/avm/contact.rb

@@ -0,0 +1,40 @@
+module AVM
+  # A contributor to an image
+  class Contact
+    FIELD_MAP = {
+      :zip => :postal_code,
+      :state => :state_province,
+      :province => :state_province
+    }
+
+    HASH_FIELDS = [ :name, :email, :telephone, :address, :city, :state, :postal_code, :country ]
+
+    attr_accessor :primary
+
+    def initialize(info)
+      @info = Hash[info.collect { |key, value| [ FIELD_MAP[key] || key, value ] }]
+      @primary = false
+    end
+
+    def method_missing(key)
+      @info[FIELD_MAP[key] || key]
+    end
+
+    def <=>(other)
+      return -1 if primary?
+      self.name <=> other.name
+    end
+
+    def to_creator_list_element
+      %{<rdf:li>#{self.name}</rdf:li>}
+    end
+
+    def primary?
+      @primary
+    end
+
+    def to_h
+      Hash[HASH_FIELDS.collect { |key| [ key, send(key) ] } ]
+    end
+  end
+end

data/lib/avm/controlled_vocabulary.rb

@@ -0,0 +1,23 @@
+module AVM
+  # Build a ControlledVocabulary set of classes for use with CV fields
+  module ControlledVocabulary
+    class << self
+      def included(klass)
+        klass::TERMS.each do |type|
+          new_klass = Class.new do
+            def to_s
+              self.class.to_s.split('::').last
+            end
+
+            def ==(other)
+              self.to_s == other.to_s
+            end
+          end
+
+          klass.const_set(type.to_sym, new_klass)
+        end
+      end
+    end
+  end
+end
+

data/lib/avm/coordinate_frame.rb

@@ -0,0 +1,10 @@
+require 'avm/controlled_vocabulary'
+
+module AVM
+  module CoordinateFrame
+    TERMS = %w{ICRS FK5 FK4 ECL GAL SGAL}
+
+    include ControlledVocabulary
+  end
+end
+

data/lib/avm/coordinate_system_projection.rb

@@ -0,0 +1,10 @@
+require 'avm/controlled_vocabulary'
+
+module AVM
+  module CoordinateSystemProjection
+    TERMS = %w{TAN SIN ARC AIT CAR CEA}
+
+    include ControlledVocabulary
+  end
+end
+

data/lib/avm/creator.rb

@@ -0,0 +1,123 @@
+require 'avm/contact'
+require 'nokogiri'
+
+module AVM
+  # A container for Contacts (contributors to an image)
+  class Creator
+    attr_reader :contacts, :image
+
+    IPTC_CORE_FIELDS = [ :address, :city, :state, :zip, :country ]
+    PRIMARY_CONTACT_FIELDS = IPTC_CORE_FIELDS + [ :province, :postal_code ]
+    IPTC_MULTI_FIELD_MAP = [ [ :telephone, 'CiTelWork' ], [ :email, 'CiEmailWork' ] ]
+    IPTC_CORE_FIELD_ELEMENT_NAMES = %w{CiAdrExtadr CiAdrCity CiAdrRegion CiAdrPcode CiAdrCtry}
+    IPTC_CORE_FIELDS_AND_NAMES = IPTC_CORE_FIELDS.zip(IPTC_CORE_FIELD_ELEMENT_NAMES)
+
+    def initialize(image, given_contacts = [])
+      @options = {}
+      @contacts = given_contacts
+      @image = image
+    end
+
+    def merge!(hash)
+      @options.merge!(hash)
+    end
+
+    def length
+      contacts.length
+    end
+
+    def [](which)
+      contacts[which]
+    end
+
+    def to_a
+      contacts.sort.collect(&:to_h)
+    end
+
+    def method_missing(key, *opts)
+      if (key_to_s = key.to_s)[-1..-1] == '='
+        @options[key_to_s[0..-2].to_sym] = opts.first
+      else
+        if PRIMARY_CONTACT_FIELDS.include?(key)
+          primary_contact_field key
+        else
+          @options[key]
+        end
+      end
+    end
+
+    def add_to_document(document)
+      document.get_refs do |refs|
+        creator = refs[:dublin_core].add_child('<dc:creator><rdf:Seq></rdf:Seq></dc:creator>')
+
+        list = creator.at_xpath('.//rdf:Seq')
+        contact_info = refs[:iptc].add_child('<Iptc4xmpCore:CreatorContactInfo rdf:parseType="Resource" />').first
+
+        contacts.sort.each do |contact| 
+          list.add_child(contact.to_creator_list_element) 
+        end
+
+        if primary_contact
+          IPTC_MULTI_FIELD_MAP.each do |key, element_name|
+            contact_info.add_child "<Iptc4xmpCore:#{element_name}>#{contacts.sort.collect(&key).join(',')}</Iptc4xmpCore:#{element_name}>"
+          end
+
+          iptc_namespace = document.doc.root.namespace_scopes.find { |ns| ns.prefix == 'Iptc4xmpCore' }
+
+          IPTC_CORE_FIELDS_AND_NAMES.each do |key, element_name|
+            node = contact_info.document.create_element(element_name, primary_contact.send(key))
+            node.namespace = iptc_namespace
+            contact_info.add_child node
+          end
+        end
+      end
+    end
+
+    def from_xml(image, document)
+      contacts = []
+      document.get_refs do |refs|
+        refs[:dublin_core].search('.//dc:creator//rdf:li').each do |name|
+          contacts << { :name => name.text.strip }
+        end
+
+        IPTC_MULTI_FIELD_MAP.each do |key, element_name|
+          if node = refs[:iptc].at_xpath(".//Iptc4xmpCore:#{element_name}")
+            node.text.split(',').collect(&:strip).each_with_index do |value, index|
+              contacts[index][key] = value
+            end
+          end
+        end
+
+        IPTC_CORE_FIELDS_AND_NAMES.each do |key, element_name|
+          if node = refs[:iptc].at_xpath("//Iptc4xmpCore:#{element_name}")
+            contacts.each { |contact| contact[key] = node.text.strip }
+          end
+        end
+      end
+
+      if !(@contacts = contacts.collect { |contact| Contact.new(contact) }).empty?
+        @contacts.first.primary = true
+      end
+    end
+
+    def primary_contact
+      @contacts.find(&:primary) || @contacts.sort.first
+    end
+
+    def create_contact(info)
+      contact = Contact.new(info)
+      contacts << contact
+      contact
+    end
+
+    private
+      def primary_contact_field(field)
+        if contact = primary_contact
+          contact.send(field)
+        else
+          nil
+        end
+      end
+  end
+end
+

data/lib/avm/image.rb

@@ -0,0 +1,355 @@
+require 'avm/creator'
+require 'avm/xmp'
+require 'avm/image_type'
+require 'avm/image_quality'
+require 'avm/spatial_quality'
+require 'avm/coordinate_system_projection'
+require 'avm/coordinate_frame'
+require 'avm/observation'
+
+module AVM
+  # A single image, which has Observations, Contacts, and other metadata
+  class Image
+    DUBLIN_CORE_FIELDS = [ :title, :description ]
+
+    PHOTOSHOP_SINGLE_FIELDS = [
+      'Headline',
+      'DateCreated',
+      'Credit'
+    ]
+
+    PHOTOSHOP_SINGLE_METHODS = [
+      :headline,
+      :date,
+      :credit
+    ]
+
+    PHOTOSHOP_SINGLES_MESSAGES = [
+      :headline,
+      :string_date,
+      :credit
+    ]
+
+    PHOTOSHOP_SINGLES_FOR_METHODS = PHOTOSHOP_SINGLE_FIELDS.zip(PHOTOSHOP_SINGLE_METHODS)
+    PHOTOSHOP_SINGLES_FOR_MESSAGES = PHOTOSHOP_SINGLE_FIELDS.zip(PHOTOSHOP_SINGLES_MESSAGES)
+
+    AVM_SINGLE_FIELDS = [ 
+      'Distance.Notes',
+      'Spectral.Notes',
+      'ReferenceURL',
+      'ID',
+      'Type',
+      'Image.ProductQuality',
+      'Spatial.Equinox',
+      'Spatial.Rotation',
+      'Spatial.Notes',
+      'Spatial.FITSheader',
+      'Spatial.Quality',
+      'Spatial.CoordsystemProjection',
+      'Spatial.CDMatrix',
+      'Spatial.Scale',
+      'Spatial.ReferencePixel',
+      'Spatial.ReferenceDimension',
+      'Spatial.ReferenceValue',
+      'Spatial.Equinox',
+      'Spatial.CoordinateFrame',
+      'Publisher',
+      'PublisherID',
+      'ResourceID',
+      'ResourceURL',
+      'RelatedResources',
+      'MetadataDate',
+      'MetadataVersion',
+      'Subject.Category',
+    ]
+
+    AVM_SINGLE_METHODS = [ 
+      :distance_notes,
+      :spectral_notes,
+      :reference_url,
+      :id,
+      :type,
+      :quality,
+      :spatial_equinox,
+      :spatial_rotation,
+      :spatial_notes,
+      :fits_header,
+      :spatial_quality,
+      :coordinate_system_projection,
+      :spatial_cd_matrix,
+      :spatial_scale,
+      :reference_pixel,
+      :reference_dimension,
+      :reference_value,
+      :equinox,
+      :coordinate_frame,
+      :publisher,
+      :publisher_id,
+      :resource_id,
+      :resource_url,
+      :related_resources,
+      :metadata_date,
+      :metadata_version,
+      :categories
+    ]
+
+    AVM_SINGLE_MESSAGES = [
+      :distance_notes, 
+      :spectral_notes, 
+      :reference_url, 
+      :id, 
+      :image_type, 
+      :image_quality,
+      :spatial_equinox,
+      :spatial_rotation,
+      :spatial_notes,
+      :fits_header,
+      :spatial_quality,
+      :coordinate_system_projection,
+      :spatial_cd_matrix,
+      :spatial_scale,
+      :reference_pixel,
+      :reference_dimension,
+      :reference_value,
+      :equinox,
+      :coordinate_frame,
+      :publisher,
+      :publisher_id,
+      :resource_id,
+      :resource_url,
+      :related_resources,
+      :string_metadata_date,
+      :metadata_version,
+      :categories
+    ]
+
+    AVM_SINGLES = AVM_SINGLE_FIELDS.zip(AVM_SINGLE_METHODS)
+    AVM_SINGLES_FOR_MESSAGES = AVM_SINGLE_FIELDS.zip(AVM_SINGLE_MESSAGES)
+
+    AVM_TO_FLOAT = [ 
+      :spatial_rotation,
+      :spatial_cd_matrix,
+      :spatial_scale,
+      :reference_pixel,
+      :reference_dimension,
+      :reference_value
+    ]
+
+    HASH_FIELDS = [ :title, :headline, :description, :distance_notes,
+      :spectral_notes, :reference_url, :credit, :date,
+      :id, :image_type, :image_quality, :coordinate_frame,
+      :equinox, :reference_value, :reference_dimension, :reference_pixel,
+      :spatial_scale, :spatial_rotation, :coordinate_system_projection, :spatial_quality,
+      :spatial_notes, :fits_header, :spatial_cd_matrix, :distance,
+      :publisher, :publisher_id, :resource_id, :resource_url,
+      :related_resources, :metadata_date, :metadata_version, :subject_names, :categories
+    ]
+
+    attr_reader :creator, :observations
+
+    def initialize(options = {})
+      @creator = AVM::Creator.new(self)
+      @options = options
+
+      AVM_TO_FLOAT.each do |field| 
+        @options[field] = case (value = @options[field])
+                          when Array
+                            value.collect(&:to_f)
+                          else
+                            value ? value.to_f : nil
+                          end
+      end
+
+
+      @observations = []
+    end
+
+    def valid?
+      self.title && self.credit
+    end
+
+    def create_observation(options)
+      observation = Observation.new(self, options)
+      @observations << observation
+      observation
+    end
+
+    def to_xml
+      document = AVM::XMP.new
+
+      creator.add_to_document(document)
+      Observation.add_to_document(document, observations)
+
+      document.get_refs do |refs|
+        DUBLIN_CORE_FIELDS.each do |field|
+          refs[:dublin_core].add_child(%{<dc:#{field}>#{alt_li_tag(send(field))}</dc:#{field}>})
+        end
+
+        PHOTOSHOP_SINGLES_FOR_MESSAGES.each do |tag, message|
+          refs[:photoshop].add_child(%{<photoshop:#{tag}>#{send(message)}</photoshop:#{tag}>})
+        end
+
+        AVM_SINGLES_FOR_MESSAGES.each do |tag, message|
+          if value = send(message)
+            case value
+            when Array
+              container_tag = (message == :related_resources) ? 'Bag' : 'Seq'
+              value = "<rdf:#{container_tag}>" + value.collect { |v| "<rdf:li>#{v.to_s}</rdf:li>" }.join + "</rdf:#{container_tag}>"
+            else
+              value = value.to_s
+            end
+
+            refs[:avm].add_child(%{<avm:#{tag}>#{value}</avm:#{tag}>})
+          end
+        end
+
+        distance_nodes = []
+        distance_nodes << rdf_li(light_years) if light_years
+        if redshift
+          distance_nodes << rdf_li('-') if distance_nodes.empty?
+          distance_nodes << rdf_li(redshift)
+        end
+
+        if !distance_nodes.empty?
+          refs[:avm].add_child(%{<avm:Distance><rdf:Seq>#{distance_nodes.join}</rdf:Seq></avm:Distance>})
+        end
+      end
+
+      document.doc
+    end
+
+    def id
+      @options[:id]
+    end
+    
+    def image_type
+      cv_class_instance_for(AVM::ImageType, :type)
+    end
+
+    def image_quality
+      cv_class_instance_for(AVM::ImageQuality, :quality)
+    end
+
+    def spatial_quality
+      cv_class_instance_for(AVM::SpatialQuality, :spatial_quality)
+    end
+
+    def coordinate_frame
+      cv_class_instance_for(AVM::CoordinateFrame, :coordinate_frame)
+    end
+
+    def coordinate_system_projection
+      cv_class_instance_for(AVM::CoordinateSystemProjection, :coordinate_system_projection)
+    end
+
+    def date
+      date_or_nil(:date)
+    end
+
+    def metadata_date
+      date_or_nil(:metadata_date)
+    end
+
+    def string_date
+      string_date_or_nil(:date)
+    end
+
+    def string_metadata_date
+      string_date_or_nil(:metadata_date)
+    end
+
+    def distance
+      [ light_years, redshift ]
+    end
+
+    def self.from_xml(string)
+      document = AVM::XMP.from_string(string)
+
+      options = {}
+
+      document.get_refs do |refs|
+        DUBLIN_CORE_FIELDS.each do |field|
+          if node = refs[:dublin_core].at_xpath(".//dc:#{field}//rdf:li[1]")
+            options[field] = node.text
+          end
+        end
+
+        if node = refs[:dublin_core].at_xpath(".//dc:subject/rdf:Bag")
+          options[:subject_names] = node.search('./rdf:li').collect(&:text)
+        end
+
+        AVM_SINGLES.each do |tag, field|
+          if node = refs[:avm].at_xpath("./avm:#{tag}")
+            if field == :categories
+              options[field] = node.text.split(";").collect(&:strip)
+            else
+              if !(list_items = node.search('.//rdf:li')).empty?
+                options[field] = list_items.collect(&:text)
+              else
+                options[field] = node.text
+              end
+            end
+          end
+        end
+
+        PHOTOSHOP_SINGLES_FOR_METHODS.each do |tag, field|
+          if node = refs[:photoshop].at_xpath("./photoshop:#{tag}")
+            options[field] = node.text
+          end
+        end
+
+        if node = refs[:avm].at_xpath('./avm:Distance')
+          list_values = node.search('.//rdf:li').collect { |li| li.text }
+
+          case list_values.length
+          when 0
+            options[:light_years] = node.text
+          when 1
+            options[:light_years] = list_values.first
+          when 2
+            options[:light_years] = (list_values.first == '-') ? nil : list_values.first
+            options[:redshift] = list_values.last
+          end
+        end
+      end
+
+      image = new(options)
+      image.creator.from_xml(self, document)
+      Observation.from_xml(image, document)
+      image
+    end
+
+    def to_h
+      hash = Hash[HASH_FIELDS.collect { |key| [ key, send(key) ] }]
+      hash[:creator] = creator.to_a
+      hash[:observations] = observations.collect(&:to_h)
+      hash
+    end
+
+    def method_missing(method)
+      @options[method]
+    end
+
+    private
+      def date_or_nil(field)
+        (Time.parse(@options[field]) rescue nil)
+      end
+
+      def string_date_or_nil(field)
+        (value = send(field)) ? value.strftime('%Y-%m-%d') : nil
+      end
+
+      def alt_li_tag(text)
+        %{<rdf:Alt><rdf:li xml:lang="x-default">#{text}</rdf:li></rdf:Alt>}
+      end
+
+      def rdf_li(text)
+        %{<rdf:li>#{text}</rdf:li>}
+      end
+
+      def cv_class_instance_for(mod, field)
+        (mod.const_get(@options[field].to_sym).new rescue nil)
+      end
+  end
+end
+