imaging-server-kit 0.0.1__py3-none-any.whl

imaging_server_kit/__init__.py

@@ -0,0 +1,8 @@
+from imaging_server_kit.client import Client
+from imaging_server_kit.server import Server, Parameters
+from imaging_server_kit.registry import Registry
+from imaging_server_kit.encoding import encode_contents, decode_contents
+from imaging_server_kit.serialization import (
+    serialize_result_tuple,
+    deserialize_result_tuple,
+)

imaging_server_kit/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)

imaging_server_kit/client.py

@@ -0,0 +1,116 @@
+import requests
+from typing import List, Dict, Tuple
+import imaging_server_kit as serverkit
+import numpy as np
+
+
+class Client:
+    def __init__(self) -> None:
+        self._server_url = ""
+        self._algorithms = {}
+
+    def connect(self, server_url: str) -> int:
+        self.server_url = server_url
+
+        try:
+            response = requests.get(f"{self.server_url}/services")
+        except Exception:
+            self.algorithms = {}
+            return (-1, "Server unavailable.")
+
+        if response.status_code == 200:
+            services = response.json().get("services")
+            self.algorithms = services
+            return (response.status_code, services)
+        else:
+            response_body = response.json()
+            self.algorithms = {}
+            return (response.status_code, response_body)
+
+    @property
+    def server_url(self) -> str:
+        return self._server_url
+
+    @server_url.setter
+    def server_url(self, server_url: str):
+        self._server_url = server_url
+
+    @property
+    def algorithms(self) -> Dict[str, str]:
+        return self._algorithms
+
+    @algorithms.setter
+    def algorithms(self, algorithms: Dict[str, str]):
+        self._algorithms = algorithms
+
+    def run_algorithm(self, algorithm: str = None, **algo_params) -> List[Tuple]:
+        if algorithm is None:
+            if len(self.algorithms) > 0:
+                algorithm = self.algorithms[0]
+            else:
+                print("No algorithms available.")
+                return []
+
+        if algorithm not in self.algorithms:
+            print(f"Not an available algorithm: {algorithm}")
+            return []
+
+        # Encode all numpy array parameters
+        for param in algo_params:
+            if isinstance(algo_params[param], np.ndarray):
+                algo_params[param] = serverkit.encode_contents(algo_params[param])
+
+        response = requests.post(
+            f"{self.server_url}/{algorithm}", json=algo_params, timeout=300
+        )
+        if response.status_code == 201:
+            return serverkit.deserialize_result_tuple(response.json())
+        elif response.status_code == 422:
+            # This actually doesn't occurr when it should...
+            print(f"Algorithm parameters are not valid!")
+            return []
+        else:
+            print(
+                f"Algorithm server returned an error status code: {response.status_code}"
+            )
+            return []
+
+    def get_algorithm_parameters(self, algorithm: str = None) -> Dict:
+        if algorithm is None:
+            if len(self.algorithms) > 0:
+                algorithm = self.algorithms[0]
+            else:
+                print("No algorithms available.")
+                return []
+        
+        response = requests.get(f"{self.server_url}/{algorithm}/parameters")
+        if response.status_code == 200:
+            return response.json()
+        else:
+            print(
+                f"Error status while attempting to get algoritm parameters: {response.status_code}"
+            )
+            return -1
+
+    def get_sample_images(self, algorithm: str = None) -> "np.ndarray":
+        if algorithm is None:
+            if len(self.algorithms) > 0:
+                algorithm = self.algorithms[0]
+            else:
+                print("No algorithms available.")
+                return []
+        
+        response = requests.get(f"{self.server_url}/{algorithm}/sample_images")
+
+        if response.status_code == 200:
+            images = []
+            for content in response.json().get("sample_images"):
+                encoded_image = content.get("sample_image")
+                image = serverkit.decode_contents(encoded_image)
+                images.append(image)
+            return images
+        else:
+            print(
+                f"Error status while attempting to get algorithm sample images: {response.status_code}"
+            )
+            return -1

imaging_server_kit/encoding.py

@@ -0,0 +1,29 @@
+import io
+import base64
+import numpy as np
+import tifffile
+
+def decode_contents(contents: str) -> np.ndarray:
+    """Decodes base64 encoded image contents into a NumPy array.
+
+    Args:
+        contents (str): The base64 encoded string of the image.
+
+    Returns:
+        np.ndarray: The decoded image represented as a NumPy array.
+    """
+    return tifffile.imread(io.BytesIO(base64.b64decode(contents)))
+
+def encode_contents(image: np.ndarray) -> str:
+    """Encodes a NumPy array image into a base64 string.
+
+    Args:
+        image (np.ndarray): The image to encode.
+
+    Returns:
+        str: The base64 encoded string representation of the image.
+    """
+    img_byte_arr = io.BytesIO()
+    tifffile.imwrite(img_byte_arr, image)
+
+    return base64.b64encode(img_byte_arr.getvalue()).decode()

imaging_server_kit/registry.py

@@ -0,0 +1,73 @@
+import requests
+from fastapi import FastAPI, Request, status, HTTPException
+
+
+class Registry:
+    def __init__(self) -> None:
+        self.app = FastAPI()
+
+        self.services = {}
+        self.register_routes()
+
+    def register_routes(self):
+        @self.app.get("/")
+        def home():
+            return list_services()
+
+        @self.app.get("/services")
+        def list_services():
+            return {"services": list(self.services.keys())}
+
+        @self.app.post("/register", status_code=status.HTTP_201_CREATED)
+        async def register_service(request: Request):
+            data = await request.json()
+            service_name = data.get("name")
+            service_url = data.get("url")
+            if service_name in self.services:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Service {service_name} is already registered.",
+                )
+
+            self.services[service_name] = service_url
+            return {"message": "Service registered"}
+
+        @self.app.post("/deregister", status_code=status.HTTP_201_CREATED)
+        async def deregister_service(request: Request):
+            data = await request.json()
+            service_name = data.get("name")
+            if service_name in self.services:
+                del self.services[service_name]
+                return {"message": "Service deregistered"}
+            else:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail=f"Service {service_name} could not be deregistered because it is not in the list of services.",
+                )
+
+        @self.app.get("/{algorithm}")
+        def get_algorithm_status(algorithm):
+            response = requests.get(f"{self.services.get(algorithm)}/")
+            return response.json()
+
+        @self.app.post("/{algorithm}", status_code=status.HTTP_201_CREATED)
+        async def run_algorithm(algorithm, request: Request):
+            data = await request.json()
+            response = requests.post(
+                f"{self.services.get(algorithm)}/{algorithm}/", json=data
+            )
+            return response.json()
+
+        @self.app.get("/{algorithm}/parameters")
+        def get_algorithm_parameters(algorithm):
+            response = requests.get(
+                f"{self.services.get(algorithm)}/{algorithm}/parameters"
+            )
+            return response.json()
+
+        @self.app.get("/{algorithm}/sample_images")
+        def get_algorithm_sample_images(algorithm):
+            response = requests.get(
+                f"{self.services.get(algorithm)}/{algorithm}/sample_images"
+            )
+            return response.json()

imaging_server_kit/serialization.py

@@ -0,0 +1,49 @@
+from typing import Dict, List, Tuple
+import numpy as np
+import imaging_server_kit as serverkit
+
+def serialize_result_tuple(result_data_tuple: List[Tuple]) -> List[Dict]:
+    """Converts the result data tuple to dict that can be serialized as JSON (used by the server)."""
+    serialized_results = []
+    for (data, data_params, data_type) in result_data_tuple:
+        if data_type in ['image', 'points', 'shapes', 'vectors', 'tracks']:
+            serialized_results.append({
+                "type": data_type,
+                "data": serverkit.encode_contents(data.astype(np.float32)),
+                "data_params": data_params
+            })
+        elif data_type == 'labels':
+            serialized_results.append({
+                "type": data_type,
+                "data": serverkit.encode_contents(data.astype(np.uint32)),
+                "data_params": data_params
+            })
+        else:
+            print(f"Unknown data_type: {data_type}")
+
+    return serialized_results
+
+def deserialize_result_tuple(serialized_results: List[Dict]) -> List[Tuple]:
+    """Converts serialized JSON results to a results data tuple (used by the client)."""
+    result_data_tuple = []
+    for result_dict in serialized_results:
+        data_type = result_dict.get("type")
+        data = result_dict.get("data")
+        data_params = result_dict.get("data_params")
+        if data_type in ["image", 'points', 'shapes', 'vectors', 'tracks']:
+            data_tuple = (
+                serverkit.decode_contents(data).astype(float),
+                data_params,
+                data_type
+            )
+        elif data_type == "labels":
+            data_tuple = (
+                serverkit.decode_contents(data).astype(int),
+                data_params,
+                data_type
+            )
+        else:
+            data_tuple = (data, data_params, "none")
+        result_data_tuple.append(data_tuple)
+
+    return result_data_tuple

imaging_server_kit/server.py

@@ -0,0 +1,97 @@
+import os
+import requests
+from typing import Type, List, Tuple
+from pydantic import BaseModel, ConfigDict
+from fastapi import FastAPI, status
+import imaging_server_kit as serverkit
+
+
+REGISTRY_URL = os.getenv("REGISTRY_URL", "http://servers_registry:8000")
+
+
+class Parameters(BaseModel):
+    ...
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Server:
+    def __init__(self, algorithm_name: str, parameters_model: Type[BaseModel]):
+        self.algorithm_name = algorithm_name
+        self.parameters_model = parameters_model
+
+        self.app = FastAPI(title=algorithm_name)
+
+        self.app.on_event("startup")(self.register_with_registry)
+        self.app.on_event("shutdown")(self.deregister_from_registry)
+
+        self.register_routes()
+
+        self.services = [self.algorithm_name]
+
+    def register_with_registry(self):
+        try:
+            response = requests.get(f"{REGISTRY_URL}/")
+        except Exception:
+            print("Registry unavailable.")
+            return
+
+        response = requests.post(
+            f"{REGISTRY_URL}/register",
+            json={
+                "name": self.algorithm_name,
+                "url": f"http://{self.algorithm_name}:8000",
+            },
+        )
+        if response.status_code == 201:
+            print(f"Service {self.algorithm_name} registered successfully.")
+        else:
+            print(f"Failed to register {self.algorithm_name}: {response.json()}")
+
+    def deregister_from_registry(self):
+        deregister_url = f"{REGISTRY_URL}/deregister"
+        response = requests.post(deregister_url, json={"name": self.algorithm_name})
+        if response.status_code == 201:
+            print(f"Service {self.algorithm_name} deregistered.")
+        else:
+            print(f"Failed to deregister {self.algorithm_name}: {response.json()}")
+
+    def register_routes(self):
+        @self.app.get("/")
+        def home():
+            return list_services()
+
+        @self.app.get("/test")
+        def test():
+            return list_services()
+
+        @self.app.get("/services")
+        def list_services():
+            return {"services": self.services}
+
+        # I noted that the 422 error doesn't get raised when parameters are invalid. Weird?
+        @self.app.post(f"/{self.algorithm_name}/", status_code=status.HTTP_201_CREATED)
+        async def run_algo(
+            algo_params: self.parameters_model,
+        ):  # To check: this should automatically validate the parameters and return HTTP-422 otherwise?
+            result_data_tuple = self.run_algorithm(**algo_params.dict())
+            serialized_results = serverkit.serialize_result_tuple(result_data_tuple)
+            return serialized_results
+
+        @self.app.get(f"/{self.algorithm_name}/parameters", response_model=dict)
+        def get_algo_params():
+            return self.parameters_model.model_json_schema()
+
+        @self.app.get(f"/{self.algorithm_name}/sample_images", response_model=dict)
+        def get_sample_images():
+            images = self.load_sample_images()
+            encoded_images = [
+                {"sample_image": serverkit.encode_contents(image)} for image in images
+            ]
+            return {"sample_images": encoded_images}
+
+    def load_sample_images(self) -> List["np.ndarray"]:
+        raise NotImplementedError("Subclasses should implement this method")
+
+    def run_algorithm(self, **algo_params) -> List[Tuple]:
+        raise NotImplementedError("Subclasses should implement this method")

imaging_server_kit-0.0.1.dist-info/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2024, EPFL
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

imaging_server_kit-0.0.1.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.1
+Name: imaging-server-kit
+Version: 0.0.1
+Summary: Run image processing algorithms in a FastAPI server.
+Author-email: Mallory Wittwer <mallory.wittwer@epfl.ch>
+License: Copyright (c) 2024, EPFL
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        * Redistributions of source code must retain the above copyright notice, this
+          list of conditions and the following disclaimer.
+        
+        * Redistributions in binary form must reproduce the above copyright notice,
+          this list of conditions and the following disclaimer in the documentation
+          and/or other materials provided with the distribution.
+        
+        * Neither the name of copyright holder nor the names of its
+          contributors may be used to endorse or promote products derived from
+          this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: homepage, https://gitlab.com/epfl-center-for-imaging/imaging-server-kit
+Project-URL: repository, https://gitlab.com/epfl-center-for-imaging/imaging-server-kit
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: uvicorn[standard]
+Requires-Dist: python-multipart
+Requires-Dist: tifffile
+Requires-Dist: numpy
+Requires-Dist: scikit-image
+
+![EPFL Center for Imaging logo](https://imaging.epfl.ch/resources/logo-for-gitlab.svg)
+# 🪐 Imaging Server Kit
+
+Run seamlessly interoperable algorithms on images using FastAPI.
+
+## Setup
+
+Build the `imaging-server-kit` image with `docker`:
+
+```
+docker build -t imaging-server-kit:3.9 .
+```
+
+or build specific images:
+
+```
+docker build -t imaging-server-kit:3.10 --file Dockerfile-3.10 .
+docker build -t imaging-server-kit:gpu --file Dockerfile-GPU .
+```
+
+**Run an algorithm server**
+
+The server will be running on `http://localhost:8000`.
+
+```bash
+docker build -t serverkit/rembg .
+docker run -it --rm -p 8000:8000 serverkit/rembg
+```
+
+**Run an algorithm server with multiple algorithms**
+
+See [deployment](./reference_deployment/README.md). The server will be running on `http://localhost:7000`.
+
+## Usage
+
+**Python client**
+
+Install the `imaging-server-kit` package with `pip`:
+
+```
+pip install git+https://gitlab.com/epfl-center-for-imaging/imaging-server-kit.git
+```
+
+Connect to an algorithm server and run algorithms from Python:
+
+```python
+from imaging_server_kit import Client
+
+client = Client()
+
+client.connect("http://localhost:7000")
+
+print(client.algorithms)
+# [`rembg`, `stardist`, `sam2`]
+
+data_tuple = client.run_algorithm(
+    algorithm="rembg",
+    image=(...),
+    rembg_model_name="silueta",
+)
+```
+
+More [examples](./examples/).
+
+**Napari client**
+
+Coming soon.
+
+**Web client**
+
+Coming soon.
+
+**QuPath client**
+
+Coming soon.
+
+**Fiji plugin**
+
+Coming soon.
+
+## Contributing
+
+Contributions are very welcome.
+
+## License
+
+This software is distributed under the terms of the [BSD-3](http://opensource.org/licenses/BSD-3-Clause) license.
+
+## Issues
+
+If you encounter any problems, please file an issue along with a detailed description.

imaging_server_kit-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+imaging_server_kit/__init__.py,sha256=6fdRi1RYnl6ibNuVQ3u29XhEpXUwWNmmz3aEKf3Ptkg,331
+imaging_server_kit/_version.py,sha256=pMnmqZnpVmaqR5nqHztNWzbbtb1oy5bPN_v7uhOH8K8,411
+imaging_server_kit/client.py,sha256=XHHWvhziwOdgvCvLiE4Pq7Eg1EOAZhxUET1VK8Pntr8,3917
+imaging_server_kit/encoding.py,sha256=RulGIVLdQnDhSSkLHo-MvBgM56zKJnvYR_Xj86GG2Aw,799
+imaging_server_kit/registry.py,sha256=rKo1UGccKuImG1MSDIFsUnKYfDz6KZ3Wl0u6HDyoKx4,2734
+imaging_server_kit/serialization.py,sha256=RcZxfBcdqjwWjcwxJA7yon_ZizeGNGL5GHkOJgSQ5Js,1931
+imaging_server_kit/server.py,sha256=fnFIVGUfB_19WqhJ4qILpVH3D5ZgNcnur9o3YCJx_qU,3481
+imaging_server_kit-0.0.1.dist-info/LICENSE,sha256=rAHt9UjSWQOkFCt0GZ-gu0Cr8fOHFW0BD-OQhixH4mM,1478
+imaging_server_kit-0.0.1.dist-info/METADATA,sha256=1iXByYLpPINWyzQeYdqAj2XzW-lpJvFjTiHE7XaSMuc,4469
+imaging_server_kit-0.0.1.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+imaging_server_kit-0.0.1.dist-info/top_level.txt,sha256=TEy2d0Zzb2kI8tDesIfbMT624gXUO6z4_J5Due618Qg,19
+imaging_server_kit-0.0.1.dist-info/RECORD,,

imaging_server_kit-0.0.1.dist-info/WHEEL

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

imaging_server_kit-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+imaging_server_kit