python-doctr 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

doctr/utils/geometry.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2021-2023, Mindee.
+# Copyright (C) 2021-2024, Mindee.
 
 # This program is licensed under the Apache License 2.0.
 # See LICENSE or go to <https://opensource.org/licenses/Apache-2.0> for full license details.
@@ -29,10 +29,30 @@ __all__ = [
 
 
 def bbox_to_polygon(bbox: BoundingBox) -> Polygon4P:
+    """Convert a bounding box to a polygon
+
+    Args:
+    ----
+        bbox: a bounding box
+
+    Returns:
+    -------
+        a polygon
+    """
     return bbox[0], (bbox[1][0], bbox[0][1]), (bbox[0][0], bbox[1][1]), bbox[1]
 
 
 def polygon_to_bbox(polygon: Polygon4P) -> BoundingBox:
+    """Convert a polygon to a bounding box
+
+    Args:
+    ----
+        polygon: a polygon
+
+    Returns:
+    -------
+        a bounding box
+    """
     x, y = zip(*polygon)
     return (min(x), min(y)), (max(x), max(y))
 
@@ -40,12 +60,18 @@ def polygon_to_bbox(polygon: Polygon4P) -> BoundingBox:
 def resolve_enclosing_bbox(bboxes: Union[List[BoundingBox], np.ndarray]) -> Union[BoundingBox, np.ndarray]:
     """Compute enclosing bbox either from:
 
-    - an array of boxes: (*, 5), where boxes have this shape:
-    (xmin, ymin, xmax, ymax, score)
+    Args:
+    ----
+        bboxes: boxes in one of the following formats:
+
+            - an array of boxes: (*, 5), where boxes have this shape:
+            (xmin, ymin, xmax, ymax, score)
 
-    - a list of BoundingBox
+            - a list of BoundingBox
 
-    Return a (1, 5) array (enclosing boxarray), or a BoundingBox
+    Returns:
+    -------
+        a (1, 5) array (enclosing boxarray), or a BoundingBox
     """
     if isinstance(bboxes, np.ndarray):
         xmin, ymin, xmax, ymax, score = np.split(bboxes, 5, axis=1)
@@ -56,18 +82,41 @@ def resolve_enclosing_bbox(bboxes: Union[List[BoundingBox], np.ndarray]) -> Unio
 
 
 def resolve_enclosing_rbbox(rbboxes: List[np.ndarray], intermed_size: int = 1024) -> np.ndarray:
+    """Compute enclosing rotated bbox either from:
+
+    Args:
+    ----
+        rbboxes: boxes in one of the following formats:
+
+            - an array of boxes: (*, 5), where boxes have this shape:
+            (xmin, ymin, xmax, ymax, score)
+
+            - a list of BoundingBox
+        intermed_size: size of the intermediate image
+
+    Returns:
+    -------
+        a (1, 5) array (enclosing boxarray), or a BoundingBox
+    """
     cloud: np.ndarray = np.concatenate(rbboxes, axis=0)
     # Convert to absolute for minAreaRect
     cloud *= intermed_size
     rect = cv2.minAreaRect(cloud.astype(np.int32))
-    return cv2.boxPoints(rect) / intermed_size
+    return cv2.boxPoints(rect) / intermed_size  # type: ignore[operator]
 
 
 def rotate_abs_points(points: np.ndarray, angle: float = 0.0) -> np.ndarray:
     """Rotate points counter-clockwise.
-    Points: array of size (N, 2)
-    """
 
+    Args:
+    ----
+        points: array of size (N, 2)
+        angle: angle between -90 and +90 degrees
+
+    Returns:
+    -------
+        Rotated points
+    """
     angle_rad = angle * np.pi / 180.0  # compute radian angle for np functions
     rotation_mat = np.array(
         [[np.cos(angle_rad), -np.sin(angle_rad)], [np.sin(angle_rad), np.cos(angle_rad)]], dtype=points.dtype
@@ -79,19 +128,18 @@ def compute_expanded_shape(img_shape: Tuple[int, int], angle: float) -> Tuple[in
     """Compute the shape of an expanded rotated image
 
     Args:
+    ----
         img_shape: the height and width of the image
         angle: angle between -90 and +90 degrees
 
     Returns:
+    -------
         the height and width of the rotated image
     """
-
-    points: np.ndarray = np.array(
-        [
-            [img_shape[1] / 2, img_shape[0] / 2],
-            [-img_shape[1] / 2, img_shape[0] / 2],
-        ]
-    )
+    points: np.ndarray = np.array([
+        [img_shape[1] / 2, img_shape[0] / 2],
+        [-img_shape[1] / 2, img_shape[0] / 2],
+    ])
 
     rotated_points = rotate_abs_points(points, angle)
 
@@ -109,15 +157,16 @@ def rotate_abs_geoms(
     image center.
 
     Args:
-        boxes: (N, 4) or (N, 4, 2) array of ABSOLUTE coordinate boxes
+    ----
+        geoms: (N, 4) or (N, 4, 2) array of ABSOLUTE coordinate boxes
         angle: anti-clockwise rotation angle in degrees
         img_shape: the height and width of the image
         expand: whether the image should be padded to avoid information loss
 
     Returns:
+    -------
         A batch of rotated polygons (N, 4, 2)
     """
-
     # Switch to polygons
     polys = (
         np.stack([geoms[:, [0, 1]], geoms[:, [2, 1]], geoms[:, [2, 3]], geoms[:, [0, 3]]], axis=1)
@@ -147,14 +196,15 @@ def remap_boxes(loc_preds: np.ndarray, orig_shape: Tuple[int, int], dest_shape:
     coordinates after a resizing of the image.
 
     Args:
+    ----
         loc_preds: (N, 4, 2) array of RELATIVE loc_preds
         orig_shape: shape of the origin image
         dest_shape: shape of the destination image
 
     Returns:
+    -------
         A batch of rotated loc_preds (N, 4, 2) expressed in the destination referencial
     """
-
     if len(dest_shape) != 2:
         raise ValueError(f"Mask length should be 2, was found at: {len(dest_shape)}")
     if len(orig_shape) != 2:
@@ -181,15 +231,17 @@ def rotate_boxes(
     is done to remove the padding that is created by rotate_page(expand=True)
 
     Args:
+    ----
         loc_preds: (N, 5) or (N, 4, 2) array of RELATIVE boxes
         angle: angle between -90 and +90 degrees
         orig_shape: shape of the origin image
         min_angle: minimum angle to rotate boxes
+        target_shape: shape of the destination image
 
     Returns:
+    -------
         A batch of rotated boxes (N, 4, 2): or a batch of straight bounding boxes
     """
-
     # Change format of the boxes to rotated boxes
     _boxes = loc_preds.copy()
     if _boxes.ndim == 2:
@@ -234,21 +286,23 @@ def rotate_image(
     """Rotate an image counterclockwise by an given angle.
 
     Args:
+    ----
         image: numpy tensor to rotate
         angle: rotation angle in degrees, between -90 and +90
         expand: whether the image should be padded before the rotation
         preserve_origin_shape: if expand is set to True, resizes the final output to the original image size
 
     Returns:
+    -------
         Rotated array, padded by 0 by default.
     """
-
     # Compute the expanded padding
     exp_img: np.ndarray
     if expand:
         exp_shape = compute_expanded_shape(image.shape[:2], angle)  # type: ignore[arg-type]
-        h_pad, w_pad = int(max(0, ceil(exp_shape[0] - image.shape[0]))), int(
-            max(0, ceil(exp_shape[1] - image.shape[1]))
+        h_pad, w_pad = (
+            int(max(0, ceil(exp_shape[0] - image.shape[0]))),
+            int(max(0, ceil(exp_shape[1] - image.shape[1]))),
         )
         exp_img = np.pad(image, ((h_pad // 2, h_pad - h_pad // 2), (w_pad // 2, w_pad - w_pad // 2), (0, 0)))
     else:
@@ -283,20 +337,27 @@ def estimate_page_angle(polys: np.ndarray) -> float:
     yleft = polys[:, 0, 1] + polys[:, 3, 1]
     xright = polys[:, 1, 0] + polys[:, 2, 0]
     yright = polys[:, 1, 1] + polys[:, 2, 1]
-    return float(np.median(np.arctan((yleft - yright) / (xright - xleft))) * 180 / np.pi)  # Y axis from top to bottom!
+    with np.errstate(divide="raise", invalid="raise"):
+        try:
+            return float(
+                np.median(np.arctan((yleft - yright) / (xright - xleft)) * 180 / np.pi)  # Y axis from top to bottom!
+            )
+        except FloatingPointError:
+            return 0.0
 
 
 def convert_to_relative_coords(geoms: np.ndarray, img_shape: Tuple[int, int]) -> np.ndarray:
     """Convert a geometry to relative coordinates
 
     Args:
+    ----
         geoms: a set of polygons of shape (N, 4, 2) or of straight boxes of shape (N, 4)
         img_shape: the height and width of the image
 
     Returns:
+    -------
         the updated geometry
     """
-
     # Polygon
     if geoms.ndim == 3 and geoms.shape[1:] == (4, 2):
         polygons: np.ndarray = np.empty(geoms.shape, dtype=np.float32)
@@ -314,12 +375,16 @@ def convert_to_relative_coords(geoms: np.ndarray, img_shape: Tuple[int, int]) ->
 
 def extract_crops(img: np.ndarray, boxes: np.ndarray, channels_last: bool = True) -> List[np.ndarray]:
     """Created cropped images from list of bounding boxes
+
     Args:
+    ----
         img: input image
         boxes: bounding boxes of shape (N, 4) where N is the number of boxes, and the relative
             coordinates (xmin, ymin, xmax, ymax)
         channels_last: whether the channel dimensions is the last one instead of the last one
+
     Returns:
+    -------
         list of cropped images
     """
     if boxes.shape[0] == 0:
@@ -330,7 +395,7 @@ def extract_crops(img: np.ndarray, boxes: np.ndarray, channels_last: bool = True
     # Project relative coordinates
     _boxes = boxes.copy()
     h, w = img.shape[:2] if channels_last else img.shape[-2:]
-    if _boxes.dtype != int:
+    if not np.issubdtype(_boxes.dtype, np.integer):
         _boxes[:, [0, 2]] *= w
         _boxes[:, [1, 3]] *= h
         _boxes = _boxes.round().astype(int)
@@ -346,12 +411,16 @@ def extract_rcrops(
     img: np.ndarray, polys: np.ndarray, dtype=np.float32, channels_last: bool = True
 ) -> List[np.ndarray]:
     """Created cropped images from list of rotated bounding boxes
+
     Args:
+    ----
         img: input image
         polys: bounding boxes of shape (N, 4, 2)
         dtype: target data type of bounding boxes
         channels_last: whether the channel dimensions is the last one instead of the last one
+
     Returns:
+    -------
         list of cropped images
     """
     if polys.shape[0] == 0:
@@ -362,7 +431,7 @@ def extract_rcrops(
     # Project relative coordinates
     _boxes = polys.copy()
     height, width = img.shape[:2] if channels_last else img.shape[-2:]
-    if _boxes.dtype != int:
+    if not np.issubdtype(_boxes.dtype, np.integer):
         _boxes[:, :, 0] *= width
         _boxes[:, :, 1] *= height
 

doctr/utils/metrics.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2021-2023, Mindee.
+# Copyright (C) 2021-2024, Mindee.
 
 # This program is licensed under the Apache License 2.0.
 # See LICENSE or go to <https://opensource.org/licenses/Apache-2.0> for full license details.
@@ -27,10 +27,12 @@ def string_match(word1: str, word2: str) -> Tuple[bool, bool, bool, bool]:
     """Performs string comparison with multiple levels of tolerance
 
     Args:
+    ----
         word1: a string
         word2: another string
 
     Returns:
+    -------
         a tuple with booleans specifying respectively whether the raw strings, their lower-case counterparts, their
             unidecode counterparts and their lower-case unidecode counterparts match
     """
@@ -84,10 +86,10 @@ class TextMatch:
         """Update the state of the metric with new predictions
 
         Args:
+        ----
             gt: list of groung-truth character sequences
             pred: list of predicted character sequences
         """
-
         if len(gt) != len(pred):
             raise AssertionError("prediction size does not match with ground-truth labels size")
 
@@ -103,7 +105,8 @@ class TextMatch:
     def summary(self) -> Dict[str, float]:
         """Computes the aggregated metrics
 
-        Returns:
+        Returns
+        -------
             a dictionary with the exact match score for the raw data, its lower-case counterpart, its unidecode
             counterpart and its lower-case unidecode counterpart
         """
@@ -129,13 +132,14 @@ def box_iou(boxes_1: np.ndarray, boxes_2: np.ndarray) -> np.ndarray:
     """Computes the IoU between two sets of bounding boxes
 
     Args:
+    ----
         boxes_1: bounding boxes of shape (N, 4) in format (xmin, ymin, xmax, ymax)
         boxes_2: bounding boxes of shape (M, 4) in format (xmin, ymin, xmax, ymax)
 
     Returns:
+    -------
         the IoU matrix of shape (N, M)
     """
-
     iou_mat: np.ndarray = np.zeros((boxes_1.shape[0], boxes_2.shape[0]), dtype=np.float32)
 
     if boxes_1.shape[0] > 0 and boxes_2.shape[0] > 0:
@@ -159,13 +163,14 @@ def box_ioa(boxes_1: np.ndarray, boxes_2: np.ndarray) -> np.ndarray:
     ioa(i, j) = inter(i, j) / area(i)
 
     Args:
+    ----
         boxes_1: bounding boxes of shape (N, 4) in format (xmin, ymin, xmax, ymax)
         boxes_2: bounding boxes of shape (M, 4) in format (xmin, ymin, xmax, ymax)
 
     Returns:
+    -------
         the IoA matrix of shape (N, M)
     """
-
     ioa_mat: np.ndarray = np.zeros((boxes_1.shape[0], boxes_2.shape[0]), dtype=np.float32)
 
     if boxes_1.shape[0] > 0 and boxes_2.shape[0] > 0:
@@ -188,13 +193,14 @@ def mask_iou(masks_1: np.ndarray, masks_2: np.ndarray) -> np.ndarray:
     """Computes the IoU between two sets of boolean masks
 
     Args:
+    ----
         masks_1: boolean masks of shape (N, H, W)
         masks_2: boolean masks of shape (M, H, W)
 
     Returns:
+    -------
         the IoU matrix of shape (N, M)
     """
-
     if masks_1.shape[1:] != masks_2.shape[1:]:
         raise AssertionError("both boolean masks should have the same spatial shape")
 
@@ -215,15 +221,16 @@ def polygon_iou(
     """Computes the IoU between two sets of rotated bounding boxes
 
     Args:
+    ----
         polys_1: rotated bounding boxes of shape (N, 4, 2)
         polys_2: rotated bounding boxes of shape (M, 4, 2)
         mask_shape: spatial shape of the intermediate masks
         use_broadcasting: if set to True, leverage broadcasting speedup by consuming more memory
 
     Returns:
+    -------
         the IoU matrix of shape (N, M)
     """
-
     if polys_1.ndim != 3 or polys_2.ndim != 3:
         raise AssertionError("expects boxes to be in format (N, 4, 2)")
 
@@ -249,16 +256,17 @@ def _rbox_to_mask(box: np.ndarray, shape: Tuple[int, int]) -> np.ndarray:
     """Converts a rotated bounding box to a boolean mask
 
     Args:
+    ----
         box: rotated bounding box of shape (4, 2)
         shape: spatial shapes of the output masks
 
     Returns:
+    -------
         the boolean mask of the specified shape
     """
-
     mask: np.ndarray = np.zeros(shape, dtype=np.uint8)
     # Get absolute coords
-    if box.dtype != int:
+    if not np.issubdtype(box.dtype, np.integer):
         abs_box = box.copy()
         abs_box[:, 0] = abs_box[:, 0] * shape[1]
         abs_box[:, 1] = abs_box[:, 1] * shape[0]
@@ -266,7 +274,7 @@ def _rbox_to_mask(box: np.ndarray, shape: Tuple[int, int]) -> np.ndarray:
     else:
         abs_box = box
         abs_box[2:] = abs_box[2:] + 1
-    cv2.fillPoly(mask, [abs_box - 1], 1)
+    cv2.fillPoly(mask, [abs_box - 1], 1.0)  # type: ignore[call-overload]
 
     return mask.astype(bool)
 
@@ -275,18 +283,19 @@ def rbox_to_mask(boxes: np.ndarray, shape: Tuple[int, int]) -> np.ndarray:
     """Converts rotated bounding boxes to boolean masks
 
     Args:
+    ----
         boxes: rotated bounding boxes of shape (N, 4, 2)
         shape: spatial shapes of the output masks
 
     Returns:
+    -------
         the boolean masks of shape (N, H, W)
     """
-
     masks: np.ndarray = np.zeros((boxes.shape[0], *shape), dtype=np.uint8)
 
     if boxes.shape[0] > 0:
         # Get absolute coordinates
-        if boxes.dtype != int:
+        if not np.issubdtype(boxes.dtype, np.integer):
             abs_boxes = boxes.copy()
             abs_boxes[:, :, 0] = abs_boxes[:, :, 0] * shape[1]
             abs_boxes[:, :, 1] = abs_boxes[:, :, 1] * shape[0]
@@ -297,7 +306,7 @@ def rbox_to_mask(boxes: np.ndarray, shape: Tuple[int, int]) -> np.ndarray:
 
         # TODO: optimize slicing to improve vectorization
         for idx, _box in enumerate(abs_boxes):
-            cv2.fillPoly(masks[idx], [_box - 1], 1)
+            cv2.fillPoly(masks[idx], [_box - 1], 1.0)  # type: ignore[call-overload]
     return masks.astype(bool)
 
 
@@ -305,10 +314,12 @@ def nms(boxes: np.ndarray, thresh: float = 0.5) -> List[int]:
     """Perform non-max suppression, borrowed from <https://github.com/rbgirshick/fast-rcnn>`_.
 
     Args:
+    ----
         boxes: np array of straight boxes: (*, 5), (xmin, ymin, xmax, ymax, score)
         thresh: iou threshold to perform box suppression.
 
     Returns:
+    -------
         A list of box indexes to keep
     """
     x1 = boxes[:, 0]
@@ -372,6 +383,7 @@ class LocalizationConfusion:
     >>> metric.summary()
 
     Args:
+    ----
         iou_thresh: minimum IoU to consider a pair of prediction and ground truth as a match
         use_polygons: if set to True, predictions and targets will be expected to have rotated format
         mask_shape: if use_polygons is True, describes the spatial shape of the image used
@@ -395,10 +407,10 @@ class LocalizationConfusion:
         """Updates the metric
 
         Args:
+        ----
             gts: a set of relative bounding boxes either of shape (N, 4) or (N, 5) if they are rotated ones
             preds: a set of relative bounding boxes either of shape (M, 4) or (M, 5) if they are rotated ones
         """
-
         if preds.shape[0] > 0:
             # Compute IoU
             if self.use_polygons:
@@ -418,10 +430,10 @@ class LocalizationConfusion:
     def summary(self) -> Tuple[Optional[float], Optional[float], Optional[float]]:
         """Computes the aggregated metrics
 
-        Returns:
+        Returns
+        -------
             a tuple with the recall, precision and meanIoU scores
         """
-
         # Recall
         recall = self.matches / self.num_gts if self.num_gts > 0 else None
 
@@ -477,6 +489,7 @@ class OCRMetric:
     >>> metric.summary()
 
     Args:
+    ----
         iou_thresh: minimum IoU to consider a pair of prediction and ground truth as a match
         use_polygons: if set to True, predictions and targets will be expected to have rotated format
         mask_shape: if use_polygons is True, describes the spatial shape of the image used
@@ -506,12 +519,12 @@ class OCRMetric:
         """Updates the metric
 
         Args:
+        ----
             gt_boxes: a set of relative bounding boxes either of shape (N, 4) or (N, 5) if they are rotated ones
             pred_boxes: a set of relative bounding boxes either of shape (M, 4) or (M, 5) if they are rotated ones
             gt_labels: a list of N string labels
             pred_labels: a list of M string labels
         """
-
         if gt_boxes.shape[0] != len(gt_labels) or pred_boxes.shape[0] != len(pred_labels):
             raise AssertionError(
                 "there should be the same number of boxes and string both for the ground truth " "and the predictions"
@@ -543,10 +556,10 @@ class OCRMetric:
     def summary(self) -> Tuple[Dict[str, Optional[float]], Dict[str, Optional[float]], Optional[float]]:
         """Computes the aggregated metrics
 
-        Returns:
+        Returns
+        -------
             a tuple with the recall & precision for each string comparison and the mean IoU
         """
-
         # Recall
         recall = dict(
             raw=self.raw_matches / self.num_gts if self.num_gts > 0 else None,
@@ -615,6 +628,7 @@ class DetectionMetric:
     >>> metric.summary()
 
     Args:
+    ----
         iou_thresh: minimum IoU to consider a pair of prediction and ground truth as a match
         use_polygons: if set to True, predictions and targets will be expected to have rotated format
         mask_shape: if use_polygons is True, describes the spatial shape of the image used
@@ -644,12 +658,12 @@ class DetectionMetric:
         """Updates the metric
 
         Args:
+        ----
             gt_boxes: a set of relative bounding boxes either of shape (N, 4) or (N, 5) if they are rotated ones
             pred_boxes: a set of relative bounding boxes either of shape (M, 4) or (M, 5) if they are rotated ones
             gt_labels: an array of class indices of shape (N,)
             pred_labels: an array of class indices of shape (M,)
         """
-
         if gt_boxes.shape[0] != gt_labels.shape[0] or pred_boxes.shape[0] != pred_labels.shape[0]:
             raise AssertionError(
                 "there should be the same number of boxes and string both for the ground truth " "and the predictions"
@@ -676,10 +690,10 @@ class DetectionMetric:
     def summary(self) -> Tuple[Optional[float], Optional[float], Optional[float]]:
         """Computes the aggregated metrics
 
-        Returns:
+        Returns
+        -------
             a tuple with the recall & precision for each class prediction and the mean IoU
         """
-
         # Recall
         recall = self.num_matches / self.num_gts if self.num_gts > 0 else None
 

doctr/utils/multithreading.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2021-2023, Mindee.
+# Copyright (C) 2021-2024, Mindee.
 
 # This program is licensed under the Apache License 2.0.
 # See LICENSE or go to <https://opensource.org/licenses/Apache-2.0> for full license details.
@@ -22,19 +22,21 @@ def multithread_exec(func: Callable[[Any], Any], seq: Iterable[Any], threads: Op
     >>> results = multithread_exec(lambda x: x ** 2, entries)
 
     Args:
+    ----
         func: function to be executed on each element of the iterable
         seq: iterable
         threads: number of workers to be used for multiprocessing
 
     Returns:
+    -------
         iterator of the function's results using the iterable as inputs
 
     Notes:
+    -----
         This function uses ThreadPool from multiprocessing package, which uses `/dev/shm` directory for shared memory.
         If you do not have write permissions for this directory (if you run `doctr` on AWS Lambda for instance),
         you might want to disable multiprocessing. To achieve that, set 'DOCTR_MULTIPROCESSING_DISABLE' to 'TRUE'.
     """
-
     threads = threads if isinstance(threads, int) else min(16, mp.cpu_count())
     # Single-thread
     if threads < 2 or os.environ.get("DOCTR_MULTIPROCESSING_DISABLE", "").upper() in ENV_VARS_TRUE_VALUES:
@@ -44,5 +46,5 @@ def multithread_exec(func: Callable[[Any], Any], seq: Iterable[Any], threads: Op
         with ThreadPool(threads) as tp:
             # ThreadPool's map function returns a list, but seq could be of a different type
             # That's why wrapping result in map to return iterator
-            results = map(lambda x: x, tp.map(func, seq))
+            results = map(lambda x: x, tp.map(func, seq))  # noqa: C417
     return results

doctr/utils/repr.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2021-2023, Mindee.
+# Copyright (C) 2021-2024, Mindee.
 
 # This program is licensed under the Apache License 2.0.
 # See LICENSE or go to <https://opensource.org/licenses/Apache-2.0> for full license details.
@@ -23,6 +23,8 @@ def _addindent(s_, num_spaces):
 
 
 class NestedObject:
+    """Base class for all nested objects in doctr"""
+
     _children_names: List[str]
 
     def extra_repr(self) -> str: