mindee 3.10.0 → 3.12.0

data/lib/mindee/extraction/tax_extractor.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require_relative 'ocr_extractor'
+
+module Mindee
+  module Extraction
+    # Tax extractor class
+    class TaxExtractor < OcrExtractor
+      # Extracts the most relevant candidate.
+      # @param candidates [Array<Hash>] a candidate for the tax.
+      # @param tax_names [Array<String>] list of all possible names the tax can have.
+      # @return [Hash, nil]
+      def self.pick_best(candidates, tax_names)
+        return candidates[0] if candidates.size == 1
+        return nil if candidates.empty?
+
+        picked = 0
+        picked_score = 0
+
+        candidates.each_with_index do |candidate, i|
+          next unless valid_candidate?(candidate, tax_names)
+
+          sum_fields_score = calculate_score(candidate, i)
+
+          if picked_score < sum_fields_score
+            picked_score = sum_fields_score
+            picked = i
+          end
+        end
+
+        candidates[picked]
+      end
+
+      # Checks whether a tax code has been properly read. Shouldn't trigger except in case of very specific regex breaks
+      # due to unsupported diacritics.
+      # @param candidate [Hash] A candidate for the tax.
+      # @param tax_names [Array<String>] list of all possible names the tax can have.
+      # @return [Boolean]
+      def self.valid_candidate?(candidate, tax_names)
+        return false if tax_names.empty? || candidate.nil? || candidate['code'].nil?
+
+        tax_names.each do |tax_name|
+          return true if remove_accents(tax_name.downcase) == remove_accents(candidate['code'].downcase)
+        end
+        false
+      end
+
+      # [Experimental] computes the score of a valid candidate for a tax.
+      # @param candidate [Hash] A candidate for the tax.
+      # @param index [Integer]
+      def self.calculate_score(candidate, index)
+        score = index + 1
+        unless candidate['rate'].nil?
+          score += 1
+          score -= 2 if candidate['rate'] > 100
+          score -= 1 if candidate['rate'] > 30
+        end
+        score += 4 unless candidate['value'].nil?
+        score += 1 unless candidate['base'].nil?
+        score
+      end
+
+      # Curates tax values based on simple rules to avoid improbable data
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @param min_rate_percentage [Integer] Minimum allowed rate on the tax.
+      # @param max_rate_percentage [Integer] Maximum allowed rate on the tax.
+      # @return [Hash]
+      def self.curate_values(found_hash, min_rate_percentage, max_rate_percentage)
+        reconstructed_hash = { 'code' => nil, 'page_id' => nil, 'rate' => nil, 'base' => nil, 'value' => nil }
+        return reconstructed_hash if found_hash.nil?
+
+        reconstructed_hash['code'] =
+          found_hash['code'].nil? ? found_hash['code'] : found_hash['code'].sub(%r{\s*\.*\s*$}, '')
+
+        if found_hash['rate'] && found_hash['rate'] < 1 && (found_hash['rate']).positive?
+          found_hash['rate'] =
+            found_hash['rate'] * 100
+        end
+        found_hash = swap_rates_if_needed(found_hash, min_rate_percentage, max_rate_percentage)
+        found_hash = decimate_rates_if_needed(found_hash)
+        found_hash = fix_rate(found_hash)
+        reconstructed_hash['rate'] = found_hash['rate']
+        set_base_and_value(reconstructed_hash, found_hash)
+      end
+
+      # Swaps the rate with base or value if rate is out of bounds
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @param min_rate_percentage [Integer] Minimum allowed rate on the tax.
+      # @param max_rate_percentage [Integer] Maximum allowed rate on the tax.
+      # @return [Hash]
+      def self.swap_rates_if_needed(found_hash, min_rate_percentage, max_rate_percentage)
+        if found_hash['rate'] && (found_hash['rate'] > max_rate_percentage || found_hash['rate'] < min_rate_percentage)
+          if valid_percentage?(found_hash['base'], min_rate_percentage, max_rate_percentage)
+            found_hash['rate'], found_hash['base'] = found_hash['base'], found_hash['rate']
+          elsif valid_percentage?(found_hash['value'], min_rate_percentage, max_rate_percentage)
+            found_hash['rate'], found_hash['value'] = found_hash['value'], found_hash['rate']
+          end
+        end
+        found_hash
+      end
+
+      # Rates can't be negative if set.
+      # @param found_hash [Hash] Hash of currently retrieved values
+      def self.fix_rate(found_hash)
+        found_hash['rate'] = found_hash['rate'].abs unless found_hash['rate'].nil?
+        found_hash
+      end
+
+      # Swaps the rate with base or value if rate is out of bounds
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @return [Hash]
+      def self.decimate_rates_if_needed(found_hash)
+        if found_hash['rate'] && found_hash['rate'] > 100
+          if !found_hash['base'].nil? && found_hash['rate'] > found_hash['base']
+            found_hash['rate'], found_hash['base'] = found_hash['base'], found_hash['rate']
+          elsif !found_hash['value'].nil? && found_hash['rate'] > found_hash['value']
+            found_hash['rate'], found_hash['value'] = found_hash['value'], found_hash['rate']
+          end
+        end
+        found_hash
+      end
+
+      # Sets the base and value in the reconstructed hash based on certain conditions
+      # @param reconstructed_hash [Hash] Hash being reconstructed with new values
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @return [Hash]
+      def self.set_base_and_value(reconstructed_hash, found_hash)
+        if found_hash['base'].nil?
+          reconstructed_hash['base'] = found_hash['base']
+          reconstructed_hash['value'] = found_hash['value']
+        elsif found_hash['value'].nil? && found_hash['base'] < found_hash['value']
+          reconstructed_hash['base'] = found_hash['value']
+          reconstructed_hash['value'] = found_hash['base']
+        else
+          reconstructed_hash['value'] = found_hash['value']
+        end
+        reconstructed_hash
+      end
+
+      # Extracts a single custom type of tax.
+      # For the sake of simplicity, this only extracts the first example, unless specifically instructed otherwise.
+      # @param ocr_result [Mindee::Parsing::Common::Ocr::Ocr] result of the OCR.
+      # @param tax_names [Array<String>] list of all possible names the tax can have.
+      # @param min_rate_percentage [Integer] Minimum allowed rate on the tax.
+      # @param max_rate_percentage [Integer] Maximum allowed rate on the tax.
+      # @return [Mindee::Parsing::Standard::TaxField, nil]
+      def self.extract_custom_tax(ocr_result, tax_names, min_rate_percentage = 0, max_rate_percentage = 100)
+        return nil if ocr_result.is_a?(Mindee::Parsing::Common::Ocr) || tax_names.empty?
+
+        tax_names.sort!
+        found_hash = pick_best(extract_horizontal_tax(ocr_result, tax_names), tax_names)
+        # a tax is considered found horizontally if it has a value, otherwise it is vertical
+        if found_hash.nil? || found_hash['value'].nil?
+          found_hash = extract_vertical_tax(ocr_result, tax_names,
+                                            found_hash)
+        end
+        found_hash = curate_values(found_hash, min_rate_percentage, max_rate_percentage)
+
+        return if found_hash.nil? || found_hash.empty?
+
+        create_tax_field(found_hash)
+      end
+
+      # Creates a tax field from a given hash.
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @return [Mindee::Parsing::Standard::TaxField]
+      def self.create_tax_field(found_hash)
+        Mindee::Parsing::Standard::TaxField.new(
+          found_hash,
+          found_hash.key?('page_id') ? found_hash['page_id'] : nil
+        )
+      end
+
+      # Extracts the rate and code, if found, from matches into the found_hash.
+      # @param matches [MatchData] RegEx matches of the values for taxes
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @param percent_first [Boolean] Whether the percentage was found before or after the tax name.
+      # @return [Hash]
+      def self.extract_percentage_from_tax(matches, found_hash, percent_first)
+        if percent_first
+          found_hash['code'] = matches[2].strip unless matches[2].nil?
+          found_hash['rate'] = parse_amount(matches[1].gsub('%', '')) unless matches[1].nil?
+        else
+          found_hash['code'] = matches[1].strip unless matches[1].nil?
+          found_hash['rate'] = parse_amount(matches[2].gsub('%', '')) unless matches[2].nil?
+        end
+        found_hash
+      end
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+
+      # Extracts the basis and value of a tax from regex matches, independent of the order.
+      # @param matches [MatchData] RegEx matches of the values for taxes
+      # @param found_hash [Hash] Hash of currently retrieved values
+      # @return [Hash]
+      def self.extract_basis_and_value(matches, found_hash)
+        if matches[4].nil? && !matches[3].nil?
+          found_hash['value'] = parse_amount(matches[3]) unless matches[3].nil?
+        elsif matches[3].nil? && !matches[4].nil?
+          found_hash['value'] = parse_amount(matches[4]) unless matches[4].nil?
+        elsif !matches[3].nil? && !matches[4].nil?
+          found_hash['base'] = parse_amount(matches[3]) unless matches[3].nil?
+          found_hash['value'] = parse_amount(matches[4]) unless matches[4].nil?
+        end
+        found_hash
+      end
+
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # Extracts tax information from a horizontal line.
+      # @param line [String] Line to be processed.
+      # @param pattern [Regexp] RegEx pattern to search the line with.
+      # @param percent_first [Boolean] Whether the percentage was found before or after the tax name.
+      # @return [Hash]
+      def self.extract_tax_from_horizontal_line(line, pattern, page_id, percent_first)
+        found_hash = {}
+
+        matches = line.match(pattern)
+
+        # Edge case for when the tax is split-up between two pages, we'll consider that
+        # the answer belongs to the first one.
+        found_hash['page_id'] = page_id unless found_hash.key?('page_id')
+        return found_hash if matches.nil?
+
+        found_hash = extract_percentage_from_tax(matches, found_hash, percent_first)
+        extract_basis_and_value(matches, found_hash)
+      end
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+
+      # Processes a horizontal line for tax extraction. Returns a hash of collected values.
+      # @param ocr_result [Mindee::Parsing::Common::Ocr::Ocr] Processed OCR results.
+      # @param tax_names [Array<String>] Possible tax names candidates.
+      # @return [Array<Hash>]
+      def self.extract_horizontal_tax(ocr_result, tax_names)
+        candidates = [{ 'code' => nil, 'value' => nil, 'base' => nil, 'rate' => nil }]
+        linear_pattern_percent_first = %r{
+          ((?:\s*-\s*)?(?:\d*[.,])*\d+[ ]?%?|%?[ ]?(?:\s*-\s*)?(?:\d*[.,])*\d+)?[ .]?
+          ([a-zA-ZÀ-ÖØ-öø-ÿ .]*[a-zA-ZÀ-ÖØ-öø-ÿ]?)[ .]?
+          ((?:\s*-\s*)?(?:\d*[.,])+\d{2,})?[ .]*
+          ((?:\s*-\s*)?(\d*[.,])*\d{2,})?
+        }x
+        linear_pattern_percent_second = %r{
+          ([a-zA-ZÀ-ÖØ-öø-ÿ .]*[a-zA-ZÀ-ÖØ-öø-ÿ]?)[ .]*
+          ((?:\s*-\s*)?(?:\d*[.,])*\d+[ ]?%?|%?[ ]?(?:\s*-\s*)?(?:\d*[.,])*\d+)?[ .]?
+          ((?:\s*-\s*)?(?:\d*[.,])+\d{2,})?[ .]*
+          ((?:\s*-\s*)?(\d*[.,])*\d{2,})?
+        }x
+        ocr_result.mvision_v1.pages.each.with_index do |page, page_id|
+          page.all_lines.each do |line|
+            clean_line = remove_currency_symbols(line.to_s.scrub.gsub(%r{[+(\[)\]¿?*_]}, '')).gsub(%r{\.{2,}}, ' ')
+                                                                                             .gsub(%r{ +}, ' ').strip
+
+            next if match_index(clean_line, tax_names).nil?
+
+            unless clean_line.match(linear_pattern_percent_second).nil?
+              candidates.append(extract_tax_from_horizontal_line(clean_line[match_index(clean_line, tax_names)..],
+                                                                 linear_pattern_percent_second, page_id, false))
+            end
+            if clean_line.include?('%') && !clean_line.match(linear_pattern_percent_first).nil?
+              candidates.append(extract_tax_from_horizontal_line(clean_line[clean_line.index(%r{\d*[.,]?\d* ?%})..],
+                                                                 linear_pattern_percent_first, page_id, true))
+            elsif !clean_line.match(linear_pattern_percent_first).nil?
+              candidates.append(extract_tax_from_horizontal_line(clean_line,
+                                                                 linear_pattern_percent_first, page_id, true))
+            end
+          end
+        end
+        candidates
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # Processes a vertical reconstructed line for tax extraction. Returns a hash of collected values.
+      # @param line [Mindee::Parsing::Common::Ocr::OcrLine] Processed OCR results.
+      # @param found_hash [Hash] Hash containing previously found values, if any.
+      # @return [Hash]
+      def self.extract_vertical_tax_values(line, found_hash)
+        amounts = []
+        line.each do |reconstructed_word|
+          amounts.push(parse_amount(reconstructed_word.text)) unless parse_amount(reconstructed_word.text).nil?
+        end
+        if amounts.length == 1 && !found_hash.key?('value')
+          found_hash['value'] = amounts[0]
+        else
+          found_hash['rate'] = amounts[0] if found_hash['rate'].nil?
+          found_hash['value'] = amounts[1] if found_hash['value'].nil?
+        end
+        found_hash
+      end
+
+      # Extracts tax data from a vertical reconstructed row.
+      # @param ocr_result [Mindee::Parsing::Common::Ocr] OCR raw results
+      # @param tax_names [Array<String>] Array of possible names a tax can have
+      # @param found_hash [Hash] Hash of currently retrieved values
+      def self.extract_vertical_tax(ocr_result, tax_names, found_hash)
+        found_hash = { 'code' => nil, 'page_id' => nil } if found_hash.nil?
+
+        ocr_result.mvision_v1.pages.each_with_index do |page, page_id|
+          page.all_words.each do |word|
+            next if match_index(word.text, tax_names).nil?
+
+            reconstructed_line = ocr_result.reconstruct_vertically(word.polygon, page_id)
+            found_hash['page_id'] = page_id if found_hash['page_id'].nil?
+            found_hash['code'] = word.text.strip if found_hash['code'].nil?
+            found_hash = extract_vertical_tax_values(reconstructed_line, found_hash)
+          end
+        end
+        found_hash
+      end
+
+      private_class_method :extract_percentage_from_tax, :extract_basis_and_value, :extract_tax_from_horizontal_line,
+                           :extract_horizontal_tax, :extract_vertical_tax_values, :extract_vertical_tax,
+                           :create_tax_field, :fix_rate, :pick_best, :calculate_score, :curate_values,
+                           :decimate_rates_if_needed, :extract_basis_and_value, :set_base_and_value, :valid_candidate?,
+                           :swap_rates_if_needed
+    end
+  end
+end

data/lib/mindee/extraction.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'extraction/tax_extractor'

data/lib/mindee/geometry/utils.rb

@@ -77,5 +77,24 @@ module Mindee
       coords = points.map(&:x)
       MinMax.new(coords.min, coords.max)
     end
+
+    # Checks whether a set of coordinates is below another on the page, with a slight margin for the lateral value.
+    # @param candidate [Array<Mindee::Geometry::Point] Polygon to check
+    # @param anchor [Array<Mindee::Geometry::Point] Reference polygon
+    # @param margin_left [Float] Margin tolerance on the left of the anchor
+    # @param margin_right [Float] Margin tolerance on the right of the anchor
+    def self.below?(candidate, anchor, margin_left, margin_right)
+      return false if Geometry.get_min_max_y(candidate).min < Geometry.get_min_max_y(anchor).min
+      if Geometry.get_min_max_x(candidate).min <
+         Geometry.get_min_max_x(anchor).min - (Geometry.get_min_max_x(anchor).min * margin_left)
+        return false
+      end
+      if Geometry.get_min_max_x(candidate).max >
+         Geometry.get_min_max_x(anchor).max + (Geometry.get_min_max_x(anchor).max * margin_right)
+        return false
+      end
+
+      true
+    end
   end
 end

data/lib/mindee/image_extraction/common/extracted_image.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative '../../input/sources'
+
+module Mindee
+  # Image Extraction Module.
+  module ImageExtraction
+    # Generic class for image extraction.
+    class ExtractedImage
+      # Id of the page the image was extracted from.
+      attr_reader :page_id
+
+      # Id of the element on a given page.
+      attr_reader :element_id
+
+      # Buffer object of the file's content.
+      attr_reader :buffer
+
+      # Internal name for the file.
+      attr_reader :internal_file_name
+
+      # Initializes the ExtractedImage with a buffer and an internal file name.
+      #
+      # @param input_source [LocalInputSource] Local source for input.
+      # @param page_id [Integer] ID of the page the element was found on.
+      # @param element_id [Integer, nil] ID of the element in a page.
+      def initialize(input_source, page_id, element_id)
+        @buffer = StringIO.new(input_source.io_stream.read)
+        @buffer.rewind
+        extension = if input_source.pdf?
+                      'jpg'
+                    else
+                      File.extname(input_source.filename)
+                    end
+        @internal_file_name = "#{input_source.filename}_p#{page_id}_#{element_id}.#{extension}"
+        @page_id = page_id
+        @element_id = element_id.nil? ? 0 : element_id
+      end
+
+      # Saves the document to a file.
+      #
+      # @param output_path [String] Path to save the file to.
+      # @param file_format [String, nil] Optional MiniMagick-compatible format for the file. Inferred from file
+      # extension if not provided.
+      # @raise [MindeeError] If an invalid path or filename is provided.
+      def save_to_file(output_path, file_format = nil)
+        resolved_path = Pathname.new(output_path).realpath
+        if file_format.nil?
+          raise ArgumentError, 'Invalid file format.' if resolved_path.extname.delete('.').empty?
+
+          file_format = resolved_path.extname.delete('.').upcase
+        end
+        @buffer.rewind
+        image = MiniMagick::Image.read(@buffer)
+        image.format file_format.downcase
+        image.write resolved_path.to_s
+        logger.info("File saved successfully to '#{resolved_path}'.")
+      rescue TypeError
+        raise 'Invalid path/filename provided.'
+      rescue StandardError
+        raise "Could not save file #{Pathname.new(output_path).basename}."
+      end
+
+      # Return the file as a Mindee-compatible BufferInput source.
+      #
+      # @return [FileInputSource] A BufferInput source.
+      def as_source
+        @buffer.rewind
+        Mindee::Input::Source::BytesInputSource.new(@buffer.read, @internal_file_name)
+      end
+    end
+  end
+end

data/lib/mindee/image_extraction/common/image_extractor.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'mini_magick'
+require 'origami'
+require 'stringio'
+require 'tempfile'
+require_relative '../../input/sources'
+require_relative 'extracted_image'
+
+module Mindee
+  # Image Extraction Module.
+  module ImageExtraction
+    def attach_image_as_new_file(input_buffer)
+      # Attaches an image as a new page in a PdfDocument object.
+      #
+      # @param [StringIO] input_buffer Input buffer. Only supports JPEG.
+      # @return [Origami::PDF] A PdfDocument handle.
+
+      magick_image = MiniMagick::Image.read(input_buffer)
+      # NOTE: some jpeg images get rendered as three different versions of themselves per output if the format isn't
+      # converted.
+      magick_image.format('jpg')
+      original_density = magick_image.resolution
+      scale_factor = original_density[0].to_f / 4.166666 # No clue why bit the resolution needs to be reduced for
+      # the pdf otherwise the resulting image shrinks.
+      magick_image.format('pdf', 0, { density: scale_factor.to_s })
+      io_buffer = StringIO.new
+      magick_image.write(io_buffer)
+      Origami::PDF.read(io_buffer)
+    end
+
+    # Extracts multiple images from a given local input source.
+    #
+    # @param [Mindee::Input::Source::LocalInputSource] input_source
+    # @param [Integer] page_id ID of the Page to extract from.
+    # @param [Array<Array<Mindee::Geometry::Point>>, Array<Mindee::Geometry::Quadrangle>] polygons List of coordinates
+    # to extract.
+    # @return [Array<Mindee::ImageExtraction::ExtractedImage>] Extracted Images.
+    def extract_multiple_images_from_source(input_source, page_id, polygons)
+      new_stream = load_doc(input_source, page_id)
+      new_stream.seek(0)
+
+      extract_images_from_polygons(input_source, new_stream, page_id, polygons)
+    end
+
+    # Retrieves a PDF document's page.
+    #
+    # @param [Origami::PDF] pdf_doc Origami PDF handle.
+    # @param [Integer] page_id Page ID.
+    def get_page(pdf_doc, page_id)
+      stream = StringIO.new
+      pdf_doc.save(stream)
+
+      options = {
+        page_indexes: [page_id - 1],
+      }
+
+      Mindee::PDF::PdfProcessor.parse(stream, options)
+    end
+
+    # Extracts images from their positions on a file (as polygons).
+    #
+    # @param [Mindee::Input::Source::LocalInputSource] input_source Local input source.
+    # @param [StringIO] pdf_stream Buffer of the PDF.
+    # @param [Integer] page_id Page ID.
+    # @param [Array<Mindee::Geometry::Point, Mindee::Geometry::Polygon, Mindee::Geometry::Quadrangle>] polygons
+    # @return [Array<Mindee::ImageExtraction::ExtractedImage>] Extracted Images.
+    def extract_images_from_polygons(input_source, pdf_stream, page_id, polygons)
+      extracted_elements = []
+
+      polygons.each_with_index do |polygon, element_id|
+        polygon = normalize_polygon(polygon)
+        page_content = read_page_content(pdf_stream)
+
+        min_max_x = Geometry.get_min_max_x([
+                                             polygon.top_left,
+                                             polygon.bottom_right,
+                                             polygon.top_right,
+                                             polygon.bottom_left,
+                                           ])
+        min_max_y = Geometry.get_min_max_y([
+                                             polygon.top_left,
+                                             polygon.bottom_right,
+                                             polygon.top_right,
+                                             polygon.bottom_left,
+                                           ])
+        file_extension = determine_file_extension(input_source)
+        cropped_image = crop_image(page_content, min_max_x, min_max_y)
+        if file_extension == 'pdf'
+          cropped_image.format('jpg')
+        else
+          cropped_image.format(file_extension)
+        end
+
+        buffer = StringIO.new
+        write_image_to_buffer(cropped_image, buffer)
+        file_name = "#{input_source.filename}_page#{page_id}-#{element_id}.#{file_extension}"
+
+        extracted_elements << create_extracted_image(buffer, file_name, page_id, element_id)
+      end
+
+      extracted_elements
+    end
+
+    # Retrieves the bounding box of a polygon.
+    #
+    # @param [Array<Point>, Mindee::Geometry::Polygon] polygon
+    def normalize_polygon(polygon)
+      if polygon.is_a?(Mindee::Geometry::Polygon)
+        Mindee::Geometry.get_bounding_box(polygon)
+      else
+        polygon
+      end
+    end
+
+    # Loads a buffer into a MiniMagick Image.
+    #
+    # @param [StringIO] pdf_stream Buffer containg the PDF
+    # @return [MiniMagick::Image] a valid MiniMagick image handle.
+    def read_page_content(pdf_stream)
+      pdf_stream.rewind
+      MiniMagick::Image.read(pdf_stream)
+    end
+
+    # Crops a MiniMagick Image from a the given bounding box.
+    #
+    # @param [MiniMagick::Image] image Input Image.
+    # @param [Mindee::Geometry::MinMax] min_max_x minimum & maximum values for the x coordinates.
+    # @param [Mindee::Geometry::MinMax] min_max_y minimum & maximum values for the y coordinates.
+    def crop_image(image, min_max_x, min_max_y)
+      width = image[:width].to_i
+      height = image[:height].to_i
+
+      image.format('jpg')
+      new_width = (min_max_x.max - min_max_x.min) * width
+      new_height = (min_max_y.max - min_max_y.min) * height
+      image.crop("#{new_width}x#{new_height}+#{min_max_x.min * width}+#{min_max_y.min * height}")
+
+      image
+    end
+
+    # Writes a MiniMagick::Image to a buffer.
+    #
+    # @param [MiniMagick::Image] image a valid MiniMagick image.
+    # @param [StringIO] buffer
+    def write_image_to_buffer(image, buffer)
+      image.write(buffer)
+    end
+
+    # Retrieves the file extension from the main file to apply it to the extracted images. Note: coerces pdf as jpg.
+    #
+    # @param [Mindee::Input::Source::LocalInputSource] input_source Local input source.
+    # @return [String] A valid file extension.
+    def determine_file_extension(input_source)
+      if input_source.pdf? || input_source.filename.downcase.end_with?('pdf')
+        'jpg'
+      else
+        File.extname(input_source.filename).strip.downcase[1..]
+      end
+    end
+
+    # Generates an ExtractedImage.
+    #
+    # @param [StringIO] buffer Buffer containing the image.
+    # @param [String] file_name Name for the file.
+    # @param [Object] page_id ID of the page the file was generated from.
+    # @param [Object] element_id ID of the element of a given page.
+    def create_extracted_image(buffer, file_name, page_id, element_id)
+      buffer.rewind
+      ExtractedImage.new(
+        Mindee::Input::Source::BytesInputSource.new(buffer.read, file_name),
+        page_id,
+        element_id
+      )
+    end
+
+    # Loads a single_page from an image file or a pdf document.
+    #
+    # @param input_file [LocalInputSource] Local input.
+    # @param [Integer] page_id Page ID.
+    # @return [MiniMagick::Image] A valid PdfDocument handle.
+    def load_doc(input_file, page_id)
+      input_file.io_stream.rewind
+      if input_file.pdf?
+        get_page(Origami::PDF.read(input_file.io_stream), page_id)
+      else
+        input_file.io_stream
+      end
+    end
+  end
+end

data/lib/mindee/image_extraction/common.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'common/image_extractor'

data/lib/mindee/image_extraction/multi_receipts_extractor/multi_receipts_extractor.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Image Extraction Module.
+  module ImageExtraction
+    def extract_receipts(input_source, inference)
+      # Extracts individual receipts from multi-receipts documents.
+      #
+      # @param input_source [LocalInputSource] Local Input Source to extract sub-receipts from.
+      # @param inference [Inference] Results of the inference.
+      # @return [Array<ExtractedImage>] Individual extracted receipts as an array of ExtractedMultiReceiptsImage.
+
+      images = []
+      raise 'No possible receipts candidates found for MultiReceipts extraction.' unless inference.prediction.receipts
+
+      (0...input_source.count_pdf_pages).each do |page_id|
+        receipt_positions = inference.pages[page_id].prediction.receipts.map(&:bounding_box)
+        images.concat(
+          extract_multiple_images_from_source(input_source, page_id + 1, receipt_positions)
+        )
+      end
+
+      images
+    end
+  end
+end

data/lib/mindee/image_extraction/multi_receipts_extractor.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'multi_receipts_extractor/multi_receipts_extractor'

data/lib/mindee/image_extraction.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'image_extraction/common'
+require_relative 'image_extraction/multi_receipts_extractor'

data/lib/mindee/input/sources.rb

@@ -118,6 +118,14 @@ module Mindee
           @io_stream.close if close
           ['document', data, { filename: Mindee::Input::Source.convert_to_unicode_escape(@filename) }]
         end
+
+        def count_pdf_pages
+          return 1 unless pdf?
+
+          @io_stream.seek(0)
+          pdf_processor = Mindee::PDF::PdfProcessor.open_pdf(@io_stream)
+          pdf_processor.pages.size
+        end
       end
 
       # Load a document from a path.