phenotypic 0.6.0__py3-none-any.whl

phenotypic/__init__.py

@@ -0,0 +1,38 @@
+__version__ = "0.6.0"
+
+from .core._image import Image
+from .core._imread import imread
+from .core._grid_image import GridImage
+
+from . import (
+    data,
+    detection,
+    measure,
+    grid,
+    abstract,
+    objects,
+    morphology,
+    pipeline,
+    correction,
+    enhancement,
+    transform,
+    util,
+)
+
+__all__ = [
+    "Image",  # Class imported from core
+    "imread",  # Function imported from core
+    "GridImage",  # Class imported from core
+    "data",  
+    "detection",  
+    "measure",  
+    "grid",  
+    "abstract",  
+    "objects",  
+    "morphology",  
+    "pipeline",  
+    "correction",  
+    "enhancement",
+    "transform",  
+    "util",  
+]

phenotypic/abstract/__init__.py

@@ -0,0 +1,27 @@
+from ._feature_measure import FeatureMeasure
+from ._image_operation import ImageOperation
+from ._image_enhancer import ImageEnhancer
+from ._image_corrector import ImageCorrector
+from ._object_detector import ObjectDetector
+from ._map_modifier import MapModifier
+from ._threshold_detector import ThresholdDetector
+from ._grid_operation import GridOperation
+from ._grid_finder import GridFinder
+from ._grid_corrector import GridCorrector
+from ._grid_map_modifier import GridMapModifier
+from ._grid_measure import GridFeatureMeasure
+
+__all__ = [
+    "FeatureMeasure",
+    "ImageOperation",
+    "ImageEnhancer",
+    "ImageCorrector",
+    "ObjectDetector",
+    "MapModifier",
+    "ThresholdDetector",
+    "GridOperation",
+    "GridFinder",
+    "GridCorrector",
+    "GridMapModifier",
+    "GridFeatureMeasure",
+]

phenotypic/abstract/_docstring_metaclass.py

@@ -0,0 +1,22 @@
+
+class MeasureDocstringMeta(type):
+    """
+    Metaclass to automatically set the docstring of measure() to match _operate()
+    """
+
+    def __new__(cls, name, bases, dct):
+        # Set the docstring of measure() to match _operate()
+        if '_operate' in dct and 'measure' in dct:
+            dct['measure'].__doc__ = dct['_operate'].__doc__
+        return super().__new__(cls, name, bases, dct)
+
+class ApplyDocstringMeta(type):
+    """
+    Metaclass to automatically set the docstring of apply() to match _operate()
+    """
+
+    def __new__(cls, name, bases, dct):
+        # Set the docstring of measure() to match _operate()
+        if '_operate' in dct and 'measure' in dct:
+            dct['measure'].__doc__ = dct['_operate'].__doc__
+        return super().__new__(cls, name, bases, dct)

phenotypic/abstract/_feature_measure.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING: from phenotypic import Image
+
+import numpy as np
+import pandas as pd
+
+from ._docstring_metaclass import MeasureDocstringMeta
+from ._image_operation import ImageOperation
+from phenotypic.util.exceptions_ import OperationFailedError, InterfaceError
+
+
+# <<Interface>>
+class FeatureMeasure:
+    """
+    A FeatureExtractor is an abstract object intended to calculate measurements on the values within detected objects of
+    the image array. The __init__ constructor & _operate method are meant to be the only parts overloaded in inherited classes. This is so
+    that the main measure method call can contain all the necessary type validation and output validation checks to streamline development.
+    """
+
+    def measure(self, image: Image) -> pd.DataFrame:
+        try:
+            imcopy: Image = image.copy()
+
+            measurement = self._operate(image)
+
+            # TODO: Fix checks
+            # if not np.array_equal(imcopy.matrix[:], image.matrix[:]): raise ValueError(ARRAY_CHANGE_ERROR_MSG)
+            # if not np.array_equal(imcopy.enh_matrix[:], image.enh_matrix[:]): raise ValueError(ENHANCED_ARRAY_CHANGE_ERROR_MSG)
+            # if not np.array_equal(imcopy.omask[:], image.omask[:]): raise ValueError(MASK_CHANGE_ERROR_MSG)
+            # if not np.array_equal(imcopy.omap[:], image.omap[:]): raise ValueError(MAP_CHANGE_ERROR_MSG)
+
+            return measurement
+        except Exception as e:
+            raise OperationFailedError(operation=self.__class__.__name__,
+                                       image_name=image.name,
+                                       err_type=type(e),
+                                       message=str(e)
+                                       )
+
+    def _operate(self, image: Image) -> pd.DataFrame:
+        raise InterfaceError

phenotypic/abstract/_grid_corrector.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+if TYPE_CHECKING: from phenotypic import GridImage
+
+from phenotypic.abstract import ImageCorrector
+from phenotypic.abstract import GridOperation
+from phenotypic.util.exceptions_ import GridImageInputError, OutputValueError
+
+
+class GridCorrector(ImageCorrector, GridOperation):
+    def __init__(self, n_rows: int, n_cols: int):
+        self.n_rows = n_rows
+        self.n_cols = n_cols
+
+    def apply(self, image: GridImage, inplace=False) -> GridImage:
+        from phenotypic import GridImage
+
+        if not isinstance(image, GridImage): raise GridImageInputError
+        output = super().apply(image, inplace=inplace)
+        if not isinstance(output, GridImage): raise OutputValueError("GridImage")
+        return output
+

phenotypic/abstract/_grid_finder.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING: from phenotypic import Image
+
+import pandas as pd
+
+from phenotypic.abstract import FeatureMeasure
+from phenotypic.abstract import GridOperation
+
+
+class GridFinder(FeatureMeasure, GridOperation):
+    """
+    GridFinder measures grid information from the objects in various ways. Using the names here allow for streamlined integration.
+    Unlike other Grid series interfaces, GridExtractors can work on regular images, and should not be dependent on the GridImage class.
+
+    Parameters:
+        nrows (int): Number of rows in the grid.
+        ncols (int): Number of columns in the grid.
+
+    """
+    def __init__(self, nrows: int, ncols: int):
+        self.nrows = nrows
+        self.ncols = ncols
+
+    def _operate(self, image: Image) -> pd.DataFrame:
+        pass

phenotypic/abstract/_grid_map_modifier.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING: from phenotypic import GridImage
+
+from phenotypic.abstract import MapModifier
+from phenotypic.abstract import GridOperation
+from phenotypic.util.exceptions_ import GridImageInputError, InterfaceError
+
+
+class GridMapModifier(MapModifier, GridOperation):
+    def apply(self, image: GridImage, inplace: bool = False) -> GridImage:
+        from phenotypic import GridImage
+        if not isinstance(image, GridImage): raise GridImageInputError()
+        output = super().apply(image=image, inplace=inplace)
+        return output
+
+    def _operate(self, image: GridImage) -> GridImage:
+        raise InterfaceError()

phenotypic/abstract/_grid_measure.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+if TYPE_CHECKING: from phenotypic import GridImage
+
+import pandas as pd
+
+
+from phenotypic.abstract import FeatureMeasure
+from phenotypic.abstract import GridOperation
+from phenotypic.util.exceptions_ import GridImageInputError, OutputValueError
+
+
+class GridFeatureMeasure(FeatureMeasure, GridOperation):
+    def __init__(self, n_rows: int, n_cols: int):
+        self.n_rows = n_rows
+        self.n_cols = n_cols
+
+    def measure(self, image: GridImage) -> pd.DataFrame:
+        from phenotypic import GridImage
+        if not isinstance(image, GridImage): raise GridImageInputError()
+        output = super().measure(image)
+        if not isinstance(output, pd.DataFrame): raise OutputValueError("pandas.DataFrame")
+        return output

phenotypic/abstract/_grid_operation.py

@@ -0,0 +1,2 @@
+class GridOperation:
+    pass

phenotypic/abstract/_image_corrector.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING: from phenotypic import Image
+
+from typing import Union, Dict
+
+from ._image_operation import ImageOperation
+from phenotypic.util.exceptions_ import InterfaceError, OperationFailedError
+
+
+class ImageCorrector(ImageOperation):
+    """ImageCorrectors are for general operations that alter every image component such as rotating. These have no integrity checks.
+
+    """
+
+    def __init__(self):
+        pass
+
+    def apply(self, image: Image, inplace=False) -> Union[Image, Dict[str, Image]]:
+        try:
+            if inplace:
+                output = self._operate(image)
+            else:
+                output = self._operate(image.copy())
+            return output
+        except Exception as e:
+            raise OperationFailedError(operation=self.__class__.__name__,
+                                                  image_name=image.name,
+                                                  err_type=type(e),
+                                                  message=str(e)
+                                                  )
+
+    def _operate(self, image: Image) -> Image:
+        raise InterfaceError

phenotypic/abstract/_image_enhancer.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING: from phenotypic import Image
+
+import numpy as np
+from ._image_operation import ImageOperation
+from phenotypic.util.exceptions_ import InterfaceError, DataIntegrityError, OperationFailedError
+from phenotypic.util.constants_ import IMAGE_FORMATS
+
+
+class ImageEnhancer(ImageOperation):
+    def __init__(self):
+        pass
+
+    def apply(self, image: Image, inplace: bool = False) -> Image:
+        try:
+            # Make a copy for post checking
+            imcopy = image.copy()
+
+            # Reset the object map in case the inherited class forgets to do so
+            image.objmap.reset()
+
+            if inplace:
+                output = self._operate(image)
+            else:
+                output = self._operate(image.copy())
+
+            if image._image_format.is_array():
+                if not np.array_equal(output.array[:], imcopy.array[:]):
+                    raise DataIntegrityError(component='array', operation=self.__class__.__name__)
+
+            if not np.array_equal(output.matrix[:], imcopy.matrix[:]):
+                raise DataIntegrityError(component='matrix', operation=self.__class__.__name__)
+
+            return output
+        except Exception as e:
+            raise OperationFailedError(operation=self.__class__.__name__,
+                                       image_name=image.name,
+                                       err_type=type(e),
+                                       message=str(e)
+                                       )
+
+    def _operate(self, image: Image) -> Image:
+        raise InterfaceError

phenotypic/abstract/_image_operation.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING: from phenotypic import Image
+
+from ..util.exceptions_ import InterfaceError
+
+class ImageOperation:
+    """
+    Represents an abstract base class for image operations.
+
+    This class provides a common abstract for applying transformations or
+    operations to images. It defines a method to apply the operation and
+    enforces the implementation of the specific operation in a subclass.
+    Users can apply operations either in-place or on a copy of the image.
+
+    """
+    def apply(self, image, inplace=False) -> Image:
+        """
+        Applies a certain operation to an image, either in-place or on a copy.
+
+        Args:
+            image (Image): The input image to apply the operation on.
+            inplace (bool): If True, modifies the image in place; otherwise,
+                operates on a copy of the image.
+
+        Returns:
+            Image: The modified image after applying the operation.
+        """
+        if inplace:
+            return self._operate(image)
+        else:
+            return self._operate(image.copy())
+
+    def _operate(self, image: Image) -> Image:
+        """
+        A placeholder for the subfunction for an image operator for processing image objects.
+
+        This method is called from apply and must be implemented in a subclass. This allows for checks for data integrity to be made.
+
+        Args:
+            image (Image): The image object to be processed by internal operations.
+
+        Raises:
+            InterfaceError: Raised if the method is not implemented in a subclass.
+        """
+        raise InterfaceError

phenotypic/abstract/_map_modifier.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING: from phenotypic import Image
+
+import numpy as np
+
+from ._image_operation import ImageOperation
+from ..util.constants_ import IMAGE_FORMATS
+from phenotypic.util.exceptions_ import OperationFailedError, InterfaceError, DataIntegrityError
+
+
+# <<Interface>>
+class MapModifier(ImageOperation):
+    """Map modifiers edit the object map and are used for removing, combining, and re-ordering objects."""
+
+    def apply(self, image: Image, inplace: bool = False) -> Image:
+        try:
+            imcopy = image.copy()
+
+            if inplace:
+                output = self._operate(image)
+            else:
+                output = self._operate(image.copy())
+
+            # TODO: Fix this check
+            if output._image_format.is_array():
+                if not np.array_equal(imcopy.array[:], output.array[:]): raise DataIntegrityError(
+                    component='array', operation=self.__class__.__name__, image_name=image.name
+                )
+
+            # TODO: Fix this check
+            # if not np.array_equal(imcopy.matrix[:], output.matrix[:]): raise DataIntegrityError(
+            #     component='matrix', operation=self.__class__.__name__, image_name=image.name
+            # )
+
+            if not np.array_equal(imcopy.enh_matrix[:], output.enh_matrix[:]): raise DataIntegrityError(
+                component='enh_matrix', operation=self.__class__.__name__, image_name=image.name
+            )
+            return output
+        except DataIntegrityError as e:
+            raise e
+        except Exception as e:
+            raise OperationFailedError(operation=self.__class__.__name__,
+                                       image_name=image.name,
+                                       err_type=type(e),
+                                       message=str(e)
+                                       )
+
+    def _operate(self, image: Image) -> Image:
+        raise InterfaceError

phenotypic/abstract/_object_detector.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING: from phenotypic import Image
+
+import numpy as np
+from ._image_operation import ImageOperation
+from phenotypic.util.exceptions_ import OperationFailedError, DataIntegrityError, InterfaceError
+
+
+# <<Interface>>
+class ObjectDetector(ImageOperation):
+    """ObjectDetectors are for detecting objects in an image. They change the image object mask and map."""
+
+    def __init__(self):
+        pass
+
+    def apply(self, image: Image, inplace: bool = False) -> Image:
+        try:
+            imcopy = image.copy()
+
+            if inplace:
+                output = self._operate(image)
+            else:
+                output = self._operate(image.copy())
+
+            # Post Operation Checks
+            if not np.array_equal(imcopy.matrix[:], output.matrix[:]): raise DataIntegrityError(component='matrix',
+                                                                                                operation=self.__class__.__name__,
+                                                                                                image_name=image.name
+                                                                                                )
+            if not np.array_equal(imcopy.enh_matrix[:], output.enh_matrix[:]): raise DataIntegrityError(component='enh_matrix',
+                                                                                                        operation=self.__class__.__name__,
+                                                                                                        image_name=image.name
+                                                                                                        )
+            output.objmap.relabel()
+            return output
+        except DataIntegrityError as e:
+            raise e
+        except Exception as e:
+            raise OperationFailedError(operation=self.__class__.__name__,
+                                       image_name=image.name,
+                                       err_type=type(e),
+                                       message=str(e)
+                                       )
+
+    def _operate(self, image: Image) -> Image:
+        raise InterfaceError

phenotypic/abstract/_threshold_detector.py

@@ -0,0 +1,8 @@
+from ._object_detector import ObjectDetector
+
+
+
+# <<Interface>>
+class ThresholdDetector(ObjectDetector):
+    """ThresholdDetectors are a type of ObjectDetector that use a threshold, such as Otsu's threshold, to detect objects in an image. They change the image object mask and map."""
+    pass

phenotypic/core/__init__.py

@@ -0,0 +1,7 @@
+from . import accessors, handlers
+
+# Define __all__ to include all imported objects
+__all__ = [
+    "accessors",
+    "handlers"
+]

phenotypic/core/_grid_image.py

@@ -0,0 +1,6 @@
+from .handlers import ImageGridHandler
+
+class GridImage(ImageGridHandler):
+    pass
+
+GridImage.__doc__ = ImageGridHandler.__doc__

phenotypic/core/_image.py

@@ -0,0 +1,16 @@
+from .handlers._image_hsv_handler import ImageHsvHandler
+
+
+class Image(ImageHsvHandler):
+    """A comprehensive class for handling image processing, including manipulation, information sync, metadata management, and format conversion.
+
+    The `Image` class is designed to load, process, and manage image data using different
+    representation formats (e.g., arrays and matrices). This class allows for metadata editing,
+    schema definition, and subcomponent handling to streamline image processing tasks.
+
+    Note:
+        - If the input_image is 2-D, the ImageHandler leave the array form as None
+        - If the input_image is 3-D, the ImageHandler will automatically set the matrix component to the grayscale representation.
+        - Added in v0.5.0, HSV handling support
+    """
+    pass

phenotypic/core/_imread.py

@@ -0,0 +1,16 @@
+from ._image import Image
+from pathlib import Path
+
+
+def imread(filepath: str):
+    """
+    Reads an image from the specified file path using the `Image().imread` method.
+
+    Args:
+        filepath (str): The path to the image file to be read.
+
+    Returns:
+        Image: An `Image` object containing the data read from the specified file.
+    """
+    filepath = Path(filepath)
+    return Image().imread(filepath)

phenotypic/core/accessors/__init__.py

@@ -0,0 +1,122 @@
+"""
+Overview
+========
+
+The ``accessors`` submodule provides a comprehensive set of tools and interfaces for accessing and interacting with the various data components of an image. These components range from raw pixel data and matrix representations to object masks, metadata, and high-level measurements. Additionally, it includes utilities that streamline development workflows involving image processing and analysis.
+
+The goal is to provide efficient, standardized access to image data while enabling intuitive and flexible integration for advanced image manipulation and analysis tasks.
+
+Image Data Containers
+=====================
+
+    This category includes classes designed to offer fundamental abstractions for accessing image data in various representations:
+
+1. :class:`ImageArray`
+    Represents the multichannel pixel data of an image when provided. Useful for direct manipulation and pixel-wise operations.
+
+2. :class:`ImageMatrix`
+    Provides structured access to the image in its matrix form, offering methods suited for mathematical or analytical operations on image data. Automatically converted from RGB using weighted luminance conversion.
+
+3. :class:`ImageEnhancedMatrix`
+    An enhanceable copy of the image matrix to improve detection while maintaining the original image data integrity.
+
+Objects and Object Mapping
+==========================
+
+These classes manage object-level abstractions and their corresponding data mappings:
+
+1. :class:`ObjectMap`
+    Represents a mapping of detected objects or regions in the image to their associated IDs. Useful for:
+
+    - Object identification
+    - Bounding box management
+    - Spatial relationships between objects.
+    - Region-based calculations
+
+2. :class:`ObjectMask`
+    An abstract specialized for working with binary masks of objects. Useful for morphological operations such as erosion, dilation, and closing.
+
+    Note:
+        Changes to the object mask will cause relabeling of the object map
+
+High-Level Object Interfaces
+============================
+
+These classes provide consolidated access to manage multiple object-level and metadata components.
+
+1. :class:`ObjectsAccessor`
+    Facilitates high-level interaction with detected objects within an image. Features include:
+
+    - Feature extraction
+    - Object comparison
+    - Visualization of detected objects
+
+2. :class:`MeasurementContainer` *(Coming Soon!)*
+    Encapsulates measurements or attributes associated with objects, such as size, shape, or intensity. Organizes measurements for reproducibility and easier analysis.
+
+3. :class:`MetadataContainer` *(Coming Soon!)*
+    Responsible for storing and accessing metadata associated with the image. Examples of metadata include:
+
+    - Acquisition details
+    - Resolution
+    - Additional contextual information.
+
+HSV (Hue, Saturation, Brightness) Interface
+===========================================
+
+1. :class:`HsvAccessor`
+Provides detailed access to the HSV (Hue, Saturation, Brightness) color space components of an image. This abstract includes support for:
+
+- Direct pixel access via ``__getitem__`` and ``__setitem__``.
+- Advanced utilities for image visualization and object-specific manipulation in the HSV domain.
+
+**Key Methods:**
+    - ``shape``: Returns the dimensions of the HSV representation.
+    - ``copy``: Creates and returns a full copy of the HSV data structure.
+    - ``histogram``: Computes a histogram for the HSV image or parts of it.
+    - ``show``: Displays the HSV image.
+    - ``show_objects``: Visualizes objects overlaid on the HSV image.
+    - ``extract_obj_hue``, ``extract_obj_saturation``, ``extract_obj_brightness``, ``extract_obj``:
+Extract specific HSV component data for individual image objects, aiding in targeted color-based analysis.
+
+Purpose and Use Cases
+=====================
+
+The ``accessors`` submodule is designed for developers and researchers working on advanced image processing tasks. It is particularly suited for:
+
+    - Object detection and feature extraction
+    - HSV color-space analysis
+    - Grid Analysis
+    - Metadata association for image datasets
+    - Advanced mathematical and matrix operations on image data.
+
+"""
+from ._image_accessor import ImageAccessor
+from ._image_data_accessor import ImageDataAccessor
+from ._image_array_accessor import ImageArray
+from ._image_matrix_accessor import ImageMatrix
+from ._image_enh_matrix_accessor import ImageEnhancedMatrix
+from ._objmap_accessor import ObjectMap
+from ._objmask_accessor import ObjectMask
+
+from ._image_objects_accessor import ObjectsAccessor
+# from ._measurement_container_interface import MeasurementAccessor
+from ._metadata_accessor import MetadataAccessor
+
+from ._hsv_accessor import HsvAccessor
+from ._grid_accessor import GridAccessor
+
+# Define __all__ to include all imported objects
+__all__ = [
+    "ImageAccessor",
+    "ImageDataAccessor",
+    "ImageArray",
+    "ImageMatrix",
+    "ImageEnhancedMatrix",
+    "ObjectMap",
+    "ObjectMask",
+    "ObjectsAccessor",
+    "HsvAccessor",
+    "GridAccessor",
+    "MetadataAccessor",
+]