chore: Move coordinate details from Element model to a metadata model (#827)

Author: six5532one

CHANGELOG.md

@@ -1,11 +1,15 @@
-## 0.7.13-dev0
+## 0.8.0-dev0
 
 ### Enhancements
 
 ### Features
 
 ### Fixes
 
+### BREAKING CHANGES
+
+* Information about an element's location is no longer returned as top-level attributes of an element. Instead, it is returned in the `coordinates` attribute of the element's metadata.
+
 ## 0.7.12
 
 ### Enhancements
@@ -28,7 +32,7 @@
 
 * More deterministic element ordering when using `hi_res` PDF parsing strategy (from unstructured-inference bump to 0.5.4)
 * Make large model available (from unstructured-inference bump to 0.5.3)
-* Combine inferred elements with extracted elements (from unstructured-inference bump to 0.5.2) 
+* Combine inferred elements with extracted elements (from unstructured-inference bump to 0.5.2)
 * `partition_email` and `partition_msg` will now process attachments if `process_attachments=True`
   and a attachment partitioning functions is passed through with `attachment_partitioner=partition`.
 

docs/source/bricks.rst

@@ -1531,7 +1531,6 @@ The output will look like:
             {
                 "data": {
                     "element_id": "ad270eefd1cc68d15f4d3e51666d4dc8",
-                    "coordinates": None,
                     "text": "A Wonderful Story About A Fox",
                     "type": "Title",
                 },
@@ -1540,7 +1539,6 @@ The output will look like:
             {
                 "data": {
                     "element_id": "8275769fdd1804f9f2b55ad3c9b0ef1b",
-                    "coordinates": None,
                     "text": "A fox ran into the chicken coop and the chickens flew off!",
                     "type": "NarrativeText",
                 },

docs/source/getting_started.rst

@@ -110,43 +110,6 @@ The following code shows how you can limit your output to only narrative text wi
 	        print("\n")
 
 
-####################
-Element coordinates
-####################
-
-Some document types support location data for the elements, usually in the form of bounding boxes. 
-The ``coordinates`` property of an ``Element`` stores the coordinates of the corners of the 
-bounding box starting from the top left corner and proceeding counter-clockwise. If the 
-coordinates are not available, the ``coordinates`` property is ``None``. 
-
-The coordinates have an associated coordinate system. A typical example of a coordinate system is 
-``PixelSpace``, which is used for representing the coordinates of images. The coordinates 
-represent pixels, the origin is in the top left and the ``y`` coordinate increases in the 
-downward direction. Information about the coordinate system is found in the 
-``Element.coordinate_system`` property, including the coordinate system name, a description, the 
-layout width, and the layout height.
-
-The coordinates of an element can be changed to a new coordinate system by using the 
-``Element.convert_coordinates_to_new_system`` method. If the ``in_place`` flag is ``True``, the 
-coordinate system and coordinates of the element are updated in place and the new coordinates are 
-returned. If the ``in_place`` flag is ``False``, only the altered coordinates are returned.
-
-.. code:: python
-
-	from unstructured.documents.elements import Element
-	from unstructured.documents.coordinates import PixelSpace, RelativeCoordinateSystem
-
-	coordinates = ((10, 10), (10, 100), (200, 100), (200, 10))
-	coordinate_system = PixelSpace(width=850, height=1100)
-	element = Element(coordinates=coordinates, coordinate_system=coordinate_system)
-	print(element.coordinate_system)
-	print(element.coordinate)
-	element.convert_coordinates_to_new_system(RelativeCoordinateSystem(), in_place=True)
-	# Should now be in terms of new coordinate system
-	print(element.coordinate_system)
-	print(element.coordinate)
-
-
 ####################
 Serializing Elements
 ####################
@@ -173,7 +136,7 @@ serializing and deserializing an ``Element`` list.
 
     elements_to_json(elements, filename=filename)
     new_elements = elements_from_json(filename=filename)
-    
+
     # alternatively, one can also serialize/deserialize to/from a string with:
     serialized_elements_json = elements_to_json(elements)
     new_elements = elements_from_json(text=serialized_elements_json)

docs/source/metadata.rst

@@ -18,6 +18,48 @@ the source file:
 * ``page_number``
 
 
+####################
+Element coordinates
+####################
+
+Some document types support location data for the elements, usually in the form of bounding boxes.
+If it exists, an element's location data is available with ``element.metadata.coordinates``.
+
+The ``coordinates`` property of an ``ElementMetadata`` stores:
+* points: These specify the corners of the bounding box starting from the top left corner and
+proceeding counter-clockwise. The points represent pixels, the origin is in the top left and
+the ``y`` coordinate increases in the downward direction.
+* system: The points have an associated coordinate system. A typical example of a coordinate system is
+``PixelSpace``, which is used for representing the coordinates of images. The coordinate system has a
+name, orientation, layout width, and layout height.
+
+Information about the element’s coordinates (including the coordinate system name, coordinate points,
+the layout width, and the layout height) can be accessed with `element.to_dict()["metadata"]["coordinates"]`.
+
+The coordinates of an element can be changed to a new coordinate system by using the
+``Element.convert_coordinates_to_new_system`` method. If the ``in_place`` flag is ``True``, the
+coordinate system and points of the element are updated in place and the new coordinates are
+returned. If the ``in_place`` flag is ``False``, only the altered coordinates are returned.
+
+.. code:: python
+
+	from unstructured.documents.elements import Element
+	from unstructured.documents.coordinates import PixelSpace, RelativeCoordinateSystem
+
+	coordinates = ((10, 10), (10, 100), (200, 100), (200, 10))
+	coordinate_system = PixelSpace(width=850, height=1100)
+	element = Element(coordinates=coordinates, coordinate_system=coordinate_system)
+	print(element.metadata.coordinates.to_dict())
+	print(element.metadata.coordinates.system.orientation)
+	print(element.metadata.coordinates.system.width)
+	print(element.metadata.coordinates.system.height)
+	element.convert_coordinates_to_new_system(RelativeCoordinateSystem(), in_place=True)
+	# Should now be in terms of new coordinate system
+	print(element.metadata.coordinates.to_dict())
+	print(element.metadata.coordinates.system.orientation)
+	print(element.metadata.coordinates.system.width)
+	print(element.metadata.coordinates.system.height)
+
 Email
 -----
 

test_unstructured/documents/test_elements.py

@@ -9,7 +9,7 @@
     Orientation,
     RelativeCoordinateSystem,
 )
-from unstructured.documents.elements import Element, NoID, Text
+from unstructured.documents.elements import CoordinatesMetadata, Element, NoID, Text
 
 
 def test_text_id():
@@ -89,34 +89,80 @@ def test_convert_coordinates_to_new_system(
     for new_coord, expected_coord in zip(new_coords, expected_coords):
         new_coord == pytest.approx(expected_coord)
     element.convert_coordinates_to_new_system(coord2, in_place=True)
-    for new_coord, expected_coord in zip(element.coordinates, expected_coords):
+    for new_coord, expected_coord in zip(element.metadata.coordinates.points, expected_coords):
         assert new_coord == pytest.approx(expected_coord)
-    assert element._coordinate_system == coord2
+    assert element.metadata.coordinates.system == coord2
 
 
-@pytest.mark.parametrize(
-    ("coordinates", "coordinate_system"),
-    [
-        (None, None),
-        (((1, 2), (1, 4), (3, 4), (3, 2)), None),
-        (None, RelativeCoordinateSystem()),
-    ],
-)
-def test_convert_coordinate_to_new_system_none(coordinates, coordinate_system):
-    element = Element(coordinates=coordinates, coordinate_system=coordinate_system)
+def test_convert_coordinate_to_new_system_none():
+    element = Element(coordinates=None, coordinate_system=None)
     coord = CoordinateSystem(100, 200)
     coord.orientation = Orientation.SCREEN
     assert element.convert_coordinates_to_new_system(coord) is None
 
 
-def test_coordinate_system():
+def test_element_constructor_coordinates_all_present():
     coordinates = ((1, 2), (1, 4), (3, 4), (3, 2))
     coordinate_system = RelativeCoordinateSystem()
     element = Element(coordinates=coordinates, coordinate_system=coordinate_system)
+    expected_coordinates_metadata = CoordinatesMetadata(
+        points=coordinates,
+        system=coordinate_system,
+    )
+    assert element.metadata.coordinates == expected_coordinates_metadata
+
+
+def test_element_constructor_coordinates_points_absent():
+    with pytest.raises(ValueError) as exc_info:
+        Element(coordinate_system=RelativeCoordinateSystem())
+    assert (
+        str(exc_info.value)
+        == "Coordinates points should not exist without coordinates system and vice versa."
+    )
+
+
+def test_element_constructor_coordinates_system_absent():
+    with pytest.raises(ValueError) as exc_info:
+        Element(coordinates=((1, 2), (1, 4), (3, 4), (3, 2)))
+    assert (
+        str(exc_info.value)
+        == "Coordinates points should not exist without coordinates system and vice versa."
+    )
+
+
+def test_coordinate_metadata_serdes():
+    coordinates = ((1, 2), (1, 4), (3, 4), (3, 2))
+    coordinate_system = RelativeCoordinateSystem()
+    coordinates_metadata = CoordinatesMetadata(points=coordinates, system=coordinate_system)
     expected_schema = {
-        "name": "RelativeCoordinateSystem",
-        "description": RelativeCoordinateSystem.__doc__,
-        "layout_width": 1,
         "layout_height": 1,
+        "layout_width": 1,
+        "points": ((1, 2), (1, 4), (3, 4), (3, 2)),
+        "system": "RelativeCoordinateSystem",
+    }
+    coordinates_metadata_dict = coordinates_metadata.to_dict()
+    assert coordinates_metadata_dict == expected_schema
+    assert CoordinatesMetadata.from_dict(coordinates_metadata_dict) == coordinates_metadata
+
+
+def test_element_to_dict():
+    coordinates = ((1, 2), (1, 4), (3, 4), (3, 2))
+    coordinate_system = RelativeCoordinateSystem()
+    element = Element(
+        element_id="awt32t1",
+        coordinates=coordinates,
+        coordinate_system=coordinate_system,
+    )
+    expected = {
+        "metadata": {
+            "coordinates": {
+                "layout_height": 1,
+                "layout_width": 1,
+                "points": ((1, 2), (1, 4), (3, 4), (3, 2)),
+                "system": "RelativeCoordinateSystem",
+            },
+        },
+        "type": None,
+        "element_id": "awt32t1",
     }
-    assert element.coordinate_system == expected_schema
+    assert element.to_dict() == expected

test_unstructured/partition/test_auto.py

@@ -214,11 +214,6 @@ def test_auto_partition_json_from_filename():
         json_data = json.load(json_f)
     json_elems = json.loads(elements_to_json(partition(filename=filename, strategy="hi_res")))
     for elem in json_elems:
-        # coordinates are always in the element data structures, even if None
-        elem.pop("coordinates")
-        elem.pop("coordinate_system")
-        elem.pop("layout_width")
-        elem.pop("layout_height")
         elem.pop("metadata")
     for elem in json_data:
         elem.pop("metadata")