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

deepdoctection/mapper/pubstruct.py

@@ -16,7 +16,7 @@
 # limitations under the License.
 
 """
-Module for mapping annotations in pubtabnet style structure
+Mapping annotations from Pubtabnet structure to Image structure.
 """
 import itertools
 import os
@@ -103,13 +103,16 @@ def _end_of_header(html: Sequence[str]) -> int:
 
 def tile_table(row_spans: Sequence[Sequence[int]], col_spans: Sequence[Sequence[int]]) -> list[list[int]]:
     """
-    Tiles a table according the row and column span scheme. A table can be represented as a list of list, where each
-    inner list has the same length. Each cell with a cell id can be located according to their row and column spans in
-    that scheme
+    Tiles a table according to the row and column span scheme. A table can be represented as a list of lists, where
+    each inner list has the same length. Each cell with a cell id can be located according to their row and column
+    spans in that scheme.
 
-    :param row_spans: A list of list of row spans
-    :param col_spans: A list of list of column spans
-    :return: A list of list of the tiling of the table, indicating the precise place of each cell.
+    Args:
+        row_spans: A list of lists of row spans.
+        col_spans: A list of lists of column spans.
+
+    Returns:
+        A list of lists of the tiling of the table, indicating the precise place of each cell.
     """
     number_of_cols = sum(col_spans[0])
     number_of_rows = len(col_spans)
@@ -255,8 +258,11 @@ def row_col_cell_ids(tiling: list[list[int]]) -> list[tuple[int, int, int]]:
     """
     Infers absolute rows and columns for every cell from the tiling of a table.
 
-    :param tiling: A list of list of tiling of a table as returned from the `_tile_table`
-    :return: A list of 3-tuples with row number, column number and cell id.
+    Args:
+        tiling: A list of lists of tiling of a table as returned from the `_tile_table`.
+
+    Returns:
+        A list of `3-tuples` with row number, column number, and cell id.
     """
     indices = sorted(
         [(i + 1, j + 1, cell_id) for i, row in enumerate(tiling) for j, cell_id in enumerate(row)], key=lambda x: x[2]
@@ -269,14 +275,15 @@ def row_col_cell_ids(tiling: list[list[int]]) -> list[tuple[int, int, int]]:
 
 def embedding_in_image(dp: Image, html: list[str], categories_name_as_key: dict[ObjectTypes, int]) -> Image:
     """
-    Generating an image, that resembles the output of an analyzer. The layout of the image is table spanning
-    the full page, i.e. there is one table image annotation. Moreover, the table annotation has an image, with cells
-    as image annotations.
-
-    :param dp: Image
-    :param html: list with html tags
-    :param categories_name_as_key: category dictionary with all possible annotations
-    :return: Image
+    Generating an image that resembles the output of an analyzer. The layout of the image is a table spanning the full
+    page, i.e. there is one table image annotation. Moreover, the table annotation has an image, with cells as image
+    annotations.
+
+    Args:
+        dp: Image html: List with html tags. categories_name_as_key: Category dictionary with all possible annotations.
+
+    Returns:
+        Image
     """
     image = Image(file_name=dp.file_name, location=dp.location, external_id=dp.image_id + "image")
     image.image = dp.image
@@ -313,12 +320,13 @@ def embedding_in_image(dp: Image, html: list[str], categories_name_as_key: dict[
 
 def nth_index(iterable: Iterable[str], value: str, n: int) -> Optional[int]:
     """
-    Returns the position of the n-th string value in an iterable, e.g. a list
+    Returns the position of the n-th string value in an iterable, e.g. a list.
+
+    Args:
+        iterable: e.g. list value: Any value `n`: `n-th` value
 
-    :param iterable: e.g. list
-    :param value: any value
-    :param n: n-th value
-    :return: position if n-th value exists else None
+    Returns:
+        Position if `n-th` value exists else `None`.
     """
     matches = (idx for idx, val in enumerate(iterable) if val == value)
     return next(itertools.islice(matches, n - 1, n), None)
@@ -338,19 +346,21 @@ def pub_to_image_uncur(  # pylint: disable=R0914
     Map a datapoint of annotation structure as given in the Pubtabnet dataset to an Image structure.
     <https://github.com/ibm-aur-nlp/PubTabNet>
 
-    :param dp: A datapoint in serialized Pubtabnet format.
-    :param categories_name_as_key: A dict of categories, e.g. DatasetCategories.get_categories(name_as_key=True)
-    :param load_image: If `True` it will load image to `Image.image`
-    :param fake_score: If dp does not contain a score, a fake score with uniform random variables in (0,1)
+    Args:
+        dp: A datapoint in serialized Pubtabnet format.
+        categories_name_as_key: A dict of categories, e.g. `DatasetCategories.get_categories(name_as_key=True)`
+        load_image: If `True` it will load image to `Image.image`
+        fake_score: If dp does not contain a score, a fake score with uniform random variables in (0,1)
                        will be added.
-    :param rows_and_cols: If set to `True`, synthetic "ITEM" ImageAnnotations will be added.  Each item has a
-                          sub-category "row_col" that is equal to "ROW" or "COL".
-    :param dd_pipe_like: This will generate an image identical to the output of the dd analyzer (e.g. table and words
+        rows_and_cols: If set to `True`, synthetic `ITEM` ImageAnnotations will be added.  Each item has a
+                          sub-category "row_col" that is equal to `ROW` or `COL`.
+        dd_pipe_like: This will generate an image identical to the output of the dd analyzer (e.g. table and words
                          annotations as well as sub annotations and relationships will be generated)
-    :param is_fintabnet: Set `True`, if this mapping is used for generating fintabnet datapoints.
-    :param pubtables_like: Set `True`, the area covering the table will be tiled with non overlapping rows and columns
+        is_fintabnet: Set `True`, if this mapping is used for generating Fintabnet datapoints.
+        pubtables_like: Set `True`, the area covering the table will be tiled with non overlapping rows and columns
                            without leaving empty space
-    :return: Image
+    Returns:
+        Image
     """
 
     if dd_pipe_like:

deepdoctection/mapper/tpstruct.py

@@ -42,14 +42,24 @@ def image_to_tp_frcnn_training(
     category_names: Optional[Union[TypeOrStr, Sequence[TypeOrStr]]] = None,
 ) -> Optional[JsonDict]:
     """
-    Maps an image to a dict to be consumed by Tensorpack Faster-RCNN bounding box detection. Note, that the returned
-    dict will not suffice for training as gt for RPN and anchors still need to be created.
-
-    :param dp: Image
-    :param add_mask: True is not implemented (yet).
-    :param category_names: A list of category names for training a model. Pass nothing to train with all annotations
-    :return: Dict with `image`, `gt_boxes`, `gt_labels` and `file_name`, provided there are some detected objects in the
-             image
+    Maps an `Image` to a dict to be consumed by Tensorpack Faster-RCNN bounding box detection.
+
+    Note:
+        The returned dict will not suffice for training as ground truth for RPN and anchors still need to be created.
+
+    Args:
+        dp: `Image`.
+        add_mask: `True` is not implemented.
+        category_names: A list of category names for training a model. Pass nothing to train with all annotations.
+
+    Returns:
+        Dict with `image`, `gt_boxes`, `gt_labels` and `file_name`, provided there are some detected objects in the
+        image.
+
+    Example:
+        ```python
+        image_to_tp_frcnn_training(dp)
+        ```
     """
 
     output: JsonDict = {}
@@ -83,15 +93,24 @@ def tf_nms_image_annotations(
     anns: Sequence[ImageAnnotation], threshold: float, image_id: Optional[str] = None, prio: str = ""
 ) -> Sequence[str]:
     """
-    Processing given image annotations through NMS. This is useful, if you want to supress some specific image
-    annotation, e.g. given by name or returned through different predictors. This is the tf version, for pt check
-    `mapper.d2struct`
-
-    :param anns: A sequence of ImageAnnotations. All annotations will be treated as if they belong to one category
-    :param threshold: NMS threshold
-    :param image_id: id in order to get the embedding bounding box
-    :param prio: If an annotation has prio, it will overwrite its given score to 1 so that it will never be suppressed
-    :return: A list of annotation_ids that belong to the given input sequence and that survive the NMS process
+    Processes given `ImageAnnotation` through `NMS`.
+
+    This is useful if you want to suppress some specific image annotation, e.g., given by name or returned through
+     different predictors. This is the TensorFlow version; for PyTorch, check `mapper.d2struct`.
+
+    Args:
+        anns: A sequence of `ImageAnnotation`. All annotations will be treated as if they belong to one category.
+        threshold: NMS threshold.
+        image_id: ID in order to get the embedding bounding box.
+        prio: If an annotation has `prio`, it will overwrite its given score to 1 so that it will never be suppressed.
+
+    Returns:
+        A list of `annotation_id` that belong to the given input sequence and that survive the NMS process.
+
+    Example:
+        ```python
+        tf_nms_image_annotations(anns, threshold)
+        ```
     """
     if len(anns) == 1:
         return [anns[0].annotation_id]
@@ -122,8 +141,9 @@ def tf_nms_image_annotations(
     ann_ids = np.array([ann.annotation_id for ann in anns], dtype="object")
 
     # Get boxes for non-priority annotations
-    boxes = convert_to_tensor([ann.get_bounding_box(image_id).to_list(mode="xyxy") for ann in anns if ann.bounding_box
-                               is not None])
+    boxes = convert_to_tensor(
+        [ann.get_bounding_box(image_id).to_list(mode="xyxy") for ann in anns if ann.bounding_box is not None]
+    )
 
     scores = convert_to_tensor([priority_to_confidence(ann, prio) for ann in anns])
     class_mask = convert_to_tensor(len(boxes), dtype=uint8)

deepdoctection/mapper/xfundstruct.py

@@ -16,7 +16,7 @@
 # limitations under the License.
 
 """
-Module for mapping annotations to and from xfund data structure
+Module for mapping annotations to and from Xfund data structure
 """
 
 import os
@@ -50,18 +50,25 @@ def xfund_to_image(
     ner_token_to_id_mapping: Mapping[ObjectTypes, Mapping[ObjectTypes, Mapping[ObjectTypes, int]]],
 ) -> Optional[Image]:
     """
-    Map a datapoint of annotation structure as given as from xfund or funsd dataset in to an Image structure
-
-    :param dp: A datapoint in dict structure as returned from the xfund or funsd dataset. Each datapoint must coincide
-               with exactly one image sample.
-    :param load_image: If 'True' it will load image to attr:`Image.image`
-    :param fake_score: If dp does not contain a score, a fake score with uniform random variables in (0,1)
-                       will be added.
-    :param categories_dict_name_as_key:
-    :param token_class_names_mapping: A dictionary, mapping original label names to normalized category names
-    :param ner_token_to_id_mapping: A dictionary, mapping token classes with bio tags (i.e. token tags) into their
-                                    category ids.
-    :return: Image
+    Maps a datapoint of annotation structure as given from Xfund or Funsd dataset into an `Image` structure.
+
+    Args:
+        dp: A datapoint in dict structure as returned from the Xfund or Funsd dataset. Each datapoint must coincide
+            with exactly one image sample.
+        load_image: If `True`, it will load image to `Image.image`.
+        fake_score: If `dp` does not contain a score, a fake score with uniform random variables in `(0,1)` will be
+                    added.
+        categories_dict_name_as_key: A mapping from `ObjectTypes` to `int` for `category_id`s.
+        token_class_names_mapping: A dictionary mapping original label names to normalized category names.
+        ner_token_to_id_mapping: A dictionary mapping token classes with bio tags (i.e. token tags) into their
+                                 category ids.
+
+    Returns:
+        `Image` or `None` if the image path is not found or an error occurs during mapping.
+
+    Note:
+        This function is intended for mapping xfund or funsd dataset annotation structures to the internal `Image`
+        representation for further processing.
     """
 
     img = dp.get("img")

deepdoctection/pipe/__init__.py

@@ -16,8 +16,7 @@
 # limitations under the License.
 
 """
-Contains pipeline components that can be plugged into each other and predictors that are invoked by their
- respective component.
+# Pipeline components and pipelines
 """
 
 from .anngen import *

deepdoctection/pipe/anngen.py

@@ -16,10 +16,10 @@
 # limitations under the License.
 
 """
-Module for datapoint populating helpers
+Datapoint manager
 """
 from dataclasses import asdict
-from typing import Mapping, Optional, Union
+from typing import Optional, Union
 
 import numpy as np
 
@@ -33,8 +33,8 @@ from ..utils.settings import ObjectTypes, Relationships
 
 class DatapointManager:
     """
-    Class whose methods provide an API for manipulating image datapoints. This includes the creation and storage of
-    annotations in the cache of the image but also in the annotations themselves.
+    This class provides an API for manipulating image datapoints. This includes the creation and storage of
+    annotations in the cache of the image as well as in the annotations themselves.
 
     When the image is transferred, the annotations are stored in a cache dictionary so that access via the annotation ID
     can be performed efficiently.
@@ -46,7 +46,6 @@ class DatapointManager:
         self._datapoint: Optional[Image] = None
         self._cache_anns: dict[str, ImageAnnotation] = {}
         self.datapoint_is_passed: bool = False
-        self.category_id_mapping: Optional[Mapping[int, int]] = None
         self.service_id = service_id
         self.model_id = model_id
         self.session_id: Optional[str] = None
@@ -54,7 +53,13 @@ class DatapointManager:
     @property
     def datapoint(self) -> Image:
         """
-        datapoint
+        Gets the datapoint.
+
+        Returns:
+            The datapoint.
+
+        Raises:
+            ValueError: If no datapoint is passed.
         """
         if self._datapoint is not None:
             return self._datapoint
@@ -63,7 +68,10 @@ class DatapointManager:
     @datapoint.setter
     def datapoint(self, dp: Image) -> None:
         """
-        datapoint
+        Sets the datapoint.
+
+        Args:
+            dp: The datapoint to set.
         """
         self._datapoint = dp
         self._cache_anns = {ann.annotation_id: ann for ann in dp.get_annotation()}
@@ -71,7 +79,10 @@ class DatapointManager:
 
     def assert_datapoint_passed(self) -> None:
         """
-        assert that datapoint is passed
+        Asserts that a datapoint is passed.
+
+        Raises:
+            AssertionError: If a datapoint has not been passed to `DatapointManager` before creating annotations.
         """
         assert self.datapoint_is_passed, "Pass datapoint to  DatapointManager before creating anns"
 
@@ -85,25 +96,34 @@ class DatapointManager:
         detect_result_max_height: Optional[float] = None,
     ) -> Optional[str]:
         """
-        Creating an image annotation from a raw `DetectionResult` dataclass. Beside dumping the annotation to the
-        `ImageAnnotation` cache you can also dump the annotation to the `image` of an annotation with given
-        `annotation_id`. This is handy if, you know, you want to send the sub image to a subsequent pipeline component.
-
-        Moreover, it is possible to generate an Image of the given raw annotation and store it in its `image`. The
-        resulting image is given as a sub image of `self` defined by it bounding box coordinates. Use `crop_image`
-        to explicitly store the sub image as numpy array.
-
-        :param detect_result: A `DetectionResult` in general coming from ObjectDetector
-        :param to_annotation_id: Will dump the created image annotation to `image` of the given annotation_id.
-                                 Requires the to_annotation to have a not `None` image.
-        :param to_image: If True will populate `image`.
-        :param crop_image: Makes only sense if to_image=True and if a numpy array is stored in the original image.
-                           Will generate `Image.image`.
-        :param detect_result_max_width: If detect result has a different scaling scheme from the image it refers to,
-                                        pass the max width possible so coords can be rescaled.
-        :param detect_result_max_height: If detect result has a different scaling scheme from the image it refers to,
-                                        pass the max height possible so coords can be rescaled.
-        :return: the annotation_id of the generated image annotation
+        Creates an image annotation from a raw `DetectionResult` dataclass.
+
+        In addition to dumping the annotation to the `ImageAnnotation` cache, you can also dump the annotation to the
+        `image` of an annotation with a given `annotation_id`. This is useful if you want to send the sub image to a
+        subsequent pipeline component.
+
+        It is also possible to generate an `Image` of the given raw annotation and store it in its `image`. The
+        resulting image is given as a sub image of `self` defined by its bounding box coordinates. Use `crop_image` to
+        explicitly store the sub image as a numpy array.
+
+        Args:
+            detect_result: A `DetectionResult`, generally coming from `ObjectDetector`.
+            to_annotation_id: Dumps the created image annotation to `image` of the given `annotation_id`. Requires the
+                              target annotation to have a non-None image.
+            to_image: If True, will populate `image`.
+            crop_image: Only makes sense if `to_image` is True and if a numpy array is stored in the original image.
+                        Will generate `Image.image`.
+            detect_result_max_width: If the detect result has a different scaling scheme from the image it refers to,
+                                     pass the max width possible so coordinates can be rescaled.
+            detect_result_max_height: If the detect result has a different scaling scheme from the image it refers to,
+                                      pass the max height possible so coordinates can be rescaled.
+
+        Returns:
+            The `annotation_id` of the generated image annotation, or `None` if there was a context error.
+
+        Raises:
+            TypeError: If `detect_result.box` is not of type list or `np.ndarray`.
+            ValueError: If the parent annotation's image is None or if the annotation's image is None.
         """
         self.assert_datapoint_passed()
         if not isinstance(detect_result.box, (list, np.ndarray)):
@@ -171,14 +191,17 @@ class DatapointManager:
         score: Optional[float] = None,
     ) -> Optional[str]:
         """
-        Create a category annotation and dump it as sub category to an already created annotation.
-
-        :param category_name: category name
-        :param category_id: category id
-        :param sub_cat_key: the key to dump the created annotation to.
-        :param annotation_id: id, of the parent annotation. Currently, this can only be an image annotation.
-        :param score: Add a score.
-        :return: the annotation_id of the generated category annotation
+        Creates a category annotation and dumps it as a subcategory to an already created annotation.
+
+        Args:
+            category_name: The category name.
+            category_id: The category id.
+            sub_cat_key: The key to dump the created annotation to.
+            annotation_id: The id of the parent annotation. Currently, this can only be an image annotation.
+            score: The score to add.
+
+        Returns:
+            The `annotation_id` of the generated category annotation, or `None` if there was a context error.
         """
         self.assert_datapoint_passed()
         with MappingContextManager(
@@ -213,15 +236,18 @@ class DatapointManager:
         score: Optional[float] = None,
     ) -> Optional[str]:
         """
-        Create a container annotation and dump it as sub category to an already created annotation.
-
-        :param category_name: category name
-        :param category_id: category id
-        :param sub_cat_key: the key to dump the created annotation to.
-        :param annotation_id: id, of the parent annotation. Currently, this can only be an image annotation.
-        :param value: A value to store
-        :param score: Add a score.
-        :return: annotation_id of the generated container annotation
+        Creates a container annotation and dumps it as a subcategory to an already created annotation.
+
+        Args:
+            category_name: The category name.
+            category_id: The category id.
+            sub_cat_key: The key to dump the created annotation to.
+            annotation_id: The id of the parent annotation. Currently, this can only be an image annotation.
+            value: The value to store.
+            score: The score to add.
+
+        Returns:
+            The `annotation_id` of the generated container annotation, or None if there was a context error.
         """
         self.assert_datapoint_passed()
         with MappingContextManager(
@@ -252,13 +278,16 @@ class DatapointManager:
         self, relationship_name: ObjectTypes, target_annotation_id: str, annotation_id: str
     ) -> Optional[str]:
         """
-        Create a relationship annotation and dump it to the target annotation.
+        Creates a relationship annotation and dumps it to the target annotation.
 
-        :param relationship_name: The relationship key
-        :param target_annotation_id: Annotation_id of the parent `ImageAnnotation`
-        :param annotation_id: The annotation_id to dump the relationship to
+        Args:
+            relationship_name: The relationship key.
+            target_annotation_id: The `annotation_id` of the parent `ImageAnnotation`.
+            annotation_id: The `annotation_id` to dump the relationship to.
 
-        :return: Annotation_id of the parent `ImageAnnotation` for references if the dumpy has been successful
+        Returns:
+            The `annotation_id` of the parent `ImageAnnotation` for reference if the dump has been successful, or `None`
+            if there was a context error.
         """
         self.assert_datapoint_passed()
         with MappingContextManager(
@@ -285,16 +314,20 @@ class DatapointManager:
         annotation_id: Optional[str] = None,
     ) -> Optional[str]:
         """
-        Creates a sub category of a summary annotation. If a summary of the given `annotation_id` does not exist, it
-        will create a new one.
-        :param summary_key: will store the category annotation as sub category
-        :param summary_name: will create the summary name as category name
-        :param summary_number: will store the value in category_id.
-        :param summary_value: will create a ContainerAnnotation and store the corresponding value
-        :param summary_score: will store the score
-        :param annotation_id: id of the parent annotation. Note, that the parent annotation must have `image` to
-        be not None.
-        :return: `annotation_id` of the generated category annotation
+        Creates a subcategory of a summary annotation.
+
+        If a summary of the given `annotation_id` does not exist, it will create a new one.
+
+        Args:
+            summary_key: Stores the category annotation as a subcategory.
+            summary_name: Creates the summary name as the category name.
+            summary_number: Stores the value in `category_id`.
+            summary_value: Creates a `ContainerAnnotation` and stores the corresponding value.
+            summary_score: Stores the score.
+            annotation_id: The id of the parent annotation. Note that the parent annotation must have `image` not None.
+
+        Returns:
+            The `annotation_id` of the generated category annotation, or None if there was a context error.
         """
         self.assert_datapoint_passed()
         if annotation_id is not None:
@@ -341,13 +374,22 @@ class DatapointManager:
 
     def deactivate_annotation(self, annotation_id: str) -> None:
         """
-        Deactivate annotation by given annotation_id
+        Deactivates the annotation by the given `annotation_id`.
 
-        :param annotation_id: annotation_id
+        Args:
+            annotation_id: The `annotation_id` to deactivate.
         """
         ann = self._cache_anns[annotation_id]
         ann.deactivate()
 
     def get_annotation(self, annotation_id: str) -> ImageAnnotation:
-        """get single `ImageAnnotation`"""
+        """
+        Gets a single `ImageAnnotation`.
+
+        Args:
+            annotation_id: The `annotation_id` of the annotation to retrieve.
+
+        Returns:
+            The `ImageAnnotation` corresponding to the given `annotation_id`.
+        """
         return self._cache_anns[annotation_id]