dsa-helpers 1.0.3.dev0__tar.gz → 1.0.4.dev1__tar.gz

{dsa_helpers-1.0.3.dev0/dsa_helpers.egg-info → dsa_helpers-1.0.4.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: dsa_helpers
-Version: 1.0.3.dev0
+Version: 1.0.4.dev1
 Summary: Utility functions for working with the DSA girder client.
 Author-email: "Juan C. Vizcarra" <jvizcar@emory.edu>
 Maintainer-email: "Juan C. Vizcarra" <jvizcar@emory.edu>
@@ -26,6 +26,7 @@ Requires-Dist: transformers[torch]
 Requires-Dist: datasets
 Requires-Dist: torchvision
 Requires-Dist: large-image
+Dynamic: license-file
 
 # Digital Slide Archive (DSA) Helpers
 Digital Slide Archive Python utility library.
@@ -39,15 +40,4 @@ This Python PyPI package is found [here](https://pypi.org/project/dsa-helpers/).
 ## Extra dependencies
 If you are getting a large image error, then install large image using the instructions provided in their [GitHub page](https://github.com/girder/large_image#:~:text=pip%20install%20large%2Dimage%5Ball%5D%20%2D%2Dfind%2Dlinks%20https%3A//girder.github.io/large_image_wheels).
 
-## Instructions for Development
-1. Install requirements for building and distributing package:
-```
-$ python3 -m pip install --upgrade build  # for building package
-$ python3 -m pip install --upgrade twine  # for uploading to PyPI
-```
-2. When ready to build:
-    - Modify "pyproject.toml" file, change the "version" key to a different value than a version already pushed.
-    - Run ```$ python3 -m build```. This will create a dist directory and put your new wheel and tar distribution files there.
-3. To install locally for development: ```$ pip3 install dist/dsa_helpers-*.whl```, choosing the wheel version you want to test.
-4. Upload to PyPI using twine: ```python3 -m twine upload --repository pypi dist/*```
-    * You can specify specific files to upload, the line above pushes everything in dist directory.
+A readthedocs for this library can be found [here](https://david-andrew-gutman-dsa-helpers.readthedocs-hosted.com/en/latest/index.html).

dsa_helpers-1.0.4.dev1/README.md

@@ -0,0 +1,13 @@
+# Digital Slide Archive (DSA) Helpers
+Digital Slide Archive Python utility library.
+
+This library is available for installation through [Python Package Index (PyPI)](https://pypi.org/).
+
+This library was tested using Python version 3.11.8 and uses the dependencies described in requirements.txt.
+
+This Python PyPI package is found [here](https://pypi.org/project/dsa-helpers/).
+
+## Extra dependencies
+If you are getting a large image error, then install large image using the instructions provided in their [GitHub page](https://github.com/girder/large_image#:~:text=pip%20install%20large%2Dimage%5Ball%5D%20%2D%2Dfind%2Dlinks%20https%3A//girder.github.io/large_image_wheels).
+
+A readthedocs for this library can be found [here](https://david-andrew-gutman-dsa-helpers.readthedocs-hosted.com/en/latest/index.html).

dsa_helpers-1.0.4.dev1/dsa_helpers/image_utils.py

@@ -0,0 +1,101 @@
+"""Image utility functions for DSA Helpers.
+
+This module provides various utility functions for image processing and
+manipulation.
+
+It includes functions for:
+- Exctracting contours from binary masks, and formatting them into a
+GeoDataFrame.
+
+Note:
+    This module requires external dependencies such as OpenCV and
+    shapely.
+"""
+
+import numpy as np
+import cv2 as cv
+from .imread import imread
+
+from shapely.affinity import translate
+from shapely.geometry import Polygon
+
+
+def label_mask_to_polygons(
+    mask: str | np.ndarray,
+    x_offset: int = 0,
+    y_offset: int = 0,
+    exclude_labels: int | list[int] = 0,
+    min_area: int = 0,
+) -> list[Polygon, int]:
+    """
+    Extract contours from a label mask and convert them into shapely
+    polygons.
+
+    Args:
+        mask (str | np.ndarray): Path to the mask image or the mask.
+        x_offset (int): Offset to add to x coordinates of polygons.
+        y_offset (int): Offset to add to y coordinates of polygons.
+        exclude_labels (int | list[int]): Label(s) to exclude from the
+            output.
+        min_area (int): Minimum area of polygons to include.
+
+    Returns:
+        list[Polygon, int]: List of polygons and their corresponding
+            labels.
+
+    """
+    # Convert exclude_labels to a list if it's an integer.
+    if isinstance(exclude_labels, int):
+        exclude_labels = [exclude_labels]
+
+    # Read the mask if it's a path.
+    if isinstance(mask, str):
+        mask = imread(mask, grayscale=True)
+
+    # Unique labels, excluding those specified in exclude_labels.
+    labels = [
+        label for label in np.unique(mask) if label not in exclude_labels
+    ]
+
+    polygons = []  # track all polygons
+
+    # Loop through unique label index.
+    for label in labels:
+        # Filter to mask for this label.
+        label_mask = (mask == label).astype(np.uint8)
+
+        # Find contours.
+        contours, hierarchy = cv.findContours(
+            label_mask, cv.RETR_TREE, cv.CHAIN_APPROX_SIMPLE
+        )
+
+        # Process the contours.
+        polygons_dict = {}
+
+        for idx, (contour, h) in enumerate(zip(contours, hierarchy[0])):
+            # The contour should contain at least three points, otherwise it's
+            # not a polygon.
+            if len(contour) > 3:
+                # To include holes, group the polygons by their parent index.
+                if idx not in polygons_dict:
+                    polygons_dict[idx] = {"holes": []}
+
+                if h[3] == -1:
+                    # This does not have a parent so its a polygon.
+                    polygons_dict[idx]["polygon"] = contour.reshape(-1, 2)
+                else:
+                    # This has a parent so its a hole.
+                    polygons_dict[h[3]]["holes"].append(contour.reshape(-1, 2))
+
+        # Convert to shapely polygon objects.
+        for data in polygons_dict.values():
+            polygon = Polygon(data["polygon"], holes=data["holes"])
+
+            # Shift the polygon by the offset.
+            polygon = translate(polygon, xoff=x_offset, yoff=y_offset)
+
+            # Include the polygon if it's greater than the minimum area.
+            if polygon.area >= min_area:
+                polygons.append([polygon, int(label)])
+
+    return polygons

dsa_helpers-1.0.4.dev1/dsa_helpers/utils.py

@@ -0,0 +1,35 @@
+"""Utility functions for DSA Helpers.
+
+This module provides various miscellaneous utility functions that are
+not grouped into their own modules.
+"""
+
+from shapely.geometry import Polygon
+
+
+def remove_small_holes(
+    polygon: Polygon, hole_area_threshold: float
+) -> Polygon:
+    """Remove small holes from a shapely polygon.
+
+    Args:
+        polygon (shapely.geometry.Polygon): Polygon to remove holes
+            from.
+        hole_area_threshold (float): Minimum area of a hole to keep it.
+
+    Returns:
+        shapely.geometry.Polygon: Polygon with small holes removed.
+
+    """
+    if not polygon.interiors:  # if there are no holes, return as is
+        return polygon
+
+    # Filter out small holes
+    new_holes = [
+        hole
+        for hole in polygon.interiors
+        if Polygon(hole).area > hole_area_threshold
+    ]
+
+    # Create a new polygon with only large holes
+    return Polygon(polygon.exterior, new_holes)

{dsa_helpers-1.0.3.dev0 → dsa_helpers-1.0.4.dev1/dsa_helpers.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: dsa_helpers
-Version: 1.0.3.dev0
+Version: 1.0.4.dev1
 Summary: Utility functions for working with the DSA girder client.
 Author-email: "Juan C. Vizcarra" <jvizcar@emory.edu>
 Maintainer-email: "Juan C. Vizcarra" <jvizcar@emory.edu>
@@ -26,6 +26,7 @@ Requires-Dist: transformers[torch]
 Requires-Dist: datasets
 Requires-Dist: torchvision
 Requires-Dist: large-image
+Dynamic: license-file
 
 # Digital Slide Archive (DSA) Helpers
 Digital Slide Archive Python utility library.
@@ -39,15 +40,4 @@ This Python PyPI package is found [here](https://pypi.org/project/dsa-helpers/).
 ## Extra dependencies
 If you are getting a large image error, then install large image using the instructions provided in their [GitHub page](https://github.com/girder/large_image#:~:text=pip%20install%20large%2Dimage%5Ball%5D%20%2D%2Dfind%2Dlinks%20https%3A//girder.github.io/large_image_wheels).
 
-## Instructions for Development
-1. Install requirements for building and distributing package:
-```
-$ python3 -m pip install --upgrade build  # for building package
-$ python3 -m pip install --upgrade twine  # for uploading to PyPI
-```
-2. When ready to build:
-    - Modify "pyproject.toml" file, change the "version" key to a different value than a version already pushed.
-    - Run ```$ python3 -m build```. This will create a dist directory and put your new wheel and tar distribution files there.
-3. To install locally for development: ```$ pip3 install dist/dsa_helpers-*.whl```, choosing the wheel version you want to test.
-4. Upload to PyPI using twine: ```python3 -m twine upload --repository pypi dist/*```
-    * You can specify specific files to upload, the line above pushes everything in dist directory.
+A readthedocs for this library can be found [here](https://david-andrew-gutman-dsa-helpers.readthedocs-hosted.com/en/latest/index.html).

{dsa_helpers-1.0.3.dev0 → dsa_helpers-1.0.4.dev1}/dsa_helpers.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ docs/source/conf.py
 docs/source/index.rst
 dsa_helpers/__init__.py
 dsa_helpers/girder_utils.py
+dsa_helpers/image_utils.py
 dsa_helpers/imread.py
 dsa_helpers/imwrite.py
 dsa_helpers/mongo_utils.py

{dsa_helpers-1.0.3.dev0 → dsa_helpers-1.0.4.dev1}/pyproject.toml

@@ -35,7 +35,7 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
 ]
 keywords = ["dsa", "girder", "girder_client"]
-version = "v1.0.3.dev0"
+version = "v1.0.4.dev1"
 
 [project.urls]
 Repository = "https://github.com/Gutman-Lab/dsa-python-utils"

{dsa_helpers-1.0.3.dev0 → dsa_helpers-1.0.4.dev1}/tests/test.ipynb

@@ -8,15 +8,6 @@
     "Test different functions of the library."
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import dsa_helpers.dash"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -101,7 +92,28 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Help on function imwrite in module dsa_helpers.imwrite:\n",
+      "\n",
+      "imwrite(fp: str, img: numpy.ndarray, grayscale: bool = False) -> None\n",
+      "    Save an image to disk.\n",
+      "\n",
+      "    Args:\n",
+      "        img (np.ndarray): The image to save.\n",
+      "        fp (str): The file path to save the image.\n",
+      "        grayscale (bool, optional): Whether to save the image as grayscale.\n",
+      "            Defaults to False.\n",
+      "\n",
+      "    Raises:\n",
+      "        ValueError: The image must be grayscale, RGB, or RGBA.\n",
+      "\n"
+     ]
+    }
+   ],
    "source": []
   }
  ],

dsa_helpers-1.0.3.dev0/README.md

@@ -1,24 +0,0 @@
-# Digital Slide Archive (DSA) Helpers
-Digital Slide Archive Python utility library.
-
-This library is available for installation through [Python Package Index (PyPI)](https://pypi.org/).
-
-This library was tested using Python version 3.11.8 and uses the dependencies described in requirements.txt.
-
-This Python PyPI package is found [here](https://pypi.org/project/dsa-helpers/).
-
-## Extra dependencies
-If you are getting a large image error, then install large image using the instructions provided in their [GitHub page](https://github.com/girder/large_image#:~:text=pip%20install%20large%2Dimage%5Ball%5D%20%2D%2Dfind%2Dlinks%20https%3A//girder.github.io/large_image_wheels).
-
-## Instructions for Development
-1. Install requirements for building and distributing package:
-```
-$ python3 -m pip install --upgrade build  # for building package
-$ python3 -m pip install --upgrade twine  # for uploading to PyPI
-```
-2. When ready to build:
-    - Modify "pyproject.toml" file, change the "version" key to a different value than a version already pushed.
-    - Run ```$ python3 -m build```. This will create a dist directory and put your new wheel and tar distribution files there.
-3. To install locally for development: ```$ pip3 install dist/dsa_helpers-*.whl```, choosing the wheel version you want to test.
-4. Upload to PyPI using twine: ```python3 -m twine upload --repository pypi dist/*```
-    * You can specify specific files to upload, the line above pushes everything in dist directory.

dsa_helpers-1.0.3.dev0/dsa_helpers/utils.py

@@ -1,78 +0,0 @@
-import numpy as np
-from . import imread
-import cv2 as cv
-
-from shapely.geometry import Polygon
-from shapely.affinity import translate
-
-
-def mask_to_shapely(
-    mask: str | np.ndarray,
-    x_offset: int = 0,
-    y_offset: int = 0,
-    background_label: int | None = 0,
-    min_area: int = 0,
-) -> list[Polygon, int]:
-    """
-    Extract contours from a label mask and convert them into shapely
-    polygons.
-
-    Args:
-        mask (str | np.ndarray): Path to the mask image or the mask.
-        x_offset (int): Offset to add to x coordinates of polygons.
-            Default is 0.
-        y_offset (int): Offset to add to y coordinates of polygons.
-            Default is 0.
-        background_label (int | None): Label value of the background class,
-            which is ignored. Default is 0. If None then all labels are
-            considered.
-
-    Returns:
-        list[Polygon, int]: List of polygons and their corresponding
-            labels.
-
-    """
-    if isinstance(mask, str):
-        mask = imread(mask, grayscale=True)
-
-    # Find unique labels (excluding background 0)
-    labels = [label for label in np.unique(mask) if label != background_label]
-
-    polygons = []  # Track all polygons.
-
-    # Loop through unique label index.
-    for label in labels:
-        # Filter to mask for this label.
-        label_mask = (mask == label).astype(np.uint8)
-
-        # Find contours.
-        contours, hierarchy = cv.findContours(
-            label_mask, cv.RETR_TREE, cv.CHAIN_APPROX_SIMPLE
-        )
-
-        # Process the contours.
-        polygons_dict = {}
-
-        for idx, (contour, h) in enumerate(zip(contours, hierarchy[0])):
-            if len(contour) > 3:
-                if idx not in polygons_dict:
-                    polygons_dict[idx] = {"holes": []}
-
-                if h[3] == -1:
-                    polygons_dict[idx]["polygon"] = contour.reshape(-1, 2)
-                else:
-                    polygons_dict[h[3]]["holes"].append(contour.reshape(-1, 2))
-
-        # Now that we know the polygon and the holes, create a Polygon object for each.
-        for data in polygons_dict.values():
-            if "polygon" in data:
-                polygon = Polygon(data["polygon"], holes=data["holes"])
-
-                # Shift the polygon by the offset.
-                polygon = translate(polygon, xoff=x_offset, yoff=y_offset)
-
-                # Skip small polygons.
-                if polygon.area >= min_area:
-                    polygons.append([polygon, label])
-
-    return polygons