datamint 1.2.4__py3-none-any.whl

datamintapi/apihandler/api_handler.py

@@ -0,0 +1,15 @@
+from .root_api_handler import RootAPIHandler
+from .annotation_api_handler import AnnotationAPIHandler
+from .exp_api_handler import ExperimentAPIHandler
+
+
+class APIHandler(RootAPIHandler, ExperimentAPIHandler, AnnotationAPIHandler):
+    """
+    Import using this code:
+
+    .. code-block:: python
+    
+        from datamintapi import APIHandler
+        api = APIHandler()
+    """
+    pass

datamintapi/apihandler/base_api_handler.py

@@ -0,0 +1,300 @@
+from typing import Optional, Literal, Generator, TypeAlias, Dict, Union, List
+import pydicom.dataset
+from requests import Session
+from requests.exceptions import HTTPError
+import logging
+import asyncio
+import aiohttp
+import nest_asyncio  # For running asyncio in jupyter notebooks
+import pydicom
+import json
+from PIL import Image
+from io import BytesIO
+import cv2
+import nibabel as nib
+from nibabel.filebasedimages import FileBasedImage as nib_FileBasedImage
+from datamintapi import configs
+from functools import wraps
+
+_LOGGER = logging.getLogger(__name__)
+
+
+ResourceStatus: TypeAlias = Literal['new', 'inbox', 'published', 'archived']
+"""TypeAlias: The available resource status. Possible values: 'new', 'inbox', 'published', 'archived'.
+"""
+ResourceFields: TypeAlias = Literal['modality', 'created_by', 'published_by', 'published_on', 'filename', 'created_at']
+"""TypeAlias: The available fields to order resources. Possible values: 'modality', 'created_by', 'published_by', 'published_on', 'filename', 'created_at' (default).
+"""
+
+_PAGE_LIMIT = 5000
+
+
+class DatamintException(Exception):
+    """
+    Base class for exceptions in this module.
+    """
+    pass
+
+
+class ResourceNotFoundError(DatamintException):
+    """
+    Exception raised when a resource is not found. 
+    For instance, when trying to get a resource by a non-existing id.
+    """
+
+    def __init__(self,
+                 resource_type: str,
+                 params: dict):
+        """ Constructor.
+
+        Args:
+            resource_type (str): A resource type.
+            params (dict): Dict of params identifying the sought resource.
+        """
+        super().__init__()
+        self.resource_type = resource_type
+        self.params = params
+
+    def set_params(self, resource_type: str, params: dict):
+        self.resource_type = resource_type
+        self.params = params
+
+    def __str__(self):
+        return f"Resource '{self.resource_type}' not found for parameters: {self.params}"
+
+
+class BaseAPIHandler:
+    """
+    Class to handle the API requests to the Datamint API
+    """
+    DATAMINT_API_VENV_NAME = configs.ENV_VARS[configs.APIKEY_KEY]
+    DEFAULT_ROOT_URL = 'https://api.datamint.io'
+
+    def __init__(self,
+                 root_url: Optional[str] = None,
+                 api_key: Optional[str] = None,
+                 check_connection: bool = True):
+        nest_asyncio.apply()  # For running asyncio in jupyter notebooks
+        self.root_url = root_url if root_url is not None else configs.get_value(configs.APIURL_KEY)
+        if self.root_url is None:
+            self.root_url = BaseAPIHandler.DEFAULT_ROOT_URL
+        self.root_url.rstrip('/')
+
+        self.api_key = api_key if api_key is not None else configs.get_value(configs.APIKEY_KEY)
+        if self.api_key is None:
+            msg = f"API key not provided! Use the environment variable " + \
+                f"{BaseAPIHandler.DATAMINT_API_VENV_NAME} or pass it as an argument."
+            raise DatamintException(msg)
+        self.semaphore = asyncio.Semaphore(10)  # Limit to 10 parallel requests
+
+        if check_connection:
+            self.check_connection()
+
+    def check_connection(self):
+        try:
+            self.get_projects()
+        except Exception as e:
+            raise DatamintException("Error connecting to the Datamint API." +
+                                    f" Please check your api_key and/or other configurations. {e}")
+
+    def _generate_curl_command(self, request_args: dict) -> str:
+        """
+        Generate a curl command for debugging purposes.
+
+        Args:
+            request_args (dict): Request arguments dictionary containing method, url, headers, etc.
+
+        Returns:
+            str: Equivalent curl command
+        """
+        method = request_args.get('method', 'GET').upper()
+        url = request_args['url']
+        headers = request_args.get('headers', {})
+        data = request_args.get('json') or request_args.get('data')
+        params = request_args.get('params')
+
+        curl_command = ['curl']
+
+        # Add method if not GET
+        if method != 'GET':
+            curl_command.extend(['-X', method])
+
+        # Add URL
+        curl_command.append(f"'{url}'")
+
+        # Add headers
+        for key, value in headers.items():
+            if key.lower() == 'apikey':
+                value = '<YOUR-API-KEY>'  # Mask API key for security
+            curl_command.extend(['-H', f"'{key}: {value}'"])
+
+        # Add query parameters
+        if params:
+            param_str = '&'.join([f"{k}={v}" for k, v in params.items()])
+            url = f"{url}?{param_str}"
+
+        # Add data
+        if data:
+            if isinstance(data, aiohttp.FormData):  # Check if it's aiohttp.FormData
+                # Handle FormData by extracting fields
+                form_parts = []
+                for options,headers,value in data._fields:
+                    # get the name from options
+                    name = options.get('name', 'file')
+                    if hasattr(value, 'read'):  # File-like object
+                        filename = getattr(value, 'name', 'file')
+                        form_parts.extend(['-F', f"'{name}=@{filename}'"])
+                    else:
+                        form_parts.extend(['-F', f"'{name}={value}'"])
+                curl_command.extend(form_parts)
+            elif isinstance(data, dict):
+                curl_command.extend(['-d', f"'{json.dumps(data)}'"])
+            else:
+                curl_command.extend(['-d', f"'{data}'"])
+
+        return ' '.join(curl_command)
+
+    async def _run_request_async(self,
+                                 request_args: dict,
+                                 session: aiohttp.ClientSession | None = None,
+                                 data_to_get: str = 'json'):
+        if session is None:
+            async with aiohttp.ClientSession() as s:
+                return await self._run_request_async(request_args, s)
+        try:
+            _LOGGER.debug(f"Running request to {request_args['url']}")
+            _LOGGER.debug(f'Equivalent curl command: "{self._generate_curl_command(request_args)}"')
+        except Exception as e:
+            _LOGGER.debug(f"Error generating curl command: {e}")
+
+        # add apikey to the headers
+        if 'headers' not in request_args:
+            request_args['headers'] = {}
+
+        request_args['headers']['apikey'] = self.api_key
+
+        async with session.request(**request_args) as response:
+            self._check_errors_response(response, request_args)
+            if data_to_get == 'json':
+                return await response.json()
+            elif data_to_get == 'text':
+                return await response.text()
+            else:
+                raise ValueError("data_to_get must be either 'json' or 'text'")
+
+    def _check_errors_response(self,
+                               response,
+                               request_args: dict):
+        try:
+            response.raise_for_status()
+        except HTTPError as e:
+            status_code = BaseAPIHandler.get_status_code(e)
+            if status_code >= 500 and status_code < 600:
+                _LOGGER.error(f"Error in request to {request_args['url']}: {e}")
+            if status_code >= 400 and status_code < 500:
+                try:
+                    _LOGGER.error(f"Error response: {response.text}")
+                    error_data = response.json()
+                except Exception as e2:
+                    _LOGGER.error(f"Error parsing the response. {e2}")
+                else:
+                    if isinstance(error_data['message'], str) and ' not found' in error_data['message'].lower():
+                        # Will be caught by the caller and properly initialized:
+                        raise ResourceNotFoundError('unknown', {})
+
+            raise e
+
+    def _check_errors_response_json(self,
+                                    response):
+        response_json = response.json()
+        if isinstance(response_json, dict):
+            response_json = [response_json]
+        if isinstance(response_json, list):
+            for r in response_json:
+                if isinstance(r, dict) and 'error' in r:
+                    if hasattr(response, 'text'):
+                        _LOGGER.error(f"Error response: {response.text}")
+                    raise DatamintException(r['error'])
+
+    def _run_request(self,
+                     request_args: dict,
+                     session: Session = None):
+        if session is None:
+            with Session() as s:
+                return self._run_request(request_args, s)
+        _LOGGER.debug(f'Equivalent curl command: "{self._generate_curl_command(request_args)}"')
+
+        # add apikey to the headers
+        if 'headers' not in request_args:
+            request_args['headers'] = {}
+
+        request_args['headers']['apikey'] = self.api_key
+        response = session.request(**request_args)
+        self._check_errors_response(response, request_args)
+        return response
+
+    def _get_endpoint_url(self, endpoint: str) -> str:
+        return f'{self.root_url}/{endpoint}'
+
+    def _run_pagination_request(self,
+                                request_params: Dict,
+                                return_field: Optional[Union[str, List]] = None
+                                ) -> Generator[Dict, None, None]:
+        offset = 0
+        params = request_params.get('params', {})
+        while True:
+            params['offset'] = offset
+            params['limit'] = _PAGE_LIMIT
+
+            response = self._run_request(request_params)
+            self._check_errors_response_json(response)
+            response = response.json()
+            if return_field is not None:
+                if isinstance(return_field, list) or isinstance(return_field, tuple):
+                    for field in return_field:
+                        response = response[field]
+                else:
+                    response = response[return_field]
+            for r in response:
+                yield r
+
+            if len(response) < _PAGE_LIMIT:
+                _LOGGER.debug(f"Last page reached. Total resources: {offset + len(response)}")
+                break
+
+            offset += _PAGE_LIMIT
+
+    @staticmethod
+    def get_status_code(e) -> int:
+        if not hasattr(e, 'response') or e.response is None:
+            return -1
+        return e.response.status_code
+
+    @staticmethod
+    def _has_status_code(e, status_code: int) -> bool:
+        return BaseAPIHandler.get_status_code(e) == status_code
+
+    @staticmethod
+    def convert_format(bytes_array: bytes,
+                       mimetype: str,
+                       file_path: str = None
+                       ) -> pydicom.dataset.Dataset | Image.Image | cv2.VideoCapture | bytes | nib_FileBasedImage:
+        content_io = BytesIO(bytes_array)
+        if mimetype == 'application/dicom':
+            return pydicom.dcmread(content_io)
+        elif mimetype in ('image/jpeg', 'image/png', 'image/tiff'):
+            return Image.open(content_io)
+        elif mimetype == 'video/mp4':
+            if file_path is None:
+                raise NotImplementedError("file_path=None is not implemented yet for video/mp4.")
+            return cv2.VideoCapture(file_path)
+        elif mimetype == 'application/json':
+            return json.loads(bytes_array)
+        elif mimetype == 'application/octet-stream':
+            return bytes_array
+        elif mimetype == 'application/nifti':
+            if file_path is None:
+                raise NotImplementedError("file_path=None is not implemented yet for application/nifti.")
+            return nib.load(file_path)
+
+        raise ValueError(f"Unsupported mimetype: {mimetype}")

datamintapi/apihandler/dto/annotation_dto.py

@@ -0,0 +1,149 @@
+"""
+Data Transfer Objects (DTOs) for handling annotations in the datamint-python-api.
+
+This module provides classes for creating and manipulating annotation data
+that can be sent to or received from the Datamint API. It includes structures
+for different annotation geometry types, metadata, and formatting utilities.
+
+Classes:
+    Handles (cornerstone): Manages annotation control points and handle properties.
+    ExternalDescription (cornerstone): Contains external metadata for annotations.
+        Metadata (cornerstone): Nested class for managing annotation positioning and reference metadata.
+    SamGeometry (datamint): Represents Segment Anything Model geometry with boxes and points.
+    MainGeometry: Combines SAM geometry with external descriptions.
+    CreateAnnotationDto: Main DTO for creating annotation requests.
+"""
+
+import json
+from typing import Any, TypeAlias, Literal
+import logging
+from enum import Enum
+from datamintapi.utils.dicom_utils import pixel_to_patient
+import pydicom
+import numpy as np
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+CoordinateSystem: TypeAlias = Literal['pixel', 'patient']
+"""TypeAlias: The available coordinate systems for annotation geometry. Possible values are 'pixel' and 'patient' (used in DICOMs).
+"""
+
+
+class AnnotationType(Enum):
+    SEGMENTATION = 'segmentation'
+    AREA = 'area'
+    DISTANCE = 'distance'
+    ANGLE = 'angle'
+    POINT = 'point'
+    LINE = 'line'
+    REGION = 'region'
+    SQUARE = 'square'
+    CIRCLE = 'circle'
+    CATEGORY = 'category'
+    LABEL = 'label'
+
+
+def _remove_none(d: dict) -> dict:
+    return {k: _remove_none(v) for k, v in d.items() if v is not None} if isinstance(d, dict) else d
+
+
+class Box:
+    def __init__(self, x0, y0, x1, y1, frame_index):
+        self.x0 = x0
+        self.y0 = y0
+        self.x1 = x1
+        self.y1 = y1
+        self.frame_index = frame_index
+
+
+class Geometry:
+    def __init__(self, type: AnnotationType | str):
+        self.type = type if isinstance(type, AnnotationType) else AnnotationType(type)
+
+    def to_dict(self) -> dict:
+        raise NotImplementedError("Subclasses must implement to_dict method.")
+
+
+class LineGeometry(Geometry):
+    def __init__(self, point1: tuple[float, float, float],
+                 point2: tuple[float, float, float]):
+        super().__init__(AnnotationType.LINE)
+        if isinstance(point1, np.ndarray):
+            point1 = point1.tolist()
+        if isinstance(point2, np.ndarray):
+            point2 = point2.tolist()
+        self.point1 = point1
+        self.point2 = point2
+
+    def to_dict(self) -> dict:
+        return {
+            'points': [self.point1, self.point2],
+        }
+
+    @staticmethod
+    def from_dicom(ds: pydicom.Dataset,
+                   point1: tuple[int, int],
+                   point2: tuple[int, int],
+                   slice_index: int | None = None) -> 'LineGeometry':
+        pixel_x1, pixel_y1 = point1
+        pixel_x2, pixel_y2 = point2
+
+        new_point1 = pixel_to_patient(ds, pixel_x1, pixel_y1,
+                                      slice_index=slice_index)
+        new_point2 = pixel_to_patient(ds, pixel_x2, pixel_y2,
+                                      slice_index=slice_index)
+        return LineGeometry(new_point1, new_point2)
+
+
+class CreateAnnotationDto:
+    def __init__(self,
+                 type: AnnotationType | str,
+                 identifier: str,
+                 scope: str,
+                 annotation_worklist_id: str,
+                 value=None,
+                 imported_from: str | None = None,
+                 import_author: str | None = None,
+                 frame_index: int | None = None,
+                 is_model: bool = None,
+                 model_id: str | None = None,
+                 geometry: Geometry | None = None,
+                 units: str = None):
+        self.type = type if isinstance(type, AnnotationType) else AnnotationType(type)
+        self.value = value
+        self.identifier = identifier
+        self.scope = scope
+        self.annotation_worklist_id = annotation_worklist_id
+        self.imported_from = imported_from
+        self.import_author = import_author
+        self.frame_index = frame_index
+        self.units = units
+        self.model_id = model_id
+        if model_id is not None:
+            if is_model == False:
+                raise ValueError("model_id==False while self.model_id is provided.")
+            is_model = True
+        self.is_model = is_model
+        self.geometry = geometry
+
+        if geometry is not None and self.type != self.geometry.type:
+            raise ValueError(f"Annotation type {self.type} does not match geometry type {self.geometry.type}.")
+
+    def to_dict(self) -> dict[str, Any]:
+        ret = {
+            "value": self.value,
+            "type": self.type.value,
+            "identifier": self.identifier,
+            "scope": self.scope,
+            'frame_index': self.frame_index,
+            'annotation_worklist_id': self.annotation_worklist_id,
+            'imported_from': self.imported_from,
+            'import_author': self.import_author,
+            'units': self.units,
+            "geometry": self.geometry.to_dict() if self.geometry else None,
+            "is_model": self.is_model,
+            "model_id": self.model_id
+        }
+        return _remove_none(ret)

datamintapi/apihandler/exp_api_handler.py

@@ -0,0 +1,204 @@
+from datamintapi.apihandler.base_api_handler import BaseAPIHandler
+from typing import Optional, Dict, List, Union, Any
+import json
+import logging
+from io import BytesIO
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class ExperimentAPIHandler(BaseAPIHandler):
+    def __init__(self,
+                 root_url: Optional[str] = None,
+                 api_key: Optional[str] = None,
+                 check_connection: bool = True,
+                 **kwargs):
+        super().__init__(root_url=root_url, api_key=api_key, check_connection=check_connection, **kwargs)
+        self.exp_url = f"{self.root_url}/experiments"
+
+    def create_experiment(self,
+                          dataset_id: str,
+                          name: str,
+                          description: str,
+                          environment: Dict) -> str:
+        request_params = {
+            'method': 'POST',
+            'url': self.exp_url,
+            'json': {"dataset_id": dataset_id,
+                     "name": name,
+                     "description": description,
+                     "environment": environment
+                     }
+        }
+
+        _LOGGER.debug(f"Creating experiment with name {name} and params {json.dumps(request_params)}")
+
+        response = self._run_request(request_params)
+
+        return response.json()['id']
+
+    def get_experiment_by_id(self, exp_id: str) -> Dict:
+        request_params = {
+            'method': 'GET',
+            'url': f"{self.exp_url}/{exp_id}"
+        }
+
+        response = self._run_request(request_params)
+
+        return response.json()
+
+    def get_experiments(self) -> List[Dict]:
+        request_params = {
+            'method': 'GET',
+            'url': self.exp_url
+        }
+
+        response = self._run_request(request_params)
+
+        return response.json()
+    
+    def get_experiment_logs(self, exp_id: str) -> List[Dict]:
+        request_params = {
+            'method': 'GET',
+            'url': f"{self.exp_url}/{exp_id}/log"
+        }
+
+        response = self._run_request(request_params)
+
+        return response.json()
+
+    def log_summary(self,
+                    exp_id: str,
+                    result_summary: Dict,
+                    ) -> None:
+        request_params = {
+            'method': 'POST',
+            'url': f"{self.exp_url}/{exp_id}/summary",
+            'json': {"result_summary": result_summary}
+        }
+
+        resp = self._run_request(request_params)
+
+    def update_experiment(self,
+                          exp_id: str,
+                          name: Optional[str] = None,
+                          description: Optional[str] = None,
+                          result_summary: Optional[Dict] = None) -> None:
+
+        # check that at least one of the optional parameters is not None
+        if not any([name, description, result_summary]):
+            return
+
+        data = {}
+
+        if name is not None:
+            data['name'] = name
+        if description is not None:
+            data['description'] = description
+        if result_summary is not None:
+            data['result_summary'] = result_summary
+
+        headers = {
+            'accept': 'application/json',
+            'Content-Type': 'application/json',
+        }
+
+        request_params = {
+            'method': 'PATCH',
+            'url': f"{self.exp_url}/{exp_id}",
+            'json': data,
+            'headers': headers
+        }
+
+        resp = self._run_request(request_params)
+
+    def log_entry(self,
+                  exp_id: str,
+                  entry: Dict):
+
+        if not isinstance(entry, dict):
+            raise ValueError(f"Invalid type for entry: {type(entry)}")
+
+        request_params = {
+            'method': 'POST',
+            'url': f"{self.exp_url}/{exp_id}/log",
+            'json': entry
+        }
+
+        resp = self._run_request(request_params)
+        return resp
+
+    def finish_experiment(self, exp_id: str):
+        pass
+        # _LOGGER.info(f"Finishing experiment with id {exp_id}")
+        # _LOGGER.warning("Finishing experiment not implemented yet")
+        # request_params = {
+        #     'method': 'POST',
+        #     'url': f"{self.exp_url}/{exp_id}/finish"
+        # }
+
+        # resp = self._run_request(request_params)
+
+    def log_model(self,
+                  exp_id: str,
+                  model: Union[Any, str, BytesIO],
+                  hyper_params: Optional[Dict] = None,
+                  torch_save_kwargs: Dict = {}) -> Dict:
+        import torch
+        if isinstance(model, torch.nn.Module):
+            f = BytesIO()
+            torch.save(model, f, **torch_save_kwargs)
+            f.seek(0)
+            f.name = None
+        elif isinstance(model, str):
+            with open(model, 'rb') as f1:
+                f = BytesIO(f1.read())
+                f.name = None
+        elif isinstance(model, BytesIO):
+            f = model
+        else:
+            raise ValueError(f"Invalid type for model: {type(model)}")
+
+        name = None
+        f.name = name
+
+        try:
+            json_data = hyper_params
+            json_data['model_name'] = name
+            request_params = {
+                'method': 'POST',
+                'url': f"{self.exp_url}/{exp_id}/model",
+                'data': json_data,
+                'files': [(None, f)],
+            }
+
+            resp = self._run_request(request_params).json()
+            return resp[0]
+        finally:
+            f.close()
+
+    def get_experiment_by_name(self, name: str, project: Dict) -> Optional[Dict]:
+        """
+        Get the experiment by name of the project.
+
+        Args:
+            name (str): Name of the experiment.
+            project (Dict): The project to search for the experiment.
+
+        Returns:
+            Optional[Dict]: The experiment if found, otherwise None.
+        """
+        # uses GET /projects/{project_id}/experiments
+
+        project_id = project['id']
+        request_params = {
+            'method': 'GET',
+            'url': f"{self.root_url}/projects/{project_id}/experiments"
+        }
+
+        response = self._run_request(request_params)
+        experiments = response.json()
+        for exp in experiments:
+            if exp['name'] == name:
+                return exp
+        return None