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

deepdoctection/pipe/sub_layout.py

@@ -16,7 +16,7 @@
 # limitations under the License.
 
 """
-Module for cell detection pipeline component
+Sub layout detection pipeline component
 """
 from __future__ import annotations
 
@@ -39,12 +39,12 @@ from .registry import pipeline_component_registry
 
 class DetectResultGenerator:
     """
-    Use:  `DetectResultGenerator` to refine raw detection results.
+    Use `DetectResultGenerator` to refine raw detection results.
 
     Certain pipeline components depend on, for example, at least one object being detected. If this is not the
-    case, the generator can generate a DetectResult with a default setting. If no object was discovered for a
-    category, a DetectResult with the dimensions of the original image is generated and added to the remaining
-    DetectResults.
+    case, the generator can generate a `DetectResult` with a default setting. If no object was discovered for a
+    category, a `DetectResult` with the dimensions of the original image is generated and added to the remaining
+    `DetectResults`.
     """
 
     def __init__(
@@ -55,11 +55,13 @@ class DetectResultGenerator:
         absolute_coords: bool = True,
     ) -> None:
         """
-        :param categories_name_as_key: The dict of all possible detection categories
-        :param group_categories: If you only want to generate only one DetectResult for a group of categories, provided
-                                 that the sum of the group is less than one, then you can pass a list of list for
-                                 grouping category ids.
-        :param absolute_coords: 'absolute_coords' value to be set in 'DetectionResult'
+        Args:
+            categories_name_as_key: The dict of all possible detection categories.
+            group_categories: If you only want to generate only one `DetectResult` for a group of categories, provided
+                that the sum of the group is less than one, then you can pass a list of list for grouping category ids.
+            exclude_category_names: List of category names to exclude from result generation.
+            absolute_coords: Value to be set in `DetectionResult` for `absolute_coords`.
+
         """
         self.categories_name_as_key = MappingProxyType(dict(categories_name_as_key.items()))
         self.width: Optional[int] = None
@@ -75,10 +77,16 @@ class DetectResultGenerator:
 
     def create_detection_result(self, detect_result_list: list[DetectionResult]) -> list[DetectionResult]:
         """
-        Adds DetectResults for which no object was detected to the list.
+        Adds `DetectResults` for which no object was detected to the list.
+
+        Args:
+            detect_result_list: `DetectResults` of a previously run `ObjectDetector`.
+
+        Returns:
+            Refined list of `DetectionResult`.
 
-        :param detect_result_list: DetectResults of a previously run ObjectDetector
-        :return: refined list
+        Raises:
+            ValueError: If `width` and `height` are not initialized.
         """
 
         if self.width is None and self.height is None:
@@ -115,10 +123,16 @@ class DetectResultGenerator:
     @staticmethod
     def _detection_result_sanity_check(detect_result_list: list[DetectionResult]) -> list[DetectionResult]:
         """
-        Go through each detect_result in the list and check if the box argument has sensible coordinates:
-        ulx >= 0 and lrx - ulx >= 0 (same for y coordinate). Remove the detection result if this condition is not
+        Go through each `detect_result` in the list and check if the `box` argument has sensible coordinates:
+        `ulx >= 0` and `lrx - ulx >= 0` (same for y coordinate). Remove the detection result if this condition is not
         satisfied. We need this check because if some detection results are not sane, we might end up with some
-        none existing categories.
+        non-existing categories.
+
+        Args:
+            detect_result_list: List of `DetectionResult` to check.
+
+        Returns:
+            List of `DetectionResult` with only valid boxes.
         """
         sane_detect_results = []
         for detect_result in detect_result_list:
@@ -143,19 +157,20 @@ class DetectResultGenerator:
 @pipeline_component_registry.register("SubImageLayoutService")
 class SubImageLayoutService(PipelineComponent):
     """
-    Component in which the selected ImageAnnotation can be selected with cropped images and presented to a detector.
+    Component in which the selected `ImageAnnotation` can be selected with cropped images and presented to a detector.
 
-    The detected DetectResults are transformed into ImageAnnotations and stored both in the cache of the parent image
-    and in the cache of the sub image.
+    The detected `DetectResults` are transformed into `ImageAnnotations` and stored both in the cache of the parent
+    image and in the cache of the sub image.
 
     If no objects are discovered, artificial objects can be added by means of a refinement process.
 
-    **Example**
-
-            detect_result_generator = DetectResultGenerator(categories_items)
-            d_items = TPFrcnnDetector(item_config_path, item_weights_path, {1: LayoutType.row,
-            2: LayoutType.column})
-            item_component = SubImageLayoutService(d_items, LayoutType.table, detect_result_generator)
+    Example:
+        ```python
+        detect_result_generator = DetectResultGenerator(categories_items)
+        d_items = TPFrcnnDetector(item_config_path, item_weights_path, {1: LayoutType.row,
+        2: LayoutType.column})
+        item_component = SubImageLayoutService(d_items, LayoutType.table, detect_result_generator)
+        ```
     """
 
     def __init__(
@@ -167,18 +182,22 @@ class SubImageLayoutService(PipelineComponent):
         padder: Optional[PadTransform] = None,
     ):
         """
-        :param sub_image_detector: object detector.
-        :param sub_image_names: Category names of ImageAnnotations to be presented to the detector.
-                                Attention: The selected ImageAnnotations must have: attr:`image` and: attr:`image.image`
-                                not None.
-        :param service_ids: List of service ids to be used for filtering the ImageAnnotations. If None, all
-                            ImageAnnotations will be used.
-        :param detect_result_generator: 'DetectResultGenerator' instance. 'categories' attribute has to be the same as
-                                        the 'categories' attribute of the 'sub_image_detector'. The generator will be
-                                        responsible to create 'DetectionResult' for some categories, if they have not
-                                        been detected by 'sub_image_detector'.
-        :param padder: 'PadTransform' to pad an image before passing to a predictor. Will be also responsible for
-                        inverse coordinate transformation.
+        Args:
+            sub_image_detector: `ObjectDetector`.
+            sub_image_names: Category names of `ImageAnnotations` to be presented to the detector.
+                Attention: The selected `ImageAnnotations` must have `image` and `image.image` not None.
+            service_ids: List of service ids to be used for filtering the `ImageAnnotations`. If None, all
+                `ImageAnnotations` will be used.
+            detect_result_generator: `DetectResultGenerator` instance. `categories` attribute has to be the same as
+                the `categories` attribute of the `sub_image_detector`. The generator will be
+                responsible to create `DetectionResult` for some categories, if they have not
+                been detected by `sub_image_detector`.
+            padder: `PadTransform` to pad an image before passing to a predictor. Will be also responsible for
+                inverse coordinate transformation.
+
+        Raises:
+            ValueError: If the categories of the `detect_result_generator` do not match the categories of the
+                        `sub_image_detector`.
         """
 
         self.sub_image_name = (
@@ -203,10 +222,13 @@ class SubImageLayoutService(PipelineComponent):
 
     def serve(self, dp: Image) -> None:
         """
-        - Selection of ImageAnnotation to present to the detector.
-        - Invoke the detector
-        - Optionally invoke the DetectResultGenerator
-        - Generate ImageAnnotations and dump to parent image and sub image.
+        - Selection of `ImageAnnotation` to present to the detector.
+        - Invoke the detector.
+        - Optionally invoke the `DetectResultGenerator`.
+        - Generate `ImageAnnotations` and dump to parent image and sub image.
+
+        Args:
+            dp: `Image` to process.
         """
         sub_image_anns = dp.get_annotation(category_names=self.sub_image_name, service_ids=self.service_ids)
         for sub_image_ann in sub_image_anns:
@@ -255,13 +277,21 @@ class SubImageLayoutService(PipelineComponent):
         )
 
     def prepare_np_image(self, sub_image_ann: ImageAnnotation) -> PixelValues:
-        """Maybe crop and pad a np_array before passing it to the predictor.
+        """
+        Maybe crop and pad a `np_array` before passing it to the predictor.
+
+        Note:
+            We currently assume a two level hierarchy of images, e.g. we can crop a sub-image from the base
+            image, e.g. the original input but we cannot crop a sub-image from an image which is itself a sub-image.
+
+        Args:
+            sub_image_ann: `ImageAnnotation` to be processed.
 
-        Note that we currently assume to a two level hierachy of images, e.g. we can crop a sub-image from the base
-        image, e.g. the original input but we cannot crop a sub-image from an image which is itself a sub-image.
+        Returns:
+            Processed `np_image`.
 
-        :param sub_image_ann: ImageAnnotation to be processed
-        :return: processed np_image
+        Raises:
+            ValueError: If `sub_image_ann.image` is `None`.
         """
         if sub_image_ann.image is None:
             raise ValueError("sub_image_ann.image is None, but must be an datapoint.Image")

deepdoctection/pipe/text.py

@@ -16,7 +16,7 @@
 # limitations under the License.
 
 """
-Module for text extraction pipeline component
+Text extraction pipeline component
 """
 
 from __future__ import annotations
@@ -40,29 +40,30 @@ __all__ = ["TextExtractionService"]
 @pipeline_component_registry.register("TextExtractionService")
 class TextExtractionService(PipelineComponent):
     """
-    Pipeline component for extracting text. Any detector can be selected, provided that it can evaluate a
-    numpy array as an image.
+    Text extraction pipeline component.
 
-    Text extraction can either be carried out over the entire image or over selected regions of interests (ROIs).
-    ROIs are layout components that have been determined by means of a pipeline component that has been run through
-    beforehand. ROI extraction is particularly suitable when an OCR component is selected as the detector and the
-    document has a complex structure. Instead of transferring the entire image, only the ROIs are transferred to
-    the detector. Since the ROI has a simpler structure than the entire document page, it can significantly improve
-    the OCR results.
+    This component is responsible for extracting text from images or selected regions of interest (ROIs) using a
+    specified detector. The detector must be able to evaluate a numpy array as an image.
 
-    Text components (currently only words) are attached to the image as image annotations. A relation is assigned in
-    relation to text and ROI or in relation to text and the entire image. When selecting ROIs, only the selected
-    categories are taken into account during processing. ROIs that are not selected are not presented to the
-    detector.
+    Text extraction can be performed on the entire image or on selected ROIs, which are layout components determined by
+    a previously run pipeline component. ROI extraction is particularly useful when using an OCR component as the
+    detector and the document has a complex structure. By transferring only the ROIs to the detector, OCR results can
+    be significantly improved due to the simpler structure of the ROI compared to the entire document page.
 
-        textract_predictor = TextractOcrDetector()
-        text_extract = TextExtractionService(textract_predictor)
+    Text components (currently only words) are attached to the image as image annotations. A relation is assigned
+    between text and ROI or between text and the entire image. When selecting ROIs, only the selected categories are
+    processed. ROIs that are not selected are not presented to the detector.
 
-        pipe = DoctectionPipe([text_extract])
-        df = pipe.analyze(path="path/to/document.pdf")
+    Example:
+    ```python
+    textract_predictor = TextractOcrDetector()
+    text_extract = TextExtractionService(textract_predictor)
 
-        for dp in df:
-            ...
+    pipe = DoctectionPipe([text_extract])
+    df = pipe.analyze(path="path/to/document.pdf")
+
+    for dp in df:
+        ...
     """
 
     def __init__(
@@ -72,12 +73,18 @@ class TextExtractionService(PipelineComponent):
         run_time_ocr_language_selection: bool = False,
     ):
         """
-        :param text_extract_detector: ObjectDetector
-        :param extract_from_roi: one or more category names for roi selection
-        :param run_time_ocr_language_selection: Only available for `TesseractOcrDetector` as this framework has
-                                                multiple language selections. Also requires that a language detection
-                                                pipeline component ran before. It will select the expert language OCR
-                                                model based on the determined language.
+        Args:
+            text_extract_detector: The detector used for text extraction.
+            extract_from_roi: One or more category names for ROI selection.
+            run_time_ocr_language_selection: If True, enables runtime OCR language selection. Only available for
+                                             `TesseractOcrDetector` as this framework supports multiple languages.
+                                              Requires a language detection pipeline component to have run before.
+                                              Selects the expert language OCR model based on the determined language.
+
+        Raises:
+            TypeError: If predicting from a cropped image and the detector is not an `ObjectDetector` or
+                       `TextRecognizer`.
+            TypeError: If `run_time_ocr_language_selection` is True and the detector is not a `TesseractOcrDetector`.
         """
 
         if extract_from_roi is None:
@@ -140,11 +147,17 @@ class TextExtractionService(PipelineComponent):
 
     def get_text_rois(self, dp: Image) -> Sequence[Union[Image, ImageAnnotation, list[ImageAnnotation]]]:
         """
-        Return image rois based on selected categories. As this selection makes only sense for specific text extractors
-        (e.g. those who do proper OCR and do not mine from text from native pdfs) it will do some sanity checks.
-        It is possible that a preceding text extractor dumped text before. If the predictor must not extract text as
-        well `get_text_rois` will return an empty list.
-        :return: list of ImageAnnotation or Image
+        Returns image ROIs based on selected categories.
+
+        This selection is only meaningful for specific text extractors (e.g., those performing OCR and not mining text
+        from native PDFs). Performs sanity checks. If a preceding text extractor has already dumped text, and the
+        predictor should not extract text as well, returns an empty list.
+
+        Args:
+            dp: The `Image` to process.
+
+        Returns:
+            A list of `ImageAnnotation` or `Image`.
         """
 
         if self.extract_from_category:
@@ -157,11 +170,17 @@ class TextExtractionService(PipelineComponent):
         self, text_roi: Union[Image, ImageAnnotation, list[ImageAnnotation]]
     ) -> Optional[Union[bytes, PixelValues, list[tuple[str, PixelValues]], int]]:
         """
-        Return raw input for a given `text_roi`. This can be a numpy array or pdf bytes and depends on the chosen
+        Returns raw input for a given `text_roi`. The input can be a numpy array or PDF bytes, depending on the chosen
         predictor.
 
-        :param text_roi: `Image` or `ImageAnnotation`
-        :return: pdf bytes or numpy array
+        Args:
+            text_roi: The `Image`, `ImageAnnotation`, or list of `ImageAnnotation` to process.
+
+        Returns:
+            PDF bytes, numpy array, or other predictor-specific input.
+
+        Raises:
+            ImageError: If required image data is missing or if `text_roi` is not an `Image` when required.
         """
 
         if isinstance(text_roi, ImageAnnotation):

deepdoctection/pipe/transform.py

@@ -16,8 +16,7 @@
 # limitations under the License.
 
 """
-Module for transform style pipeline components. These pipeline components are used for various transforming operations
-on images (e.g. deskew, de-noising or more general GAN like operations.
+Transform style pipeline components.
 """
 
 from __future__ import annotations
@@ -32,9 +31,10 @@ from .registry import pipeline_component_registry
 @pipeline_component_registry.register("SimpleTransformService")
 class SimpleTransformService(PipelineComponent):
     """
-    Pipeline component for transforming an image. The service is designed for applying transform predictors that
-    take an image as numpy array as input and return the same. The service itself will change the underlying metadata
-    like height and width of the returned transform.
+    Pipeline component for transforming an image.
+
+    The service is designed for applying transform predictors that take an image as numpy array as input and return
+    the same. The service itself will change the underlying metadata like height and width of the returned transform.
 
     This component is meant to be used at the very first stage of a pipeline. If components have already returned image
     annotations then this component will currently not re-calculate bounding boxes in terms of the transformed image.
@@ -43,8 +43,10 @@ class SimpleTransformService(PipelineComponent):
 
     def __init__(self, transform_predictor: ImageTransformer):
         """
+        Initializes a `SimpleTransformService`.
 
-        :param transform_predictor: image transformer
+        Args:
+            transform_predictor: Image transformer.
         """
         self.transform_predictor = transform_predictor
         super().__init__(self._get_name(transform_predictor.name), self.transform_predictor.model_id)

deepdoctection/train/d2_frcnn_train.py

@@ -16,7 +16,7 @@
 # limitations under the License.
 
 """
-Module for training Detectron2 `GeneralizedRCNN`
+Training Detectron2 `GeneralizedRCNN`
 """
 from __future__ import annotations
 
@@ -111,10 +111,12 @@ class WandbWriter(EventWriter):
         **kwargs: Any,
     ):
         """
-        :param project: W&B Project name
-        :param config: the project level configuration object
-        :param window_size: the scalars will be median-smoothed by this window size
-        :param kwargs: other arguments passed to `wandb.init(...)`
+        Args:
+            project: W&B Project name.
+            repo: Repository name.
+            config: The project level configuration object.
+            window_size: The scalars will be median-smoothed by this window size.
+            **kwargs: Other arguments passed to `wandb.init(...)`.
         """
         if config is None:
             config = {}
@@ -137,8 +139,10 @@ class WandbWriter(EventWriter):
 
 class D2Trainer(DefaultTrainer):
     """
-    Detectron2 `DefaultTrainer` with some custom method for handling datasets and running evaluation. The setting is
-    made to train standard models in detectron2.
+    Detectron2 `DefaultTrainer` with some custom method for handling datasets and running evaluation.
+
+    Info:
+        The setting is made to train standard models in Detectron2.
     """
 
     def __init__(self, cfg: CfgNode, torch_dataset: IterableDataset[Any], mapper: DatasetMapper) -> None:
@@ -150,10 +154,16 @@ class D2Trainer(DefaultTrainer):
 
     def build_hooks(self) -> list[HookBase]:
         """
-        Overwritten from DefaultTrainer. This ensures that the EvalHook is being called before the writer and
-        all metrics are being written to JSON, Tensorboard etc.
+        Builds the list of hooks for training.
+
+        Note:
+            This ensures that the `EvalHook` is being called before the writer and all metrics are being written to
+            JSON, Tensorboard etc.
+
+        Returns:
+            List of `HookBase` objects.
+
 
-        :return: list[HookBase]
         """
         cfg = self.cfg.clone()
         cfg.defrost()
@@ -203,10 +213,12 @@ class D2Trainer(DefaultTrainer):
     def build_writers(self) -> list[EventWriter]:
         """
         Build a list of writers to be using `default_writers()`.
-        If you'd like a different list of writers, you can overwrite it in
-        your trainer.
 
-        :return: A list of `EventWriter` objects.
+        Note:
+            If you'd like a different list of writers, you can overwrite it in your trainer.
+
+        Returns:
+            A list of `EventWriter` objects.
         """
         writers_list = default_writers(self.cfg.OUTPUT_DIR, self.max_iter)
         if self.cfg.WANDB.USE_WANDB:
@@ -220,10 +232,13 @@ class D2Trainer(DefaultTrainer):
 
     def build_train_loader(self, cfg: CfgNode) -> DataLoader[Any]:  # pylint: disable=W0221
         """
-        Overwritten method from `DefaultTrainer`.
+        Builds the data loader for training.
+
+        Args:
+            cfg: Configuration.
 
-        :param cfg: Configuration
-        :return: The data loader for a given dataset adapter, mapper.
+        Returns:
+            The data loader for a given dataset adapter and mapper.
         """
         return build_detection_train_loader(
             dataset=self.dataset, mapper=self.mapper, total_batch_size=cfg.SOLVER.IMS_PER_BATCH
@@ -231,10 +246,13 @@ class D2Trainer(DefaultTrainer):
 
     def eval_with_dd_evaluator(self, **build_eval_kwargs: str) -> Union[list[dict[str, Any]], dict[str, Any]]:
         """
-        Running the Evaluator. This method will be called from the `EvalHook`
+        Runs the evaluator. This method will be called from the `EvalHook`.
 
-        :param build_eval_kwargs: dataflow eval config kwargs of the underlying dataset
-        :return: A dict of evaluation results
+        Args:
+            **build_eval_kwargs: Dataflow eval config kwargs of the underlying dataset.
+
+        Returns:
+            A dict or list of dicts with evaluation results.
         """
         assert self.evaluator is not None
         assert self.evaluator.pipe_component is not None
@@ -251,13 +269,16 @@ class D2Trainer(DefaultTrainer):
         build_val_dict: Optional[Mapping[str, str]] = None,
     ) -> None:
         """
-        Setup of evaluator before starting training. During training, predictors will be replaced by current
-        checkpoints.
+        Setup of evaluator before starting training.
+
+        Note:
+            During training, predictors will be replaced by current checkpoints.
 
-        :param dataset_val: dataset on which to run evaluation
-        :param pipeline_component: pipeline component to plug into the evaluator
-        :param metric: A metric class
-        :param build_val_dict: evaluation dataflow build config
+        Args:
+            dataset_val: Dataset on which to run evaluation.
+            pipeline_component: Pipeline component to plug into the evaluator.
+            metric: A metric class or instance.
+            build_val_dict: Evaluation dataflow build config.
         """
         if wandb_available():
             run = wandb.run if wandb.run is not None else None
@@ -295,50 +316,47 @@ def train_d2_faster_rcnn(
     pipeline_component_name: Optional[str] = None,
 ) -> None:
     """
-    Adaptation of <https://github.com/facebookresearch/detectron2/blob/main/tools/train_net.py> for training Detectron2
-    standard models
-
-    Train Detectron2 from scratch or fine-tune a model using this API. Compared to Tensorpack this framework trains much
-    faster, e.g. <https://detectron2.readthedocs.io/en/latest/notes/benchmarks.html> .
-
-    This training script is devoted to the case where one cluster with one GPU is available. To run on several machines
-    with more than one GPU use `detectron2.engine.launch` .
-
-        if __name__ == "__main__":
-
-                launch(train_d2_faster_rcnn,
-                       num_gpus,
-                       num_machines,
-                       machine_rank,
-                       dist_url,
-                       args=(path_config_yaml,
-                             path_weights,
-                             config_overwrite,
-                             log_dir,
-                             build_train_config,
-                             dataset_val,
-                             build_val_config,
-                             metric_name,
-                             metric,
-                             pipeline_component_name),)
-
-
-    :param path_config_yaml: path to a D2 config file. Check
-                             https://github.com/facebookresearch/detectron2/blob/main/detectron2/config/defaults.py
-                             for various settings.
-    :param dataset_train: the dataset to use for training.
-    :param path_weights: path to a checkpoint, if you want to continue training or fine-tune. Will train from scratch if
-                         an empty string is passed
-    :param config_overwrite: Pass a list of arguments if some configs from the .yaml file should be replaced. Use the
-                             list convention, e.g. ['TRAIN.STEPS_PER_EPOCH=500', 'OUTPUT.RESULT_SCORE_THRESH=0.4']
-    :param log_dir: Path to log dir. Will default to `train_log/frcnn`
-    :param build_train_config: dataflow build setting. Again, use list convention setting, e.g. ['max_datapoints=1000']
-    :param dataset_val: the dataset to use for validation.
-    :param build_val_config: same as `build_train_config` but for validation
-    :param metric_name: A metric name to choose for validation. Will use the default setting. If you want a custom
-                        metric setting, pass a metric explicitly.
-    :param metric: A metric to choose for validation.
-    :param pipeline_component_name: A pipeline component name to use for validation.
+    Adaptation of https://github.com/facebookresearch/detectron2/blob/main/tools/train_net.py for training Detectron2
+    standard models.
+
+    Trains Detectron2 from scratch or fine-tunes a model using this API.
+
+    Info:
+        This training script is devoted to the case where one cluster with one GPU is available. To run on several
+        machines with more than one GPU use `detectron2.engine.launch`.
+
+    Example:
+        ```python
+        launch(train_d2_faster_rcnn,
+               num_gpus,
+               num_machines,
+               machine_rank,
+               dist_url,
+               args=(path_config_yaml,
+                     path_weights,
+                     config_overwrite,
+                     log_dir,
+                     build_train_config,
+                     dataset_val,
+                     build_val_config,
+                     metric_name,
+                     metric,
+                     pipeline_component_name),)
+        ```
+
+    Args:
+        path_config_yaml: Path to a Detectron2 config file.
+        dataset_train: The dataset to use for training.
+        path_weights: Path to a checkpoint, if you want to continue training or fine-tune. Will train from scratch if
+                      an empty string is passed.
+        config_overwrite: List of arguments if some configs from the .yaml file should be replaced.
+        log_dir: Path to log dir. Will default to `train_log/frcnn`.
+        build_train_config: Dataflow build setting.
+        dataset_val: The dataset to use for validation.
+        build_val_config: Same as `build_train_config` but for validation.
+        metric_name: A metric name to choose for validation.
+        metric: A metric to choose for validation.
+        pipeline_component_name: A pipeline component name to use for validation.
     """
 
     assert cuda.device_count() > 0, "Has to train with GPU!"