iiif-presentation 1.1.0 → 1.2.0

data/lib/iiif/v3/presentation/canvas.rb

@@ -0,0 +1,82 @@
+module IIIF
+  module V3
+    module Presentation
+      class Canvas < IIIF::V3::AbstractResource
+
+        TYPE = 'Canvas'.freeze
+
+        def required_keys
+          super + %w{ id label }
+        end
+
+        def prohibited_keys
+          super + PAGING_PROPERTIES + %w{ viewing_direction format nav_date start_canvas content_annotations }
+        end
+
+        def int_only_keys
+          super + %w{ depth }
+        end
+
+        def array_only_keys
+          super + %w{ content }
+        end
+
+        def legal_viewing_hint_values
+          super + %w{ paged continuous non-paged facing-pages auto-advance }
+        end
+
+        def initialize(hsh={})
+          hsh['type'] = TYPE unless hsh.has_key? 'type'
+          super(hsh)
+        end
+
+        def validate
+          super
+
+          id_uri = URI.parse(self['id'])
+          unless self['id'] =~ /^https?:/ && id_uri.fragment.nil?
+            err_msg = "id must be an http(s) URI without a fragment for #{self.class}"
+            raise IIIF::V3::Presentation::IllegalValueError, err_msg
+          end
+
+          content = self['content']
+          if content && content.any?
+            unless content.all? { |entry| entry.instance_of?(IIIF::V3::Presentation::AnnotationPage) }
+              err_msg = 'All entries in the content list must be a IIIF::V3::Presentation::AnnotationPage'
+              raise IIIF::V3::Presentation::IllegalValueError, err_msg
+            end
+            content.each do |anno_page|
+              annos = anno_page['items']
+              if annos && annos.any?
+                unless annos.all? { |anno| anno.target == self.id }
+                  err_msg = 'URI of the canvas must be repeated in the target field of included Annotations'
+                  raise IIIF::V3::Presentation::IllegalValueError, err_msg
+                end
+              end
+            end
+          end
+
+          # "A canvas MUST have exactly one width and one height, or exactly one duration.
+          # It may have width, height and duration.""
+          height = self['height']
+          width = self['width']
+          if (!!height ^ !!width) # this is an exclusive or: forces height and width to boolean
+            extent_err_msg = "#{self.class} requires both height and width or neither"
+            raise IIIF::V3::Presentation::IllegalValueError, extent_err_msg
+          end
+          # NOTE:  relaxing requirement for (exactly one width and one height, and/or exactly one duration)
+          #  as Stanford has objects (such as txt files) for which this makes no sense
+          #  (see sul-dlss/purl/issues/169)
+          # duration = self['duration']
+          # unless (height && width) || duration
+          #   extent_err_msg = "#{self.class} must have (a height and a width) and/or a duration"
+          #   raise IIIF::V3::Presentation::IllegalValueError, extent_err_msg
+          # end
+
+          # TODO: Content must not be associated with space or time outside of the Canvas’s dimensions,
+          # such as at coordinates below 0,0, greater than the height or width, before 0 seconds, or after the duration.
+        end
+      end
+    end
+  end
+end

data/lib/iiif/v3/presentation/choice.rb

@@ -0,0 +1,51 @@
+module IIIF
+  module V3
+    module Presentation
+      class Choice < IIIF::V3::AbstractResource
+
+        TYPE = 'Choice'.freeze
+
+        def prohibited_keys
+          super + CONTENT_RESOURCE_PROPERTIES + PAGING_PROPERTIES +
+          %w{ nav_date viewing_direction start_canvas content_annotations }
+        end
+
+        def any_type_keys
+          super + %w{ default }
+        end
+
+        def string_only_keys
+          super + %w{ choice_hint }
+        end
+
+        def array_only_keys;
+          super + %w{ items };
+        end
+
+        def legal_viewing_hint_values
+          %w{ none }
+        end
+
+        def legal_choice_hint_values
+          %w{ client user }
+        end
+
+        def initialize(hsh={})
+          hsh['type'] = TYPE unless hsh.has_key? 'type'
+          super(hsh)
+        end
+
+        def validate
+          super
+
+          if self.has_key?('choice_hint')
+            unless self.legal_choice_hint_values.include?(self['choice_hint'])
+              m = "choiceHint for #{self.class} must be one of #{self.legal_choice_hint_values}."
+              raise IIIF::V3::Presentation::IllegalValueError, m
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iiif/v3/presentation/collection.rb

@@ -0,0 +1,52 @@
+module IIIF
+  module V3
+    module Presentation
+      class Collection < IIIF::V3::AbstractResource
+
+        TYPE = 'Collection'.freeze
+
+        def required_keys
+          super + %w{ id label }
+        end
+
+        def array_only_keys
+          super + %w{ collections manifests }
+        end
+
+        # TODO: navDate (collection or manifest only) - The value must be an xsd:dateTime literal in UTC, expressed in the form “YYYY-MM-DDThh:mm:ssZ”;  There must be at most one navDate associated with any given resource.
+
+        # TODO: paging properties
+        # Collection, AnnotationCollection, (formerly layer --> AnnotationPage???) allow;  forbidden o.w.
+        # ---
+        # first, last, next, prev
+        #   id is URI, but may have other info
+        # total, startIndex
+        #   The value must be a non-negative integer.
+
+        def legal_viewing_hint_values
+          %w{ auto-advance together }
+        end
+
+        def initialize(hsh={})
+          hsh['type'] = TYPE unless hsh.has_key? 'type'
+          super(hsh)
+        end
+
+        def validate
+          super
+          # TODO: each member of collections and manifests must be a Hash
+          # TODO: each member of collections and manifests MUST have id, type, and label
+          # TODO: navDate (collection or manifest only) - The value must be an xsd:dateTime literal in UTC, expressed in the form “YYYY-MM-DDThh:mm:ssZ”;  There must be at most one navDate associated with any given resource.
+
+          # TODO: paging properties
+          # Collection, AnnotationCollection, (formerly layer --> AnnotationPage???) allow;  forbidden o.w.
+          # ---
+          # first, last, next, prev
+          #   id is URI, but may have other info
+          # total, startIndex
+          #   The value must be a non-negative integer.
+        end
+      end
+    end
+  end
+end

data/lib/iiif/v3/presentation/image_resource.rb

@@ -0,0 +1,110 @@
+require 'faraday'
+
+module IIIF
+  module V3
+    module Presentation
+      class ImageResource < Resource
+
+        TYPE = 'Image'.freeze
+
+        def initialize(hsh={})
+          hsh['type'] = TYPE unless hsh.has_key? 'type'
+          super(hsh)
+        end
+
+        class << self
+          IMAGE_API_DEFAULT_PARAMS = '/full/!200,200/0/default.jpg'.freeze
+          DEFAULT_FORMAT = 'image/jpeg'.freeze
+          # Create a new ImageResource that includes a IIIF Image API Service
+          # See http://iiif.io/api/presentation/2.0/#image-resources
+          #
+          # Params
+          #  * :service_id (required) - The base URI for the image on the image
+          #      server.
+          #  * :resource_id - The id for the resource; if supplied this should
+          #      resolve to an actual image. Default:
+          #      "#{:service_id}/full/!200,200/0/default.jpg"
+          #  * :format - The format of the image that is returned when
+          #       `:resource_id` is resolved. Default: 'image/jpeg'
+          #  * :height (Integer)
+          #  * :profile (String)
+          #  * :width (Integer) - If width, height, and profile are not supplied,
+          #      this method will try to get the info from the server (based on
+          #      :resource_id) and raise an Exception if this is not possible for
+          #       some reason.
+          #  * :copy_info (bool)- Even if width and height are supplied, try to
+          #      get the info.json from the server and copy it in. Default: false
+          #
+          # Raises:
+          #  * KeyError if `:service_id` is not supplied
+          #  * Expections related to HTTP problems if a call to an image server fails
+          #
+          # The result is something like this:
+          #
+          # {
+          #   "id":"http://www.example.org/iiif/book1/res/page1.jpg",
+          #   "type": "Image",
+          #   "format": "image/jpeg",
+          #   "service": {
+          #     "@context": "http://iiif.io/api/image/2/context.json",
+          #     "id":"http://www.example.org/images/book1-page1",
+          #     "profile":"http://iiif.io/api/image/2/profiles/level2.json",
+          #   },
+          #   "height":2000,
+          #   "width":1500
+          # }
+          #
+          def create_image_api_image_resource(params={})
+
+            service_id = params.fetch(:service_id)
+            resource_id_default = "#{service_id}#{IMAGE_API_DEFAULT_PARAMS}"
+            resource_id = params.fetch(:resource_id, resource_id_default)
+            format = params.fetch(:format, DEFAULT_FORMAT)
+            height = params.fetch(:height, nil)
+            profile = params.fetch(:profile, nil)
+            width = params.fetch(:width, nil)
+            copy_info = params.fetch(:copy_info, false)
+
+            have_whp = [width, height, profile].all? { |prop| !prop.nil? }
+
+            remote_info = get_info(service_id) if !have_whp || copy_info
+
+            resource = self.new
+            resource['id'] = resource_id
+            resource.format = format
+            resource.width = width.nil? ? remote_info['width'] : width
+            resource.height = height.nil? ? remote_info['height'] : height
+            resource_service = Service.new
+            if copy_info
+              resource_service.merge!(remote_info)
+              resource_service['id'] ||= resource_service.delete('@id')
+            else
+              resource_service['id'] = service_id
+              if profile.nil?
+                if remote_info['profile'].kind_of?(Array)
+                  resource_service['profile'] = remote_info['profile'][0]
+                else
+                  resource_service['profile'] = remote_info['profile']
+                end
+              else
+                resource_service['profile'] = profile
+              end
+            end
+            resource.service = [resource_service]
+            return resource
+          end
+
+          protected
+          def get_info(svc_id)
+            conn = Faraday.new("#{svc_id}/info.json") do |c|
+              c.use Faraday::Response::RaiseError
+              c.adapter :net_http
+            end
+            resp = conn.get # raises exceptions that indicate HTTP problems
+            JSON.parse(resp.body)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iiif/v3/presentation/manifest.rb

@@ -0,0 +1,82 @@
+module IIIF
+  module V3
+    module Presentation
+      class Manifest < IIIF::V3::AbstractResource
+
+        TYPE = 'Manifest'.freeze
+
+        def required_keys
+          # NOTE:  relaxing requirement for items as Universal Viewer currently only accepts sequences
+          #  see https://github.com/sul-dlss/osullivan/issues/27, sul-dlss/purl/issues/167
+          # super + %w{ id label items }
+          super + %w{ id label }
+        end
+
+        def prohibited_keys
+          super + CONTENT_RESOURCE_PROPERTIES + PAGING_PROPERTIES + %w{ start_canvas content_annotation }
+        end
+
+        def uri_only_keys
+          super + %w{ id }
+        end
+
+        def array_only_keys
+          # NOTE: allowing 'items' or 'sequences' as Universal Viewer currently only accepts sequences
+          #  see https://github.com/sul-dlss/osullivan/issues/27, sul-dlss/purl/issues/167
+          # super + %w{ items structures }
+          super + %w{ items structures sequences }
+        end
+
+        def legal_viewing_hint_values
+          %w{ individuals paged continuous auto-advance }
+        end
+
+        def initialize(hsh={})
+          hsh['type'] = TYPE unless hsh.has_key? 'type'
+          super(hsh)
+        end
+
+        def validate
+          super # also checks navDate format
+
+          unless self['id'] =~ /^https?:/
+            err_msg = "id must be an http(s) URI for #{self.class}"
+            raise IIIF::V3::Presentation::IllegalValueError, err_msg
+          end
+
+          # Items object list
+          unless self&.[]('items')&.any?
+            m = 'The items list must have at least one entry (and it must be a IIIF::V3::Presentation::Canvas)'
+            raise IIIF::V3::Presentation::MissingRequiredKeyError, m
+          end
+          validate_items_list(self['items']) if self['items']
+
+          # TODO: when embedding a sequence without any extensions within a manifest, the sequence must not have the @context field.
+
+          # TODO: AnnotationLists must not be embedded within the manifest
+
+          if self['structures']
+            unless self['structures'].all? { |entry| entry.instance_of?(IIIF::V3::Presentation::Range)}
+              m = 'All entries in the structures list must be a IIIF::V3::Presentation::Range'
+              raise IIIF::V3::Presentation::IllegalValueError, m
+            end
+          end
+        end
+
+        # NOTE: allowing 'items' or 'sequences' as Universal Viewer currently only accepts sequences
+        #  see https://github.com/sul-dlss/osullivan/issues/27, sul-dlss/purl/issues/167
+        def validate_items_list(items_array)
+          unless items_array.size >= 1
+            m = 'The items list must have at least one entry (and it must be a IIIF::V3::Presentation::Canvas)'
+            raise IIIF::V3::Presentation::MissingRequiredKeyError, m
+          end
+
+          unless items_array.all? { |entry| entry.instance_of?(IIIF::V3::Presentation::Canvas) }
+            m = 'All entries in the items list must be a IIIF::V3::Presentation::Canvas'
+            raise IIIF::V3::Presentation::IllegalValueError, m
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iiif/v3/presentation/range.rb

@@ -0,0 +1,39 @@
+module IIIF
+  module V3
+    module Presentation
+      # Ranges are linked or embedded within the manifest in a structures field
+      class Range < Sequence
+
+        TYPE = 'Range'.freeze
+
+        def required_keys
+          super + %w{ id label }
+        end
+
+        # TODO: contentAnnotations: links to AnnotationCollection
+        # TODO: startCanvas: A link from a Sequence or Range to a Canvas that is contained within it
+
+        def array_only_keys
+          super + %w{ members }
+        end
+
+        def legal_viewing_hint_values
+          super + %w{ top }
+        end
+
+        def initialize(hsh={})
+          hsh['type'] = TYPE unless hsh.has_key? 'type'
+          super(hsh)
+        end
+
+        def validate
+          super
+          # TODO: Ranges must have URIs and they should be http(s) URIs.
+          # TODO: Values of the members array must be canvas or range
+          # TODO: contentAnnotations: links to AnnotationCollection
+          # TODO: startCanvas: A link from a Sequence or Range to a Canvas that is contained within it
+        end
+      end
+    end
+  end
+end

data/lib/iiif/v3/presentation/resource.rb

@@ -0,0 +1,30 @@
+module IIIF
+  module V3
+    module Presentation
+      # class for generic content resource
+      class Resource < IIIF::V3::AbstractResource
+
+        def required_keys
+          super + %w{ id }
+        end
+
+        def prohibited_keys
+          super + PAGING_PROPERTIES + %w{ nav_date viewing_direction start_canvas content_annotations}
+        end
+
+        def uri_only_keys
+          super + %w{ id }
+        end
+
+        def validate
+          super
+
+          unless self['id'] =~ /^https?:/
+            err_msg = "id must be an http(s) URI for #{self.class}"
+            raise IIIF::V3::Presentation::IllegalValueError, err_msg
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iiif/v3/presentation/sequence.rb

@@ -0,0 +1,66 @@
+module IIIF
+  module V3
+    module Presentation
+      class Sequence < IIIF::V3::AbstractResource
+
+        TYPE = 'Sequence'.freeze
+
+        # NOTE:  relaxing requirement for items as Universal Viewer currently only accepts canvases
+        #  see https://github.com/sul-dlss/osullivan/issues/27, sul-dlss/purl/issues/167
+        # def required_keys
+        #   super + %w{ items }
+        # end
+
+        def prohibited_keys
+          super + CONTENT_RESOURCE_PROPERTIES + PAGING_PROPERTIES + %w{ nav_date content_annotations }
+        end
+
+        # NOTE: allowing 'items' or 'canvases' as Universal Viewer currently only accepts canvases
+        #  see https://github.com/sul-dlss/osullivan/issues/27, sul-dlss/purl/issues/167
+        def array_only_keys
+          super + %w{ canvases }
+        end
+
+        def legal_viewing_hint_values
+          %w{ individuals paged continuous auto-advance }
+        end
+
+        def initialize(hsh={})
+          hsh['type'] = TYPE unless hsh.has_key? 'type'
+          super(hsh)
+        end
+
+        def validate
+          super
+
+          # Canvas object list
+          # NOTE: allowing 'items' or 'canvases' as Universal Viewer currently only accepts canvases
+          #  see https://github.com/sul-dlss/osullivan/issues/27, sul-dlss/purl/issues/167
+          unless (self['items'] && self['items'].any?) ||
+              (self['canvases'] && self['canvases'].any?)
+            m = 'The (items or canvases) list must have at least one entry (and it must be a IIIF::V3::Presentation::Canvas)'
+            raise IIIF::V3::Presentation::MissingRequiredKeyError, m
+          end
+          validate_canvas_list(self['items']) if self['items']
+          validate_canvas_list(self['canvases']) if self['canvases']
+
+          # TODO: startCanvas: A link from a Sequence or Range to a Canvas that is contained within it
+
+          # TODO: All external Sequences must have a dereference-able http(s) URI
+        end
+
+        def validate_canvas_list(canvas_array)
+          unless canvas_array.size >= 1
+            m = 'The (items or canvases) list must have at least one entry (and it must be a IIIF::V3::Presentation::Canvas)'
+            raise IIIF::V3::Presentation::MissingRequiredKeyError, m
+          end
+
+          unless canvas_array.all? { |entry| entry.instance_of?(IIIF::V3::Presentation::Canvas) }
+            m = 'All entries in the (items or canvases) list must be a IIIF::V3::Presentation::Canvas'
+            raise IIIF::V3::Presentation::IllegalValueError, m
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iiif/v3/presentation/service.rb

@@ -0,0 +1,51 @@
+module IIIF
+  module V3
+    module Presentation
+      # See http://prezi3.iiif.io/api/annex/services for more info
+      class Service < AbstractResource
+
+        # constants included here for convenience
+        IIIF_IMAGE_V2_TYPE = 'ImageService2'.freeze
+        IIIF_IMAGE_V2_LEVEL1_PROFILE = 'http://iiif.io/api/image/2/level1.json'.freeze
+        IIIF_AUTHENTICATION_V1_LOGIN_PROFILE = 'http://iiif.io/api/auth/1/login'.freeze
+        IIIF_AUTHENTICATION_V1_TOKEN_PROFILE = 'http://iiif.io/api/auth/1/token'.freeze
+
+        # service class doesn't require type
+        def required_keys
+          super.reject {|el| el == 'type' }
+        end
+
+        def prohibited_keys
+          super + CONTENT_RESOURCE_PROPERTIES + PAGING_PROPERTIES +
+            %w{ nav_date viewing_direction start_canvas content_annotations }
+        end
+
+        def uri_only_keys
+          super + %w{ @context id @id }
+        end
+
+        def any_type_keys
+          super + %w{ profile }
+        end
+
+        def validate
+          super
+          if IIIF_IMAGE_V2_TYPE == self['type'] || IIIF_IMAGE_V2_TYPE == self['@type']
+            unless self.has_key?('id') || self.has_key?('@id')
+              m = "id or @id values are required for IIIF::V3::Presentation::Service with type or @type #{IIIF_IMAGE_V2_TYPE}"
+              raise IIIF::V3::Presentation::MissingRequiredKeyError, m
+            end
+            if self.has_key?('id') && self.has_key?('@id') && (self['@id'] != self['id'])
+              m = "id and @id values must match for IIIF::V3::Presentation::Service with type or @type #{IIIF_IMAGE_V2_TYPE}"
+              raise IIIF::V3::Presentation::IllegalValueError, m
+            end
+            unless self.has_key?('profile')
+              m = "profile should be present for IIIF::V3::Presentation::Service with type or @type #{IIIF_IMAGE_V2_TYPE}"
+              raise IIIF::V3::Presentation::MissingRequiredKeyError, m
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iiif/v3/presentation.rb

@@ -0,0 +1,36 @@
+require_relative 'abstract_resource'
+require_relative '../ordered_hash'
+
+# NOTE: image_resource must follow resource due to inheritance
+# NOTE: range must follow sequence due to inheritance
+%w{
+  annotation
+  annotation_collection
+  annotation_page
+  canvas
+  choice
+  collection
+  manifest
+  resource
+  image_resource
+  sequence
+  range
+  service
+}.each do |f|
+  require File.join(File.dirname(__FILE__), 'presentation', f)
+end
+
+module IIIF
+  module V3
+    module Presentation
+      CONTEXT ||= [
+       'http://www.w3.org/ns/anno.jsonld',
+       'http://iiif.io/api/presentation/3/context.json'
+      ]
+
+      class MissingRequiredKeyError < StandardError; end
+      class ProhibitedKeyError < StandardError; end
+      class IllegalValueError < StandardError; end
+    end
+  end
+end