IIIFManifest

Code: CircleCI Coverage Status

Docs: Contribution Guidelines Apache 2.0 License

Community Support: Samvera Community Slack

What is IIIFManifest

IIIF http://iiif.io/ defines an API for presenting related images in a viewer. This transforms Hydra::Works objects into that format usable by players such as http://universalviewer.io/

Product Owner & Maintenance

iiif_manifest is a Core Component of the Samvera Community. The documentation for what this means can be found here.

Product Owner

kdid

Usage

Your application must have an object that implements #file_set_presenters and #work_presenters. The former method should return as set of leaf nodes and the later any interstitial nodes. If none are found an empty array should be returned.

Additionally, it must have a #description method that returns a string.

Additionally it should implement #manifest_url that shows where the manifest can be found.

Additionally it should implement #manifest_metadata to provide an array containing hashes of metadata Label/Value pairs.

Additionally it may implement #search_service to contain the url for a IIIF search api compliant search endpoint and #autocomplete_service to contain the url for a IIIF search api compliant autocomplete endpoint. Please note, the autocomplete service is embedded within the search service description so if an autocomplete_service is supplied without a search_service it will be ignored. The IIIF profile added to the service descriptions is version 0 as this is the version supported by the current version of Universal Viewer. Only include a search_service within the manifest if your application has implemented a IIIF search service at the endpoint specified in the manifest.

Additionally it may implement #service to contain an array of hashes for services other than search_service or autocomplete_service. Each must contain "@id" (V2) or "id" (V3) and "@context" (V2) or "type" (V3) and may contain any other arbitrary properties.

Additionally it may implement #sequence_rendering to contain an array of hashes for file downloads to be offered at sequences level. Each hash must contain "@id", "format" (mime type) and "label" (eg. { "@id" => "download url", "format" => "application/pdf", "label" => "user friendly label" }).

Finally, it may implement ranges, which returns an array of objects which represent a table of contents or similar structure, each of which responds to label, ranges, and file_set_presenters.

For example:

  class Book
    def initialize(id, pages = [])
      @id = id
      @pages = pages
    end

    def file_set_presenters
      @pages
    end

    def work_presenters
      []
    end

    def manifest_url
      "http://test.host/books/#{@id}/manifest"
    end

    def description
      'a brief description'
    end

    def manifest_metadata
          [
            { "label" => "Title", "value" => "Title of the Item" },
            { "label" => "Creator", "value" => "Morrissey, Stephen Patrick" }
          ]
    end

    def search_service
      "http://test.host/books/#{@id}/search"
    end

    def autocomplete_service
      "http://test.host/books/#{@id}/autocomplete"
    end

    def service
      [
        {
          "@context" => "http://iiif.io/api/annext/services/example/context.json",
          "@id" => "https://example.org/service",
          "profile" => "https://example.org/docs/service"
        }
      ]
    end

    def sequence_rendering
      [{"@id" => "http://test.host/file_set/id/download", "format" => "application/pdf", "label" => "Download"}]
    end

    def ranges
      [
        ManifestRange.new(
          label: "Table of Contents",
          ranges: [
            ManifestRange.new(
              label: "Chapter 1",
              file_set_presenters: @pages
            )
          ]
        )
      ]
    end
  end

  class ManifestRange
    attr_reader :label, :ranges, :file_set_presenters
    def initialize(label:, ranges: [], file_set_presenters: [])
      @label = label
      @ranges = ranges
      @file_set_presenters = file_set_presenters
    end
  end

The class that represents the leaf nodes, must implement #id. It must also implement #display_image which returns an instance of IIIFManifest::DisplayImage

In Presentation 3.0, additionally it may implement;

  • #item_metadata to contain an array of hashes for metadata to be displayed at each leaf node. Items must contain "label" and "value" properties.
  • #sequence_rendering to contain an array of hashes for file downloads to be offered at each leaf node. This follows a similar format as #sequence_rendering at sequences level
  • #see_also to contain an array of hashes for related resources to be offered at each leaf node. Items must contain "id" and "type" properties. Items should contain "label", "format", and "profile" properties.
  • #part_of to contain an array of hashes for parent resources to be offered at each leaf node. Items must contain "id" and "type" properties. Items should contain "label".
  • #homepage to contain an array of hashes for homepage resources to be offered at each leaf node. Items must contain "id", "type", and "label" properties. Items should contain a "format" property and may contain a "language" property.
  • #placeholder_content to contain an instance of IIIFManifest::V3::DisplayContent for placeholderCanvas at each leaf node
  • #service to contain an array of hashes for services. Each must contain "id" and "type" and may contain any other arbitrary properties.
  class Page
    def initialize(id)
      @id = id
    end

    def id
      @id
    end

    def display_image
      IIIFManifest::DisplayImage.new(id,
                                     width: 100,
                                     height: 100,
                                     format: "image/jpeg",
                                     iiif_endpoint: endpoint
                                     )
    end

    # --------------------------------------- Presentation 3.0 ---------------------------------------
    def sequence_rendering
      [{"@id" => "http://test.host/display_image/id/download", "format" => "application/pdf", "label" => "Download"}]
    end

    def see_also
      [{"id" => "http://test.host/display_image/id/image.json", "type" => "dataset", "format" => "application/json", "label" => "Related Resource"}]
    end

    def part_of
      [{"id" => "http://test.host/display_image/id/parent.json", "type" => "manifest"}]
    end

    def homepage
      [{"id" => "http://test.host/display_image/id/homepage", "type" => "Text", "label" => "Item Homepage"}]
    end

    def placeholder_content
      IIIFManifest::V3::DisplayContent.new(id,
                                           width: 100,
                                           height: 100,
                                           type: "Image",
                                           format: "image/jpeg")
    end

    def service
      [
        {
          "@context" => "http://iiif.io/api/annext/services/example/context.json",
          "@id" => "https://example.org/service",
          "profile" => "https://example.org/docs/service"
        }
      ]
    end
    # --------------------------------------- Presentation 3.0 ---------------------------------------

    private

      def endpoint
        IIIFManifest::IIIFEndpoint.new("http://test.host/images/#{id}",
                                       profile: "http://iiif.io/api/image/2/level2.json")
      end
  end

Then you can produce the manifest on the book object like this:

  book = Book.new('book-77',[Page.new('page-99')])
  IIIFManifest::ManifestFactory.new(book).to_h.to_json

Presentation 3.0

Provisional support for the 3.0 version of the IIIF presentation api spec has been added with a focus on audiovisual content. The change log lists the changes to the specification.

The presentation 3.0 support has been contained to the V3 namespace. Version 2.0 manifests are still being built using IIIFManifest::ManifestFactory while version 3.0 manifests can now be built using IIIFManifest::V3::ManifestFactory.

  book = Book.new('book-77',[Page.new('page-99')])
  IIIFManifest::V3::ManifestFactory.new(book).to_h.to_json

Notable changes for Presentation 3.0

  • Presenters must still define #description but it is now serialized as summary. (https://iiif.io/api/presentation/3.0/change-log/#126-rename-description-to-summary)
  • All textual strings, including metadata labels and values, are now serialized as language maps and may be provided as a hash with language code keys with string values. Values not provided in this format are automatically converted so no change to #description, #manifest_metadata, range labels, or other fields are required. (https://iiif.io/api/presentation/3.0/change-log/#133-use-language-map-pattern-for-label-value-summary)
  • Presenters may implement #homepage to contain a hash for linking back to a repository webpage for this manifest. The hash must contain "id", "format" (mime type), "type", and "label" (eg. { "id" => "repository url", "format" => "text/html", "type" => "Text", "label" => { "en": ["View in repository"] }).
  • File set presenters may target a fragment of its content by providing #media_fragment which will be appended to its id.
  • Range objects may now implement #items instead of #ranges and #file_set_presenters to allow for interleaving these objects. #items is not required and existing range objects should continue to work.
  • File set presenters may provide,
    • #display_content which should return an instance of IIIFManifest::V3::DisplayContent (or an array of instances in the case of a user Choice)
    • #annotation_content which should return an instance of IIIFManifest::V3::AnnotationContent (or an array of instances in the case of a canvas having multiple annotations)
    • #display_image is no longer required but will still work if provided
    • #sequence_rendering is supported at leaf node level, to present an array of file downloads available at each leaf node
    • #part_of is supported at leaf node level, to present an array of parent resources available at each leaf node.
    • #homepage is supported at leaf node level, to present an array of homepage resources available at each leaf node.
    • #placeholder_content which returns an instance of IIIFManifest::V3::DisplayContent presents a placeholderCanvas at leaf node level
  • DisplayContent may provide #auth_service which should return a hash containing a IIIF Authentication service definition (https://iiif.io/api/auth/1.0/) that will be included on the content resource.

Configuration

The label, rights, homepage, description (V2 only), and summary (V3 only) properties can be configured to pull its information from different attributes.

NOTE: In the V2 manifest, label and description is expected to be a string so if the model's attribute is multivalued, only the first value would be used.

To enable this, add the following code to a config file at config/initializers/iiif_manifest_config.rb in your application.

  # Example: use the default configuration but amend the summary property
  IIIFManifest.config do |config|
    config.manifest_property_to_record_method_name_map.merge!(summary: :abstract, rights: :license)
  end

In the above example of a V3 manifest (since it is a summary instead of description), the summary property will be using the model's #abstract attribute value instead of the default #description. The rights property will use the model's #license attribute instead of the default #rights_statement. All other configurable properties will use their defaults.

  # Example: use this configuration to set the max edge length of thumbnails, default is 200
   IIIFManifest.confg do |config|
     config.max_edge_for_thumbnail = 100
   end

Thumbnails have been added for version 3 manifests because Universal Viewer currently require them to be explicitly set otherwise they would not show up. The above example is used to configure what the default size for the thumbnails would be.

# Example: use this configuration to disable thumbnails to show up by default on the manifest level (version 3 only)
  IIIFManifest.confg do |config|
    config.manifest_thumbnail = false
  end

According to the Presentation API 3.0 specifications:

A Manifest SHOULD have the thumbnail property with at least one item.

The above configuration allows you to disable that if desired since it is not a MUST.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/samvera-labs/iiif_manifest. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

If you're working on PR for this project, create a feature branch off of main.

This repository follows the Samvera Community Code of Conduct and language recommendations. Please do not create a branch called master for this repository or as part of your pull request; the branch will either need to be removed or renamed before it can be considered for inclusion in the code base and history of this repository.

Help

The Samvera community is here to help. Please see our support guide.

Acknowledgments

This software has been developed by and is brought to you by the Samvera community. Learn more at the Samvera website.

Samvera Logo