deepdoctection 0.42.1__py3-none-any.whl → 0.43__py3-none-any.whl

deepdoctection/extern/d2detect.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-D2 GeneralizedRCNN model as predictor for deepdoctection pipeline
+D2 `GeneralizedRCNN` models in PyTorch or Torchscript
 """
+
 from __future__ import annotations
 
 import io
@@ -53,12 +54,14 @@ with try_import() as d2_import_guard:
 
 def _d2_post_processing(predictions: dict[str, Instances], nms_thresh_class_agnostic: float) -> dict[str, Instances]:
     """
-    D2 postprocessing steps, so that detection outputs are aligned with outputs of other packages (e.g. Tensorpack).
-    Apply a class agnostic NMS.
+    D2 postprocessing steps. Apply a class agnostic NMS.
+
+    Args:
+        predictions: Prediction outputs from the model.
+        nms_thresh_class_agnostic: Nms being performed over all class predictions
 
-    :param predictions: Prediction outputs from the model.
-    :param nms_thresh_class_agnostic: Nms being performed over all class predictions
-    :return: filtered predictions outputs
+    Returns:
+        filtered Instances
     """
     instances = predictions["instances"]
     class_masks = torch.ones(instances.pred_classes.shape, dtype=torch.uint8)
@@ -74,14 +77,17 @@ def d2_predict_image(
     nms_thresh_class_agnostic: float,
 ) -> list[DetectionResult]:
     """
-    Run detection on one image, using the D2 model callable. It will also handle the preprocessing internally which
-    is using a custom resizing within some bounds.
-
-    :param np_img: ndarray
-    :param predictor: torch nn module implemented in Detectron2
-    :param resizer: instance for resizing the input image
-    :param nms_thresh_class_agnostic: class agnostic nms threshold
-    :return: list of DetectionResult
+    Run detection on one image. It will also handle the preprocessing internally which is using a custom resizing
+    within some bounds.
+
+    Args:
+        np_img: ndarray
+        predictor: torch nn module implemented in Detectron2
+        resizer: instance for resizing the input image
+        nms_thresh_class_agnostic: class agnostic NMS threshold
+
+    Returns:
+       list of `DetectionResult`s
     """
     height, width = np_img.shape[:2]
     resized_img = resizer.get_transform(np_img).apply_image(np_img)
@@ -107,15 +113,18 @@ def d2_jit_predict_image(
     np_img: PixelValues, d2_predictor: nn.Module, resizer: InferenceResize, nms_thresh_class_agnostic: float
 ) -> list[DetectionResult]:
     """
-    Run detection on an image using torchscript. It will also handle the preprocessing internally which
-    is using a custom resizing within some bounds. Moreover, and different from the setting where Detectron2 is used
+    Run detection on an image using Torchscript. It will also handle the preprocessing internally which
+    is using a custom resizing within some bounds. Moreover, and different from the setting where D2 is used
     it will also handle the resizing of the bounding box coords to the original image size.
 
-    :param np_img: ndarray
-    :param d2_predictor: torchscript nn module
-    :param resizer: instance for resizing the input image
-    :param nms_thresh_class_agnostic: class agnostic nms threshold
-    :return: list of DetectionResult
+    Args:
+        np_img: ndarray
+        d2_predictor: torchscript nn module
+        resizer: instance for resizing the input image
+        nms_thresh_class_agnostic: class agnostic nms threshold
+
+    Returns:
+        list of `DetectionResult`s
     """
     height, width = np_img.shape[:2]
     resized_img = resizer.get_transform(np_img).apply_image(np_img)
@@ -153,11 +162,14 @@ class D2FrcnnDetectorMixin(ObjectDetector, ABC):
         filter_categories: Optional[Sequence[TypeOrStr]] = None,
     ):
         """
-        :param categories: A dict with key (indices) and values (category names). Index 0 must be reserved for a
-                           dummy 'BG' category. Note, that this convention is different from the builtin D2 framework,
-                           where models in the model zoo are trained with 'BG' class having the highest index.
-        :param filter_categories: The model might return objects that are not supposed to be predicted and that should
-                                  be filtered. Pass a list of category names that must not be returned
+        Args:
+            categories: A dict with key (indices) and values (category names). Index 0 must be reserved for a
+                        dummy 'BG' category.
+                        Note:
+                             This convention is different from the builtin D2 framework, where models in the model
+                             zoo are trained with `BG` class having the highest index.
+            filter_categories: The model might return objects that are not supposed to be predicted and that should
+                               be filtered. Pass a list of category names that must not be returned
         """
 
         self.categories = ModelCategories(init_categories=categories)
@@ -166,10 +178,12 @@ class D2FrcnnDetectorMixin(ObjectDetector, ABC):
 
     def _map_category_names(self, detection_results: list[DetectionResult]) -> list[DetectionResult]:
         """
-        Populating category names to detection results
+        Populating category names to `DetectionResult`s
 
-        :param detection_results: list of detection results. Will also filter categories
-        :return: List of detection results with attribute class_name populated
+        Args:
+            detection_results: list of `DetectionResult`s. Will also filter categories
+        Returns:
+            List of `DetectionResult`s with attribute `class_name` populated
         """
         filtered_detection_result: list[DetectionResult] = []
         shifted_categories = self.categories.shift_category_ids(shift_by=-1)
@@ -190,8 +204,9 @@ class D2FrcnnDetectorMixin(ObjectDetector, ABC):
     def get_inference_resizer(min_size_test: int, max_size_test: int) -> InferenceResize:
         """Returns the resizer for the inference
 
-        :param min_size_test: minimum size of the resized image
-        :param max_size_test: maximum size of the resized image
+        Args:
+            min_size_test: minimum size of the resized image
+            max_size_test: maximum size of the resized image
         """
         return InferenceResize(min_size_test, max_size_test)
 
@@ -208,19 +223,21 @@ class D2FrcnnDetector(D2FrcnnDetectorMixin):
 
     Currently, masks are not included in the data model.
 
-    There are no adjustment to the original implementation of Detectron2. Only one post-processing step is followed by
-    the standard D2 output that takes into account of the situation that detected objects are disjoint. For more infos
-    on this topic, see <https://github.com/facebookresearch/detectron2/issues/978> .
+    Note:
+        There are no adjustment to the original implementation of Detectron2. Only one post-processing step is followed
+        by the standard D2 output that takes into account of the situation that detected objects are disjoint. For more
+        infos on this topic, see <https://github.com/facebookresearch/detectron2/issues/978>.
 
-    ```python
-        config_path = ModelCatalog.get_full_path_configs("dd/d2/item/CASCADE_RCNN_R_50_FPN_GN.yaml")
-        weights_path = ModelDownloadManager.maybe_download_weights_and_configs("item/d2_model-800000-layout.pkl")
-        categories = ModelCatalog.get_profile("item/d2_model-800000-layout.pkl").categories
+    Example:
+        ```python
+            config_path = ModelCatalog.get_full_path_configs("dd/d2/item/CASCADE_RCNN_R_50_FPN_GN.yaml")
+            weights_path = ModelDownloadManager.maybe_download_weights_and_configs("item/d2_model-800000-layout.pkl")
+            categories = ModelCatalog.get_profile("item/d2_model-800000-layout.pkl").categories
 
-        d2_predictor = D2FrcnnDetector(config_path,weights_path,categories,device="cpu")
+            d2_predictor = D2FrcnnDetector(config_path,weights_path,categories,device="cpu")
 
-        detection_results = d2_predictor.predict(bgr_image_np_array)
-    ```
+            detection_results = d2_predictor.predict(bgr_image_np_array)
+        ```
     """
 
     def __init__(
@@ -238,17 +255,18 @@ class D2FrcnnDetector(D2FrcnnDetectorMixin):
         The configuration of the model uses the full stack of build model tools of D2. For more information
         please check <https://detectron2.readthedocs.io/en/latest/tutorials/models.html#build-models-from-yacs-config>.
 
-        :param path_yaml: The path to the yaml config. If the model is built using several config files, always use
-                          the highest level .yaml file.
-        :param path_weights: The path to the model checkpoint.
-        :param categories: A dict with key (indices) and values (category names). Index 0 must be reserved for a
-                           dummy 'BG' category. Note, that this convention is different from the builtin D2 framework,
-                           where models in the model zoo are trained with 'BG' class having the highest index.
-        :param config_overwrite:  Overwrite some hyperparameters defined by the yaml file with some new values. E.g.
-                                 ["OUTPUT.FRCNN_NMS_THRESH=0.3","OUTPUT.RESULT_SCORE_THRESH=0.6"].
-        :param device: "cpu" or "cuda". If not specified will auto select depending on what is available
-        :param filter_categories: The model might return objects that are not supposed to be predicted and that should
-                                  be filtered. Pass a list of category names that must not be returned
+        Args:
+            path_yaml: The path to the yaml config. If the model is built using several config files, always use
+                       the highest level .yaml file.
+            path_weights: The path to the model checkpoint.
+            categories: A dict with key (indices) and values (category names). Index 0 must be reserved for a
+                        dummy `BG` category. Note, that this convention is different from the builtin D2 framework,
+                        where models in the model zoo are trained with `BG` class having the highest index.
+            config_overwrite:  Overwrite some hyperparameters defined by the yaml file with some new values. E.g.
+                               `["OUTPUT.FRCNN_NMS_THRESH=0.3","OUTPUT.RESULT_SCORE_THRESH=0.6"]`.
+            device: "cpu" or "cuda". If not specified will auto select depending on what is available
+            filter_categories: The model might return objects that are not supposed to be predicted and that should
+                               be filtered. Pass a list of category names that must not be returned
         """
         super().__init__(categories, filter_categories)
 
@@ -283,10 +301,13 @@ class D2FrcnnDetector(D2FrcnnDetectorMixin):
     @staticmethod
     def _set_model(config: CfgNode) -> GeneralizedRCNN:
         """
-        Build the D2 model. It uses the available builtin tools of D2
+        Build the model. It uses the available built-in tools of D2
 
-        :param config: Model config
-        :return: The GeneralizedRCNN model
+        Args:
+            config: Model config
+
+        Returns:
+            `GeneralizedRCNN` model
         """
         return build_model(config.clone()).eval()
 
@@ -299,8 +320,11 @@ class D2FrcnnDetector(D2FrcnnDetectorMixin):
         """
         Prediction per image.
 
-        :param np_img: image as numpy array
-        :return: A list of DetectionResult
+        Args:
+            np_img: image as `np.array`
+
+        Returns:
+            A list of `DetectionResult`s
         """
         detection_results = d2_predict_image(
             np_img,
@@ -332,25 +356,28 @@ class D2FrcnnDetector(D2FrcnnDetectorMixin):
         device: Optional[Union[Literal["cpu", "cuda"], torch.device]] = None,
     ) -> GeneralizedRCNN:
         """
-        Get the wrapped model. Useful if one do not want to build the wrapper but only needs the instantiated model.
+        Get the wrapped model. Useful, if one does not want to build the wrapper but only needs the instantiated model.
 
         Example:
-        ```python
-
+            ```python
             path_yaml = ModelCatalog.get_full_path_configs("dd/d2/item/CASCADE_RCNN_R_50_FPN_GN.yaml")
             weights_path = ModelDownloadManager.maybe_download_weights_and_configs("item/d2_model-800000-layout.pkl")
             model = D2FrcnnDetector.get_wrapped_model(path_yaml,weights_path,["OUTPUT.FRCNN_NMS_THRESH=0.3",
                                                                               "OUTPUT.RESULT_SCORE_THRESH=0.6"],
                                                                               "cpu")
             detect_result_list = d2_predict_image(np_img,model,InferenceResize(800,1333),0.3)
-        ```
-        :param path_yaml: The path to the yaml config. If the model is built using several config files, always use
-                          the highest level .yaml file.
-        :param path_weights: The path to the model checkpoint.
-        :param config_overwrite: Overwrite some hyperparameters defined by the yaml file with some new values. E.g.
-                                 ["OUTPUT.FRCNN_NMS_THRESH=0.3","OUTPUT.RESULT_SCORE_THRESH=0.6"].
-        :param device: "cpu" or "cuda". If not specified will auto select depending on what is available
-        :return: Detectron2 GeneralizedRCNN model
+            ```
+
+        Args:
+            path_yaml: The path to the `yaml` config. If the model is built using several config files, always use
+                       the highest level `.yaml` file.
+            path_weights: The path to the model checkpoint.
+            config_overwrite: Overwrite some hyperparameters defined by the yaml file with some new values. E.g.
+                              `["OUTPUT.FRCNN_NMS_THRESH=0.3","OUTPUT.RESULT_SCORE_THRESH=0.6"]`.
+            device: "cpu" or "cuda". If not specified will auto select depending on what is available
+
+        Returns:
+            `GeneralizedRCNN` model
         """
 
         device = get_torch_device(device)
@@ -379,14 +406,13 @@ class D2FrcnnTracingDetector(D2FrcnnDetectorMixin):
     be installed. The associated config setting only contains parameters that are involved in pre-and post-processing.
     Depending on running the model with CUDA or on a CPU, it will need the appropriate exported model.
 
-    Currently, masks are not included in the data model.
-
-    There are no adjustment to the original implementation of Detectron2. Only one post-processing step is followed by
-    the standard D2 output that takes into account of the situation that detected objects are disjoint. For more infos
-    on this topic, see <https://github.com/facebookresearch/detectron2/issues/978> .
+    Note:
+        There are no adjustment to the original implementation of Detectron2. Only one post-processing step is followed
+        by the standard D2 output that takes into account of the situation that detected objects are disjoint. For more
+        infos on this topic, see <https://github.com/facebookresearch/detectron2/issues/978>.
 
     Example:
-    ```python
+        ```python
         config_path = ModelCatalog.get_full_path_configs("dd/d2/item/CASCADE_RCNN_R_50_FPN_GN.yaml")
         weights_path = ModelDownloadManager.maybe_download_weights_and_configs("item/d2_model-800000-layout.pkl")
         categories = ModelCatalog.get_profile("item/d2_model-800000-layout.pkl").categories
@@ -394,7 +420,7 @@ class D2FrcnnTracingDetector(D2FrcnnDetectorMixin):
         d2_predictor = D2FrcnnDetector(config_path,weights_path,categories)
 
         detection_results = d2_predictor.predict(bgr_image_np_array)
-    ```
+        ```
     """
 
     def __init__(
@@ -406,18 +432,19 @@ class D2FrcnnTracingDetector(D2FrcnnDetectorMixin):
         filter_categories: Optional[Sequence[TypeOrStr]] = None,
     ):
         """
-        Set up the torchscript predictor.
-
-        :param path_yaml: The path to the yaml config. If the model is built using several config files, always use
-                          the highest level .yaml file.
-        :param path_weights: The path to the model checkpoint.
-        :param categories: A dict with key (indices) and values (category names). Index 0 must be reserved for a
-                           dummy 'BG' category. Note, that this convention is different from the builtin D2 framework,
-                           where models in the model zoo are trained with 'BG' class having the highest index.
-        :param config_overwrite:  Overwrite some hyperparameters defined by the yaml file with some new values. E.g.
-                                 ["OUTPUT.FRCNN_NMS_THRESH=0.3","OUTPUT.RESULT_SCORE_THRESH=0.6"].
-        :param filter_categories: The model might return objects that are not supposed to be predicted and that should
-                                  be filtered. Pass a list of category names that must not be returned
+        Set up the Torchscript predictor.
+
+        Args:
+            path_yaml: The path to the `yaml` config. If the model is built using several config files, always use
+                       the highest level `.yaml` file.
+            path_weights: The path to the model checkpoint.
+            categories: A dict with key (indices) and values (category names). Index 0 must be reserved for a
+                        dummy `BG` category. Note, that this convention is different from the builtin D2 framework,
+                        where models in the model zoo are trained with `BG` class having the highest index.
+            config_overwrite:  Overwrite some hyperparameters defined by the yaml file with some new values. E.g.
+                               `["OUTPUT.FRCNN_NMS_THRESH=0.3","OUTPUT.RESULT_SCORE_THRESH=0.6"]`.
+            filter_categories: The model might return objects that are not supposed to be predicted and that should
+                               be filtered. Pass a list of category names that must not be returned
         """
 
         super().__init__(categories, filter_categories)
@@ -441,15 +468,20 @@ class D2FrcnnTracingDetector(D2FrcnnDetectorMixin):
         cfg = set_config_by_yaml(path_yaml)
         config_overwrite = config_overwrite if config_overwrite else []
         config_overwrite.extend([f"MODEL.WEIGHTS={os.fspath(path_weights)}"])
+        cfg.freeze(False)
         cfg.update_args(config_overwrite)
+        cfg.freeze()
         return cfg
 
     def predict(self, np_img: PixelValues) -> list[DetectionResult]:
         """
         Prediction per image.
 
-        :param np_img: image as numpy array
-        :return: A list of DetectionResult
+        Args:
+            np_img: image as `np.array`
+
+        Returns:
+            A list of `DetectionResult`s
         """
         detection_results = d2_jit_predict_image(
             np_img,
@@ -478,10 +510,13 @@ class D2FrcnnTracingDetector(D2FrcnnDetectorMixin):
     @staticmethod
     def get_wrapped_model(path_weights: PathLikeOrStr) -> torch.jit.ScriptModule:
         """
-        Get the wrapped model. Useful if one do not want to build the wrapper but only needs the instantiated model.
+        Get the wrapped model. Useful, if one do not want to build the wrapper but only needs the instantiated model.
+
+        Args:
+            path_weights: The path to the model checkpoint. The model must be exported as Torchscript.
 
-        :param path_weights:
-        :return:
+        Returns:
+            `torch.jit.ScriptModule` model
         """
         with open(path_weights, "rb") as file:
             buffer = io.BytesIO(file.read())

deepdoctection/extern/deskew.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-jdeskew estimator and rotator to deskew images: <https://github.com/phamquiluan/jdeskew>
+Jdeskew estimator and rotator: <https://github.com/phamquiluan/jdeskew>
 """
+
 from __future__ import annotations
 
 from lazy_imports import try_import
@@ -47,14 +48,19 @@ class Jdeskewer(ImageTransformer):
         """
         Rotation of the image according to the angle determined by the jdeskew estimator.
 
-        **Example**:
-                    jdeskew_predictor = Jdeskewer()
-                    detection_result = jdeskew_predictor.predict(np_image)
-                    jdeskew_predictor.transform(np_image, DetectionResult(angle=5.0))
+        Example:
+            ```python
+            jdeskew_predictor = Jdeskewer()
+            detection_result = jdeskew_predictor.predict(np_image)
+            jdeskew_predictor.transform(np_image, DetectionResult(angle=5.0))
+            ```
+
+        Args:
+            np_img: image as `np.array`
+            specification: `DetectionResult` with angle value
 
-        :param np_img: image as numpy array
-        :param specification: DetectionResult with angle value
-        :return: image rotated by the angle
+        Returns:
+            image rotated by the angle
         """
         if abs(specification.angle) > self.min_angle_rotation:  # type: ignore
             return viz_handler.rotate_image(np_img, specification.angle)  # type: ignore
@@ -64,8 +70,11 @@ class Jdeskewer(ImageTransformer):
         """
         Predict the angle of the image to deskew it.
 
-        :param np_img: image as numpy array
-        :return: DetectionResult with angle value
+        Args:
+            np_img: image as `np.array`
+
+        Returns:
+            `DetectionResult` with angle value
         """
         return DetectionResult(angle=round(float(get_angle(np_img)), 4))