datamint 1.6.0__py3-none-any.whl → 1.6.3__py3-none-any.whl

datamint/apihandler/annotation_api_handler.py

@@ -10,7 +10,6 @@ import os
 import asyncio
 import aiohttp
 from requests.exceptions import HTTPError
-from deprecated.sphinx import deprecated
 from .dto.annotation_dto import CreateAnnotationDto, LineGeometry, BoxGeometry, CoordinateSystem, AnnotationType
 import pydicom
 import json
@@ -237,7 +236,7 @@ class AnnotationAPIHandler(BaseAPIHandler):
     async def _upload_volume_segmentation_async(self,
                                                 resource_id: str,
                                                 file_path: str | np.ndarray,
-                                                name: dict[int, str] | dict[tuple, str],
+                                                name: str | dict[int, str] | dict[tuple, str] | None,
                                                 imported_from: Optional[str] = None,
                                                 author_email: Optional[str] = None,
                                                 worklist_id: Optional[str] = None,
@@ -263,6 +262,13 @@ class AnnotationAPIHandler(BaseAPIHandler):
         Raises:
             ValueError: If name is not a string or file format is unsupported for volume upload.
         """
+
+        if isinstance(name, str):
+            raise NotImplementedError("`name=string` is not supported yet for volume segmentation.")
+        if isinstance(name, dict):
+            if any(isinstance(k, tuple) for k in name.keys()):
+                raise NotImplementedError("For volume segmentations, `name` must be a dictionary with integer keys only.") 
+                
         # Prepare file for upload
         if isinstance(file_path, str):
             if file_path.endswith('.nii') or file_path.endswith('.nii.gz'):
@@ -275,7 +281,8 @@ class AnnotationAPIHandler(BaseAPIHandler):
                         form.add_field('model_id', model_id)  # Add model_id if provided
                     if worklist_id is not None:
                         form.add_field('annotation_worklist_id', worklist_id)
-                    form.add_field('segmentation_map', json.dumps(name), content_type='application/json')
+                    if name is not None:
+                        form.add_field('segmentation_map', json.dumps(name), content_type='application/json')
 
                     request_params = dict(
                         method='POST',
@@ -449,30 +456,27 @@ class AnnotationAPIHandler(BaseAPIHandler):
         if isinstance(file_path, str) and not os.path.exists(file_path):
             raise FileNotFoundError(f"File {file_path} not found.")
 
-        name = AnnotationAPIHandler.standardize_segmentation_names(name)
-
         # Handle NIfTI files specially - upload as single volume
         if isinstance(file_path, str) and (file_path.endswith('.nii') or file_path.endswith('.nii.gz')):
             _LOGGER.info(f"Uploading NIfTI segmentation file: {file_path}")
             if frame_index is not None:
                 raise ValueError("Do not provide frame_index for NIfTI segmentations.")
             loop = asyncio.get_event_loop()
-            task = self._upload_segmentations_async(
+            task = self._upload_volume_segmentation_async(
                 resource_id=resource_id,
-                frame_index=None,
                 file_path=file_path,
                 name=name,
                 imported_from=imported_from,
                 author_email=author_email,
-                discard_empty_segmentations=False,
                 worklist_id=worklist_id,
                 model_id=model_id,
-                transpose_segmentation=transpose_segmentation,
-                upload_volume=True
+                transpose_segmentation=transpose_segmentation
             )
             return loop.run_until_complete(task)
         # All other file types are converted to multiple PNGs and uploaded frame by frame.
 
+        name = AnnotationAPIHandler.standardize_segmentation_names(name)
+
         to_run = []
         # Generate IOs for the segmentations.
         nframes, fios = AnnotationAPIHandler._generate_segmentations_ios(file_path,

datamint/apihandler/dto/annotation_dto.py

@@ -18,7 +18,7 @@ import json
 from typing import Any, TypeAlias, Literal
 import logging
 from enum import Enum
-from datamint.utils.dicom_utils import pixel_to_patient
+from medimgkit.dicom_utils import pixel_to_patient
 import pydicom
 import numpy as np
 

datamint/apihandler/root_api_handler.py

@@ -6,8 +6,8 @@ from requests.exceptions import HTTPError
 import logging
 import asyncio
 import aiohttp
-from datamint.utils.dicom_utils import anonymize_dicom, to_bytesio, is_dicom
-from datamint.utils import dicom_utils
+from medimgkit.dicom_utils import anonymize_dicom, to_bytesio, is_dicom
+from medimgkit import dicom_utils
 import pydicom
 from pathlib import Path
 from datetime import date
@@ -447,6 +447,8 @@ class RootAPIHandler(BaseAPIHandler):
                                   for segfiles in segmentation_files]
             
             for segfiles in segmentation_files:
+                if segfiles is None:
+                    continue
                 if 'files' not in segfiles:
                     raise ValueError("segmentation_files must contain a 'files' key with a list of file paths.")
                 if 'names' in segfiles:

datamint/client_cmd_tools/datamint_upload.py

@@ -5,7 +5,7 @@ from humanize import naturalsize
 import logging
 from pathlib import Path
 import sys
-from datamint.utils.dicom_utils import is_dicom
+from medimgkit.dicom_utils import is_dicom
 import fnmatch
 from typing import Generator, Optional, Any
 from collections import defaultdict
@@ -15,6 +15,7 @@ from datamint.client_cmd_tools.datamint_config import ask_api_key
 from datamint.utils.logging_utils import load_cmdline_logging_config
 import yaml
 from collections.abc import Iterable
+import pandas as pd
 
 # Create two loggings: one for the user and one for the developer
 _LOGGER = logging.getLogger(__name__)
@@ -23,6 +24,38 @@ _USER_LOGGER = logging.getLogger('user_logger')
 MAX_RECURSION_LIMIT = 1000
 
 
+def _read_segmentation_names(segmentation_names_path: str | Path) -> dict:
+    """
+    Read a segmentation names file (yaml or csv) and return its content as a dictionary.
+    If the file is a YAML file, it should contain two keys: "segmentation_names" and "class_names".
+    If the file is a CSV file, it should contain the following columns:
+    index, r, g, b, ..., name
+    """
+    segmentation_names_path = Path(segmentation_names_path)
+    if segmentation_names_path.suffix in ['.yaml', '.yml']:
+        with open(segmentation_names_path, 'r') as f:
+            metadata = yaml.safe_load(f)
+    elif segmentation_names_path.suffix in ['.csv', '.tsv']:
+        df = pd.read_csv(segmentation_names_path,
+                         header=None,
+                         index_col=0,
+                         sep=None,  # use sep=None to automatically detect the separator
+                         engine='python'
+                         )
+        df = df.rename(columns={1: 'r', 2: 'g', 3: 'b', df.columns[-1]: 'name'})
+        # df = df.set_index(['r', 'g', 'b'])
+        metadata = {'class_names': df['name'].to_dict()}
+    else:
+        raise ValueError(f"Unsupported file format: {segmentation_names_path.suffix}")
+
+    if 'segmentation_names' in metadata:
+        segnames = sorted(metadata['segmentation_names'],
+                          key=lambda x: len(x))
+        metadata['segmentation_names'] = segnames
+
+    return metadata
+
+
 def _is_valid_path_argparse(x):
     """
     argparse type that checks if the path exists
@@ -101,7 +134,6 @@ def walk_to_depth(path: str | Path,
                     continue
                 yield from walk_to_depth(child, depth-1, exclude_pattern)
         else:
-            _LOGGER.debug(f"yielding {child} from {path}")
             yield child
 
 
@@ -157,31 +189,32 @@ def handle_api_key() -> str | None:
 
 def _find_segmentation_files(segmentation_root_path: str,
                              images_files: list[str],
-                             segmentation_metainfo: dict = None
-                             ) -> Optional[list[dict]]:
+                             segmentation_metainfo: dict | None = None
+                             ) -> list[dict]:
     """
     Find the segmentation files that match the images files based on the same folder structure
     """
 
-    if segmentation_root_path is None:
-        return None
-
-    if len(images_files) == 1 and os.path.isfile(images_files[0]) and os.path.isfile(segmentation_root_path):
-        return [{'files': [segmentation_root_path]}]
-
-    segmentation_files = []
-    acceptable_extensions = ['.nii.gz', '.nii', '.png']
-
+    segnames = None
+    classnames = None
     if segmentation_metainfo is not None:
         if 'segmentation_names' in segmentation_metainfo:
             segnames = sorted(segmentation_metainfo['segmentation_names'],
                               key=lambda x: len(x))
-        else:
-            segnames = None
         classnames = segmentation_metainfo.get('class_names', None)
         if classnames is not None:
             _LOGGER.debug(f"Number of class names: {len(classnames)}")
 
+    if len(images_files) == 1 and os.path.isfile(images_files[0]) and os.path.isfile(segmentation_root_path):
+        ret = [{'files': [segmentation_root_path]}]
+        if classnames is not None:
+            ret[0]['names'] = classnames
+        _LOGGER.debug(f"Returning segmentation files: {ret}")
+        return ret
+
+    segmentation_files = []
+    acceptable_extensions = ['.nii.gz', '.nii', '.png']
+
     segmentation_root_path = Path(segmentation_root_path).absolute()
 
     for imgpath in images_files:
@@ -197,7 +230,6 @@ def _find_segmentation_files(segmentation_root_path: str,
         else:
             common_parent = Path(*common_parent)
 
-        _LOGGER.debug(f"_find_segmentation_files::common_parent: {common_parent}")
         path_structure = imgpath_parent.relative_to(common_parent).parts[1:]
 
         # path_structure = imgpath_parent.relative_to(root_path).parts[1:]
@@ -230,24 +262,47 @@ def _find_segmentation_files(segmentation_root_path: str,
             if len(frame_indices) > 0:
                 seginfo['frame_index'] = frame_indices
 
-            if segmentation_metainfo is not None:
-                snames_associated = []
-                for segfile in seg_files:
-                    if segnames is None:
-                        snames_associated.append(classnames)
+            snames_associated = []
+            for segfile in seg_files:
+                # check if there is a metadata file associated, besides json, with the segmentation
+                for ext in ['.yaml', '.yml', '.csv']:
+                    if str(segfile).endswith('nii.gz'):
+                        # has two extensions, so we need to remove both
+                        metadata_file = segfile.with_suffix('').with_suffix(ext)
+                        if not metadata_file.exists():
+                            metadata_file = segfile.with_suffix(ext)
+                    else:
+                        metadata_file = segfile.with_suffix(ext)
+                    if metadata_file.exists():
+                        _LOGGER.debug(f"Found metadata file: {metadata_file}")
+                        try:
+                            new_segmentation_metainfo = _read_segmentation_names(metadata_file)
+                            cur_segnames = new_segmentation_metainfo.get('segmentation_names', segnames)
+                            cur_classnames = new_segmentation_metainfo.get('class_names', classnames)
+                            break
+                        except Exception as e:
+                            _LOGGER.warning(f"Error reading metadata file {metadata_file}: {e}")
+                else:
+                    cur_segnames = segnames
+                    cur_classnames = classnames
+
+                if cur_segnames is None:
+                    _LOGGER.debug(f'adding {cur_classnames}')
+                    snames_associated.append(cur_classnames)
+                else:
+                    for segname in cur_segnames:
+                        if segname in str(segfile):
+                            if cur_classnames is not None:
+                                new_segname = {cid: f'{segname}_{cname}' for cid, cname in cur_classnames.items()}
+                                new_segname.update({'default': segname})
+                            else:
+                                new_segname = segname
+                            snames_associated.append(new_segname)
+                            break
                     else:
-                        for segname in segnames:
-                            if segname in str(segfile):
-                                if classnames is not None:
-                                    new_segname = {cid: f'{segname}_{cname}' for cid, cname in classnames.items()}
-                                    new_segname.update({'default': segname})
-                                else:
-                                    new_segname = segname
-                                snames_associated.append(new_segname)
-                                break
-                        else:
-                            _USER_LOGGER.warning(f"Segmentation file {segname} does not match any segmentation name.")
-                            snames_associated.append(None)
+                        _USER_LOGGER.warning(f"Segmentation file {segfile} does not match any segmentation name.")
+                        snames_associated.append(None)
+            if len(snames_associated) > 0:
                 seginfo['names'] = snames_associated
 
             segmentation_files.append(seginfo)
@@ -268,7 +323,7 @@ def _find_json_metadata(file_path: str | Path) -> Optional[str]:
         Optional[str]: Path to the JSON metadata file if found, None otherwise
     """
     file_path = Path(file_path)
-    
+
     # Handle .nii.gz files specially - need to remove both extensions
     if file_path.name.endswith('.nii.gz'):
         base_name = file_path.name[:-7]  # Remove .nii.gz
@@ -320,7 +375,7 @@ def _collect_metadata_files(files_path: list[str], auto_detect_json: bool) -> tu
     if used_json_files:
         _LOGGER.debug(f"Filtering out {len(used_json_files)} JSON metadata files from main upload list")
         filtered_metadata_files = []
-        
+
         for original_file in files_path:
             if original_file not in used_json_files:
                 original_index = files_path.index(original_file)
@@ -376,8 +431,10 @@ def _parse_args() -> tuple[Any, list[str], Optional[list[dict]], Optional[list[s
                         help='Path to the segmentation file(s) or a directory')
     parser.add_argument('--segmentation_names', type=_is_valid_path_argparse, metavar="FILE",
                         required=False,
-                        help='Path to a yaml file containing the segmentation names.' +
-                        ' The file may contain two keys: "segmentation_names" and "class_names".')
+                        help='Path to a yaml or csv file containing the segmentation names.' +
+                        ' If yaml, the file may contain two keys: "segmentation_names" and "class_names".'
+                        ' If csv, the file should contain the following columns:'
+                        ' index, r, g, b, ..., name')
     parser.add_argument('--yes', action='store_true',
                         help='Automatically answer yes to all prompts')
     parser.add_argument('--transpose-segmentation', action='store_true', default=False,
@@ -407,6 +464,7 @@ def _parse_args() -> tuple[Any, list[str], Optional[list[dict]], Optional[list[s
     if args.verbose:
         # Get the console handler and set to debug
         logging.getLogger().handlers[0].setLevel(logging.DEBUG)
+        logging.getLogger('datamint').handlers[0].setLevel(logging.DEBUG)
         _LOGGER.setLevel(logging.DEBUG)
         _USER_LOGGER.setLevel(logging.DEBUG)
 
@@ -446,15 +504,17 @@ def _parse_args() -> tuple[Any, list[str], Optional[list[dict]], Optional[list[s
             raise ValueError(f"No valid non-metadata files found in {args.path}")
 
         if args.segmentation_names is not None:
-            with open(args.segmentation_names, 'r') as f:
-                segmentation_names = yaml.safe_load(f)
+            segmentation_names = _read_segmentation_names(args.segmentation_names)
         else:
             segmentation_names = None
 
         _LOGGER.debug(f'finding segmentations at {args.segmentation_path}')
-        segmentation_files = _find_segmentation_files(args.segmentation_path,
-                                                      file_path,
-                                                      segmentation_metainfo=segmentation_names)
+        if args.segmentation_path is None:
+            segmentation_files = None
+        else:
+            segmentation_files = _find_segmentation_files(args.segmentation_path,
+                                                          file_path,
+                                                          segmentation_metainfo=segmentation_names)
 
         _LOGGER.info(f"args parsed: {args}")
 

datamint/dataset/base_dataset.py

@@ -14,9 +14,9 @@ from torch.utils.data import DataLoader
 import torch
 from torch import Tensor
 from datamint.apihandler.base_api_handler import DatamintException
-from datamint.utils.dicom_utils import is_dicom
+from medimgkit.dicom_utils import is_dicom
 import cv2
-from datamint.utils.io_utils import read_array_normalized
+from medimgkit.io_utils import read_array_normalized
 from datetime import datetime
 
 _LOGGER = logging.getLogger(__name__)

{datamint-1.6.0.dist-info → datamint-1.6.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: datamint
-Version: 1.6.0
+Version: 1.6.3
 Summary: A library for interacting with the Datamint API, designed for efficient data management, processing and Deep Learning workflows.
 Requires-Python: >=3.10
 Classifier: Programming Language :: Python :: 3
@@ -19,6 +19,7 @@ Requires-Dist: humanize (>=4.0.0,<5.0.0)
 Requires-Dist: lazy-loader (>=0.3.0)
 Requires-Dist: lightning
 Requires-Dist: matplotlib
+Requires-Dist: medimgkit
 Requires-Dist: nest-asyncio (>=1.0.0,<2.0.0)
 Requires-Dist: nibabel (>=4.0.0)
 Requires-Dist: numpy

{datamint-1.6.0.dist-info → datamint-1.6.3.dist-info}/RECORD

@@ -1,16 +1,16 @@
 datamint/__init__.py,sha256=7rKCCsaa4RBRTIfuHB708rai1xwDHLtkFNFJGKYG5D4,757
-datamint/apihandler/annotation_api_handler.py,sha256=jEY0Ka5RikkD2435cDNQ59l3M4NSkOJ1NwRreWQYl4c,51616
+datamint/apihandler/annotation_api_handler.py,sha256=ChwaSYjoOAVS7vuyP3-cfpDHaHwk_wXLf8QQaSU_oSM,51893
 datamint/apihandler/api_handler.py,sha256=cdVSddrFCKlF_BJ81LO1aJ0OP49rssjpNEFzJ6Q7YyY,384
 datamint/apihandler/base_api_handler.py,sha256=XSxZEQEkbQpuixGDu_P9jbxUQht3Z3JgxaeiFKPkVDM,11690
-datamint/apihandler/dto/annotation_dto.py,sha256=otCIesoqGBlbSOw4ErqFsXp2HwJsPNUQlkynQh_7pHg,7110
+datamint/apihandler/dto/annotation_dto.py,sha256=qId1RK1VO7dXrvGJ7dqJ31jBQB7Z8yy5x0tLSiMxTB4,7105
 datamint/apihandler/exp_api_handler.py,sha256=hFUgUgBc5rL7odK7gTW3MnrvMY1pVfJUpUdzRNobMQE,6226
-datamint/apihandler/root_api_handler.py,sha256=OIGq6aHX64B94MmAikcFzF0rdekRH4l1S59x2Pa_DJA,51739
+datamint/apihandler/root_api_handler.py,sha256=O8Gn1Gp3w7AYeuT_FbwH413o6P_eAYLoRiW0baGY_b4,51795
 datamint/client_cmd_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 datamint/client_cmd_tools/datamint_config.py,sha256=md7dnWrbl10lPtXKbmD9yo6onLJsajeG8Vz0ZWH1v4M,8181
-datamint/client_cmd_tools/datamint_upload.py,sha256=VyLL2FgY9ibfbdp4K6HrKt0jgkQH-SVuU71D6e77074,26436
+datamint/client_cmd_tools/datamint_upload.py,sha256=pSCZ6PYSQEOaHYW1KcVodthArsEoQhYwEzVeh_qdjTk,29470
 datamint/configs.py,sha256=Bdp6NydYwyCJ2dk19_gf_o3M2ZyQOmMHpLi8wEWNHUk,1426
 datamint/dataset/__init__.py,sha256=4PlUKSvVhdfQvvuq8jQXrkdqnot-iTTizM3aM1vgSwg,47
-datamint/dataset/base_dataset.py,sha256=MQZ_wNFex4BKBfb4fAcXV6-fQXFV_zBK1ybWrMm6_pg,39092
+datamint/dataset/base_dataset.py,sha256=bSMuNHUzU7heN0awGemTn3e2zPLhuCsh-qSs_Qt6i9w,39082
 datamint/dataset/dataset.py,sha256=AwS92t5kdmpm9NKFfXFmDmZxEbbPfb_FOMn-FWfu3bE,26590
 datamint/examples/__init__.py,sha256=zcYnd5nLVme9GCTPYH-1JpGo8xXK2WEYvhzcy_2alZc,39
 datamint/examples/example_projects.py,sha256=7Nb_EaIdzJTQa9zopqc-WhTBQWQJSoQZ_KjRS4PB4FI,2931
@@ -18,12 +18,10 @@ datamint/experiment/__init__.py,sha256=5qQOMzoG17DEd1YnTF-vS0qiM-DGdbNh42EUo91CR
 datamint/experiment/_patcher.py,sha256=ZgbezoevAYhJsbiJTvWPALGTcUiMT371xddcTllt3H4,23296
 datamint/experiment/experiment.py,sha256=aHK9dRFdQTi569xgUg1KqlCZLHZpDmSH3g3ndPIZvXw,44546
 datamint/logging.yaml,sha256=a5dsATpul7QHeUHB2TjABFjWaPXBMbO--dgn8GlRqwk,483
-datamint/utils/dicom_utils.py,sha256=sLukP6MB_acx7t868O2HDd_RDEILa97mEe_V9m1EMCY,28991
-datamint/utils/io_utils.py,sha256=lKnUCJEip7W9Xj9wOWsTAA855HnKbjwQON1WjMGqJmM,7374
 datamint/utils/logging_utils.py,sha256=DvoA35ATYG3JTwfXEXYawDyKRfHeCrH0a9czfkmz8kM,1851
 datamint/utils/torchmetrics.py,sha256=lwU0nOtsSWfebyp7dvjlAggaqXtj5ohSEUXOg3L0hJE,2837
 datamint/utils/visualization.py,sha256=yaUVAOHar59VrGUjpAWv5eVvQSfztFG0eP9p5Vt3l-M,4470
-datamint-1.6.0.dist-info/METADATA,sha256=F73Llyz1xUSDM5luVjsjL8EZwLP8VAcMV91vpi2BVqw,4065
-datamint-1.6.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-datamint-1.6.0.dist-info/entry_points.txt,sha256=mn5H6jPjO-rY0W0CAZ6Z_KKWhMLvyVaSpoqk77jlTI4,145
-datamint-1.6.0.dist-info/RECORD,,
+datamint-1.6.3.dist-info/METADATA,sha256=lfTFnSMYn7LTxb3jmUv_bAFBBDGQc6csTw91adX_xqI,4090
+datamint-1.6.3.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+datamint-1.6.3.dist-info/entry_points.txt,sha256=mn5H6jPjO-rY0W0CAZ6Z_KKWhMLvyVaSpoqk77jlTI4,145
+datamint-1.6.3.dist-info/RECORD,,

datamint/utils/dicom_utils.py

@@ -1,707 +0,0 @@
-from pydicom.pixels import pixel_array
-import pydicom
-from pydicom.uid import generate_uid
-from typing import Sequence, Generator, IO, TypeVar, Generic
-import warnings
-from copy import deepcopy
-import logging
-from pathlib import Path
-from pydicom.misc import is_dicom as pydicom_is_dicom
-from io import BytesIO
-import os
-import numpy as np
-from collections import defaultdict
-import uuid
-import hashlib
-from tqdm import tqdm
-
-import pydicom.uid
-
-_LOGGER = logging.getLogger(__name__)
-
-CLEARED_STR = "CLEARED_BY_DATAMINT"
-
-T = TypeVar('T')
-
-
-class GeneratorWithLength(Generic[T]):
-    def __init__(self, generator: Generator[T, None, None], length: int):
-        self.generator = generator
-        self.length = length
-
-    def __len__(self):
-        return self.length
-
-    def __iter__(self):
-        return self.generator
-
-    def __next__(self) -> T:
-        return next(self.generator)
-
-    def close(self):
-        self.generator.close()
-
-    def throw(self, *args):
-        return self.generator.throw(*args)
-
-    def send(self, *args):
-        return self.generator.send(*args)
-
-
-class TokenMapper:
-    def __init__(self, seed: int = 42):
-        self.seed = seed
-
-    def get_token(self, tag: tuple, value: str, simple_id=False) -> str:
-        """Get a consistent token for a given tag and value pair."""
-        if value is None or value == CLEARED_STR:
-            return CLEARED_STR
-
-        # Use a hash function to generate a consistent token
-        token = hashlib.md5(f"{tag}{value}{self.seed}".encode()).hexdigest()
-        if simple_id:
-            return token
-        return generate_uid(entropy_srcs=['DATAMINT', token])
-
-
-_TOKEN_MAPPER = TokenMapper()
-
-
-def anonymize_dicom(ds: pydicom.Dataset,
-                    retain_codes: Sequence[tuple] = [],
-                    copy=False,
-                    token_mapper: TokenMapper = None) -> pydicom.Dataset:
-    """
-    Anonymize a DICOM file by clearing all the specified DICOM tags
-    according to the DICOM standard https://www.dicomstandard.org/News-dir/ftsup/docs/sups/sup55.pdf.
-    This function will generate a new UID for the new DICOM file and clear the specified DICOM tags
-    with consistent tokens for related identifiers.
-
-    Args:
-        ds: pydicom Dataset object.
-        retain_codes: A list of DICOM tag codes to retain the value of.
-        copy: If True, the function will return a copy of the input Dataset object.
-        token_mapper: TokenMapper instance to maintain consistent tokens across calls.
-            If None, uses a global instance.
-
-    Returns:
-        pydicom Dataset object with specified DICOM tags cleared
-    """
-    if copy:
-        ds = deepcopy(ds)
-
-    if token_mapper is None:
-        token_mapper = _TOKEN_MAPPER
-
-    # https://www.dicomstandard.org/News-dir/ftsup/docs/sups/sup55.pdf
-    tags_to_clear = [
-        (0x0008, 0x0014), (0x0008, 0x0050), (0x0008, 0x0080), (0x0008, 0x0081), (0x0008, 0x0090),
-        (0x0008, 0x0092), (0x0008, 0x0094), (0x0008, 0x1010), (0x0008, 0x1030), (0x0008, 0x103E),
-        (0x0008, 0x1040), (0x0008, 0x1048), (0x0008, 0x1050), (0x0008, 0x1060), (0x0008, 0x1070),
-        (0x0008, 0x1080), (0x0008, 0x1155), (0x0008, 0x2111), (0x0010, 0x0010), (0x0010, 0x0020),
-        (0x0010, 0x0030), (0x0010, 0x0032), (0x0010, 0x0040), (0x0010, 0x1000), (0x0010, 0x1001),
-        (0x0010, 0x1010), (0x0010, 0x1020), (0x0010, 0x1030), (0x0010, 0x1090), (0x0010, 0x2160),
-        (0x0010, 0x2180), (0x0010, 0x21B0), (0x0010, 0x4000), (0x0018, 0x1000), (0x0018, 0x1030),
-        (0x0020, 0x000D), (0x0020, 0x000E),  # StudyInstanceUID  and SeriesInstanceUID
-        (0x0020, 0x0010), (0x0020, 0x0052), (0x0020, 0x0200), (0x0020, 0x4000), (0x0008, 0x0018),
-        (0x0040, 0x0275), (0x0040, 0xA730), (0x0088, 0x0140), (0x3006, 0x0024), (0x3006, 0x00C2)
-    ]
-
-    # Frame of Reference UID, Series Instance UID, Concatenation UID, and Instance UID, and StudyInstanceUID are converted to new UIDs
-    uid_tags = [(0x0020, 0x0052), (0x0020, 0x000E), (0x0020, 0x9161),
-                (0x0010, 0x0020), (0x0008, 0x0018), (0x0020, 0x000D)]
-    simple_id_tags = [(0x0010, 0x0020)]  # Patient ID
-
-    for code in retain_codes:
-        if code in tags_to_clear:
-            tags_to_clear.remove(code)
-
-    # Clear the specified DICOM tags
-    with warnings.catch_warnings():  # Supress UserWarning from pydicom
-        warnings.filterwarnings("ignore", category=UserWarning, module='pydicom')
-        for tag in tags_to_clear:
-            if tag in ds:
-                if tag == (0x0008, 0x0094):  # Phone number
-                    ds[tag].value = "000-000-0000"
-                # If tag is a floating point number, set it to 0.0
-                elif ds[tag].VR in ['FL', 'FD', 'DS']:
-                    ds[tag].value = 0
-                elif ds[tag].VR == 'SQ':
-                    del ds[tag]
-                else:
-                    if tag in uid_tags:
-                        try:
-                            # Use consistent token mapping for identifiers
-                            original_value = ds[tag].value
-                            ds[tag].value = token_mapper.get_token(tag, original_value, simple_id=tag in simple_id_tags)
-                            tag_name = pydicom.datadict.keyword_for_tag(tag)
-                        except ValueError as e:
-                            ds[tag].value = CLEARED_STR
-                    else:
-                        ds[tag].value = CLEARED_STR
-    if hasattr(ds, 'file_meta') and hasattr(ds, 'SOPInstanceUID'):
-        ds.file_meta.MediaStorageSOPInstanceUID = ds.SOPInstanceUID
-    return ds
-
-
-def is_dicom(f: str | Path | BytesIO) -> bool:
-    if isinstance(f, BytesIO):
-        fp = BytesIO(f.getbuffer())  # Avoid modifying the original BytesIO object
-        fp.read(128)  # preamble
-
-        return fp.read(4) == b"DICM"
-
-    if isinstance(f, Path):
-        f = str(f)
-    if os.path.isdir(f):
-        return False
-
-    fname = f.lower()
-    if fname.endswith('.dcm') or fname.endswith('.dicom'):
-        return True
-
-    # Check if the file has an extension
-    if os.path.splitext(f)[1] != '':
-        return False
-
-    try:
-        return pydicom_is_dicom(f)
-    except FileNotFoundError as e:
-        return None
-
-
-def to_bytesio(ds: pydicom.Dataset, name: str) -> BytesIO:
-    """
-    Convert a pydicom Dataset object to BytesIO object.
-    """
-    dicom_bytes = BytesIO()
-    pydicom.dcmwrite(dicom_bytes, ds)
-    dicom_bytes.seek(0)
-    dicom_bytes.name = name
-    dicom_bytes.mode = 'rb'
-    return dicom_bytes
-
-
-def load_image_normalized(dicom: pydicom.Dataset, index: int = None) -> np.ndarray:
-    """
-    Normalizes the shape of an array of images to (n, c, y, x)=(#slices, #channels, height, width).
-    It uses dicom.Rows, dicom.Columns, and other information to determine the shape.
-
-    Args:
-        dicom: A dicom with images of varying shapes.
-
-    Returns:
-        A numpy array of shape (n, c, y, x)=(#slices, #channels, height, width).
-    """
-    n = dicom.get('NumberOfFrames', 1)
-    if index is None:
-        images = dicom.pixel_array
-    else:
-        if index is not None and index >= n:
-            raise ValueError(f"Index {index} is out of bounds. The number of frames is {n}.")
-        images = pixel_array(dicom, index=index)
-        n = 1
-    shape = images.shape
-
-    c = dicom.get('SamplesPerPixel')
-
-    # x=width, y=height
-    if images.ndim == 2:
-        # Single grayscale image (y, x)
-        # Reshape to (1, 1, y, x)
-        return images.reshape((1, 1) + images.shape)
-    elif images.ndim == 3:
-        # (n, y, x) or (y, x, c)
-        if shape[0] == 1 or (n is not None and n > 1):
-            # (n, y, x)
-            return images.reshape(shape[0], 1, shape[1], shape[2])
-        if shape[2] in (1, 3, 4) or (c is not None and c > 1):
-            # (y, x, c)
-            images = images.transpose(2, 0, 1)
-            return images.reshape(1, *images.shape)
-    elif images.ndim == 4:
-        if shape[3] == c or shape[3] in (1, 3, 4) or (c is not None and c > 1):
-            # (n, y, x, c) -> (n, c, y, x)
-            return images.transpose(0, 3, 1, 2)
-
-    raise ValueError(f"Unsupported DICOM normalization with shape: {shape}, SamplesPerPixel: {c}, NumberOfFrames: {n}")
-
-
-def assemble_dicoms(files_path: list[str | IO],
-                    return_as_IO: bool = False) -> GeneratorWithLength[pydicom.Dataset | IO]:
-    """
-    Assemble multiple DICOM files into a single multi-frame DICOM file.
-    This function will merge the pixel data of the DICOM files and generate a new DICOM file with the combined pixel data.
-
-    Args:
-        files_path: A list of file paths to the DICOM files to be merged.
-
-    Returns:
-        A generator that yields the merged DICOM files.
-    """
-    dicoms_map = defaultdict(list)
-    
-    for file_path in tqdm(files_path, desc="Reading DICOMs metadata", unit="file"):
-        dicom = pydicom.dcmread(file_path,
-                                specific_tags=['SeriesInstanceUID', 'InstanceNumber', 'Rows', 'Columns'])
-        series_uid = dicom.get('SeriesInstanceUID', None)
-        if series_uid is None:
-            # generate a random uid
-            series_uid = pydicom.uid.generate_uid()
-        instance_number = dicom.get('InstanceNumber', 0)
-        rows = dicom.get('Rows', None)
-        columns = dicom.get('Columns', None)
-        dicoms_map[series_uid].append((instance_number, file_path, rows, columns))
-        if hasattr(file_path, "seek"):
-            file_path.seek(0)
-    
-    # Validate that all DICOMs with the same SeriesInstanceUID have matching dimensions
-    for series_uid, dicom_list in dicoms_map.items():
-        if len(dicom_list) <= 1:
-            continue
-            
-        # Get dimensions from first DICOM
-        first_rows = dicom_list[0][2]
-        first_columns = dicom_list[0][3]
-        
-        # Check all other DICOMs have the same dimensions
-        for instance_number, file_path, rows, columns in dicom_list:
-            if rows != first_rows or columns != first_columns:
-                msg = (
-                    f"Dimension mismatch in SeriesInstanceUID {series_uid}: "
-                    f"Expected {first_rows}x{first_columns}, got {rows}x{columns} "
-                    f"for file {file_path} and {dicom_list[0][1]}"
-                )
-                _LOGGER.error(msg)
-                raise ValueError(msg)
-
-    # filter out the two last elements of the tuple (rows, columns)
-    dicoms_map = {fr_uid: [(instance_number, file_path) for instance_number, file_path, _, _ in dicoms]
-                  for fr_uid, dicoms in dicoms_map.items()}
-    
-    gen = _generate_merged_dicoms(dicoms_map, return_as_IO=return_as_IO)
-    return GeneratorWithLength(gen, len(dicoms_map))
-
-
-def _create_multiframe_attributes(merged_ds: pydicom.Dataset,
-                                  all_dicoms: list[pydicom.Dataset]) -> pydicom.Dataset:
-    ### Shared Functional Groups Sequence ###
-    shared_seq_dataset = pydicom.dataset.Dataset()
-
-    # check if pixel spacing or spacing between slices are equal for all dicoms
-    pixel_spacing = merged_ds.get('PixelSpacing', None)
-    all_pixel_spacing_equal = all(ds.get('PixelSpacing', None) == pixel_spacing
-                                  for ds in all_dicoms)
-    spacing_between_slices = merged_ds.get('SpacingBetweenSlices', None)
-    all_spacing_b_slices_equal = all(ds.get('SpacingBetweenSlices', None) == spacing_between_slices
-                                     for ds in all_dicoms)
-
-    # if they are equal, add them to the shared functional groups sequence
-    if (pixel_spacing is not None and all_pixel_spacing_equal) or (spacing_between_slices is not None and all_spacing_b_slices_equal):
-        pixel_measure = pydicom.dataset.Dataset()
-        if pixel_spacing is not None:
-            pixel_measure.PixelSpacing = pixel_spacing
-        if spacing_between_slices is not None:
-            pixel_measure.SpacingBetweenSlices = spacing_between_slices
-        pixel_measures_seq = pydicom.Sequence([pixel_measure])
-        shared_seq_dataset.PixelMeasuresSequence = pixel_measures_seq
-
-    if len(shared_seq_dataset) > 0:
-        shared_seq = pydicom.Sequence([shared_seq_dataset])
-        merged_ds.SharedFunctionalGroupsSequence = shared_seq
-    #######
-
-    ### Per-Frame Functional Groups Sequence ###
-    perframe_seq_list = []
-    for ds in all_dicoms:
-        per_frame_dataset = pydicom.dataset.Dataset()  # root dataset for each frame
-        pos_dataset = pydicom.dataset.Dataset()
-        orient_dataset = pydicom.dataset.Dataset()
-        pixel_measure = pydicom.dataset.Dataset()
-        framenumber_dataset = pydicom.dataset.Dataset()
-
-        if 'ImagePositionPatient' in ds:
-            pos_dataset.ImagePositionPatient = ds.ImagePositionPatient
-        if 'ImageOrientationPatient' in ds:
-            orient_dataset.ImageOrientationPatient = ds.ImageOrientationPatient
-        if 'PixelSpacing' in ds and all_pixel_spacing_equal == False:
-            pixel_measure.PixelSpacing = ds.PixelSpacing
-        if 'SpacingBetweenSlices' in ds and all_spacing_b_slices_equal == False:
-            pixel_measure.SpacingBetweenSlices = ds.SpacingBetweenSlices
-
-        # Add datasets to the per-frame dataset
-        per_frame_dataset.PlanePositionSequence = pydicom.Sequence([pos_dataset])
-        per_frame_dataset.PlaneOrientationSequence = pydicom.Sequence([orient_dataset])
-        per_frame_dataset.PixelMeasuresSequence = pydicom.Sequence([pixel_measure])
-        per_frame_dataset.FrameContentSequence = pydicom.Sequence([framenumber_dataset])
-
-        perframe_seq_list.append(per_frame_dataset)
-    if len(perframe_seq_list[0]) > 0:
-        perframe_seq = pydicom.Sequence(perframe_seq_list)
-        merged_ds.PerFrameFunctionalGroupsSequence = perframe_seq
-        merged_ds.FrameIncrementPointer = (0x5200, 0x9230)
-
-    return merged_ds
-
-
-def _generate_dicom_name(ds: pydicom.Dataset) -> str:
-    """
-    Generate a meaningful name for a DICOM dataset using its attributes.
-
-    Args:
-        ds: pydicom Dataset object
-
-    Returns:
-        A string containing a descriptive name with .dcm extension
-    """
-    components = []
-
-    # if hasattr(ds, 'filename'):
-    #     components.append(os.path.basename(ds.filename))
-    if hasattr(ds, 'SeriesDescription'):
-        components.append(ds.SeriesDescription)
-    if len(components) == 0 and hasattr(ds, 'SeriesNumber'):
-        components.append(f"ser{ds.SeriesNumber}")
-    if hasattr(ds, 'StudyDescription'):
-        components.append(ds.StudyDescription)
-    elif hasattr(ds, 'StudyID'):
-        components.append(ds.StudyID)
-
-    # Join components and add extension
-    if len(components) > 0:
-        description = "_".join(str(x) for x in components) + ".dcm"
-        # Clean description - remove special chars and spaces
-        description = "".join(c if c.isalnum() else "_" for c in description)
-        if len(description) > 0:
-            return description
-
-    if hasattr(ds, 'SeriesInstanceUID'):
-        return ds.SeriesInstanceUID + ".dcm"
-
-    # Fallback to generic name if no attributes found
-    return ds.filename if hasattr(ds, 'filename') else f"merged_dicom_{uuid.uuid4()}.dcm"
-
-
-def _generate_merged_dicoms(dicoms_map: dict[str, list],
-                            return_as_IO: bool = False) -> Generator[pydicom.Dataset, None, None]:
-    for _, dicoms in dicoms_map.items():
-        dicoms.sort(key=lambda x: x[0])
-        files_path = [file_path for _, file_path in dicoms]
-
-        all_dicoms = [pydicom.dcmread(file_path) for file_path in files_path]
-
-        # Use the first dicom as a template
-        merged_dicom = all_dicoms[0]
-
-        # Combine pixel data
-        pixel_arrays = np.stack([ds.pixel_array for ds in all_dicoms], axis=0)
-
-        # Update the merged dicom
-        merged_dicom.PixelData = pixel_arrays.tobytes()
-        merged_dicom.NumberOfFrames = len(pixel_arrays)  # Set number of frames
-        merged_dicom.SOPInstanceUID = pydicom.uid.generate_uid()  # Generate new SOP Instance UID
-        # Removed deprecated attributes and set Transfer Syntax UID instead:
-        merged_dicom.file_meta.TransferSyntaxUID = pydicom.uid.ImplicitVRLittleEndian
-
-        # Free up memory
-        for ds in all_dicoms[1:]:
-            del ds.PixelData
-
-        # create multi-frame attributes
-        # check if FramTime is equal for all dicoms
-        frame_time = merged_dicom.get('FrameTime', None)
-        all_frame_time_equal = all(ds.get('FrameTime', None) == frame_time for ds in all_dicoms)
-        if frame_time is not None and all_frame_time_equal:
-            merged_dicom.FrameTime = frame_time  # (0x0018,0x1063)
-            merged_dicom.FrameIncrementPointer = (0x0018, 0x1063)  # points to 'FrameTime'
-        else:
-            # TODO: Sometimes FrameTime is present but not equal for all dicoms. In this case, check out 'FrameTimeVector'.
-            merged_dicom = _create_multiframe_attributes(merged_dicom, all_dicoms)
-
-        # Remove tags of single frame dicoms
-        for attr in ['ImagePositionPatient', 'SliceLocation', 'ImageOrientationPatient',
-                     'PixelSpacing', 'SpacingBetweenSlices', 'InstanceNumber']:
-            if hasattr(merged_dicom, attr):
-                delattr(merged_dicom, attr)
-
-        if return_as_IO:
-            name = _generate_dicom_name(merged_dicom)
-            yield to_bytesio(merged_dicom, name=name)
-        else:
-            yield merged_dicom
-
-
-"""
-- The Slice Location (0020,1041) is usually a derived attribute,
-typically computed from Image Position (Patient) (0020,0032)
-"""
-
-
-def get_space_between_slices(ds: pydicom.Dataset) -> float:
-    """
-    Get the space between slices from a DICOM dataset.
-
-    Parameters:
-        ds (pydicom.Dataset): The DICOM dataset containing image metadata.
-
-    Returns:
-        float: Space between slices in millimeters.
-    """
-    # Get the Spacing Between Slices attribute
-    if 'SpacingBetweenSlices' in ds:
-        return ds.SpacingBetweenSlices
-
-    if 'SharedFunctionalGroupsSequence' in ds:
-        shared_group = ds.SharedFunctionalGroupsSequence[0]
-        if 'PixelMeasuresSequence' in shared_group and 'SpacingBetweenSlices' in shared_group.PixelMeasuresSequence[0]:
-            return shared_group.PixelMeasuresSequence[0].SpacingBetweenSlices
-
-    if 'SliceThickness' in ds:
-        return ds.SliceThickness
-
-    return 1.0  # Default value if not found
-
-
-def get_image_orientation(ds: pydicom.Dataset, slice_index: int) -> np.ndarray:
-    """
-    Get the image orientation from a DICOM dataset.
-
-    Parameters:
-        ds (pydicom.Dataset): The DICOM dataset containing image metadata.
-
-    Returns:
-        numpy.ndarray: Image orientation (X, Y, Z) for the specified slice.
-    """
-    # Get the Image Orientation Patient attribute
-    if 'ImageOrientationPatient' in ds:
-        return ds.ImageOrientationPatient
-
-    if 'PerFrameFunctionalGroupsSequence' in ds:
-        if 'PlaneOrientationSequence' in ds.PerFrameFunctionalGroupsSequence[slice_index]:
-            return ds.PerFrameFunctionalGroupsSequence[slice_index].PlaneOrientationSequence[0].ImageOrientationPatient
-
-    if 'SharedFunctionalGroupsSequence' in ds:
-        return ds.SharedFunctionalGroupsSequence[0].PlaneOrientationSequence[0].ImageOrientationPatient
-
-    raise ValueError("ImageOrientationPatient not found in DICOM dataset.")
-
-
-def get_slice_orientation(ds: pydicom.Dataset, slice_index: int) -> np.ndarray:
-    """
-    Get the slice orientation from a DICOM dataset.
-
-    Parameters:
-        ds (pydicom.Dataset): The DICOM dataset containing image metadata.
-        slice_index (int): 0-based index of the slice in the 3D volume. This is the `InstanceNumber-1`.
-
-    Returns:
-        numpy.ndarray: Slice orientation (X, Y, Z) for the specified slice.
-    """
-    # Get the Image Orientation Patient attribute
-
-    x_orient, y_orient = np.array(get_image_orientation(ds, slice_index), dtype=np.float64).reshape(2, 3)
-    # compute the normal vector of the slice
-    slice_orient = np.cross(x_orient, y_orient)
-    # normalize the vector to space_between_slices
-    space_between_slices = get_space_between_slices(ds)
-    slice_orient = slice_orient / np.linalg.norm(slice_orient) * space_between_slices
-
-    return slice_orient
-
-
-def _get_instance_number(ds: pydicom.Dataset, slice_index: int | None = None) -> int:
-    if slice_index is None:
-        if 'InstanceNumber' in ds and ds.InstanceNumber is not None:
-            return ds.InstanceNumber
-        elif 'NumberOfFrames' in ds and ds.NumberOfFrames == 1:
-            return 0
-        else:
-            raise ValueError("Slice index is required for multi-frame images.")
-    else:
-        if slice_index < 0:
-            raise ValueError("Slice index must be a non-negative integer.")
-        if 'NumberOfFrames' in ds and slice_index >= ds.NumberOfFrames:
-            _LOGGER.warning(f"Slice index {slice_index} exceeds number of frames {ds.NumberOfFrames}.")
-        root_instance_number = ds.get('InstanceNumber', 1)
-        if root_instance_number is None:
-            root_instance_number = 1
-        return root_instance_number + slice_index
-
-
-def get_image_position(ds: pydicom.Dataset,
-                       slice_index: int | None = None) -> np.ndarray:
-    """
-    Get the image position for a specific slice in a DICOM dataset.
-
-    Parameters:
-        ds (pydicom.Dataset): The DICOM dataset containing image metadata.
-        slice_index (int): Index of the slice in the 3D volume.
-
-    Returns:
-        numpy.ndarray: Image position (X, Y, Z) for the specified slice.
-    """
-
-    instance_number = _get_instance_number(ds, slice_index)
-
-    if 'PerFrameFunctionalGroupsSequence' in ds:
-        if slice_index is not None:
-            frame_groups = ds.PerFrameFunctionalGroupsSequence[slice_index]
-            if 'PlanePositionSequence' in frame_groups and 'ImagePositionPatient' in frame_groups.PlanePositionSequence[0]:
-                return frame_groups.PlanePositionSequence[0].ImagePositionPatient
-        else:
-            logging.warning("PerFrameFunctionalGroupsSequence is available, but slice_index is not provided.")
-
-    # Get the Image Position Patient attribute
-    if 'ImagePositionPatient' in ds:
-        if 'SliceLocation' in ds:
-            _LOGGER.debug("SliceLocation attribute is available, but not accounted for in calculation.")
-        x = np.array(ds.ImagePositionPatient, dtype=np.float64)
-        sc_orient = get_slice_orientation(ds, slice_index)
-        return x + sc_orient*(instance_number-ds.get('InstanceNumber', 1))
-
-    raise ValueError("ImagePositionPatient not found in DICOM dataset.")
-
-
-def get_pixel_spacing(ds: pydicom.Dataset, slice_index: int) -> np.ndarray:
-    """
-    Get the pixel spacing from a DICOM dataset.
-
-    Parameters:
-        ds (pydicom.Dataset): The DICOM dataset containing image metadata.
-        slice_index (int): Index of the slice in the 3D volume.
-
-    Returns:
-        numpy.ndarray: Pixel spacing (X, Y) for the specified slice.
-    """
-    # Get the Pixel Spacing attribute
-    if 'PixelSpacing' in ds:
-        return np.array(ds.PixelSpacing, dtype=np.float64)
-
-    if 'PerFrameFunctionalGroupsSequence' in ds:
-        if 'PixelMeasuresSequence' in ds.PerFrameFunctionalGroupsSequence[slice_index]:
-            return ds.PerFrameFunctionalGroupsSequence[slice_index].PixelMeasuresSequence[0].PixelSpacing
-
-    if 'SharedFunctionalGroupsSequence' in ds:
-        if 'PixelMeasuresSequence' in ds.SharedFunctionalGroupsSequence[0]:
-            return ds.SharedFunctionalGroupsSequence[0].PixelMeasuresSequence[0].PixelSpacing
-
-    raise ValueError("PixelSpacing not found in DICOM dataset.")
-
-
-def pixel_to_patient(ds: pydicom.Dataset,
-                     pixel_x, pixel_y,
-                     slice_index: int | None = None,
-                     instance_number: int | None = None) -> np.ndarray:
-    """
-    Convert pixel coordinates (pixel_x, pixel_y) to patient coordinates in DICOM.
-
-    Parameters:
-        ds (pydicom.Dataset): The DICOM dataset containing image metadata.
-        pixel_x (float): X coordinate in pixel space.
-        pixel_y (float): Y coordinate in pixel space.
-        slice_index (int): Index of the slice of the `ds.pixel_array`.
-        instance_number (int): Instance number of the slice in the 3D volume.
-
-
-    Returns:
-        numpy.ndarray: Patient coordinates (X, Y, Z).
-    """
-
-    # - image_position is the origin of the image in patient coordinates (ImagePositionPatient)
-    # - row_vector and col_vector are the direction cosines from ImageOrientationPatient
-    # - pixel_spacing is the physical distance between the centers of adjacent pixels
-
-    if slice_index is not None and instance_number is not None:
-        raise ValueError("Either slice_index or instance_number should be provided, not both.")
-
-    if slice_index is None:
-        if instance_number is None:
-            instance_number = _get_instance_number(ds)
-        root_instance_number = ds.get('InstanceNumber', 1)
-        if root_instance_number is None:
-            root_instance_number = 1
-        slice_index = instance_number - root_instance_number
-
-    # Get required DICOM attributes
-    image_position = np.array(get_image_position(ds, slice_index), dtype=np.float64)
-    image_orientation = np.array(get_image_orientation(ds, slice_index), dtype=np.float64).reshape(2, 3)
-    # image_position = np.array(ds.ImagePositionPatient, dtype=np.float64)  # (0020,0032)
-    # image_orientation = np.array(ds.ImageOrientationPatient, dtype=np.float64).reshape(2, 3)  # (0020,0037)
-    # pixel_spacing = np.array(ds.PixelSpacing, dtype=np.float64)  # (0028,0030)
-    pixel_spacing = np.array(get_pixel_spacing(ds, slice_index), dtype=np.float64)  # (0028,0030)
-
-    # Compute row and column vectors from image orientation
-    row_vector = image_orientation[0]
-    col_vector = image_orientation[1]
-
-    # Compute patient coordinates
-    patient_coords = image_position + pixel_x * pixel_spacing[0] * row_vector + pixel_y * pixel_spacing[1] * col_vector
-
-    return patient_coords
-
-
-def determine_anatomical_plane(ds: pydicom.Dataset,
-                               slice_axis: int,
-                               alignment_threshold: float = 0.95) -> str:
-    """
-    Determine the anatomical plane of a DICOM slice (Axial, Sagittal, Coronal, Oblique, or Unknown).
-
-    Args:
-        ds (pydicom.Dataset): The DICOM dataset containing the image metadata.
-        slice_axis (int): The axis of the slice to analyze (0, 1, or 2).
-        alignment_threshold (float): Threshold for considering alignment with anatomical axes.
-
-    Returns:
-        str: The name of the anatomical plane ('Axial', 'Sagittal', 'Coronal', 'Oblique', or 'Unknown').
-
-    Raises:
-        ValueError: If `slice_index` is not 0, 1, or 2.
-    """
-
-    if slice_axis not in [0, 1, 2]:
-        raise ValueError("slice_index must be 0, 1 or 2")
-    # Check if Image Orientation Patient exists
-    if not hasattr(ds, 'ImageOrientationPatient') or ds.ImageOrientationPatient is None:
-        return "Unknown"
-    # Get the Image Orientation Patient (IOP) - 6 values defining row and column directions
-    iop = np.array(ds.ImageOrientationPatient, dtype=float)
-    if len(iop) != 6:
-        return "Unknown"
-    # Extract row and column direction vectors
-    row_dir = iop[:3]  # First 3 values: row direction cosines
-    col_dir = iop[3:]  # Last 3 values: column direction cosines
-    # Calculate the normal vector (slice direction) using cross product
-    normal = np.cross(row_dir, col_dir)
-    normal = normal / np.linalg.norm(normal)  # Normalize
-    # Define standard anatomical axes
-    # LPS coordinate system: L = Left, P = Posterior, S = Superior
-    axes = {
-        'sagittal': np.array([1, 0, 0]),   # L-R axis (left-right)
-        'coronal': np.array([0, 1, 0]),    # A-P axis (anterior-posterior)
-        'axial': np.array([0, 0, 1])       # S-I axis (superior-inferior)
-    }
-    # For each slice_index, determine which axis we're examining
-    if slice_axis == 0:
-        # ds.pixel_array[0,:,:] - slicing along first dimension
-        # The normal vector corresponds to the direction we're slicing through
-        examine_vector = normal
-    elif slice_axis == 1:
-        # ds.pixel_array[:,0,:] - slicing along second dimension
-        # This corresponds to the row direction
-        examine_vector = row_dir
-    elif slice_axis == 2:
-        # ds.pixel_array[:,:,0] - slicing along third dimension
-        # This corresponds to the column direction
-        examine_vector = col_dir
-    # Find which anatomical axis is most aligned with our examine_vector
-    max_dot = 0
-    best_axis = "Unknown"
-    for axis_name, axis_vector in axes.items():
-        dot_product = abs(np.dot(examine_vector, axis_vector))
-        if dot_product > max_dot:
-            max_dot = dot_product
-            best_axis = axis_name
-    if max_dot >= alignment_threshold:
-        return best_axis.capitalize()
-    else:
-        return "Oblique"

datamint/utils/io_utils.py

@@ -1,187 +0,0 @@
-import numpy as np
-import nibabel as nib
-from PIL import Image
-from .dicom_utils import load_image_normalized, is_dicom
-import pydicom
-import os
-from typing import Any
-import logging
-from PIL import ImageFile
-import cv2
-
-ImageFile.LOAD_TRUNCATED_IMAGES = True
-
-_LOGGER = logging.getLogger(__name__)
-
-IMAGE_EXTS = ('.png', '.jpg', '.jpeg')
-NII_EXTS = ('.nii', '.nii.gz')
-VIDEO_EXTS = ('.mp4', '.avi', '.mov', '.mkv')
-
-
-def read_video(file_path: str, index: int = None) -> np.ndarray:
-    cap = cv2.VideoCapture(file_path)
-    if not cap.isOpened():
-        raise ValueError(f"Failed to open video file: {file_path}")
-    try:
-        if index is None:
-            frames = []
-            while True:
-                ret, frame = cap.read()
-                if not ret:
-                    break
-                # Convert BGR to RGB and transpose to (C, H, W) format
-                frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
-                frame = frame.transpose(2, 0, 1)
-                frames.append(frame)
-            imgs = np.array(frames)  # shape: (#frames, C, H, W)
-        else:
-            while index > 0:
-                cap.grab()
-                index -= 1
-            ret, frame = cap.read()
-            if not ret:
-                raise ValueError(f"Failed to read frame {index} from video file: {file_path}")
-            # Convert BGR to RGB and transpose to (C, H, W) format
-            frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
-            imgs = frame.transpose(2, 0, 1)
-    finally:
-        cap.release()
-
-    if imgs is None or len(imgs) == 0:
-        raise ValueError(f"No frames found in video file: {file_path}")
-
-    return imgs
-
-
-def read_nifti(file_path: str, mimetype: str | None = None) -> np.ndarray:
-    """
-    Read a NIfTI file and return the image data in standardized format.
-    
-    Args:
-        file_path: Path to the NIfTI file (.nii or .nii.gz)
-        mimetype: Optional MIME type of the file. If provided, it can help in determining how to read the file.
-        
-    Returns:
-        np.ndarray: Image data with shape (#frames, C, H, W)
-    """
-    from nibabel.filebasedimages import ImageFileError
-    try:
-        imgs = nib.load(file_path).get_fdata()  # shape: (W, H, #frame) or (W, H)
-    except ImageFileError as e:
-        if mimetype is None:
-            raise e
-        # has_ext = os.path.splitext(file_path)[1] != ''
-        if mimetype == 'application/gzip':
-            with gzip.open(file_path, 'rb') as f:
-                imgs = nib.Nifti1Image.from_stream(f).get_fdata()
-        elif mimetype in ('image/x.nifti', 'application/x-nifti'):
-            with open(file_path, 'rb') as f:
-                imgs = nib.Nifti1Image.from_stream(f).get_fdata()
-        else:
-            raise e
-    if imgs.ndim == 2:
-        imgs = imgs.transpose(1, 0)
-        imgs = imgs[np.newaxis, np.newaxis]
-    elif imgs.ndim == 3:
-        imgs = imgs.transpose(2, 1, 0)
-        imgs = imgs[:, np.newaxis]
-    else:
-        raise ValueError(f"Unsupported number of dimensions in '{file_path}': {imgs.ndim}")
-
-    return imgs
-
-
-def read_image(file_path: str) -> np.ndarray:
-    with Image.open(file_path) as pilimg:
-        imgs = np.array(pilimg)
-    if imgs.ndim == 2:  # (H, W)
-        imgs = imgs[np.newaxis, np.newaxis]
-    elif imgs.ndim == 3:  # (H, W, C)
-        imgs = imgs.transpose(2, 0, 1)[np.newaxis]  # (H, W, C) -> (1, C, H, W)
-
-    return imgs
-
-
-def read_array_normalized(file_path: str,
-                          index: int | None = None,
-                          return_metainfo: bool = False,
-                          use_magic=False) -> np.ndarray | tuple[np.ndarray, Any]:
-    """
-    Read an array from a file.
-
-    Args:
-        file_path: The path to the file.
-        index: If specified, read only the frame at this index (0-based).
-            If None, read all frames.
-        Supported file formats are NIfTI (.nii, .nii.gz), PNG (.png), JPEG (.jpg, .jpeg) and npy (.npy).
-
-    Returns:
-        The array read from the file in shape (#frames, C, H, W), if `index=None`,
-            or (C, H, W) if `index` is specified.
-    """
-    if not os.path.exists(file_path):
-        raise FileNotFoundError(f"File not found: {file_path}")
-
-    metainfo = None
-
-    try:
-        if is_dicom(file_path):
-            ds = pydicom.dcmread(file_path)
-            if index is not None:
-                imgs = load_image_normalized(ds, index=index)[0]
-            else:
-                imgs = load_image_normalized(ds)
-            # Free up memory
-            if hasattr(ds, '_pixel_array'):
-                ds._pixel_array = None
-            if hasattr(ds, 'PixelData'):
-                ds.PixelData = None
-            metainfo = ds
-        else:
-            if use_magic:
-                import magic  # it is important to import here because magic has an OS lib dependency.
-                mime_type = magic.from_file(file_path, mime=True)
-            else:
-                mime_type = ""
-
-            if mime_type.startswith('video/') or file_path.endswith(VIDEO_EXTS):
-                imgs = read_video(file_path, index)
-            else:
-                if mime_type in ('image/x.nifti', 'application/x-nifti') or mime_type == 'application/gzip' or file_path.endswith(NII_EXTS):
-                    imgs = read_nifti(file_path, mimetype=mime_type)
-                    # For NIfTI files, try to load associated JSON metadata
-                    if return_metainfo:
-                        json_path = file_path.replace('.nii.gz', '.json').replace('.nii', '.json')
-                        if os.path.exists(json_path):
-                            try:
-                                import json
-                                with open(json_path, 'r') as f:
-                                    metainfo = json.load(f)
-                                _LOGGER.debug(f"Loaded JSON metadata from {json_path}")
-                            except Exception as e:
-                                _LOGGER.warning(f"Failed to load JSON metadata from {json_path}: {e}")
-                                metainfo = None
-                elif mime_type.startswith('image/') or file_path.endswith(IMAGE_EXTS):
-                    imgs = read_image(file_path)
-                elif file_path.endswith('.npy') or mime_type == 'application/x-numpy-data':
-                    imgs = np.load(file_path)
-                    if imgs.ndim != 4:
-                        raise ValueError(f"Unsupported number of dimensions in '{file_path}': {imgs.ndim}")
-                else:
-                    raise ValueError(f"Unsupported file format '{mime_type}' of '{file_path}'")
-
-                if index is not None:
-                    if len(imgs) > 1:
-                        _LOGGER.warning(f"It is inefficient to load all frames from '{file_path}' to access a single frame." +
-                                        " Consider converting the file to a format that supports random access (DICOM), or" +
-                                        " convert to png/jpeg files or" +
-                                        " manually handle all frames at once instead of loading a specific frame.")
-                    imgs = imgs[index]
-
-        if return_metainfo:
-            return imgs, metainfo
-        return imgs
-
-    except Exception as e:
-        _LOGGER.error(f"Failed to read array from '{file_path}': {e}")
-        raise e