dsa-helpers 0.1__py3-none-any.whl

dsa_helpers/__init__.py

@@ -0,0 +1,5 @@
+# Shadow imports.
+from .login import login
+
+# Modules that should be available.
+from . import girder_utils

dsa_helpers/girder_utils.py

@@ -0,0 +1,120 @@
+# Functions using the girder client.
+from girder_client import GirderClient
+import pickle
+import numpy as np
+
+
+def get_item_large_image_metadata(gc: GirderClient, item_id: str) -> dict:
+    """Get large image metadata for an item.
+
+    Args:
+        gc (girder_client.GirderClient): The authenticated girder client.
+        item_id (str): The item id.
+
+    Returns:
+        dict: The metadata of the large image item.
+
+    """
+    return gc.get(f"item/{item_id}/tiles")
+
+
+def get_thumbnail(
+    gc: GirderClient,
+    item_id: str,
+    mag: float | None = None,
+    width: int | None = None,
+    height: int | None = None,
+    fill: int | tuple = (255, 255, 255),
+) -> np.ndarray:
+    """Get the thumbnail image by a specific magnification or shape. If mag is
+    not None, then width and height are ignored. Fill is only used when both
+    width and height are provided, to return the thumbnail at the exact shape.
+    DSA convention will fill the height of the image, centering the image and
+    filling the top and bottom of the image equally.
+
+    Args:
+        gc (girder_client.GirderClient): The authenticated girder client.
+        item_id (str): The item id.
+        mag (float, optional): The magnification. Defaults to None.
+        width (int, optional): The width of the thumbnail. Defaults to None.
+        height (int, optional): The height of the thumbnail. Defaults to None.
+        fill (int | tuple, optional): The fill color. Defaults to (255, 255, 255).
+
+    Returns:
+        np.ndarray: The thumbnail image.
+
+    Raises:
+        ValueError: If neither mag, width, nor height is provided.
+
+    """
+    if all([mag is None, width is None, height is None]):
+        raise ValueError("Either mag, width, or height must be provided.")
+
+    if mag is not None:
+        get_url = f"item/{item_id}/tiles/region?magnification{mag}"
+    else:
+        # Instead use width and height.
+        get_url = f"item/{item_id}/tiles/thumbnail?"
+
+        if width is not None and height is not None:
+            if isinstance(fill, (tuple, list)):
+                if len(fill) == 3:
+                    fill = f"rgb({fill[0]},{fill[1]},{fill[2]})"
+                elif len(fill) == 4:
+                    fill = f"rgba({fill[0]},{fill[1]},{fill[2]},{fill[3]})"
+
+            get_url += f"width={width}&height={height}&fill={fill}"
+        elif width is not None:
+            get_url += f"width={width}"
+        else:
+            get_url += f"height={height}"
+
+    get_url += "&encoding=pickle"
+
+    response = gc.get(get_url, jsonResp=False)
+
+    return pickle.loads(response.content)
+
+
+def get_region(
+    gc: GirderClient,
+    item_id: str,
+    left: int,
+    top: int,
+    width: int,
+    height: int,
+    mag: float | None = None,
+) -> np.ndarray:
+    """Get a region of the image for an item. Note that the output image might
+    not be in the shape (width, height) if left + width or top + height exceeds
+    the image size. The output image will be the maximum size possible.
+
+    Args:
+        gc (girder_client.GirderClient): The authenticated girder client.
+        item_id (str): The item id.
+        left (int): The left coordinate.
+        top (int): The top coordinate.
+        width (int): The width of the region.
+        height (int): The height of the region.
+        mag (float, optional): The magnification. Defaults to None which returns
+            the image at scan magnification. Using a mag lower than the scan
+            magnification will result in an ouptut image smaller than the
+            width and height. Similarly, using a mag higher than the scan
+            magnification will result in an output image larger than the width
+            and height.
+
+    Returns:
+        np.ndarray: The region of the image.
+
+    """
+    get_url = (
+        f"item/{item_id}/tiles/region?left={left}&top={top}&regionWidth="
+        f"{width}&regionHeight={height}&encoding=pickle"
+    )
+
+    if mag is not None:
+        get_url += f"&magnification={mag}"
+
+    response = gc.get(get_url, jsonResp=False)
+
+    return pickle.loads(response.content)

dsa_helpers/login.py

@@ -0,0 +1,40 @@
+# Login / authenticate function for the girder client.
+from girder_client import GirderClient
+
+
+def login(
+    api_url: str,
+    login_or_email: str | None = None,
+    password: str | None = None,
+    api_key: str | None = None,
+) -> GirderClient:
+    """Authenticate a girder client with the given credentials or interactively
+    if none is given.
+
+    Args:
+        api_url (str): The DSA girder API url.
+        login_or_email (str | None): The login or email. Defaults to None.
+        password (str | None): Password for login / email. Defaults to None.
+        api_key (str | None): The api key to authenticate with. Defaults to None.
+
+    Returns:
+        girder_client.GirderClient: The authenticated girder client.
+
+    Raises:
+        ValueError: If neither login_or_email nor api_key is provided.
+
+    """
+    if login_or_email is None and api_key is None:
+        raise ValueError("Either login_or_email or api_key must be provided.")
+
+    gc = GirderClient(apiUrl=api_url)
+
+    if api_key is None:
+        if password is None:
+            _ = gc.authenticate(username=login_or_email, interactive=True)
+        else:
+            _ = gc.authenticate(username=login_or_email, password=password)
+    else:
+        _ = gc.authenticate(apiKey=api_key)
+
+    return gc

dsa_helpers-0.1.dist-info/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dsa_helpers-0.1.dist-info/METADATA

@@ -0,0 +1,22 @@
+Metadata-Version: 2.1
+Name: dsa_helpers
+Version: 0.1
+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>
+Project-URL: Repository, https://github.com/Gutman-Lab/dsa-python-utils
+Keywords: dsa,girder,girder_client
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: girder-client ==3.2.3
+Requires-Dist: numpy ==2.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.

dsa_helpers-0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+dsa_helpers/__init__.py,sha256=xMnPN050W8KjVTg38p9xStBCGAjfBx8kD5TnbITBd9o,107
+dsa_helpers/girder_utils.py,sha256=KJ5Mr5RbRa67rfeo6_FbAVv8jKDZmyco_0d3fdpY_t4,4067
+dsa_helpers/login.py,sha256=etJ5NUKkKo8mw_x5bbUJU8E3XD4RTOZLjhYIJrfb2QQ,1275
+dsa_helpers-0.1.dist-info/LICENSE,sha256=2bm9uFabQZ3Ykb_SaSU_uUbAj2-htc6WJQmS_65qD00,1073
+dsa_helpers-0.1.dist-info/METADATA,sha256=51tQr3e2PaUgITkSLLDItXYN50sTB_UX2KOTVwkC72Y,884
+dsa_helpers-0.1.dist-info/WHEEL,sha256=-oYQCr74JF3a37z2nRlQays_SX2MqOANoqVjBBAP2yE,91
+dsa_helpers-0.1.dist-info/top_level.txt,sha256=BmAEDVvDa1MJlSUFHWzx73UKec3o1K6dFUd9tHwgHGo,12
+dsa_helpers-0.1.dist-info/RECORD,,

dsa_helpers-0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (71.0.3)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dsa_helpers-0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+dsa_helpers