✨ add Cropper support

Author: ianardee

.pylintrc

@@ -249,7 +249,7 @@ indent-after-paren=4
 indent-string='    '
 
 # Maximum number of characters on a single line.
-max-line-length=100
+max-line-length=120
 
 # Maximum number of lines in a module.
 max-module-lines=1000

mindee/client.py

@@ -2,6 +2,7 @@
 from typing import BinaryIO, Dict, Optional, Type
 
 from mindee.documents import (
+    CropperV1,
     CustomV1,
     FinancialV1,
     InvoiceV3,
@@ -53,19 +54,33 @@ def parse(
         include_words: bool = False,
         close_file: bool = True,
         page_options: Optional[PageOptions] = None,
+        cropper: bool = False,
     ) -> PredictResponse[TypeDocument]:
         """
         Call prediction API on the document and parse the results.
 
         :param document_class: The document class to use.
-          The response object will be instanced based on this parameter.
-        :param endpoint_name: For custom documents, the "API name" field
-          in the "Settings" page of the API Builder.
-        :param account_name: API username, the endpoint owner
-        :param include_words: Include all the words of the document in the response
+            The response object will be instantiated based on this parameter.
+
+        :param endpoint_name: For custom endpoints, the "API name" field in the "Settings" page of the API Builder.
+            Do not set for standard (off the shelf) endpoints.
+
+        :param account_name: For custom endpoints, your account or organization username on the API Builder.
+            This is normally not required unless you have a custom endpoint which has the
+            same name as standard (off the shelf) endpoint.
+            Do not set for standard (off the shelf) endpoints.
+
+        :param include_words: Whether to include the full text for each page.
+            This performs a full OCR operation on the server and will increase response time.
+
         :param close_file: Whether to ``close()`` the file after parsing it.
           Set to ``False`` if you need to access the file after this operation.
-        :param page_options: Options for preparing multipage documents.
+
+        :param page_options: If set, remove pages from the document as specified.
+            This is done before sending the file to the server and is useful to avoid page limitations.
+
+        :param cropper: Whether to include cropper results for each page.
+            This performs a cropping operation on the server and will increase response time.
         """
         bound_classname = get_bound_classname(document_class)
         if bound_classname != CustomV1.__name__:
@@ -108,14 +123,17 @@ def parse(
                 page_options.on_min_pages,
                 page_options.page_indexes,
             )
-        return self._make_request(document_class, doc_config, include_words, close_file)
+        return self._make_request(
+            document_class, doc_config, include_words, close_file, cropper
+        )
 
     def _make_request(
         self,
         document_class: TypeDocument,
         doc_config: DocumentConfig,
         include_words: bool,
         close_file: bool,
+        cropper: bool,
     ) -> PredictResponse[TypeDocument]:
         if get_bound_classname(document_class) != doc_config.document_class.__name__:
             raise RuntimeError("Document class mismatch!")
@@ -125,6 +143,7 @@ def _make_request(
             self.input_doc,
             include_words=include_words,
             close_file=close_file,
+            cropper=cropper,
         )
 
         dict_response = response.json()
@@ -228,6 +247,15 @@ def _init_default_endpoints(self) -> None:
                     )
                 ],
             ),
+            (OTS_OWNER, CropperV1.__name__): DocumentConfig(
+                document_type="cropper_v1",
+                document_class=CropperV1,
+                endpoints=[
+                    StandardEndpoint(
+                        url_name="cropper", version="1", api_key=self.api_key
+                    )
+                ],
+            ),
         }
 
     def add_endpoint(

mindee/documents/__init__.py

@@ -1,4 +1,5 @@
 from mindee.documents import us
+from mindee.documents.cropper import CropperV1, TypeCropperV1
 from mindee.documents.custom import CustomV1, TypeCustomV1
 from mindee.documents.financial import FinancialV1, TypeFinancialV1
 from mindee.documents.invoice import InvoiceV3, TypeInvoiceV3

mindee/documents/base.py

@@ -4,6 +4,7 @@
 
 from mindee.endpoints import Endpoint
 from mindee.fields.orientation import OrientationField
+from mindee.fields.position import PositionField
 from mindee.input.sources import InputSource
 
 TypeApiPrediction = Dict[str, Any]
@@ -40,6 +41,8 @@ class Document:
     # orientation is only present on page-level, not document-level
     orientation: Optional[OrientationField] = None
     """Page orientation"""
+    cropper: List[PositionField]
+    """Cropper results"""
 
     def __init__(
         self,
@@ -56,6 +59,7 @@ def __init__(
         self.type = document_type
 
         if page_n is not None:
+            self._set_extras(api_prediction["extras"])
             self.orientation = OrientationField(
                 api_prediction["orientation"], page_n=page_n
             )
@@ -66,6 +70,7 @@ def request(
         input_source: InputSource,
         include_words: bool = False,
         close_file: bool = True,
+        cropper: bool = False,
     ):
         """
         Make request to prediction endpoint.
@@ -74,8 +79,19 @@ def request(
         :param endpoints: Endpoints config
         :param include_words: Include Mindee vision words in http_response
         :param close_file: Whether to `close()` the file after parsing it.
+        :param cropper: Including Mindee cropper results.
         """
-        return endpoints[0].predict_req_post(input_source, include_words, close_file)
+        return endpoints[0].predict_req_post(
+            input_source, include_words, close_file, cropper=cropper
+        )
+
+    def _set_extras(self, extras: TypeApiPrediction):
+        self.cropper = []
+        try:
+            for crop in extras["cropper"]["cropping"]:
+                self.cropper.append(PositionField(crop))
+        except KeyError:
+            pass
 
     def _build_from_api_prediction(
         self, api_prediction: TypeApiPrediction, page_n: Optional[int] = None

mindee/documents/cropper/__init__.py

@@ -0,0 +1 @@
+from .cropper_v1 import CropperV1, TypeCropperV1

mindee/documents/cropper/cropper_v1.py

@@ -0,0 +1,60 @@
+from typing import List, Optional, TypeVar
+
+from mindee.documents.base import Document, TypeApiPrediction, clean_out_string
+from mindee.fields.position import PositionField
+
+
+class CropperV1(Document):
+    cropping: List[PositionField]
+    """List of all detected cropped elements in the image"""
+
+    def __init__(
+        self,
+        api_prediction: TypeApiPrediction,
+        input_source=None,
+        page_n: Optional[int] = None,
+        document_type="cropper",
+    ):
+        """
+        Custom document object.
+
+        :param document_type: Document type
+        :param api_prediction: Raw prediction from HTTP response
+        :param input_source: Input object
+        :param page_n: Page number for multi pages pdf input
+        """
+        super().__init__(
+            input_source=input_source,
+            document_type=document_type,
+            api_prediction=api_prediction,
+            page_n=page_n,
+        )
+        self._build_from_api_prediction(api_prediction["prediction"], page_n=page_n)
+
+    def _build_from_api_prediction(
+        self, api_prediction: TypeApiPrediction, page_n: Optional[int] = None
+    ) -> None:
+        """Build the document from an API response JSON."""
+        self.cropping = []
+
+        # cropping is only present on pages
+        if page_n is None:
+            return
+
+        for crop in api_prediction["cropping"]:
+            self.cropping.append(PositionField(prediction=crop))
+
+    def _checklist(self) -> None:
+        pass
+
+    def __str__(self):
+        cropping = "\n          ".join([str(crop) for crop in self.cropping])
+        return clean_out_string(
+            "----- Cropper Data -----\n"
+            f"Filename: {self.filename or ''}\n"
+            f"Cropping: {cropping}\n"
+            "------------------------"
+        )
+
+
+TypeCropperV1 = TypeVar("TypeCropperV1", bound=CropperV1)

mindee/documents/financial/financial_v1.py

@@ -11,6 +11,7 @@
 from mindee.fields.payment_details import PaymentDetails
 from mindee.fields.tax import TaxField
 from mindee.fields.text import TextField
+from mindee.input.sources import InputSource
 
 
 class FinancialV1(Document):
@@ -150,9 +151,10 @@ def __str__(self) -> str:
     @staticmethod
     def request(
         endpoints: List[Endpoint],
-        input_source,
+        input_source: InputSource,
         include_words: bool = False,
         close_file: bool = True,
+        cropper: bool = False,
     ):
         """
         Make request to prediction endpoint.
@@ -161,14 +163,15 @@ def request(
         :param endpoints: Endpoints config
         :param include_words: Include Mindee vision words in http_response
         :param close_file: Whether to `close()` the file after parsing it.
+        :param cropper: Including Mindee cropper results.
         """
         if "pdf" in input_source.file_mimetype:
             # invoices is index 0, receipts 1 (this should be cleaned up)
             index = 0
         else:
             index = 1
         return endpoints[index].predict_req_post(
-            input_source, include_words, close_file
+            input_source, include_words, close_file, cropper=cropper
         )
 
     def _checklist(self) -> None:

mindee/documents/us/bank_check/bank_check_v1.py

@@ -73,9 +73,7 @@ def _build_from_api_prediction(
         ]
 
     def __str__(self) -> str:
-        payees = ", ".join(
-            [payee.value if payee.value is not None else "" for payee in self.payees]
-        )
+        payees = ", ".join([str(payee) for payee in self.payees])
         return clean_out_string(
             "----- US Bank Check V1 -----\n"
             f"Filename: {self.filename or ''}\n"

mindee/endpoints.py

@@ -84,25 +84,32 @@ def predict_req_post(
         input_source: InputSource,
         include_words: bool = False,
         close_file: bool = True,
+        cropper: bool = False,
     ) -> requests.Response:
         """
         Make a request to POST a document for prediction.
 
         :param input_source: Input object
         :param include_words: Include raw OCR words in the response
         :param close_file: Whether to `close()` the file after parsing it.
+        :param cropper: Including Mindee cropping results.
         :return: requests response
         """
         files = {"document": input_source.read_contents(close_file)}
         data = {}
         if include_words:
             data["include_mvision"] = "true"
 
+        params = {}
+        if cropper:
+            params["cropper"] = "true"
+
         response = requests.post(
             f"{self._url_root}/predict",
             files=files,
             headers=self.base_headers,
             data=data,
+            params=params,
             timeout=self.timeout,
         )
         return response

mindee/fields/position.py

@@ -12,10 +12,15 @@
 
 class PositionField(BaseField):
     value: Optional[Polygon] = None
+    """Polygon of cropped area, identical to the ``polygon`` property."""
     polygon: Optional[Polygon] = None
+    """Polygon of cropped area"""
     quadrangle: Optional[Quadrilateral] = None
+    """Quadrangle of cropped area (does not exceed the canvas)"""
     rectangle: Optional[Quadrilateral] = None
+    """Oriented rectangle of cropped area (may exceed the canvas)"""
     bounding_box: Optional[Quadrilateral] = None
+    """Straight rectangle of cropped area (does not exceed the canvas)"""
 
     def __init__(
         self,
@@ -57,3 +62,8 @@ def get_polygon(key: str) -> Optional[Polygon]:
         self.polygon = get_polygon("polygon")
 
         self.value = self.polygon
+
+    def __str__(self) -> str:
+        if self.polygon is None:
+            return ""
+        return f"Polygon with {len(self.polygon)} points."