iiif_print 1.0.0

data/lib/iiif_print/engine.rb

@@ -0,0 +1,77 @@
+require 'active_fedora'
+require 'hyrax'
+require 'blacklight_iiif_search'
+
+module IiifPrint
+  # module constants:
+  GEM_PATH = Gem::Specification.find_by_name("iiif_print").gem_dir
+
+  # Engine Class
+  class Engine < ::Rails::Engine
+    isolate_namespace IiifPrint
+
+    # rubocop:disable Metrics/BlockLength
+    config.to_prepare do
+      # We don't have a hard requirement of Bullkrax but in our experience, lingering on earlier
+      # versions can introduce bugs of both Bulkrax and some of the assumptions that we've resolved.
+      # Very early versions of Bulkrax do not have VERSION defined
+      if defined?(Bulkrax) && !ENV.fetch("SKIP_IIIF_PRINT_BULKRAX_VERSION_REQUIREMENT", false)
+        if !defined?(Bulkrax::VERSION) || (Bulkrax::VERSION.to_i < 5)
+          raise "IiifPrint does not have a hard dependency on Bulkrax, " \
+                "but if you have Bulkrax installed we recommend at least version 5.0.0.  " \
+                "To ignore this recommendation please add SKIP_IIIF_PRINT_BULKRAX_VERSION_REQUIREMENT " \
+                "to your ENV variables."
+        end
+      end
+
+      # Inject PluggableDerivativeService ahead of Hyrax default.
+      #   This wraps Hyrax default, but allows multiple valid services
+      #   to be configured, instead of just the _first_ valid service.
+      #
+      #   To configure specific services, inject each service, in desired order
+      #   to IiifPrint::PluggableDerivativeService.plugins array.
+
+      Hyrax::DerivativeService.services.unshift(
+        IiifPrint::PluggableDerivativeService
+      )
+
+      Hyrax::IiifManifestPresenter.prepend(IiifPrint::IiifManifestPresenterBehavior)
+      Hyrax::IiifManifestPresenter::Factory.prepend(IiifPrint::IiifManifestPresenterFactoryBehavior)
+      Hyrax::ManifestBuilderService.prepend(IiifPrint::ManifestBuilderServiceBehavior)
+      Hyrax::Renderers::FacetedAttributeRenderer.prepend(Hyrax::Renderers::FacetedAttributeRendererDecorator)
+      Hyrax::WorksControllerBehavior.prepend(IiifPrint::WorksControllerBehaviorDecorator)
+      Hyrax::WorkShowPresenter.prepend(IiifPrint::WorkShowPresenterDecorator)
+
+      IiifPrint::ChildIndexer.decorate_work_types!
+      IiifPrint::FileSetIndexer.decorate(Hyrax::FileSetIndexer)
+
+      ::BlacklightIiifSearch::IiifSearchResponse.prepend(IiifPrint::IiifSearchResponseDecorator)
+      ::BlacklightIiifSearch::IiifSearchAnnotation.prepend(IiifPrint::BlacklightIiifSearch::AnnotationDecorator)
+      Hyrax::Actors::FileSetActor.prepend(IiifPrint::Actors::FileSetActorDecorator)
+
+      # Extending the presenter to the base url which includes the protocol.
+      # We need the base url to render the facet links and normalize the interface.
+      Hyrax::IiifManifestPresenter.send(:attr_accessor, :base_url)
+      Hyrax::IiifManifestPresenter::DisplayImagePresenter.send(:attr_accessor, :base_url)
+      # Extending this class because there is an #ability= but not #ability and this definition
+      # mirrors the Hyrax::IiifManifestPresenter#ability.
+      module Hyrax::IiifManifestPresenter::DisplayImagePresenterDecorator
+        def ability
+          @ability ||= NullAbility.new
+        end
+      end
+      Hyrax::IiifManifestPresenter::DisplayImagePresenter.prepend(Hyrax::IiifManifestPresenter::DisplayImagePresenterDecorator)
+
+      Hyrax.config do |config|
+        config.callback.set(:after_create_fileset) do |file_set, user|
+          IiifPrint.config.handle_after_create_fileset(file_set, user)
+        end
+      end
+    end
+
+    config.after_initialize do
+      IiifPrint::Solr::Document.decorate(SolrDocument)
+    end
+    # rubocop:enable Metrics/BlockLength
+  end
+end

data/lib/iiif_print/errors.rb

@@ -0,0 +1,9 @@
+module IiifPrint
+  # generic/base IiifPrint-specific exception:
+  class IiifPrintError < StandardError
+  end
+
+  # Data transformation or read-error:
+  class DataError < IiifPrintError
+  end
+end

data/lib/iiif_print/image_tool.rb

@@ -0,0 +1,119 @@
+require 'open3'
+require 'tmpdir'
+
+module IiifPrint
+  class ImageTool
+    attr_accessor :path, :ftype
+
+    def initialize(path)
+      @path = path
+      @ftype = magic
+      @metadata = nil
+    end
+
+    # @return [Hash] hash with following symbol keys, and respectively
+    #   typed String and/or Integer values.
+    #   :width, :height — both in Integer px units
+    #   :color — (String enumerated from 'gray', 'monochrome', 'color')
+    #   :num_components - Integer, number of channels
+    #   :bits_per_component — Integer, bits per channel (e.g. 8 vs. 1)
+    #   :content_type — RFC 2045 MIME type
+    def metadata
+      return @metadata unless @metadata.nil?
+      @metadata = jp2? ? jp2_metadata : identify_metadata
+    end
+
+    # Convert source image to image at destination path, inferring file type
+    #   from destination file extension.  In case of JP2 files, create
+    #   intermediate file using OpenJPEG 2000 that ImageMagick can use.
+    #   Only outputs monochrome output if monochrome is true, destination
+    #   format is TIFF.
+    # @param destination [String] Path to output / destination file
+    # @param monochrome [Boolean] true if monochrome output, otherwise false
+    def convert(destination, monochrome = false)
+      raise 'JP2 output not yet supported' if destination.end_with?('jp2')
+      return convert_image(jp2_to_tiff(@path), destination, monochrome) if jp2?
+      convert_image(@path, destination, monochrome)
+    end
+
+    private
+
+    def convert_image(source, destination, monochrome)
+      monochrome &&= destination.slice(-4, 4).index('tif')
+      mono_opts = "-depth 1 -monochrome -compress Group4 -type bilevel "
+      opts = monochrome ? mono_opts : ''
+      cmd = "convert #{source} #{opts}#{destination}"
+      `#{cmd}`
+    end
+
+    def jp2_to_tiff(source)
+      intermediate_path = File.join(Dir.mktmpdir, 'intermediate.tif')
+      jp2_cmd = "opj_decompress -i #{source} -o #{intermediate_path}"
+      `#{jp2_cmd}`
+      intermediate_path
+    end
+
+    def jp2_metadata
+      result = IiifPrint::JP2ImageMetadata.new(path).technical_metadata
+      result[:content_type] = 'image/jp2'
+      result
+    end
+
+    def im_line_select(lines, key)
+      line = lines.find { |l| l.scrub.downcase.strip.start_with?(key) }
+      # Given "key: value" line, return the value as String stripped of
+      #   leading and trailing whitespace
+      return line if line.nil?
+      line.strip.split(':')[-1].strip
+    end
+
+    # @return [Array(Integer, Integer)] width, height in Integer px units
+    def im_identify_geometry(lines)
+      img_geo = im_line_select(lines, 'geometry').split('+')[0]
+      img_geo.split('x').map(&:to_i)
+    end
+
+    # @return [Array<String>] lines of output from imagemagick `identify`
+    def im_identify
+      cmd = "identify -verbose #{path}"
+      `#{cmd}`.lines
+    end
+
+    def im_mime(lines)
+      return 'application/pdf' if pdf? # workaround older imagemagick bug
+      im_line_select(lines, 'mime type')
+    end
+
+    def populate_im_color!(lines, result)
+      bpc = im_line_select(lines, 'depth').split('-')[0].to_i # '1-bit' -> 1
+      colorspace = im_line_select(lines, 'colorspace')
+      color = colorspace == 'Gray' ? 'gray' : 'color'
+      has_alpha = !im_line_select(lines, 'Alpha').nil?
+      result[:num_components] = (color == 'gray' ? 1 : 3) + (has_alpha ? 1 : 0)
+      result[:color] = bpc == 1 ? 'monochrome' : color
+      result[:bits_per_component] = bpc
+    end
+
+    # Return metadata by means of imagemagick identify
+    def identify_metadata
+      result = {}
+      lines = im_identify
+      result[:width], result[:height] = im_identify_geometry(lines)
+      result[:content_type] = im_mime(lines)
+      populate_im_color!(lines, result)
+      result
+    end
+
+    def magic
+      File.read(@path, 23, 0)
+    end
+
+    def jp2?
+      @ftype.end_with?('ftypjp2')
+    end
+
+    def pdf?
+      magic.start_with?('%PDF-')
+    end
+  end
+end

data/lib/iiif_print/jobs/application_job.rb

@@ -0,0 +1,8 @@
+module IiifPrint
+  module Jobs
+    # TODO: Consider inheriting from ::Application job.  That means we would have the upstreams
+    # based job behavior.
+    class ApplicationJob < ActiveJob::Base
+    end
+  end
+end

data/lib/iiif_print/jobs/child_works_from_pdf_job.rb

@@ -0,0 +1,107 @@
+module IiifPrint
+  module Jobs
+    class ChildWorksFromPdfJob < IiifPrint::Jobs::ApplicationJob
+      # Break a pdf into individual pages
+      # @param parent_work
+      # @param pdf_paths: [<Array => String>] paths to pdfs
+      # @param user: [User]
+      # @param admin_set_id: [<String>]
+      # @param prior_pdfs: [<Integer>] count of pdfs already on parent work
+      def perform(parent_work, pdf_paths, user, admin_set_id, prior_pdfs)
+        @parent_work = parent_work
+        @child_admin_set_id = admin_set_id
+        child_model = @parent_work.iiif_print_config.pdf_split_child_model
+
+        # handle each input pdf
+        pdf_paths.each_with_index do |path, pdf_idx|
+          split_pdf(path, pdf_idx, user, prior_pdfs, child_model)
+        end
+
+        # Link newly created child works to the parent
+        # @param user: [User] user
+        # @param parent_id: [<String>] parent work id
+        # @param parent_model: [<String>] parent model
+        # @param child_model: [<String>] child model
+        IiifPrint::Jobs::CreateRelationshipsJob.set(wait: 10.minutes).perform_later(
+          user: user,
+          parent_id: @parent_work.id,
+          parent_model: @parent_work.class.to_s,
+          child_model: child_model.to_s
+        )
+
+        # TODO: clean up image_files and pdf_paths
+      end
+
+      private
+
+      def split_pdf(path, pdf_idx, user, prior_pdfs_count, child_model)
+        image_files = @parent_work.iiif_print_config.pdf_splitter_service.new(path).to_a
+        return if image_files.blank?
+
+        pdf_sequence = pdf_idx + prior_pdfs_count
+        prepare_import_data(pdf_sequence, image_files, user)
+
+        # submit the job to create all the child works for one PDF
+        # @param [User] user
+        # @param [Hash<String => String>] titles
+        # @param [Hash<String => String>] resource_types (optional)
+        # @param [Array<String>] uploaded_files Hyrax::UploadedFile IDs
+        # @param [Hash] attributes attributes to apply to all works, including :model
+        # @param [Hyrax::BatchCreateOperation] operation
+        operation = Hyrax::BatchCreateOperation.create!(
+          user: user,
+          operation_type: "PDF Batch Create"
+        )
+        BatchCreateJob.perform_later(user,
+                                     @child_work_titles,
+                                     {},
+                                     @uploaded_files,
+                                     attributes.merge!(model: child_model.to_s).with_indifferent_access,
+                                     operation)
+      end
+
+      def prepare_import_data(pdf_sequence, image_files, user)
+        @uploaded_files = []
+        @child_work_titles = {}
+        image_files.each_with_index do |image_path, idx|
+          file_id = create_uploaded_file(user, image_path).to_s
+          file_title = set_title(@parent_work.title.first, pdf_sequence, idx)
+          @uploaded_files << file_id
+          @child_work_titles[file_id] = file_title
+          # save child work info to create the member relationships
+          PendingRelationship.create!(child_title: file_title,
+                                      parent_id: @parent_work.id,
+                                      child_order: sort_order(pdf_sequence, idx))
+        end
+      end
+
+      def sort_order(pdf_sequence, idx)
+        "#{pdf_sequence} #{idx}"
+      end
+
+      def create_uploaded_file(user, path)
+        uf = Hyrax::UploadedFile.new
+        uf.user_id = user.id
+        uf.file = CarrierWave::SanitizedFile.new(path)
+        uf.save!
+        uf.id
+      end
+
+      def set_title(title, pdf_sequence, idx)
+        pdf_index = "Pdf Nbr #{pdf_sequence + 1}"
+        page_number = "Page #{idx + 1}"
+        "#{title}: #{pdf_index}, #{page_number}"
+      end
+
+      # TODO: what attributes do we need to fill in from the parent work? What about AllinsonFlex?
+      def attributes
+        {
+          admin_set_id: @child_admin_set_id.to_s,
+          creator: @parent_work.creator.to_a,
+          rights_statement: @parent_work.rights_statement.to_a,
+          visibility: @parent_work.visibility.to_s
+        }
+      end
+    end
+  end
+end

data/lib/iiif_print/jobs/create_relationships_job.rb

@@ -0,0 +1,78 @@
+module IiifPrint
+  module Jobs
+    # Break a pdf into individual pages
+    class CreateRelationshipsJob < IiifPrint::Jobs::ApplicationJob
+      # Link newly created child works to the parent
+      # @param user: [User] user
+      # @param parent_id: [<String>] parent work id
+      # @param parent_model: [<String>] parent model
+      # @param child_model: [<String>] child model
+      def perform(user:, parent_id:, parent_model:, child_model:)
+        if completed_child_data_for(parent_id, child_model)
+          # add the members
+          parent_work = parent_model.constantize.find(parent_id)
+          create_relationships(user: user, parent: parent_work, ordered_children: @child_works)
+          @pending_children.each(&:destroy)
+        else
+          # reschedule the job and end this one normally
+          #
+          # TODO: Depending on how things shake out, we could be infinitely rescheduling this job.
+          # Consider a time to live parameter.
+          reschedule(user: user, parent_id: parent_id, parent_model: parent_model, child_model: child_model)
+        end
+      end
+
+      private
+
+      # load @child_works, and return true or false
+      def completed_child_data_for(parent_id, child_model)
+        @child_works = []
+        found_all_children = true
+
+        # find and sequence all pending children
+        @pending_children = IiifPrint::PendingRelationship.where(parent_id: parent_id).order('child_order asc')
+
+        # find child works (skip out if any haven't yet been created)
+        @pending_children.each do |child|
+          # find by title... if any aren't found, the child works are not yet ready
+          found_children = find_children_by_title_for(child.child_title, child_model)
+          found_all_children = false if found_children.empty?
+          break unless found_all_children == true
+          @child_works += found_children
+        end
+        # return boolean
+        found_all_children
+      end
+
+      def find_children_by_title_for(title, model)
+        # We should only find one, but there is no guarantee of that and `:where` returns an array.
+        model.constantize.where(title: title)
+      end
+
+      def reschedule(user:, parent_id:, parent_model:, child_model:)
+        CreateRelationshipsJob.set(wait: 10.minutes).perform_later(
+          user: user,
+          parent_id: parent_id,
+          parent_model: parent_model,
+          child_model: child_model
+        )
+      end
+
+      def create_relationships(user:, parent:, ordered_children:)
+        records_hash = {}
+        ordered_children.map(&:id).each_with_index do |child_id, i|
+          records_hash[i.to_s] = { id: child_id }
+        end
+        attrs = { work_members_attributes: records_hash }
+        parent.try(:reindex_extent=, Hyrax::Adapters::NestingIndexAdapter::LIMITED_REINDEX)
+        env = Hyrax::Actors::Environment.new(parent, Ability.new(user), attrs)
+
+        Hyrax::CurationConcern.actor.update(env)
+        # need to reindex all file_sets to make all ancestors are indexed
+        ordered_children.each do |child_work|
+          child_work.file_sets.each(&:update_index) if child_work.respond_to?(:file_sets)
+        end
+      end
+    end
+  end
+end

data/lib/iiif_print/jp2_derivative_service.rb

@@ -0,0 +1,118 @@
+require 'open3'
+
+module IiifPrint
+  class JP2DerivativeService < BaseDerivativeService
+    # OpenJPEG 2000 Command to make NDNP-compliant grayscale JP2:
+    CMD_GRAY = 'opj_compress -i %<source_file>s -o %<out_file>s ' \
+              '-d 0,0 -b 64,64 -n 6 -p RLCP -t 1024,1024 -I -M 1 ' \
+              '-r 64,53.821,45.249,40,32,26.911,22.630,20,16,14.286,' \
+              '11.364,10,8,6.667,5.556,4.762,4,3.333,2.857,2.500,2,' \
+              '1.667,1.429,1.190,1'.freeze
+
+    # OpenJPEG 2000 Command to make RGB JP2:
+    CMD_COLOR = 'opj_compress -i %<source_file>s -o %<out_file>s ' \
+                '-d 0,0 -b 64,64 -n 6 -p RPCL -t 1024,1024 -I -M 1 '\
+                '-r 2.4,1.48331273,.91673033,.56657224,.35016049,.21641118,' \
+                '.13374944,.0944,.08266171'.freeze
+
+    # OpenJPEG 1.x command replacement for 2.x opj_compress, takes same options;
+    #   this is necessary on Ubuntu Trusty (e.g. Travis CI)
+    CMD_1X = 'image_to_j2k'.freeze
+
+    # Target file extension of this service plugin:
+    self.target_extension = 'jp2'.freeze
+
+    attr_reader :file_set
+    delegate :uri, :mime_type, to: :file_set
+
+    def initialize(file_set)
+      # cached result string for imagemagick `identify` command
+      @command = nil
+      @unlink_after_creation = []
+      super(file_set)
+    end
+
+    def create_derivatives(filename)
+      # Base class takes care of loading @source_path, @dest_path
+      super(filename)
+
+      # no creation if jp2 master => deemed unnecessary/duplicative
+      return if mime_type == 'image/jp2'
+
+      # if we have a non-TIFF source, or a 1-bit monochrome source, we need
+      #   to make a NetPBM-based intermediate (temporary) file for OpenJPEG
+      #   to consume.
+      needs_intermediate = !tiff_source? || one_bit?
+
+      # We use either intermediate temp file, or temp symlink (to work
+      #   around OpenJPEG 2000 file naming quirk).
+      needs_intermediate ? make_intermediate_source : make_symlink
+
+      # Get OpenJPEG command, rendered with source, destination, appropriate
+      #   to either color or grayscale source
+      render_cmd = opj_command
+
+      # Run the generated command to make derivative file at @dest_path
+      `#{render_cmd}`
+
+      # Clean up any intermediate files or symlinks used during creation
+      cleanup_intermediate
+    end
+
+    private
+
+    # source introspection:
+
+    def tiff_source?
+      identify[:content_type] == 'image/tiff'
+    end
+
+    def make_symlink
+      # OpenJPEG binaries have annoying quirk of only using TIFF input
+      #   files whose name ends in .TIF or .tif (three letter); for all
+      #   non-monochrome TIFF files, we just assume we need to symlink
+      #   to such a filename.
+      tmpname = File.join(Dir.tmpdir, "#{SecureRandom.uuid}.tif")
+      FileUtils.ln_s(@source_path, tmpname)
+      @unlink_after_creation.push(tmpname)
+      # finally, point @source_path for command at intermediate link:
+      @source_path = tmpname
+    end
+
+    def make_intermediate_source
+      # generate a random filename to be made, with appropriate extension,
+      #   inside /tmp dir:
+      tmpname = File.join(
+        Dir.tmpdir,
+        format(
+          "#{SecureRandom.uuid}.%<ext>s",
+          ext: use_color? ? 'ppm' : 'pgm'
+        )
+      )
+      # if pdf source, get only first page
+      source_path = @source_path
+      source_path += '[0]' if @source_path.ends_with?('pdf')
+      # Use ImageMagick `convert` to create intermediate bitmap:
+      `convert #{source_path} #{tmpname}`
+      @unlink_after_creation.push(tmpname)
+      # finally, point @source_path for command at intermediate file:
+      @source_path = tmpname
+    end
+
+    def opj_command
+      # Get a command template appropriate to OpenJPEG 1.x or 2.x
+      use_openjpeg_1x = `which opj_compress`.empty?
+      cmd = use_color? ? CMD_COLOR : CMD_GRAY
+      cmd = cmd.sub('opj_compress', 'image_to_j2k') if use_openjpeg_1x
+      # return command with source and destination file names injected
+      format(cmd, source_file: @source_path, out_file: @dest_path)
+    end
+
+    def cleanup_intermediate
+      # remove symlink or intermediate file once we no longer need
+      @unlink_after_creation.each do |path|
+        FileUtils.rm(path)
+      end
+    end
+  end
+end

data/lib/iiif_print/jp2_image_metadata.rb

@@ -0,0 +1,81 @@
+module IiifPrint
+  class JP2ImageMetadata
+    TOKEN_MARKER_START = "\xFF".force_encoding("BINARY").freeze
+    TOKEN_MARKER_SIZ = "\x51".force_encoding("BINARY").freeze
+    TOKEN_IHDR = 'ihdr'.freeze
+
+    attr_accessor :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    # @param io [IO] IO stream opened in binary mode, for reading
+    # @return [Array(Integer, Integer)] X size, Y size, in Integer-typed px
+    def extract_jp2_dim(io)
+      raise IOError, 'file not open in binary mode' unless io.binmode?
+      buffer = ''
+      siz_found = false
+      # Informed by ISO/IEC 15444-1:2000, pp. 26-27
+      #   via:
+      #   http://hosting.astro.cornell.edu/~carcich/LRO/jp2/ISO_JPEG200_Standard/INCITS+ISO+IEC+15444-1-2000.pdf
+      #
+      # first 23 bytes are file-magic, we can skip
+      io.seek(23, IO::SEEK_SET)
+      while !siz_found && !buffer.nil?
+        # read one byte at a time, until we hit marker start 0xFF
+        buffer = io.read(1) while buffer != TOKEN_MARKER_START
+        # - on 0xFF read subsequent byte; if value != 0x51, continue
+        buffer = io.read(1)
+        next if buffer != TOKEN_MARKER_SIZ
+        # - on 0x51, read next 12 bytes
+        buffer = io.read(12)
+        siz_found = true
+      end
+      # discard first 4 bytes; next 4 bytes are XSiz; last 4 bytes are YSiz
+      x_siz = buffer.byteslice(4, 4).unpack('N').first
+      y_siz = buffer.byteslice(8, 4).unpack('N').first
+      [x_siz, y_siz]
+    end
+
+    # @param io [IO] IO stream opened in binary mode, for reading
+    # @return [Array(Integer, Integer)] number components, bits-per-component
+    def extract_jp2_components(io)
+      raise IOError, 'file not open in binary mode' unless io.binmode?
+      io.seek(0, IO::SEEK_SET)
+      # IHDR should be in first 64 bytes
+      buffer = io.read(64)
+      ihdr_data = buffer.split(TOKEN_IHDR)[-1]
+      raise IOError if ihdr_data.nil?
+      num_components = ihdr_data.byteslice(8, 2).unpack('n').first
+      # stored as "bit depth of the components in the codestream, minus 1", so add 1
+      bits_per_component = ihdr_data.byteslice(10, 1).unpack('c').first + 1
+      [num_components, bits_per_component]
+    end
+
+    def validate_jp2(io)
+      # verify file is jp2
+      magic = io.read(23)
+      raise IOError, 'Not JP2 file' unless magic.end_with?('ftypjp2')
+    end
+
+    # @param path [String] path to jp2, for reading
+    # @return [Hash] hash
+    def technical_metadata
+      io = File.open(path, 'rb')
+      io.seek(0, IO::SEEK_SET)
+      validate_jp2(io)
+      x_siz, y_siz = extract_jp2_dim(io)
+      nc, bpc = extract_jp2_components(io)
+      color = nc >= 3 ? 'color' : 'gray'
+      io.close
+      {
+        color: bpc == 1 ? 'monochrome' : color,
+        num_components: nc,
+        bits_per_component: bpc,
+        width: x_siz,
+        height: y_siz
+      }
+    end
+  end
+end

data/lib/iiif_print/lineage_service.rb

@@ -0,0 +1,41 @@
+module IiifPrint
+  # The purpose of this module is to encode lineage related services:
+  #
+  # - {.ancestor_ids_for}
+  # - {.descendent_file_set_ids_for}
+  #
+  # The ancestor and descendent_file_sets are useful for ensuring we index together related items.
+  # For example, when I have a work that is a book, and one file set per page of that book, when I
+  # search the book I want to find the text within the given book's pages.
+  #
+  # The methods of this module should be considered as defining an interface.
+  module LineageService
+    ##
+    # @api public
+    #
+    # @param object [#in_works] An object that responds to #in_works
+    # @return [Array<String>]
+    def self.ancestor_ids_for(object)
+      ancestor_ids ||= []
+      object.in_works.each do |work|
+        ancestor_ids << work.id
+        ancestor_ids += ancestor_ids_for(work) if work.is_child
+      end
+      ancestor_ids.flatten.compact.uniq
+    end
+
+    ##
+    # @param object [#ordered_works, #file_sets, #member_ids]
+    # @return [Array<String>] the ids of associated file sets
+    def self.descendent_file_set_ids_for(object)
+      # enables us to return parents when searching for child OCR
+      file_set_ids = object.file_sets.map(&:id)
+      object.ordered_works&.each do |child|
+        file_set_ids += descendent_file_set_ids_for(child)
+      end
+      # enables us to return parents when searching for child metadata
+      file_set_ids += object.member_ids
+      file_set_ids.flatten.uniq.compact
+    end
+  end
+end