mindee-lite 5.0.0.beta1

data/lib/mindee/geometry/point.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions for geometry.
+  module Geometry
+    # A relative set of coordinates (X, Y) on the document.
+    class Point
+      # @return [Float]
+      attr_reader :x
+      # @return [Float]
+      attr_reader :y
+
+      # rubocop:disable Naming/MethodParameterName
+
+      # @param x [Float]
+      # @param y [Float]
+      def initialize(x, y)
+        @x = x
+        @y = y
+      end
+      # rubocop:enable Naming/MethodParameterName
+
+      # @return [Float]
+      def [](key)
+        case key
+        when 0
+          @x
+        when 1
+          @y
+        else
+          throw '0 or 1 only'
+        end
+      end
+
+      # @return [String] Point as a string.
+      def to_s
+        "(#{@x},#{@y})"
+      end
+    end
+  end
+end

data/lib/mindee/geometry/polygon.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions & classes for geometry.
+  module Geometry
+    # Contains any number of vertex coordinates (Points).
+    class Polygon < Array
+      # @param server_response [Hash] Raw server response hash.
+      def initialize(server_response)
+        points = [] # @type var points: Array[Mindee::Geometry::Point]
+        server_response.map do |point|
+          points << Point.new(point[0], point[1])
+        end
+        super(points)
+      end
+
+      # Get the central point (centroid) of the polygon.
+      # @return [Mindee::Geometry::Point]
+      def centroid
+        Geometry.get_centroid(self)
+      end
+
+      # Determine if the Point is in the Polygon's Y-axis.
+      # @param point [Mindee::Geometry::Point]
+      # @return [bool]
+      def point_in_y?(point)
+        min_max = Geometry.get_min_max_y(self)
+        point.y.between?(min_max.min, min_max.max)
+      end
+
+      # @return [String] Polygon as a string.
+      def to_s
+        "(#{join(', ')})"
+      end
+    end
+  end
+end

data/lib/mindee/geometry/quadrilateral.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions & classes for geometry.
+  module Geometry
+    # Contains exactly 4 relative vertices coordinates (Points).
+    class Quadrilateral
+      # @return [Mindee::Geometry::Point]
+      attr_reader :top_left
+      # @return [Mindee::Geometry::Point]
+      attr_reader :top_right
+      # @return [Mindee::Geometry::Point]
+      attr_reader :bottom_right
+      # @return [Mindee::Geometry::Point]
+      attr_reader :bottom_left
+
+      # @param top_left [Mindee::Geometry::Point]
+      # @param top_right [Mindee::Geometry::Point]
+      # @param bottom_right [Mindee::Geometry::Point]
+      # @param bottom_left [Mindee::Geometry::Point]
+      def initialize(top_left, top_right, bottom_right, bottom_left)
+        @top_left = top_left
+        @top_right = top_right
+        @bottom_right = bottom_right
+        @bottom_left = bottom_left
+      end
+
+      # @return [Mindee::Geometry::Point]
+      def [](key)
+        case key
+        when 0
+          @top_left
+        when 1
+          @top_right
+        when 2
+          @bottom_right
+        when 3
+          @bottom_left
+        else
+          throw '0, 1, 2, 3 only'
+        end
+      end
+
+      # A quadrilateral has four corners, always.
+      def size
+        4
+      end
+    end
+  end
+end

data/lib/mindee/geometry/utils.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Various helper functions for geometry.
+  module Geometry
+    # Transform a prediction into a Quadrilateral.
+    # @param prediction [Array<Array<Float>>]
+    # @return [Mindee::Geometry::Quadrilateral]
+    def self.quadrilateral_from_prediction(prediction)
+      throw "Prediction must have exactly 4 points, found #{prediction.size}" if prediction.size != 4
+
+      Quadrilateral.new(
+        Point.new(prediction[0][0], prediction[0][1]),
+        Point.new(prediction[1][0], prediction[1][1]),
+        Point.new(prediction[2][0], prediction[2][1]),
+        Point.new(prediction[3][0], prediction[3][1])
+      )
+    end
+
+    # Gets the points of a bounding box for a given set of points
+    # @param vertices [Array<Mindee::Geometry::Point>]
+    # @return [Array<Float>]
+    def self.get_bbox(vertices)
+      x_coords = vertices.map(&:x)
+      y_coords = vertices.map(&:y)
+      [x_coords.min, y_coords.min, x_coords.max, y_coords.max]
+    end
+
+    # Creates the bounding box for a given set of points
+    # @param vertices [Array<Mindee::Geometry::Point>]
+    # @return [Mindee::Geometry::Quadrilateral]
+    def self.get_bounding_box(vertices)
+      x_min, y_min, x_max, y_max = get_bbox(vertices)
+      Quadrilateral.new(
+        Point.new(x_min, y_min),
+        Point.new(x_max, y_min),
+        Point.new(x_max, y_max),
+        Point.new(x_min, y_max)
+      )
+    end
+
+    # Get the central point (centroid) given a sequence of points.
+    # @param points [Array<Mindee::Geometry::Point>]
+    # @return [Mindee::Geometry::Point]
+    def self.get_centroid(points)
+      vertices_count = points.size
+      x_sum = points.map(&:x).sum
+      y_sum = points.map(&:y).sum
+      Point.new(x_sum / vertices_count, y_sum / vertices_count)
+    end
+
+    # Get the maximum and minimum Y value given a sequence of points.
+    # @param points [Array<Mindee::Geometry::Point>]
+    # @return [Mindee::Geometry::MinMax]
+    def self.get_min_max_y(points)
+      coords = points.map(&:y)
+      MinMax.new(coords.min, coords.max)
+    end
+
+    # Get the maximum and minimum X value given a sequence of points.
+    # @param points [Array<Mindee::Geometry::Point>]
+    # @return [Mindee::Geometry::MinMax]
+    def self.get_min_max_x(points)
+      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
+    # @return bool
+    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/geometry.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'geometry/min_max'
+require_relative 'geometry/point'
+require_relative 'geometry/quadrilateral'
+require_relative 'geometry/polygon'
+require_relative 'geometry/utils'

data/lib/mindee/http/.rubocop.yml

@@ -0,0 +1,7 @@
+inherit_from: ../../../.rubocop.yml
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10

data/lib/mindee/http/http_error_handler.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../error/mindee_http_error'
+
+module Mindee
+  module HTTP
+    # Mindee HTTP error module.
+    module ErrorHandler
+      module_function
+
+      # Extracts the HTTP error from the response hash, or the job error if there is one.
+      # @param response [Hash] dictionary response retrieved by the server
+      def extract_error(response)
+        return unless response.respond_to?(:each_pair)
+
+        if !response.dig('api_request', 'error').empty?
+          response.dig('api_request', 'error')
+        elsif !response.dig('job', 'error').empty?
+          response.dig('job', 'error')
+        end
+      end
+
+      # Creates an error object based on what's retrieved from a request.
+      # @param response [Hash] dictionary response retrieved by the server
+      def create_error_obj(response)
+        error_obj = extract_error(response)
+        if error_obj.nil?
+          error_obj = if response.include?('Maximum pdf pages')
+                        {
+                          'code' => 'TooManyPages',
+                          'message' => 'Maximum amound of pdf pages reached.',
+                          'details' => response,
+                        }
+                      elsif response.include?('Max file size is')
+                        {
+                          'code' => 'FileTooLarge',
+                          'message' => 'Maximum file size reached.',
+                          'details' => response,
+                        }
+                      elsif response.include?('Invalid file type')
+                        {
+                          'code' => 'InvalidFiletype',
+                          'message' => 'Invalid file type.',
+                          'details' => response,
+                        }
+                      elsif response.include?('Gateway timeout')
+                        {
+                          'code' => 'RequestTimeout',
+                          'message' => 'Request timed out.',
+                          'details' => response,
+                        }
+                      elsif response.include?('Too Many Requests')
+                        {
+                          'code' => 'TooManyRequests',
+                          'message' => 'Too Many Requests.',
+                          'details' => response,
+                        }
+                      else
+                        {
+                          'code' => 'UnknownError',
+                          'message' => 'Server sent back an unexpected reply.',
+                          'details' => response,
+                        }
+                      end
+
+        end
+        error_obj
+      end
+
+      # Creates an appropriate HTTP error exception, based on retrieved http error code
+      # @param url [String] the url of the product
+      # @param response [Hash] dictionary response retrieved by the server
+      def handle_error(url, response)
+        code = response.code.to_i
+        begin
+          parsed_hash = JSON.parse(response.body, object_class: Hash)
+        rescue JSON::ParserError
+          parsed_hash = response.body.to_s
+        end
+        error_obj = create_error_obj(parsed_hash)
+        case code
+        when 400..499
+          Error::MindeeHTTPClientError.new(error_obj || {}, url, code)
+        when 500..599
+          Error::MindeeHTTPServerError.new(error_obj || {}, url, code)
+        else
+          Error::MindeeHTTPError.new(error_obj || {}, url, code)
+        end
+      end
+
+      # Creates an appropriate HTTP error exception for a V2 API response, based on retrieved http error code.
+      # @param hashed_response [Hash] dictionary response retrieved by the server
+      def generate_v2_error(hashed_response)
+        code = hashed_response[:code].to_i
+        if hashed_response.key?(:status)
+          Error::MindeeHTTPErrorV2.new(hashed_response.transform_keys(&:to_s))
+        elsif code < 200 || code > 399
+          Error::MindeeHTTPErrorV2.new({ 'status' => code, 'detail' => 'No details available.' })
+        else
+          Error::MindeeHTTPErrorV2.new({ 'status' => -1, 'detail' => 'Unknown Error.' })
+        end
+      end
+    end
+  end
+end

data/lib/mindee/http/response_validation.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+module Mindee
+  module HTTP
+    # Module dedicated to the validation & sanitizing of HTTP responses.
+    module ResponseValidation
+      # Checks if the synchronous response is valid. Returns True if the response is valid.
+      # @param [Net::HTTPResponse] response
+      # @return [bool]
+      def self.valid_sync_response?(response)
+        return false unless (200..399).cover?(response.code.to_i)
+
+        begin
+          JSON.parse(response.body, object_class: Hash)
+        rescue StandardError
+          return false
+        end
+        true
+      end
+
+      # Checks if a V2 response is valid.
+      # @param [Net::HTTPResponse] response
+      # @return [bool]
+      def self.valid_v2_response?(response)
+        return false unless valid_sync_response?(response)
+
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+
+        return false if hashed_response.dig('job', 'status').to_s == 'Failed'
+
+        return false if hashed_response.dig('job',
+                                            'error') && !(hashed_response.dig('job',
+                                                                              'error').empty? || hashed_response.dig(
+                                                                                'job', 'error'
+                                                                              ).nil?)
+
+        true
+      end
+
+      # Checks if the asynchronous response is valid. Also checks if it is a valid synchronous response.
+      # Returns true if the response is valid.
+      # @param [Net::HTTPResponse] response
+      # @return [bool]
+      def self.valid_async_response?(response)
+        return false unless valid_sync_response?(response)
+
+        return false unless (200..302).cover?(response.code.to_i)
+
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+
+        return false if hashed_response.dig('job', 'status') == Mindee::V1::Parsing::Common::JobStatus::FAILURE
+
+        return false if hashed_response.dig('job', 'error') && !hashed_response.dig('job', 'error').empty?
+
+        true
+      end
+
+      # Checks and correct the response object depending on the possible kinds of returns.
+      # @param response [Net::HTTPResponse]
+      def self.clean_request!(response)
+        return response if (response.code.to_i < 200) || (response.code.to_i > 302) # : Net::HTTPResponse
+
+        return response if response.body.empty?
+
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+        if hashed_response.dig('api_request', 'status_code').to_i > 399
+          response.instance_variable_set(:@code, hashed_response['api_request']['status_code'].to_s)
+        end
+
+        return if !hashed_response.dig('job', 'error').empty? &&
+                  (hashed_response.dig('job',
+                                       'status').downcase != Mindee::V1::Parsing::Common::JobStatus::FAILURE.to_s)
+
+        response.instance_variable_set(:@code, '500')
+      end
+    end
+  end
+end

data/lib/mindee/http.rb

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

data/lib/mindee/image/extracted_image.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative '../input/sources'
+require_relative '../logging'
+
+module Mindee
+  # Image Extraction Module.
+  module Image
+    # 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 :filename
+
+      # Initializes the ExtractedImage with a buffer and an internal file name.
+      #
+      # @param input_source [LocalInputSource, BytesInputSource] 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.
+      # @param preserve_input_filename [Boolean] If true, keep the input source filename as-is.
+      def initialize(input_source, page_id, element_id, preserve_input_filename: false)
+        @buffer = StringIO.new(input_source.io_stream.read.to_s)
+        @buffer.rewind
+
+        @filename = if preserve_input_filename
+                      input_source.filename.to_s
+                    else
+                      extension = if input_source.pdf?
+                                    '.jpg'
+                                  else
+                                    File.extname(input_source.filename)
+                                  end
+                      base_name = File.basename(input_source.filename, File.extname(input_source.filename))
+                      "#{base_name}_p#{page_id}_#{element_id}#{extension}"
+                    end
+        @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 write_to_file(output_path, file_format = nil)
+        resolved_path = Pathname.new(File.expand_path(output_path))
+        if file_format.nil?
+          raise Error::MindeeImageError, 'Invalid file format.' if resolved_path.extname.delete('.').empty?
+
+          file_format = resolved_path.extname.delete('.').upcase
+        end
+        begin
+          @buffer.rewind
+          image = MiniMagick::Image.read(@buffer)
+          image.format file_format.to_s.downcase
+          image.write resolved_path.to_s
+          logger.info("File saved successfully to '#{resolved_path}'")
+        rescue StandardError
+          raise Error::MindeeImageError, "Could not save file '#{output_path}'. " \
+                                         'Is the provided file path valid?.'
+        end
+      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 || '', @filename)
+      end
+
+      # Return the file as a Mindee-compatible BufferInput source.
+      #
+      # @return [FileInputSource] A BufferInput source.
+      def as_input_source
+        as_source
+      end
+    end
+  end
+end

data/lib/mindee/image/image_compressor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Image processing module.
+  module Image
+    # Image compressor module to handle image compression.
+    module ImageCompressor
+      # Resize and/or compress an SKBitmap. This assumes the ratio was provided before hands.
+      # @param image [MiniMagick::Image, StringIO] Input image.
+      # @param quality [Integer, nil] Quality of the final file.
+      # @param max_width [Integer, nil] Maximum width. If not specified, the horizontal ratio will remain the same.
+      # @param max_height [Integer] Maximum height. If not specified, the vertical ratio will remain the same.
+      # @return [StringIO]
+      def self.compress_image(image, quality: 85, max_width: nil, max_height: nil)
+        processed_image = ImageUtils.to_image(image)
+        processed_image.format 'jpg'
+        final_width, final_height = ImageUtils.calculate_new_dimensions(
+          processed_image,
+          max_width: max_width,
+          max_height: max_height
+        )
+        ImageUtils.resize_image(processed_image, final_width, final_height) if final_width || final_height
+        ImageUtils.compress_image_quality(processed_image, quality)
+
+        ImageUtils.image_to_stringio(processed_image)
+      end
+    end
+  end
+end

data/lib/mindee/image/image_extractor.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+Mindee::Dependency.require_all_deps!
+require 'mini_magick'
+require 'origami'
+require 'stringio'
+require 'tempfile'
+require_relative '../input/sources'
+require_relative 'extracted_image'
+
+module Mindee
+  # Image Extraction Module.
+  module Image
+    # Image Extraction wrapper class.
+    module ImageExtractor
+      # 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.
+      def self.attach_image_as_new_file(input_buffer, format: 'jpg')
+        magick_image = MiniMagick::Image.read(input_buffer)
+        # NOTE: We force format consolidation to a single format to avoid frames being interpreted as the final output.
+        magick_image.format(format)
+        original_density = magick_image.resolution
+        scale_factor = original_density[0].to_f / 4.166666 # Convert from default 300 DPI to 72.
+        magick_image.format('pdf', 0, { density: scale_factor.to_s })
+        Origami::PDF.read(StringIO.new(magick_image.to_blob))
+      end
+
+      # Extracts multiple images from a given local input source.
+      #
+      # @param [Input::Source::LocalInputSource] input_source
+      # @param [Integer] page_id ID of the Page to extract from.
+      # @param [Array<Array<Geometry::Point>>, Array<Geometry::Quadrilateral>] polygons List of coordinates to extract.
+      # @return [Array<Image::ExtractedImage>] Extracted Images.
+      def self.extract_multiple_images_from_source(input_source, page_id, polygons)
+        new_stream = load_input_source_pdf_page_as_stringio(input_source, page_id)
+        new_stream.seek(0)
+
+        extract_images_from_polygons(input_source, new_stream, page_id, polygons)
+      end
+
+      # Extracts images from their positions on a file (as polygons).
+      #
+      # @param [Input::Source::LocalInputSource] input_source Local input source.
+      # @param [StringIO] pdf_stream Buffer of the PDF.
+      # @param [Integer] page_id Page ID.
+      # @param [Array<Geometry::Point, Geometry::Polygon, Geometry::Quadrilateral>] polygons
+      # @return [Array<Image::ExtractedImage>] Extracted Images.
+      def self.extract_images_from_polygons(input_source, pdf_stream, page_id, polygons)
+        extracted_elements = [] # @type var extracted_elements: Array[Image::ExtractedImage]
+
+        polygons.each_with_index do |polygon, element_id|
+          polygon = ImageUtils.normalize_polygon(polygon)
+          page_content = ImageUtils.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 = ImageUtils.determine_file_extension(input_source)
+          cropped_image = ImageUtils.crop_image(page_content, min_max_x, min_max_y)
+          if file_extension == 'pdf'
+            cropped_image.format('jpg')
+          else
+            cropped_image.format(file_extension.to_s)
+          end
+
+          buffer = StringIO.new
+          ImageUtils.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
+
+      # Generates an ExtractedImage.
+      #
+      # @param [StringIO] buffer Buffer containing the image.
+      # @param [String] file_name Name for the file.
+      # @param [Integer] page_id ID of the page the file was universal from.
+      # @param [Integer] element_id ID of the element of a given page.
+      def self.create_extracted_image(buffer, file_name, page_id, element_id)
+        buffer.rewind
+        ExtractedImage.new(
+          Input::Source::BytesInputSource.new(buffer.read.to_s, file_name),
+          page_id,
+          element_id,
+          preserve_input_filename: true
+        )
+      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 [StringIO] A valid PdfDocument handle.
+      def self.load_input_source_pdf_page_as_stringio(input_file, page_id)
+        input_file.io_stream.rewind
+        if input_file.pdf?
+          PDF::PDFProcessor.get_page(Origami::PDF.read(input_file.io_stream), page_id)
+        else
+          input_file.io_stream
+        end
+      end
+    end
+  end
+end