Merge pull request #181 from ThomasDelteil/improve_analyze_expense

Improving analyze expense support

Author: ThomasDelteil

README.md

@@ -89,7 +89,7 @@ print(document.identity_documents[0].get("FIRST_NAME"))
 
 ```py
 document = extractor.analyze_expense(file_source="tests/fixtures/receipt.jpg")
-print(document.expense_documents[0].get("TOTAL").text)
+print(document.expense_documents[0].summary_fields.get("TOTAL")[0].text)
 # '$1810.46'
 ```
 

docs/source/notebooks/using_analyze_expense.ipynb

@@ -143,4 +143,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/source/notebooks/using_analyze_id.ipynb

@@ -37,7 +37,10 @@ def test_analyze_expense_from_path(self):
 
         self.assertIsInstance(document, Document)
         self.assertEqual(len(document.pages), 1)
-        self.assertEqual(document.expense_documents[0].get("TOTAL").text, "$1810.46")
+        self.assertEqual(document.expense_documents[0].summary_fields.TOTAL[0].value.text, "$1810.46")
+        self.assertEqual(len(document.expense_documents[0].summary_groups.VENDOR), 2)
+        self.assertEqual(len(document.expense_documents[0].line_items_groups[0].to_pandas()), 4,
+                         "There are 4 line item in the receipts")
 
     def test_analyze_expense_from_image(self):
         # Testing local single image input
@@ -50,7 +53,10 @@ def test_analyze_expense_from_image(self):
 
         self.assertIsInstance(document, Document)
         self.assertEqual(len(document.pages), 1)
-        self.assertEqual(document.expense_documents[0].get("TOTAL").text, "$1810.46")
+        self.assertEqual(document.expense_documents[0].summary_fields.TOTAL[0].value.text, "$1810.46")
+        self.assertEqual(len(document.expense_documents[0].summary_groups.VENDOR), 2)
+        self.assertEqual(len(document.expense_documents[0].line_items_groups[0].to_pandas()), 4,
+                         "There are 4 line item in the receipts")
 
 if __name__ == "__main__":
     test = TestTextractorAnalyzeExpense()

tests/fixtures/invoice.png

@@ -211,6 +211,68 @@ class AnalyzeIDFields(Enum):
     # Only available in passports
     PLACE_OF_BIRTH = "PLACE_OF_BIRTH"
 
+class AnalyzeExpenseLineItemFields(Enum):
+    ITEM = "ITEM"
+    PRICE = "PRICE"
+    PRODUCT_CODE = "PRODUCT_CODE"
+    QUANTITY = "QUANTITY"
+    UNIT_PRICE = "UNIT_PRICE"
+    EXPENSE_ROW = "EXPENSE_ROW"
+
+class AnalyzeExpenseFields(Enum):
+    ACCOUNT_NUMBER = "ACCOUNT_NUMBER"
+    ADDRESS = "ADDRESS"
+    ADDRESS_BLOCK = "ADDRESS_BLOCK"
+    AMOUNT_DUE = "AMOUNT_DUE"
+    AMOUNT_PAID = "AMOUNT_PAID"
+    CITY = "CITY"
+    COUNTRY = "COUNTRY"
+    CUSTOMER_NUMBER = "CUSTOMER_NUMBER"
+    DELIVERY_DATE = "DELIVERY_DATE"
+    DISCOUNT = "DISCOUNT"
+    DUE_DATE = "DUE_DATE"
+    GRATUITY = "GRATUITY"
+    INVOICE_RECEIPT_DATE = "INVOICE_RECEIPT_DATE"
+    INVOICE_RECEIPT_ID = "INVOICE_RECEIPT_ID"
+    NAME = "NAME"
+    ORDER_DATE = "ORDER_DATE"
+    OTHER = "OTHER"
+    PAYMENT_TERMS = "PAYMENT_TERMS"
+    PO_NUMBER = "PO_NUMBER"
+    PRIOR_BALANCE = "PRIOR_BALANCE"
+    RECEIVER_ABN_NUMBER = "RECEIVER_ABN_NUMBER"
+    RECEIVER_ADDRESS = "RECEIVER_ADDRESS"
+    RECEIVER_GST_NUMBER = "RECEIVER_GST_NUMBER"
+    RECEIVER_NAME = "RECEIVER_NAME"
+    RECEIVER_PAN_NUMBER = "RECEIVER_PAN_NUMBER"
+    RECEIVER_PHONE = "RECEIVER_PHONE"
+    RECEIVER_VAT_NUMBER = "RECEIVER_VAT_NUMBER"
+    SERVICE_CHARGE = "SERVICE_CHARGE"
+    SHIPPING_HANDLING_CHARGE = "SHIPPING_HANDLING_CHARGE"
+    STATE = "STATE"
+    STREET = "STREET"
+    SUBTOTAL = "SUBTOTAL"
+    TAX = "TAX"
+    TAX_PAYER_ID = "TAX_PAYER_ID"
+    TOTAL = "TOTAL"
+    VENDOR_ABN_NUMBER = "VENDOR_ABN_NUMBER"
+    VENDOR_ADDRESS = "VENDOR_ADDRESS"
+    VENDOR_GST_NUMBER = "VENDOR_GST_NUMBER"
+    VENDOR_NAME = "VENDOR_NAME"
+    VENDOR_PAN_NUMBER = "VENDOR_PAN_NUMBER"
+    VENDOR_PHONE = "VENDOR_PHONE"
+    VENDOR_URL = "VENDOR_URL"
+    VENDOR_VAT_NUMBER = "VENDOR_VAT_NUMBER"
+    ZIP_CODE = "ZIP_CODE"
+
+class AnalyzeExpenseFieldsGroup(Enum):
+    RECEIVER = "RECEIVER"
+    RECEIVER_BILL_TO = "RECEIVER_BILL_TO"
+    RECEIVER_SHIP_TO = "RECEIVER_SHIP_TO"
+    RECEIVER_SOLD_TO = "RECEIVER_SOLD_TO"
+    VENDOR = "VENDOR"
+    VENDOR_REMIT_TO = "VENDOR_REMIT_TO"
+    VENDOR_SUPPLIER = "VENDOR_SUPPLIER"
 
 class CLIPrint(Enum):
     ALL = 0

tests/test_analyze_expense.py

@@ -2,7 +2,7 @@
 on the image of the document page."""
 
 from abc import ABC
-from typing import Tuple
+from typing import Tuple, List
 
 try:
     import numpy as np
@@ -104,6 +104,24 @@ def _denormalize(
 
         return x, y, width, height
 
+    @classmethod
+    def enclosing_bbox(cls, bboxes, spatial_object:SpatialObject=None):
+        """
+        :param bboxes [BoundingBox]: list of bounding boxes
+        :param spatial_object SpatialObject: spatial object to be added to the returned bbox
+        :return:
+        """
+        x1, y1, x2, y2 = float('inf'), float('inf'), float('-inf'), float('-inf')
+        assert any([bbox is not None for bbox in bboxes]), "At least one bounding box needs to be non-null"
+        for bbox in bboxes:
+            if bbox is not None:
+                x1 = min(x1, bbox.x)
+                x2 = max(x2, bbox.x + bbox.width)
+                y1 = min(y1, bbox.y)
+                y2 = max(y2, bbox.y + bbox.height)
+        return BoundingBox(x1, y1, x2-x1, y2-y1, spatial_object=spatial_object)
+
+
     @classmethod
     def _from_dict(
         cls, bbox_dict: Dict[str, float], spatial_object: SpatialObject = None

textractor/data/constants.py

@@ -1,98 +1,138 @@
 """The ExpenseDocument class is the object representation of an AnalyzeID response. It is similar to a dictionary. Despite its name it does not inherit from Document as the AnalyzeID response does not contains position information."""
 
-import os
-from typing import List, Dict, Union
-from textractor.entities.bbox import SpatialObject
-from textractor.entities.expense_field import ExpenseField
+from collections import defaultdict
+from typing import List
 
-from textractor.exceptions import InputError
+from textractor.data.constants import AnalyzeExpenseFieldsGroup as AEFieldsGroup, AnalyzeExpenseFields as AEFields
+from textractor.entities.expense_field import ExpenseField, LineItemGroup, BoundingBox, DocumentEntity
 
 
-class ExpenseDocument(SpatialObject):
+class Fields(dict):
+    """
+    Dictionary to hold Summary Fields
+    Dynamically added properties to enable ease of discovery
+    """
+    def __init__(self):
+        super(Fields, self).__init__()
+        # We dynamically set the fields to None to help with discoverability
+        for field in AEFields:
+            setattr(self.__class__, field.name, property(lambda self, field=field: self.get(field.name)))
+
+    def __repr__(self):
+        output = ""
+        for key, value in self.items():
+            output += f"{key}:"
+            offset = 0
+            if len(value):
+                output += "\n"
+                offset = 4
+            for field in value:
+                output += " "*offset + str(field).replace('\n', '\\n') + "\n"
+
+        return output
+
+class FieldsGroups(dict):
+    """
+    Summary Fields Group dictionary
+    {GROUP_KEY_NAME: {GROUP_ID_1: [SUMMARY_FIELD1, SUMMARY_FIELD2]}}
+    """
+
+    def __init__(self):
+        super(FieldsGroups, self).__init__()
+        for group in AEFieldsGroup:
+            setattr(self.__class__, group.name, property(lambda self, group=group: self.get(group.name)))
+
+    def __repr__(self):
+        output = ""
+        for key, group in self.items():
+            output += f"{key}: \n"
+            for block in group.values():
+                for expense_field in block:
+                    output +=  "  " + str(expense_field).replace('\n', '\\n') + "\n"
+                output += "\n"
+            output += "\n"
+        return output
+
+    def get_group_bboxes(self, key: str):
+        """
+        Return the enclosing bboxes for each group for a given group key
+        :param key: Group key e.g VENDOR
+        :return:
+        """
+        bboxes = []
+        for groups in self.get(key, {}).values():
+            bboxes.append(BoundingBox.enclosing_bbox([f.bbox for f in groups]))
+        return bboxes
+
+
+class ExpenseDocument(DocumentEntity):
     """
     Represents the description of a single expense document.
     """
 
     def __init__(
-        self, summary_fields: List[ExpenseField], line_item_fields: List[ExpenseField]
+        self, summary_fields: List[ExpenseField], line_items_groups: List[LineItemGroup], bounding_box: BoundingBox, page:int
     ):
         """
-        Creates a new document, ideally containing entity objects pertaining to each page.
-
-        :param num_pages: Number of pages in the input Document.
-        """
-        super().__init__(width=0, height=0)
-        self._summary_fields = ExpenseDocument._fields_to_dict(summary_fields)
-        self._line_item_fields = ExpenseDocument._fields_to_dict(line_item_fields)
-
-    @classmethod
-    def _fields_to_dict(
-        cls, fields: Union[List[ExpenseField], List[Dict]]
-    ) -> Dict[str, ExpenseField]:
-        """Converts a list of expense field to a dictionary of ExpenseField
-
-        :param fields: Expense fields
-        :type fields: Union[List[ExpenseField], List[Dict]]
-        :raises InputError: Raised if `fields` is not of of type Union[List[ExpenseField], List[Dict]])
-        :return: Dictionary that maps keys to ExpenseFields
-        :rtype: Dict[str, ExpenseField]
+        :param summary_fields: List of ExpenseFields, not including line item ones
+        :param line_items_groups: Groups of Line Item tables
+        :param bounding_box: The bounding box for that ExpenseDocument
+        :param page: The page where that document is
         """
-        if not fields:
-            return {}
-        elif isinstance(fields, list) and isinstance(fields[0], ExpenseField):
-            return {
-                (
-                    expense_field.key.text
-                    if expense_field.key else
-                    expense_field.type.text
-                ): expense_field
-                for expense_field in fields
-            }
-        elif isinstance(fields, list) and isinstance(fields[0], dict):
-            field_dict = {}
-            for expense_field in fields.values():
-                field_dict[expense_field["key"]] = ExpenseField(
-                    expense_field["key"],
-                    expense_field["value"],
-                    expense_field["confidence"],
-                )
-            return field_dict
-        else:
-            raise InputError(
-                f"fields needs to be a list of ExpenseFields or a list of dictionaries, not {type(fields)}"
-            )
+        super().__init__('', bbox=bounding_box)
+        self._summary_fields_list = summary_fields
+        self._line_items_groups = line_items_groups
+        self.summary_fields = Fields()
+        self.summary_groups = FieldsGroups()
+        self._unnormalized_fields = defaultdict(list)
+        self._assign_summary_fields()
+        self._page = page
 
     @property
-    def summary_fields(self) -> Dict[str, ExpenseField]:
-        """Returns a dictionary of summary fields
-
-        :return: Dictionary of summary fields
-        :rtype: Dict[str, ExpenseField]
-        """
-        return self._summary_fields
-
-    @summary_fields.setter
-    def summary_fields(self, summary_fields: Dict[str, ExpenseField]):
-        """Setter for summary_fields
-
-        :param summary_fields: Summary fields
-        :type summary_fields: Dict[str, ExpenseField]
-        """
-        self._summary_fields = summary_fields
+    def page(self):
+        return self._page
 
-    def __getitem__(self, key) -> str:
-        return self._summary_fields.get(key, self._line_item_fields.get(key)).value
+    @property
+    def bbox(self):
+        return BoundingBox.enclosing_bbox([s.bbox for s in self._summary_fields_list]+[g.bbox for g in self._line_items_groups], spatial_object=self._bbox.spatial_object)
+
+    def _assign_summary_fields(self):
+        for field in self._summary_fields_list:
+            # We assign them as properties
+            name = field.type.text
+
+            # Adding it to the dicts of normalized field
+            if name in self.summary_fields:
+                self.summary_fields[name].append(field)
+            else:
+                self.summary_fields[name] = [field]
+
+            # Adding it to the dicts of unnormalized fields using the provided key
+            key = field.key.text if field.key else ""
+            self._unnormalized_fields[key].append(field)
+
+            # If the field is part of a group, we add it to the list of fields for that group
+            for group_properties in field.group_properties:
+                for property_type in group_properties.types:
+                    if property_type not in self.summary_groups:
+                        self.summary_groups[property_type] = dict()
+                    if group_properties.id not in self.summary_groups[property_type]:
+                        self.summary_groups[property_type][group_properties.id] = []
+                    self.summary_groups[property_type][group_properties.id].append(field)
 
-    def get(self, key) -> Union[str, None]:
-        result = self._summary_fields.get(key, self._line_item_fields.get(key))
-        if result is None:
-            return None
-        return result.value
+    @property
+    def summary_fields_list(self):
+        return self._summary_fields_list
 
-    def keys(self) -> List[str]:
-        return list(self._summary_fields.keys())
+    @property
+    def line_items_groups(self) -> List[LineItemGroup]:
+        return self._line_items_groups
 
     def __repr__(self) -> str:
-        return os.linesep.join(
-            [f"{str(k)}: {str(v)}" for k, v in self._summary_fields.items()]
-        )
+        output = f"Summary fields: {len(self.summary_fields)}\n"
+        output += "Line Item Groups:"
+        output += "\n" if len(self.line_items_groups) > 1 else " "
+        for i, line_item in enumerate(self.line_items_groups):
+            output += f"index {line_item.index}: {len(line_item.rows)} row{'s' if (len(line_item.rows) > 1) else ''}"
+        return output
+