dbdicom 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

dbdicom/api.py

@@ -1,3 +1,4 @@
+from typing import Union
 
 import vreg
 
@@ -87,14 +88,14 @@ def patients(path, name:str=None, contains:str=None, isin:list=None)->list:
     return p
 
 
-def studies(entity:str | list, name:str=None, contains:str=None, isin:list=None)->list:
+def studies(entity:str | list, desc:str=None, contains:str=None, isin:list=None)->list:
     """Return a list of studies in the DICOM folder.
 
     Args:
         entity (str or list): path to a DICOM folder (to search in 
             the whole folder), or a two-element list identifying a 
             patient (to search studies of a given patient).
-        name (str, optional): value of StudyDescription, to search for 
+        desc (str, optional): value of StudyDescription, to search for 
             studies with a given description. Defaults to None.
         contains (str, optional): substring of StudyDescription, to 
             search for studies based on part of their description. 
@@ -107,12 +108,12 @@ def studies(entity:str | list, name:str=None, contains:str=None, isin:list=None)
     """
     if isinstance(entity, str): # path = folder
         dbd = open(entity)
-        s = dbd.studies(entity, name, contains, isin)
+        s = dbd.studies(entity, desc, contains, isin)
         dbd.close()
         return s
     elif len(entity)==2: # path = patient
         dbd = open(entity[0])
-        s = dbd.studies(entity, name, contains, isin)
+        s = dbd.studies(entity, desc, contains, isin)
         dbd.close()
         return s
     else:
@@ -121,7 +122,7 @@ def studies(entity:str | list, name:str=None, contains:str=None, isin:list=None)
             "with a folder and a patient name."
         )
 
-def series(entity:str | list, name:str=None, contains:str=None, isin:list=None)->list:
+def series(entity:str | list, desc:str=None, contains:str=None, isin:list=None)->list:
     """Return a list of series in the DICOM folder.
 
     Args:
@@ -129,7 +130,7 @@ def series(entity:str | list, name:str=None, contains:str=None, isin:list=None)-
             the whole folder), or a list identifying a 
             patient or a study (to search series of a given patient 
             or study).
-        name (str, optional): value of SeriesDescription, to search for 
+        desc (str, optional): value of SeriesDescription, to search for 
             series with a given description. Defaults to None.
         contains (str, optional): substring of SeriesDescription, to 
             search for series based on part of their description. 
@@ -142,12 +143,12 @@ def series(entity:str | list, name:str=None, contains:str=None, isin:list=None)-
     """
     if isinstance(entity, str): # path = folder
         dbd = open(entity)
-        s = dbd.series(entity, name, contains, isin)
+        s = dbd.series(entity, desc, contains, isin)
         dbd.close()
         return s
     elif len(entity) in [2,3]:
         dbd = open(entity[0])
-        s = dbd.series(entity, name, contains, isin)
+        s = dbd.series(entity, desc, contains, isin)
         dbd.close()
         return s
     else:
@@ -189,42 +190,54 @@ def move(from_entity:list, to_entity:list):
     dbd.delete(from_entity)
     dbd.close()
 
+def split_series(series:list, attr:Union[str, tuple])->dict:
+    """
+    Split a series into multiple series
+    
+    Args:
+        series (list): series to split.
+        attr (str or tuple): dicom attribute to split the series by.  
+    Returns:
+        dict: dictionary with keys the unique values found (ascending) 
+        and as values the series corresponding to that value.     
+    """
+    dbd = open(series[0])
+    split_series = dbd.split_series(series, attr)
+    dbd.close()
+    return split_series
+
 
-def volume(series:list, dims:list=None, multislice=False) -> vreg.Volume3D:
-    """Read a vreg.Volume3D from a DICOM series
+def volume(entity:Union[list, str], dims:list=None) -> Union[vreg.Volume3D, list]:
+    """Read volume or volumes.
 
     Args:
-        series (list): DICOM series to read
+        entity (list, str): DICOM entity to read
         dims (list, optional): Non-spatial dimensions of the volume. Defaults to None.
-        multislice (bool, optional): Whether the data are to be read 
-            as multislice or not. In multislice data the voxel size 
-            is taken from the slice gap rather thsan the slice thickness. Defaults to False.
 
     Returns:
-        vreg.Volume3D: vole read from the series.
+        vreg.Volume3D | list: If the entity is a series this returns 
+        a volume, else a list of volumes.
     """
-    dbd = open(series[0])
-    vol = dbd.volume(series, dims, multislice)
+    if isinstance(entity, str):
+        entity = [entity]
+    dbd = open(entity[0])
+    vol = dbd.volume(entity, dims)
     dbd.close()
     return vol
 
-def write_volume(vol:vreg.Volume3D, series:list, ref:list=None, 
-                 multislice=False):
+def write_volume(vol:Union[vreg.Volume3D, tuple], series:list, ref:list=None):
     """Write a vreg.Volume3D to a DICOM series
 
     Args:
-        vol (vreg.Volume3D): Volume to write to the series.
+        vol (vreg.Volume3D or tuple): Volume to write to the series.
         series (list): DICOM series to read
         dims (list, optional): Non-spatial dimensions of the volume. Defaults to None.
-        multislice (bool, optional): Whether the data are to be read 
-            as multislice or not. In multislice data the voxel size 
-            is taken from the slice gap rather thsan the slice thickness. Defaults to False.
     """
     dbd = open(series[0])
-    dbd.write_volume(vol, series, ref, multislice)
+    dbd.write_volume(vol, series, ref)
     dbd.close()
 
-def to_nifti(series:list, file:str, dims:list=None, multislice=False):
+def to_nifti(series:list, file:str, dims:list=None):
     """Save a DICOM series in nifti format.
 
     Args:
@@ -232,27 +245,21 @@ def to_nifti(series:list, file:str, dims:list=None, multislice=False):
         file (str): file path of the nifti file.
         dims (list, optional): Non-spatial dimensions of the volume. 
             Defaults to None.
-        multislice (bool, optional): Whether the data are to be read 
-            as multislice or not. In multislice data the voxel size 
-            is taken from the slice gap rather thaan the slice thickness. Defaults to False.
     """
     dbd = open(series[0])
-    dbd.to_nifti(series, file, dims, multislice)
+    dbd.to_nifti(series, file, dims)
     dbd.close()
 
-def from_nifti(file:str, series:list, ref:list=None, multislice=False):
+def from_nifti(file:str, series:list, ref:list=None):
     """Create a DICOM series from a nifti file.
 
     Args:
         file (str): file path of the nifti file.
         series (list): DICOM series to create
         ref (list): DICOM series to use as template.
-        multislice (bool, optional): Whether the data are to be written
-            as multislice or not. In multislice data the voxel size 
-            is written in the slice gap rather thaan the slice thickness. Defaults to False.
     """
     dbd = open(series[0])
-    dbd.from_nifti(file, series, ref, multislice)
+    dbd.from_nifti(file, series, ref)
     dbd.close()
 
 def pixel_data(series:list, dims:list=None, include:list=None) -> tuple:
@@ -270,6 +277,8 @@ def pixel_data(series:list, dims:list=None, include:list=None) -> tuple:
             is provide these are returned as a dictionary in a third 
             return value.
     """
+    if isinstance(series, str):
+        series = [series]
     dbd = open(series[0])
     array = dbd.pixel_data(series, dims, include)
     dbd.close()
@@ -289,11 +298,12 @@ def unique(pars:list, entity:list) -> dict:
     """Return a list of unique values for a DICOM entity
 
     Args:
-        pars (list): attributes to return.
+        pars (list, str/tuple): attribute or attributes to return.
         entity (list): DICOM entity to search (Patient, Study or Series)
 
     Returns:
-        dict: dictionary with unique values for each attribute.
+        dict: if a pars is a list, this returns a dictionary with 
+        unique values for each attribute. If pars is a scalar this returnes a list of values
     """
     dbd = open(entity[0])
     u = dbd.unique(pars, entity)

dbdicom/database.py

@@ -20,6 +20,7 @@ COLUMNS = [
     'PatientName', 
     'StudyDescription', 
     'StudyDate', 
+    'StudyID',
     'SeriesDescription', 
     'SeriesNumber', 
     'InstanceNumber', 
@@ -77,6 +78,7 @@ def _multiframe_to_singleframe(path, df):
 
 def _tree(df):
     # A human-readable summary tree
+    # TODO: Add version number
 
     df.sort_values(['PatientID','StudyInstanceUID','SeriesNumber'], inplace=True)
     df = df.fillna('None')
@@ -94,10 +96,12 @@ def _tree(df):
         for uid_study in df_patient.StudyInstanceUID.unique():
             df_study = df_patient[df_patient.StudyInstanceUID == uid_study]
             study_desc = df_study.StudyDescription.values[0]
+            study_id = df_study.StudyID.values[0]
             study_date = df_study.StudyDate.values[0]
             study = {
                 'StudyDescription': study_desc,
                 'StudyDate': study_date,
+                'StudyID': study_id,
                 'StudyInstanceUID': uid_study,
                 'series': [],
             }

dbdicom/dataset.py

@@ -229,7 +229,8 @@ def write(ds, file, status=None):
     dir = os.path.dirname(file)
     if not os.path.exists(dir):
         os.makedirs(dir)
-    ds.save_as(file, write_like_original=False)
+    #ds.save_as(file, write_like_original=False) # deprecated
+    ds.save_as(file, enforce_file_format=True)
 
 
 def codify(source_file, save_file, **kwargs):
@@ -513,32 +514,24 @@ def set_lut(ds, RGB):
 
 
 
-def affine(ds, multislice=False):
-    if multislice:
-        return image.affine_matrix(
-            get_values(ds, 'ImageOrientationPatient'), 
-            get_values(ds, 'ImagePositionPatient'), 
-            get_values(ds, 'PixelSpacing'), 
-            get_values(ds, 'SpacingBetweenSlices'),
-        )
-    else:
-        return image.affine_matrix(
-            get_values(ds, 'ImageOrientationPatient'), 
-            get_values(ds, 'ImagePositionPatient'), 
-            get_values(ds, 'PixelSpacing'), 
-            get_values(ds, 'SliceThickness'),
-        )
+def affine(ds):
+    # Spacing Between Slices is not required so can be absent
+    slice_spacing = ds.get("SpacingBetweenSlices")
+    if slice_spacing is None:
+        slice_spacing = ds.get("SliceThickness")
+    return image.affine_matrix(
+        get_values(ds, 'ImageOrientationPatient'), 
+        get_values(ds, 'ImagePositionPatient'), 
+        get_values(ds, 'PixelSpacing'), 
+        slice_spacing, 
+    )
 
-
-def set_affine(ds, affine, multislice=False):
+def set_affine(ds, affine):
     if affine is None:
         raise ValueError('The affine cannot be set to an empty value')
     v = image.dismantle_affine_matrix(affine)
     set_values(ds, 'PixelSpacing', v['PixelSpacing'])
-    if multislice:
-        set_values(ds, 'SpacingBetweenSlices', v['SliceThickness'])
-    else:
-        set_values(ds, 'SliceThickness', v['SliceThickness'])
+    set_values(ds, 'SpacingBetweenSlices', v['SpacingBetweenSlices'])
     set_values(ds, 'ImageOrientationPatient', v['ImageOrientationPatient'])
     set_values(ds, 'ImagePositionPatient', v['ImagePositionPatient'])
     set_values(ds, 'SliceLocation', np.dot(v['ImagePositionPatient'], v['slice_cosine']))
@@ -602,10 +595,10 @@ def set_pixel_data(ds, array):
     ds.PixelData = array.tobytes()
 
 
-def volume(ds, multislice=False):
-    return vreg.volume(pixel_data(ds), affine(ds, multislice))
+def volume(ds):
+    return vreg.volume(pixel_data(ds), affine(ds))
 
-def set_volume(ds, volume:vreg.Volume3D, multislice=False):
+def set_volume(ds, volume:vreg.Volume3D):
     if volume is None:
         raise ValueError('The volume cannot be set to an empty value.')
     try:
@@ -621,7 +614,7 @@ def set_volume(ds, volume:vreg.Volume3D, multislice=False):
     if image.ndim != 2:
         raise ValueError("Can only write 2D images to a dataset.")
     set_pixel_data(ds, image)
-    set_affine(ds, volume.affine, multislice)
+    set_affine(ds, volume.affine)
     if volume.coords is not None:
         # All other dimensions should have size 1
         coords = volume.coords.reshape((volume.coords.shape[0], -1))