mindee 3.4.0 → 3.5.0

data/docs/eu_driver_license_v1.md

@@ -0,0 +1,223 @@
+---
+title: EU EU Driver License OCR Ruby
+---
+The Ruby OCR SDK supports the [EU Driver License API](https://platform.mindee.com/mindee/eu_driver_license).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/eu_driver_license/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![EU Driver License sample](https://github.com/mindee/client-lib-test-data/blob/main/products/eu_driver_license/default_sample.jpg?raw=true)
+
+# Quick-Start
+```rb
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+
+# Load a file from disk
+input_source = mindee_client.source_from_path('/path/to/the/file.ext')
+
+# Parse the file
+result = mindee_client.parse(
+  input_source,
+  Mindee::Product::EU::DriverLicense::DriverLicenseV1
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+
+# Print the document-level parsed data
+# puts result.document.inference.prediction
+```
+
+**Output (RST):**
+```rst
+########
+Document
+########
+:Mindee ID: b19cc32e-b3e6-4ff9-bdc7-619199355d54
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/eu_driver_license v1.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Country Code: FR
+:Document ID: 13AA00002
+:Driver License Category: AM A1 B1 B D BE DE
+:Last Name: MARTIN
+:First Name: PAUL
+:Date Of Birth: 1981-07-14
+:Place Of Birth: Utopiacity
+:Expiry Date: 2018-12-31
+:Issue Date: 2013-01-01
+:Issue Authority: 99999UpiaCity
+:MRZ: D1FRA13AA000026181231MARTIN<<9
+:Address:
+
+Page Predictions
+================
+
+Page 0
+------
+:Photo: Polygon with 4 points.
+:Signature: Polygon with 4 points.
+:Country Code: FR
+:Document ID: 13AA00002
+:Driver License Category: AM A1 B1 B D BE DE
+:Last Name: MARTIN
+:First Name: PAUL
+:Date Of Birth: 1981-07-14
+:Place Of Birth: Utopiacity
+:Expiry Date: 2018-12-31
+:Issue Date: 2013-01-01
+:Issue Authority: 99999UpiaCity
+:MRZ: D1FRA13AA000026181231MARTIN<<9
+:Address:
+```
+
+# Field Types
+## Standard Fields
+These fields are generic and used in several products.
+
+### Basic Field
+Each prediction object contains a set of fields that inherit from the generic `Field` class.
+A typical `Field` object will have the following attributes:
+
+* **value** (`String`, `Float`, `Integer`, `Boolean`): corresponds to the field value. Can be `nil` if no value was extracted.
+* **confidence** (Float, nil): the confidence score of the field prediction.
+* **bounding_box** (`Mindee::Geometry::Quadrilateral`, `nil`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document.
+* **polygon** (`Mindee::Geometry::Polygon`, `nil`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image.
+* **page_id** (`Integer`, `nil`): the ID of the page, is `nil` when at document-level.
+* **reconstructed** (`Boolean`): indicates whether an object was reconstructed (not extracted as the API gave it).
+
+
+Aside from the previous attributes, all basic fields have access to a `to_s` method that can be used to print their value as a string.
+
+### Date Field
+Aside from the basic `Field` attributes, the date field `DateField` also implements the following: 
+
+* **date_object** (`Date`): an accessible representation of the value as a JavaScript object.
+
+
+### Position Field
+The position field `PositionField` does not implement all the basic `Field` attributes, only **bounding_box**, **polygon** and **page_id**. On top of these, it has access to:
+
+* **rectangle** (`Mindee::Geometry::Quadrilateral`): a Polygon with four points that may be oriented (even beyond canvas).
+* **quadrangle** (`Mindee::Geometry::Quadrilateral`): a free polygon made up of four points.
+
+### String Field
+The text field `StringField` only has one constraint: it's **value** is a `String` (or `nil`).
+
+## Page-Level Fields
+Some fields are constrained to the page level, and so will not be retrievable to through the document.
+
+# Attributes
+The following fields are extracted for EU Driver License V1:
+
+## Address
+**address** ([StringField](#string-field)): EU driver license holders address
+
+```rb
+puts result.document.inference.prediction.address.value
+```
+
+## Driver License Category
+**category** ([StringField](#string-field)): EU driver license holders categories
+
+```rb
+puts result.document.inference.prediction.category.value
+```
+
+## Country Code
+**country_code** ([StringField](#string-field)): Country code extracted as a string.
+
+```rb
+puts result.document.inference.prediction.country_code.value
+```
+
+## Date Of Birth
+**date_of_birth** ([DateField](#date-field)): The date of birth of the document holder
+
+```rb
+puts result.document.inference.prediction.date_of_birth.value
+```
+
+## Document ID
+**document_id** ([StringField](#string-field)): ID number of the Document.
+
+```rb
+puts result.document.inference.prediction.document_id.value
+```
+
+## Expiry Date
+**expiry_date** ([DateField](#date-field)): Date the document expires
+
+```rb
+puts result.document.inference.prediction.expiry_date.value
+```
+
+## First Name
+**first_name** ([StringField](#string-field)): First name(s) of the driver license holder
+
+```rb
+puts result.document.inference.prediction.first_name.value
+```
+
+## Issue Authority
+**issue_authority** ([StringField](#string-field)): Authority that issued the document
+
+```rb
+puts result.document.inference.prediction.issue_authority.value
+```
+
+## Issue Date
+**issue_date** ([DateField](#date-field)): Date the document was issued
+
+```rb
+puts result.document.inference.prediction.issue_date.value
+```
+
+## Last Name
+**last_name** ([StringField](#string-field)): Last name of the driver license holder.
+
+```rb
+puts result.document.inference.prediction.last_name.value
+```
+
+## MRZ
+**mrz** ([StringField](#string-field)): Machine-readable license number
+
+```rb
+puts result.document.inference.prediction.mrz.value
+```
+
+## Photo
+[📄](#page-level-fields "This field is only present on individual pages.")**photo** ([PositionField](#position-field)): Has a photo of the EU driver license holder
+
+```rb
+for photo_elem in result.document.photo do
+  puts photo_elem.polygon
+end
+```
+
+## Place Of Birth
+**place_of_birth** ([StringField](#string-field)): Place where the driver license holder was born
+
+```rb
+puts result.document.inference.prediction.place_of_birth.value
+```
+
+## Signature
+[📄](#page-level-fields "This field is only present on individual pages.")**signature** ([PositionField](#position-field)): Has a signature of the EU driver license holder
+
+```rb
+for signature_elem in result.document.signature do
+  puts signature_elem.polygon
+end
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/financial_document_v1.md

@@ -34,48 +34,52 @@ puts result.document
 ########
 Document
 ########
-:Mindee ID: 81c1d637-3a84-41d9-b40a-f72ca2a58826
+:Mindee ID: a6b54e2d-a7fa-4e08-8de6-6cd296f50f3d
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/financial_document v1.1
+:Product: mindee/financial_document v1.2
 :Rotation applied: Yes
 
 Prediction
 ==========
 :Locale: en; en; USD;
-:Invoice Number:
-:Reference Numbers:
-:Purchase Date: 2014-07-07
-:Due Date: 2014-07-07
-:Total Net: 40.48
-:Total Amount: 53.82
+:Invoice Number: INT-001
+:Reference Numbers: 2412/2019
+:Purchase Date: 2019-02-11
+:Due Date: 2019-02-26
+:Total Net: 195.00
+:Total Amount: 204.75
 :Taxes:
   +---------------+--------+----------+---------------+
   | Base          | Code   | Rate (%) | Amount        |
   +===============+========+==========+===============+
-  |               | TAX    |          | 3.34          |
+  |               |        | 5.00     | 9.75          |
   +---------------+--------+----------+---------------+
 :Supplier Payment Details:
-:Supplier Name: LOGANS
+:Supplier Name: JOHN SMITH
 :Supplier Company Registrations:
-:Supplier Address: 2513 s stemmons freeway lewisville tx 75067
-:Supplier Phone Number: 9724596042
-:Customer Name:
+:Supplier Address: 4490 Oak Drive Albany, NY 12210
+:Supplier Phone Number:
+:Customer Name: JESSIE M HORNE
 :Customer Company Registrations:
-:Customer Address:
-:Document Type: EXPENSE RECEIPT
-:Purchase Subcategory: restaurant
-:Purchase Category: food
-:Total Tax: 3.34
-:Tip and Gratuity: 10.00
-:Purchase Time: 20:20
+:Customer Address: 2019 Redbud Drive New York, NY 10011
+:Document Type: INVOICE
+:Purchase Subcategory:
+:Purchase Category: miscellaneous
+:Total Tax: 9.75
+:Tip and Gratuity:
+:Purchase Time:
 :Line Items:
   +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
   | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price |
   +======================================+==============+==========+============+==============+==============+============+
-  | TAX                                  |              |          |            |              | 3.34         |            |
+  | Front and rear brake cables          |              | 1.00     |            |              | 100.00       | 100.00     |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | New set of pedal arms                |              | 2.00     |            |              | 50.00        | 25.00      |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | Labon 3hrs                           |              | 3.00     |            |              | 45.00        | 15.00      |
   +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
 
 Page Predictions
@@ -84,37 +88,41 @@ Page Predictions
 Page 0
 ------
 :Locale: en; en; USD;
-:Invoice Number:
-:Reference Numbers:
-:Purchase Date: 2014-07-07
-:Due Date: 2014-07-07
-:Total Net: 40.48
-:Total Amount: 53.82
+:Invoice Number: INT-001
+:Reference Numbers: 2412/2019
+:Purchase Date: 2019-02-11
+:Due Date: 2019-02-26
+:Total Net: 195.00
+:Total Amount: 204.75
 :Taxes:
   +---------------+--------+----------+---------------+
   | Base          | Code   | Rate (%) | Amount        |
   +===============+========+==========+===============+
-  |               | TAX    |          | 3.34          |
+  |               |        | 5.00     | 9.75          |
   +---------------+--------+----------+---------------+
 :Supplier Payment Details:
-:Supplier Name: LOGANS
+:Supplier Name: JOHN SMITH
 :Supplier Company Registrations:
-:Supplier Address: 2513 s stemmons freeway lewisville tx 75067
-:Supplier Phone Number: 9724596042
-:Customer Name:
+:Supplier Address: 4490 Oak Drive Albany, NY 12210
+:Supplier Phone Number:
+:Customer Name: JESSIE M HORNE
 :Customer Company Registrations:
-:Customer Address:
-:Document Type: EXPENSE RECEIPT
-:Purchase Subcategory: restaurant
-:Purchase Category: food
-:Total Tax: 3.34
-:Tip and Gratuity: 10.00
-:Purchase Time: 20:20
+:Customer Address: 2019 Redbud Drive New York, NY 10011
+:Document Type: INVOICE
+:Purchase Subcategory:
+:Purchase Category: miscellaneous
+:Total Tax: 9.75
+:Tip and Gratuity:
+:Purchase Time:
 :Line Items:
   +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
   | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price |
   +======================================+==============+==========+============+==============+==============+============+
-  | TAX                                  |              |          |            |              | 3.34         |            |
+  | Front and rear brake cables          |              | 1.00     |            |              | 100.00       | 100.00     |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | New set of pedal arms                |              | 2.00     |            |              | 50.00        | 25.00      |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | Labon 3hrs                           |              | 3.00     |            |              | 45.00        | 15.00      |
   +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
 ```
 

data/docs/generated_v1.md

@@ -0,0 +1,90 @@
+---
+title: Generated API Ruby
+---
+The Ruby OCR SDK supports generated APIs.
+Generated APIs can theoretically support all APIs in a catch-all generic format.
+
+# Quick-Start
+
+```ruby
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+
+# Load a file from disk
+input_source = mindee_client.source_from_path('/path/to/the/file.ext')
+
+# Initialize a custom endpoint for this product
+custom_endpoint = mindee_client.create_endpoint(
+  account_name: 'my-account',
+  endpoint_name: 'my-endpoint',
+  version: 'my-version'
+)
+
+# Parse the file
+result = mindee_client.enqueue_and_parse(
+  input_source,
+  Mindee::Product::Generated::GeneratedV1,
+  endpoint: custom_endpoint
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+```
+
+# Generated Endpoints
+
+You may have noticed in the previous step that in order to access a custom build, you will need to provide an account and an endpoint name at the very least.
+
+Although it is optional, the version number should match the latest version of your build in most use-cases.
+If it is not set, it will default to "1".
+
+# Field Types
+
+## Generated Fields
+
+### Generated List Field
+
+A `GeneratedListField` is a special type of custom list that implements the following:
+
+- **values** (`Array<StringField`[GeneratedObjectField](#Generated-object-field)`>`): the confidence score of the field prediction.
+- **page_id** (`Integer`): only available for some documents ATM.
+
+Since the inner contents can vary, the value isn't accessed through a property, but rather through the following functions:
+
+- **contents_list()** (`-> Array<String, Float>>`): returns a list of values for each element.
+- **contents_string(separator=" ")** (`-> String`): returns a list of concatenated values, with an optional **separator** `String` between them.
+> **Note:** the `to_s` method returns a string representation of all values of this object, with an empty space between each of them.
+
+### Generated Object Field
+
+Unrecognized structures and sometimes values of `ListField`s are stored in a `GeneratedObjectField` structure, which is implemented dynamically depending on the object's structure.
+
+- **page_id** (`[Integer, nil]`): the ID of the page, is `nil` when at document-level.
+- **raw_value** (`[String, nil]`): an optional field for when some post-processing has been done on fields (e.g. amounts). `nil` in most instances.
+- **confidence** (`[Float, nil]`): the confidence score of the field prediction. Warning: support isn't guaranteed on all APIs.
+
+
+> **Other fields**:No matter what, other fields will be stored in a dictionary-like structure with a `key: value` pair where `key` is a string and `value` is a nullable string. They can be accessed like any other regular value, but won't be suggested by your IDE.
+
+
+### StringField
+The text field `StringField` only has one constraint: its **value** is an `Optional[str]`.
+
+
+# Attributes
+
+Generated builds always have access to at least two attributes:
+
+## Fields
+
+**fields** (`Hash<String, Array<`[GeneratedListField](#generated-list-field),[GeneratedObjectField](#generated-object-field), `(#stringfield)[StringField]>>`):
+
+```ruby
+puts result.document.inference.prediction.fields["my-field"].to_s
+```
+
+# Questions?
+
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/invoices_v4.md

@@ -310,6 +310,9 @@ puts result.document.inference.prediction.supplier_name.value
 ```rb
 for supplier_payment_details_elem in result.document.inference.prediction.supplier_payment_details do
   puts supplier_payment_details_elem.value
+    puts supplier_payment_details_elem.rate
+    puts supplier_payment_details_elem.code
+    puts supplier_payment_details_elem.basis
 end
 ```
 
@@ -318,7 +321,7 @@ end
 
 ```rb
 for taxes_elem in result.document.inference.prediction.taxes do
-  puts taxes_elem.to_s
+  puts taxes_elem.value
 end
 ```
 

data/docs/proof_of_address_v1.md

@@ -34,12 +34,12 @@ puts result.document
 ########
 Document
 ########
-:Mindee ID: 3a7e1da6-d4d0-4704-af91-051fe5484c2e
+:Mindee ID: 5d2361e9-405e-4fc1-8531-f92a3aef0c38
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/proof_of_address v1.0
+:Product: mindee/proof_of_address v1.1
 :Rotation applied: Yes
 
 Prediction
@@ -47,7 +47,7 @@ Prediction
 :Locale: en; en; USD;
 :Issuer Name: PPL ELECTRIC UTILITIES
 :Issuer Company Registrations:
-:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN,PA 18101-1175
+:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN.PA 18101-1175
 :Recipient Name:
 :Recipient Company Registrations:
 :Recipient Address: 123 MAIN ST ANYTOWN,PA 18062
@@ -73,7 +73,7 @@ Page 0
 :Locale: en; en; USD;
 :Issuer Name: PPL ELECTRIC UTILITIES
 :Issuer Company Registrations:
-:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN,PA 18101-1175
+:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN.PA 18101-1175
 :Recipient Name:
 :Recipient Company Registrations:
 :Recipient Address: 123 MAIN ST ANYTOWN,PA 18062

data/docs/us_driver_license_v1.md

@@ -54,7 +54,7 @@ Prediction
 :Date Of Birth: 1957-02-01
 :Restrictions: NONE
 :Endorsements: NONE
-:Class:
+:Driver License Class: D
 :Sex: M
 :Height: 5-08
 :Weight: 185
@@ -79,7 +79,7 @@ Page 0
 :Date Of Birth: 1957-02-01
 :Restrictions: NONE
 :Endorsements: NONE
-:Class:
+:Driver License Class: D
 :Sex: M
 :Height: 5-08
 :Weight: 185

data/lib/mindee/client.rb

@@ -38,6 +38,7 @@ module Mindee
     # @param cropper [Boolean] Whether to include cropper results for each page.
     #  This performs a cropping operation on the server and will increase response time.
     #
+    #
     # @return [Mindee::Parsing::Common::ApiResponse]
     def parse(
       input_source,
@@ -80,6 +81,7 @@ module Mindee
     # @param cropper [Boolean] Whether to include cropper results for each page.
     #  This performs a cropping operation on the server and will increase response time.
     #
+    #
     # @return [Mindee::Parsing::Common::ApiResponse]
     def enqueue(
       input_source,
@@ -118,7 +120,6 @@ module Mindee
     end
 
     # rubocop:disable Metrics/ParameterLists
-
     # Enqueue a document for async parsing and automatically try to retrieve it
     #
     # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
@@ -139,7 +140,7 @@ module Mindee
     #  This performs a cropping operation on the server and will increase response time.
     # @param initial_delay_sec [Integer, Float, nil] initial delay before polling. Defaults to 4.
     # @param delay_sec [Integer, Float, nil] delay between polling attempts. Defaults to 2.
-    # @param max_retries [Integer, nil] maximum amount of retries. Defaults to 30.
+    # @param max_retries [Integer, nil] maximum amount of retries. Defaults to 60.
     # @return [Mindee::Parsing::Common::ApiResponse]
     def enqueue_and_parse(
       input_source,
@@ -151,7 +152,7 @@ module Mindee
       cropper: false,
       initial_delay_sec: 4,
       delay_sec: 2,
-      max_retries: 30
+      max_retries: 60
     )
       enqueue_res = enqueue(
         input_source,
@@ -178,6 +179,7 @@ module Mindee
 
       queue_res
     end
+
     # rubocop:enable Metrics/ParameterLists
 
     # Load a document from an absolute path, as a string.

data/lib/mindee/http/endpoint.rb

@@ -46,9 +46,9 @@ module Mindee
 
       # Call the prediction API.
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean]
-      # @param close_file [Boolean]
-      # @param cropper [Boolean]
+      # @param all_words [Boolean] Whether the full word extraction needs to be performed
+      # @param close_file [Boolean] Whether the file will be closed after reading
+      # @param cropper [Boolean] Whether a cropping operation will be applied
       # @return [Hash]
       def predict(input_source, all_words, close_file, cropper)
         check_api_key
@@ -62,8 +62,9 @@ module Mindee
 
       # Call the prediction API.
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param close_file [Boolean]
-      # @param cropper [Boolean]
+      # @param all_words [Boolean] Whether the full word extraction needs to be performed
+      # @param close_file [Boolean] Whether the file will be closed after reading
+      # @param cropper [Boolean] Whether a cropping operation will be applied
       # @return [Hash]
       def predict_async(input_source, all_words, close_file, cropper)
         check_api_key
@@ -91,10 +92,10 @@ module Mindee
       private
 
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean]
-      # @param close_file [Boolean]
-      # @param cropper [Boolean]
-      # @return [Net::HTTPResponse]
+      # @param all_words [Boolean] Whether the full word extraction needs to be performed
+      # @param close_file [Boolean] Whether the file will be closed after reading
+      # @param cropper [Boolean] Whether a cropping operation will be applied
+      # @return [Net::HTTP, nil]
       def predict_req_post(input_source, all_words: false, close_file: true, cropper: false)
         uri = URI("#{@url_root}/predict")
 
@@ -122,9 +123,9 @@ module Mindee
       end
 
       # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
-      # @param all_words [Boolean]
-      # @param close_file [Boolean]
-      # @param cropper [Boolean]
+      # @param all_words [Boolean] Whether the full word extraction needs to be performed
+      # @param close_file [Boolean] Whether the file will be closed after reading
+      # @param cropper [Boolean] Whether a cropping operation will be applied
       # @return [Net::HTTPResponse]
       def document_queue_req_get(input_source, all_words, close_file, cropper)
         uri = URI("#{@url_root}/predict_async")

data/lib/mindee/input/sources.rb

@@ -7,6 +7,7 @@ require_relative '../pdf'
 
 module Mindee
   module Input
+    # Document source handling.
     module Source
       # Mime types accepted by the server.
       ALLOWED_MIME_TYPES = [
@@ -107,8 +108,7 @@ module Mindee
           @io_stream = PdfProcessor.parse(@io_stream, options)
         end
 
-        # Reads a document. Packs it into bytes if needed.
-        # Note: only needs filename in case of some pdf files.
+        # Reads a document.
         # @param close [Boolean]
         # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
         def read_document(close: true)
@@ -116,9 +116,7 @@ module Mindee
           # Avoids needlessly re-packing some files
           data = @io_stream.read
           @io_stream.close if close
-          return ['document', data, { filename: @filename }] if pdf?
-
-          ['document', [data].pack('m')]
+          ['document', data, { filename: Mindee::Input::Source.convert_to_unicode_escape(@filename) }]
         end
       end
 
@@ -142,6 +140,16 @@ module Mindee
           io_stream.set_encoding Encoding::BINARY
           super(io_stream, filename, fix_pdf: fix_pdf)
         end
+
+        # Overload of the same function to prevent a base64 from being re-encoded.
+        # @param close [Boolean]
+        # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
+        def read_document(close: true)
+          @io_stream.seek(0)
+          data = @io_stream.read
+          @io_stream.close if close
+          ['document', [data].pack('m'), { filename: Source.convert_to_unicode_escape(@filename) }]
+        end
       end
 
       # Load a document from raw bytes.
@@ -178,6 +186,21 @@ module Mindee
           @url = url
         end
       end
+
+      # Replaces non-ASCII characters by their unicode escape sequence.
+      # Keeps other characters as is.
+      # @return A clean String.
+      def self.convert_to_unicode_escape(string)
+        unicode_escape_string = ''.dup
+        string.each_char do |char|
+          unicode_escape_string << if char.bytesize > 1
+                                     "\\u#{char.unpack1('U').to_s(16).rjust(4, '0')}"
+                                   else
+                                     char
+                                   end
+        end
+        unicode_escape_string
+      end
     end
   end
 end