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

{dsa_helpers-1.0.3.dev0/dsa_helpers.egg-info → dsa_helpers-1.0.4}/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
 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/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.3.dev0/dsa_helpers/utils.py → dsa_helpers-1.0.4/dsa_helpers/image_utils.py

@@ -1,16 +1,30 @@
+"""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
-from . import imread
 import cv2 as cv
+from .imread import imread
 
-from shapely.geometry import Polygon
 from shapely.affinity import translate
+from shapely.geometry import Polygon
 
 
-def mask_to_shapely(
+def label_mask_to_polygons(
     mask: str | np.ndarray,
     x_offset: int = 0,
     y_offset: int = 0,
-    background_label: int | None = 0,
+    exclude_labels: int | list[int] = 0,
     min_area: int = 0,
 ) -> list[Polygon, int]:
     """
@@ -20,25 +34,30 @@ def mask_to_shapely(
     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.
+        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)
 
-    # Find unique labels (excluding background 0)
-    labels = [label for label in np.unique(mask) if label != background_label]
+    # 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.
+    polygons = []  # track all polygons
 
     # Loop through unique label index.
     for label in labels:
@@ -54,16 +73,21 @@ def mask_to_shapely(
         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))
 
-        # Now that we know the polygon and the holes, create a Polygon object for each.
+        # Convert to shapely polygon objects.
         for data in polygons_dict.values():
             if "polygon" in data:
                 polygon = Polygon(data["polygon"], holes=data["holes"])
@@ -71,8 +95,8 @@ def mask_to_shapely(
                 # Shift the polygon by the offset.
                 polygon = translate(polygon, xoff=x_offset, yoff=y_offset)
 
-                # Skip small polygons.
+                # Include the polygon if it's greater than the minimum area.
                 if polygon.area >= min_area:
-                    polygons.append([polygon, label])
+                    polygons.append([polygon, int(label)])
 
     return polygons

dsa_helpers-1.0.4/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/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
 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}/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}/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"
 
 [project.urls]
 Repository = "https://github.com/Gutman-Lab/dsa-python-utils"

{dsa_helpers-1.0.3.dev0 → dsa_helpers-1.0.4}/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.