deepvisiontools 0.0.1__py3-none-any.whl

deepvisiontools/__init__.py

@@ -0,0 +1,16 @@
+from deepvisiontools.config.config import Configuration
+from deepvisiontools.train.trainer import Trainer
+from deepvisiontools.data.dataset import DeepVisionDataset, DeepVisionLoader
+from deepvisiontools.utils import visualization
+from deepvisiontools.inference.predictor import Predictor
+
+__version__ = "0.0.1"
+
+__all__ = (
+    Configuration,
+    Trainer,
+    DeepVisionDataset,
+    DeepVisionLoader,
+    visualization,
+    Predictor,
+)

deepvisiontools/config/__init__.py

@@ -0,0 +1,3 @@
+from deepvisiontools.config.config import Configuration
+
+__all__ = ["Configuration"]

deepvisiontools/config/config.py

@@ -0,0 +1,176 @@
+from typing import Literal, Union
+import deepvisiontools.config.errors as er
+import numpy as np
+import torch
+import random as rd
+
+
+class _SingletonConfig(type):
+    """Metaclass for Config class Singleton design pattern"""
+
+    _instance = None
+
+    def __call__(cls, *args, **kwargs):
+        if not isinstance(cls._instance, cls):
+            cls._instance = super().__call__(*args, **kwargs)
+        return cls._instance
+
+
+class Configuration(metaclass=_SingletonConfig):
+    """Configuration class for deepvisiontools (Singleton -> can be instancied once and then point to same object). Store all configuration information about the library configuration.
+    If you wish to changes parameters later on, you can simply modify the corresponding attributes.
+
+
+    Args:
+        device (``Literal["cpu", "cuda"]``, **optional**): Device to be used by default when creating objects, running models etc. Defaults to "cpu".
+        data_type (``Literal["instance_mask", "bbox", "keypoint", "semantic_mask"]``, **optional**): Default format to use in dataset, models, prediction etc. Defaults to "bbox".
+        num_classes (``int``, **optional**): Number of classes in model. Defaults to 1.
+        mask_min_size (``int``, **optional**): Minimal size of mask to be considered : below this threshold annotation will be ignored. Defaults to 15.
+        semantic_mask_logits_combination (``Literal["avg", "min", "max"]``): How to combine logits in patchification or adding semantic masks. avg takes the mean, min takes the minimum and max takes the maximum.
+        splitted_mask_handling (``bool``, **optional**): If set to True redefine masks that are splitted (after cropping for example) so they belong to independant objects. Defaults to False.
+        model_nms_threshold (``float``, **optional**): Default nms iou threshold used in models. Defaults to 0.45.
+        model_confidence_threshold (``float``, **optional**): Default model confidence threshold to consider it a valid object prediction. Defaults to 0.5.
+        model_max_detection (``int``, **optional**): Maximum number of objects outputed by a model (useful for some models such as yolo type models). Defaults to 300.
+        metrics_matcher_type (``Literal["bbox", "instance_mask"]``, **optional**): Object matcher data type used in metrics (note that instance_mask is slower because needs transition to cpu to save gpu memory). If data_type is instance mask and matcher type is bbox will convert it to bbox for matching in metrics. Defaults to "bbox".
+        metrics_match_iou_threshold (``float``, **optional**): Metrics matcher iou threshold. Defaults to 0.45.
+        patchifier_mode (``Literal["bbox", "instance_mask"]``, **optional**): Patchifier data type used for nms and duplicate supresser. If data_type is mask and patchifier to bbox will convert for according operations. Defaults to "bbox".
+        seed (``Union[False, int]``, **optional**): use a manual seed to enforce reproducibility (you probably want to also switch deterministic to True in that case). If False it ends reproducibility. Defaults to False.
+        deterministic (``bool``, **optional**): Use deterministic algorithms. Helps further reproducibility (see also seeds). Be careful : some models can't be deterministic so sometimes you need to switch it to False even if you are manually seeding. Defaults to False.
+
+
+    Example:
+    ----------
+
+    .. highlight:: python
+    .. code-block:: python
+
+        >>> from deepvisiontools import Configuration()
+        >>> config = Configuration(data_type = "instance_mask") # can instantiate with given parameter
+        >>> config.device = "cuda"  # can modify parameters by modifying attributes / properties
+
+
+    Attributes
+    ----------
+
+    Attributes:
+        - data_type (``Literal["instance_mask", "bbox", "keypoint", "semantic_mask"]``, **optional**): Default format to use in dataset, models, prediction etc. Defaults to "bbox".
+        - num_classes (``int``): Number of classes in model. Defaults to 1.
+        - mask_min_size (``int``): Minimal size of mask to be considered : below this threshold annotation will be ignored. Defaults to 15.
+        - semantic_mask_logits_combination (``Literal["avg", "min", "max"]``): How to combine logits in patchification or adding semantic masks. avg takes the mean, min takes the minimum and max takes the maximum.
+        - splitted_mask_handling (``bool``): If set to True redefine masks that are splitted (after cropping for example) so they belong to independant objects. Defaults to False.
+        - model_nms_threshold (``float``): Default nms iou threshold used in models. Defaults to 0.45.
+        - model_confidence_threshold (``float``): Default model confidence threshold to consider it a valid object prediction. Defaults to 0.5.
+        - model_max_detection (``int``): Maximum number of objects outputed by a model (useful for some models such as yolo type models). Defaults to 300.
+        - metrics_matcher_type (``Literal["bbox", "instance_mask"]``): Object matcher data type used in metrics. If data_type is instance mask and matcher type is bbox will convert it to bbox for matching in metrics. Defaults to "bbox".
+        - metrics_match_iou_threshold (``float``): Metrics matcher iou threshold. Defaults to 0.45.
+        - patchifier_mode (``Literal["bbox", "instance_mask"]``): Patchifier data type used for nms and duplicate supresser. If data_type is mask and patchifier to bbox will convert for according operations. Defaults to "bbox".
+
+
+    Attributes
+    ----------
+
+    Properties:
+        - device (``Literal["cpu", "cuda"]``): Device to be used by default when creating objects, running models etc. Defaults to "cpu".
+        - seed (``Union[False, int]``, **optional**): use a manual seed to enforce reproducibility (you probably want to also switch deterministic to True in that case). If False it ends reproducibility. Defaults to False.
+        - deterministic (``bool``, **optional**): Use deterministic algorithms. Helps further reproducibility (see also seeds). Be careful : some models can't be deterministic so sometimes you need to switch it to False even if you are manually seeding. Defaults to False.
+
+
+
+    Notes:
+        1) If you use instance_mask, bbox will included when needed from the masks.
+        2) you can change model_nms_threshold and model_confidence_threshold for the entire lib by modifying the attributes
+        3) In instance mode, by default the target ``Format`` remove small objects in case their masks contains less than min_mask_threshold (default 5 pixels).
+        Change the attribute to modify this behaviour.
+        4) The option splitted_mask_handling is by default False.
+        If you set to True, when performing transformation on object mask that split it into discontinuous sub-masks the library creates new objects for every sub-masks.
+        Otherwise they will still be describing the same unique object
+
+    """
+
+    def __init__(
+        self,
+        device: Literal["cpu", "cuda"] = "cpu",
+        data_type: Literal[
+            "instance_mask", "bbox", "keypoint", "semantic_mask"
+        ] = "bbox",
+        num_classes: int = 1,
+        mask_min_size: int = 20,
+        semantic_mask_logits_combination: Literal["avg", "min", "max"] = "avg",
+        splitted_mask_handling: bool = False,
+        model_nms_threshold: float = 0.45,
+        model_confidence_threshold: float = 0.5,
+        model_max_detection: int = 300,
+        metrics_matcher_type: Literal["bbox", "instance_mask"] = "bbox",
+        metrics_match_iou_threshold: float = 0.45,
+        patchifier_mode: Literal["bbox", "instance_mask"] = "bbox",
+        seed: Union[False, int] = False,
+        deterministic: bool = False,
+    ):
+
+        # generic
+        self.data_type = data_type
+        self.device: str = device
+        self.num_classes: int = num_classes
+        # Format specific parameters
+        self.mask_min_size = mask_min_size
+        self.splitted_mask_handling = splitted_mask_handling
+        self.semantic_mask_logits_combination = semantic_mask_logits_combination
+        # Model build_results parameters
+        self.model_nms_threshold = model_nms_threshold
+        self.model_confidence_threshold = model_confidence_threshold
+        self.model_max_detection = model_max_detection
+        # metrics params
+        self.metrics_matcher_type = metrics_matcher_type
+        self.metrics_match_iou_threshold = metrics_match_iou_threshold
+        # patchifier setup
+        self.patchifier_mode = patchifier_mode
+        # reproducibility
+        self.seed = seed
+        self.deterministic = deterministic
+
+    @property
+    def device(self):
+        return self._device
+
+    @device.setter
+    def device(self, val: Literal["cpu", "cuda"]):
+        er.check_device_availability(val)
+        self._device = val
+
+    @property
+    def seed(self):
+        return self._seed
+
+    @seed.setter
+    def seed(self, val: Union[False, int]):
+        assert val == False or isinstance(
+            val, int
+        ), f"seed must be a int or False. Got {val}"
+        if val:
+            rd.seed(val)
+            np.random.seed(val)
+            torch.manual_seed(val)
+        else:
+            rd.seed()
+            np.random.seed()
+            torch.seed()
+        self._seed = val
+
+    @property
+    def deterministic(self):
+        return self.deterministic
+
+    @deterministic.setter
+    def deterministic(self, val: bool):
+        assert isinstance(val, bool), f"deterministic must be a bool, got {val}"
+        if val:
+            torch.use_deterministic_algorithms(True)
+            # disable convolutions benchmark
+            if torch.cuda.is_available():
+                torch.backends.cudnn.benchmark = False
+        else:
+            torch.use_deterministic_algorithms(False)
+            # disable convolutions benchmark
+            if torch.cuda.is_available():
+                torch.backends.cudnn.benchmark = True
+        self._deterministic = val

deepvisiontools/config/errors.py

@@ -0,0 +1,12 @@
+import torch
+
+
+def check_device_availability(device):
+    assert (
+        device == "cpu" or device == "cuda"
+    ), f"{device} is not a valid device, must be: cuda or: cpu"
+    if device != "cpu":
+        assert (
+            torch.cuda.is_available()
+        ), "CUDA seems unavailable. Please run torch.cuda.is_available() to verify"
+    pass

deepvisiontools/data/__init__.py

@@ -0,0 +1,24 @@
+from deepvisiontools.data.dataset import DeepVisionDataset, DeepVisionLoader
+from deepvisiontools.data.augmentation_class import Augmentation
+from deepvisiontools.data.additional_augmentations import (
+    RandomCropAndResize,
+    RandomCenterCropAndResize,
+    RandomChangeBackground,
+    RandomPadAndResize,
+)
+from deepvisiontools.data.batch_augmentations import (
+    AbstractBatchAugmenter,
+    MosaicBatchAugmenter,
+)
+
+__all__ = (
+    "DeepVisionDataset",
+    "DeepVisionLoader",
+    "Augmentation",
+    "RandomCropAndResize",
+    "RandomPadAndResize",
+    "RandomChangeBackground",
+    "RandomCenterCropAndResize",
+    "AbstractBatchAugmenter",
+    "MosaicBatchAugmenter",
+)

deepvisiontools/data/additional_augmentations.py

@@ -0,0 +1,201 @@
+import torch
+import torchvision.transforms.v2 as T
+from torchvision.transforms.v2 import Transform
+from typing import Sequence, Union, Tuple
+import random as rd
+from pathlib import Path
+from deepvisiontools.preprocessing.image import load_image
+from torchvision.tv_tensors import BoundingBoxes, Mask
+from torch import Tensor
+import copy
+
+
+class RandomCropAndResize(Transform):
+    """
+    With a given probability, apply RandomCrop and Resize from torchvision.transforms.v2.
+    NB : here we resize only and systematically if cropped.
+
+    Args:
+        crop (``Union[int, Sequence[int]]``): Size to crop
+        resize (``Union[int, Sequence[int]]``): Size to resize
+        p (``float``, **optional**): probability. Defaults to 0.5.
+
+
+    **Methods**:
+    """
+
+    def __init__(
+        self,
+        crop: Union[int, Sequence[int]],
+        resize: Union[int, Sequence[int]],
+        p=0.5,
+        **kwargs,
+    ):
+
+        super().__init__(**kwargs)
+        self.p = p
+        self.crop = T.RandomCrop(crop)
+        self.resize = T.Resize(resize)
+
+    def forward(self, *inputs):
+        if torch.rand(1) >= self.p:
+            pass
+        else:
+            inputs = self.crop.forward(inputs)
+            inputs = self.resize.forward(inputs)
+        return inputs
+
+
+class RandomCenterCropAndResize(Transform):
+    """
+    With a given probability, apply CenterCrop and Resize from torchvision.transforms.v2.
+    NB : here we resize only and systematically if cropped.
+
+        Args:
+            crop (``Union[int, Sequence[int]]``): Size to crop
+            resize (``Union[int, Sequence[int]]``): Size to resize
+            p (``float``, **optional**): probability. Defaults to 0.5.
+    """
+
+    def __init__(self, crop: Sequence[int], resize: Sequence[int], p=0.5, **kwargs):
+        super().__init__(**kwargs)
+        self.p = p
+        self.crop = T.CenterCrop(crop)
+        self.resize = T.Resize(resize)
+
+    def forward(self, *inputs):
+        if torch.rand(1) >= self.p:
+            pass
+        else:
+            inputs = self.crop.forward(inputs)
+            inputs = self.resize.forward(inputs)
+        return inputs
+
+
+class RandomPadAndResize(Transform):
+    """
+    With a given probability, apply Pad and Resize from torchvision.transforms.v2. This looks like a zoom out effect by decreasing spatial resolution.
+    NB : here we resize only and systematically if Padded.
+
+        Args:
+            MaxPad (``Union[int, Sequence[int]]``): maximum padding bounds can be int for common padding bound for all borders or sequence of 4 ints for (t, l, b, r)
+            resize (``Tuple[int, int]``): Size to resize
+            p (``float``, **optional**): probability to apply transformation. Defaults to 0.5.
+    """
+
+    def __init__(
+        self,
+        maxpad: Sequence[int],
+        resize: Tuple[int, int],
+        p=0.5,
+        **kwargs,
+    ):
+
+        super().__init__(**kwargs)
+        self.p = p
+        self.max_pad = (maxpad,) * 4 if isinstance(maxpad, int) else maxpad
+        self.resize = T.Resize(resize)
+
+    def forward(self, *inputs):
+        if torch.rand(1) >= self.p:
+            return inputs
+        else:
+            t = rd.randrange(0, self.max_pad[0])
+            l = rd.randrange(0, self.max_pad[1])
+            r = rd.randrange(0, self.max_pad[2])
+            b = rd.randrange(0, self.max_pad[3])
+            padder = T.Pad([t, l, b, r])
+            inputs = padder(inputs)
+            inputs = self.resize(inputs)
+        return inputs
+
+
+class RandomChangeBackground(Transform):
+    """With a given probability p, swap image background. New background is taken from an image folder for which path is provided.
+    Note 1 : it is implemented only for instance_mask, semantic_mask and bbox data type
+    Note 2 : new background image type must be one of .jpg, .jpeg, .png, .tif, .tiff, .PNG, .JPG, .JPEG, .TIF, .TIFF
+    Args:
+        background_dir_path (``Union[str, Path]``): Path to background folder
+        p (``float``, **optional**): Probability. Defaults to 0.5.
+    """
+
+    IMPLEMENTED_TVTENSOR = [
+        BoundingBoxes,
+        Mask,
+    ]  # list of available hooks, i.e implemented for these type of tv_tensor
+
+    IMG_TYPE = [
+        ".jpg",
+        ".jpeg",
+        ".png",
+        ".tif",
+        ".tiff",
+        ".PNG",
+        ".JPG",
+        ".JPEG",
+        ".TIF",
+        ".TIFF",
+    ]
+
+    def __init__(self, background_dir_path: Union[str, Path], p: float = 0.5, **kwargs):
+
+        super().__init__(**kwargs)
+        path = (
+            background_dir_path
+            if isinstance(background_dir_path, Path)
+            else Path(background_dir_path)
+        )
+        list_bckg_imgs = []
+        for stem in RandomChangeBackground.IMG_TYPE:
+            list_bckg_imgs += list(path.glob(f"*{stem}"))
+        self.bckg_imgs = list_bckg_imgs
+        self.p = p
+        self._truth_extracter = _ExtractTruthFromTargetImage()
+
+    def forward(self, *inputs):
+        mu = torch.rand(1)
+        if mu > self.p:
+            return inputs
+        assert (
+            len(inputs) == 2
+        ), f"RandomChangeBackground is implemented only for exactly image and target input provided. You can't provide only image or additional item like scores. Got {inputs}"
+        image, target = inputs
+        assert (
+            type(target) in RandomChangeBackground.IMPLEMENTED_TVTENSOR
+        ), f"RandomChangeBackground is implemented only for {RandomChangeBackground.IMPLEMENTED_TVTENSOR} torchvision tv_tensors. Got {type(target)}"
+
+        # randomly select background image
+        original_dtype = image.dtype
+        image = image.float()
+        idx = torch.randint(0, len(self.bckg_imgs), (1,)).item()
+        bck_img = load_image(self.bckg_imgs[idx]).to(image.device).float()
+        bck_img = T.Resize(image.shape[-2:])(bck_img)
+        removed_bckg = self._truth_extracter(image, target)
+        removed_bckg[removed_bckg == -1.0] = bck_img[removed_bckg == -1.0]
+        return removed_bckg.to(original_dtype), target
+
+
+class _ExtractTruthFromTargetImage:
+    """Handle background removing from target. Background is asserted as -1 to avoid errors removing 0 entries from image."""
+
+    def __call__(self, image: Tensor, targ: Tensor) -> Tensor:
+        if isinstance(targ, Mask):
+            rm_bckg = self._call_mask(image, targ)
+        elif isinstance(targ, BoundingBoxes):
+            rm_bckg = self._call_bbox(image, targ)
+        return rm_bckg
+
+    def _call_mask(self, image: Tensor, targ: Mask) -> Tensor:
+        removed_bckg = copy.deepcopy(image)
+        removed_bckg[:, targ == 0] = -1.0
+        return removed_bckg
+
+    def _call_bbox(self, image: Tensor, targ: BoundingBoxes) -> Tensor:
+        mask = Mask(torch.zeros(image.shape[-2:]))
+        for box in targ:
+            x1, y1, x2, y2 = box.to(torch.uint64).split(1)
+            x1, y1, x2, y2 = tuple(
+                max(i.item(), 0) for i in (x1, y1, x2, y2)
+            )  # ensure that bbox has coordinates positive
+            mask[y1:y2, x1:x2] = 1
+        return self._call_mask(image, mask)

deepvisiontools/data/augmentation_class.py

@@ -0,0 +1,37 @@
+from typing import List
+from deepvisiontools.formats import (
+    BaseFormat,
+    BboxFormat,
+    BboxData,
+    InstanceMaskData,
+    InstanceMaskFormat,
+)
+import torchvision.transforms.v2 as T
+from torch import Tensor
+from torchvision.tv_tensors import Image
+import torch
+import deepvisiontools.data.errors as er
+
+# Tested : Mask : Ok : RandomResize, RandomCrop, RandomZoomOut, ScaleJitter, RandomHorizontalFlip / Vertical, RandomRotation, RandomAffine, RandomPerspective
+#           Errors : RandomCropIou if you have masks only -> needs boxes
+#           boxes : Ok : same as mask but careful with crop / rotation : can lead to slightly off new boxes as per rotation / crops don't preserve structural information of boxes by nature
+
+# TODO check augmentation rotation with boxes : got an error of different input shape / canvas size between image and boxes
+
+
+class Augmentation:
+    """Class that handles augmentation in dataset. Call on different Formats (data_type) specific methods
+    Args:
+        augmentations (List[T.Transform]): List of torchvision.transforms.v2 Transform classes (or from deepvisiontools.data.additional_augmentations)
+    """
+
+    def __init__(self, augmentations: List[T.Transform]) -> None:
+        self.transform = T.Compose(augmentations)
+
+    def __call__(self, image: Tensor, target: BaseFormat):
+        """Augment depending on format type"""
+        image = Image(image)
+        transformed_target, _, transformed_img = target.apply_augmentation(
+            image, self.transform
+        )
+        return transformed_img, transformed_target