dbdicom 0.3.11__tar.gz → 0.3.12__tar.gz

{dbdicom-0.3.11/src/dbdicom.egg-info → dbdicom-0.3.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbdicom
-Version: 0.3.11
+Version: 0.3.12
 Summary: A pythonic interface for reading and writing DICOM databases
 Author-email: Steven Sourbron <s.sourbron@sheffield.ac.uk>, Ebony Gunwhy <e.gunwhy@sheffield.ac.uk>
 Project-URL: Homepage, https://openmiblab.github.io/dbdicom/

{dbdicom-0.3.11 → dbdicom-0.3.12}/pyproject.toml

@@ -7,7 +7,7 @@ requires = ['setuptools>=61.2']
 
 [project]
 name = "dbdicom"
-version = "0.3.11"
+version = "0.3.12"
 dependencies = [ 
     "tqdm",
     "importlib-resources",

{dbdicom-0.3.11 → dbdicom-0.3.12}/src/dbdicom/api.py

@@ -240,6 +240,23 @@ def volume(series:list, dims:list=None, verbose=1) -> vreg.Volume3D:
     return vol
 
 
+def volumes_2d(series:list, dims:list=None, verbose=1) -> vreg.Volume3D:
+    """Read 2D volumes from the series
+
+    Args:
+        entity (list, str): DICOM series to read
+        dims (list, optional): Non-spatial dimensions of the volume. Defaults to None.
+        verbose (bool, optional): If set to 1, shows progress bar. Defaults to 1.
+
+    Returns:
+        list of vreg.Volume3D
+    """
+    dbd = open(series[0])
+    vol = dbd.volumes_2d(series, dims, verbose)
+    dbd.close()
+    return vol
+
+
 def values(series:list, *attr, dims:list=None, verbose=1) -> Union[np.ndarray, list]:
     """Read the values of some attributes from a DICOM series
 
@@ -259,16 +276,23 @@ def values(series:list, *attr, dims:list=None, verbose=1) -> Union[np.ndarray, l
     return values
 
 
-def write_volume(vol:Union[vreg.Volume3D, tuple], series:list, ref:list=None):
+
+def write_volume(vol:Union[vreg.Volume3D, tuple], series:list, 
+                 ref:list=None, append=False, verbose=1):
     """Write a vreg.Volume3D to a DICOM series
 
     Args:
         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.
+        append (bool): by default write_volume will only write to a new series, 
+            and raise an error when attempting to write to an existing series. 
+            To overrule this behaviour and add the volume to an existing series, set append to True. 
+            Default is False.
+        verbose (bool): if set to 1, a progress bar is shown. verbose=0 does not show updates.
     """
     dbd = open(series[0])
-    dbd.write_volume(vol, series, ref)
+    dbd.write_volume(vol, series, ref, append, verbose)
     dbd.close()
 
 
@@ -337,39 +361,27 @@ def files(entity:list) -> list:
     return files
 
 
-def pixel_data(series:list, dims:list=None, coords=False, attr:list=None) -> tuple:
+def pixel_data(series:list, dims:list=None, verbose=1) -> tuple:
     """Read the pixel data from a DICOM series
 
     Args:
-        series (list): DICOM series to read
+        series (list or str): DICOM series to read. This can also 
+            be a path to a folder containing DICOM files, or a 
+            patient or study to read all series in that patient or 
+            study. In those cases a list is returned.
         dims (list, optional): Dimensions of the array.
-        coords (bool): If set to True, the coordinates of the 
-            slices are returned alongside the pixel data.
-        attr (list, optional): list of DICOM attributes that are 
-            read on the fly to avoid reading the data twice.
 
     Returns:
-        tuple: numpy array with pixel values and an array with 
-            coordinates of the slices according to dims. If include 
-            is provide these are returned as a dictionary in a third 
-            return value.
+        numpy.ndarray or tuple: numpy array with pixel values, with 
+            at least 3 dimensions (x,y,z). 
     """
     if isinstance(series, str):
         series = [series]
     dbd = open(series[0])
-    array = dbd.pixel_data(series, dims, coords, attr)
+    array = dbd.pixel_data(series, dims, verbose)
     dbd.close()
     return array
 
-# write_pixel_data()
-# values()
-# write_values()
-# to_png(series, folder, dims)
-# to_npy(series, folder, dims)
-# split(series, attribute)
-# extract(series, *kwargs) # subseries
-
-# zeros(series, shape, dims)
 
 def unique(pars:list, entity:list) -> dict:
     """Return a list of unique values for a DICOM entity
@@ -420,6 +432,8 @@ def _copy_and_extract_zips(src_folder, dest_folder):
                 if file.lower().endswith('.zip'):
                     try:
                         zip_dest_folder = dest_file_path[:-4]
+                        if os.path.exists(zip_dest_folder):
+                            continue
                         with zipfile.ZipFile(src_file_path, 'r') as zip_ref:
                             zip_ref.extractall(zip_dest_folder)
                         #tqdm.write(f"Extracted ZIP: {src_file_path}")
@@ -427,6 +441,8 @@ def _copy_and_extract_zips(src_folder, dest_folder):
                     except zipfile.BadZipFile:
                         tqdm.write(f"Bad ZIP file skipped: {src_file_path}")
                 else:
+                    if os.path.exists(dest_file_path):
+                        continue
                     shutil.copy2(src_file_path, dest_file_path)
 
                 pbar.update(1)

{dbdicom-0.3.11 → dbdicom-0.3.12}/src/dbdicom/dataset.py

@@ -85,8 +85,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) # deprecated
-    ds.save_as(file, enforce_file_format=True)
+    ds.save_as(file, write_like_original=False) # deprecated
+    # ds.save_as(file, enforce_file_format=True)
 
 
 def codify(source_file, save_file, **kwargs):
@@ -232,11 +232,20 @@ def set_lut(ds, RGB):
 
 
 
-def affine(ds):
-    # Spacing Between Slices is not required so can be absent
-    slice_spacing = ds.get("SpacingBetweenSlices")
-    if slice_spacing is None:
+def affine(ds, multislice=False):
+    
+    if multislice:
+        # For 2D scans the slice_spacing is the slice thickness
         slice_spacing = ds.get("SliceThickness")
+    else:
+        # For 3D scans the slice spacing is the SpacingBetweenSlices
+        # Spacing Between Slices is not required so can be absent
+        # This is less critical because when reading a 3D volume the 
+        # definitive slice_spacing is inferred from the slice positions.
+        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'), 
@@ -339,8 +348,8 @@ def set_pixel_data(ds, array):
 #     ds.PixelData = array.tobytes()
 
 
-def volume(ds):
-    return vreg.volume(pixel_data(ds), affine(ds))
+def volume(ds, multislice=False):
+    return vreg.volume(pixel_data(ds), affine(ds, multislice=multislice))
 
 
 

{dbdicom-0.3.11 → dbdicom-0.3.12}/src/dbdicom/dbd.py

@@ -292,6 +292,8 @@ class DataBaseDicom():
                 v.affine[:3,2] = -v.affine[:3,2]
                 # Then try again
             vol = vreg.join(vols)
+
+        # For multi-dimensional volumes, set dimensions and coordinates
         if vol.ndim > 3:
             # Coordinates of slice 0
             c0 = [c[0,...] for c in coords[1:]]
@@ -300,6 +302,128 @@ class DataBaseDicom():
         return vol
 
 
+    def volumes_2d(self, entity:Union[list, str], dims:list=None, verbose=1) -> list:
+        """Read 2D volumes from the series
+
+        Args:
+            entity (list, str): DICOM series to read
+            dims (list, optional): Non-spatial dimensions of the volume. Defaults to None.
+            verbose (bool, optional): If set to 1, shows progress bar. Defaults to 1.
+
+        Returns:
+            list of vreg.Volume3D
+        """
+        # if isinstance(entity, str): # path to folder
+        #     return [self.volume(s, dims) for s in self.series(entity)]
+        # if len(entity) < 4: # folder, patient or study
+        #     return [self.volume(s, dims) for s in self.series(entity)]
+        
+        if dims is None:
+            dims = []
+        elif isinstance(dims, str):
+            dims = [dims]
+        else:
+            dims = list(dims)
+        dims = ['SliceLocation'] + dims
+
+        # Read dicom files
+        values = {}
+        volumes = {}
+
+        files = register.files(self.register, entity)
+        for f in tqdm(files, desc='Reading volume..', disable=(verbose==0)):
+            ds = pydicom.dcmread(f)
+            values_f = get_values(ds, dims)
+            vol = dbdataset.volume(ds, multislice=True)
+            slice_loc = values_f[0]
+            if slice_loc in volumes:
+                volumes[slice_loc].append(vol)
+                for d in range(len(dims)):
+                    values[slice_loc][d].append(values_f[d])
+            else:
+                volumes[slice_loc] = [vol]
+                values[slice_loc] = [[values_f[d]] for d in range(len(dims))]
+
+        # Build a volume for each slice location
+        volumes_2d = []
+        for slice_loc in volumes.keys():
+            vols_list = volumes[slice_loc]
+
+            if values == {}:
+                if len(vols_list) > 1:
+                    raise ValueError(
+                        "Cannot return a 2D volume - multiple slices at the same "
+                        "location. \n Use InstanceNumber or another suitable DICOM "
+                        "attribute as dimension to sort them.")
+                volumes_2d.append(vols_list[0])
+                continue
+
+            # Sort by coordinata values
+            vals_list = values[slice_loc]
+
+            # Format coordinates as mesh
+            coords = [np.array(v) for v in vals_list]
+            coords, inds = dbdicom.utils.arrays.meshvals(coords)
+
+            # Check that all slices have the same coordinates
+            if len(dims) > 1:
+                # Loop over all coordinates after slice location
+                for c in coords[1:]:
+                    # Loop over all slice locations
+                    for k in range(1, c.shape[0]):
+                        # Coordinate c of slice k
+                        if not np.array_equal(c[k,...], c[0,...]):
+                            raise ValueError(
+                                "Cannot build a single volume. Not all slices "
+                                "have the same coordinates."     
+                            )
+
+            # Build volumes, sort and reshape along the coordinates
+            vols = np.array(vols_list)
+            vols = vols[inds].reshape(coords[0].shape)
+        
+            # Join 2D volumes along the extra dimensions
+            vol = vreg.join(vols[0,...].reshape((1,) + vols.shape[1:]))
+
+            # For multi-dimensional volumes, set dimensions and coordinates
+            if vol.ndim > 3:
+                # Coordinates of slice 0
+                c0 = [c[0,...] for c in coords[1:]]
+                vol.set_coords(c0)
+                vol.set_dims(dims[1:])
+
+            volumes_2d.append(vol)
+            
+        return volumes_2d
+
+
+    def pixel_data(self, series:list, dims:list=None, verbose=1) -> np.ndarray:
+        """Read the pixel data from a DICOM series
+
+        Args:
+            series (list or str): DICOM series to read. This can also 
+                be a path to a folder containing DICOM files, or a 
+                patient or study to read all series in that patient or 
+                study. In those cases a list is returned.
+            dims (list, optional): Dimensions of the array.
+
+        Returns:
+            numpy.ndarray or tuple: numpy array with pixel values, with 
+                at least 3 dimensions (x,y,z). 
+        """
+        vols = self.volumes_2d(series, dims, verbose)
+        for v in vols[1:]:
+            if v.shape != vols[0].shape:
+                raise ValueError(
+                    "Cannot return a pixel array because slices have different shapes." \
+                    "Instead try using volumes_2d to return a list of 2D volumes."
+                )
+        slices = [v.values for v in vols]
+        pixel_array = np.concatenate(slices, axis=2)
+        return pixel_array
+        
+    
+
     def values(self, series:list, *attr, dims:list=None, verbose=1) -> Union[dict, tuple]:
         """Read the values of some attributes from a DICOM series
 
@@ -355,7 +479,7 @@ class DataBaseDicom():
 
     def write_volume(
             self, vol:Union[vreg.Volume3D, tuple], series:list, 
-            ref:list=None, 
+            ref:list=None, append=False, verbose=1,
         ):
         """Write a vreg.Volume3D to a DICOM series
 
@@ -363,10 +487,16 @@ class DataBaseDicom():
             vol (vreg.Volume3D): Volume to write to the series.
             series (list): DICOM series to read
             ref (list): Reference series
+            append (bool): by default write_volume will only write to a new series, 
+               and raise an error when attempting to write to an existing series. 
+               To overrule this behaviour and add the volume to an existing series, set append to True. 
+               Default is False.
+            verbose (bool): if set to 1, a progress bar is shown
         """
         series_full_name = full_name(series)
         if series_full_name in self.series():
-            raise ValueError(f"Series {series_full_name[-1]} already exists in study {series_full_name[-2]}.")
+            if not append:
+                raise ValueError(f"Series {series_full_name[-1]} already exists in study {series_full_name[-2]}.")
 
         if isinstance(vol, tuple):
             vol = vreg.volume(vol[0], vol[1])
@@ -388,13 +518,13 @@ class DataBaseDicom():
 
         if vol.ndim==3:
             slices = vol.split()
-            for i, sl in tqdm(enumerate(slices), desc='Writing volume..'):
+            for i, sl in tqdm(enumerate(slices), desc='Writing volume..', disable=verbose==0):
                 dbdataset.set_volume(ds, sl)
                 self._write_dataset(ds, attr, n + 1 + i)
         else:
             i=0
             vols = vol.separate().reshape(-1)
-            for vt in tqdm(vols, desc='Writing volume..'):
+            for vt in tqdm(vols, desc='Writing volume..', disable=verbose==0):
                 slices = vt.split()
                 for sl in slices:
                     dbdataset.set_volume(ds, sl)
@@ -506,108 +636,7 @@ class DataBaseDicom():
         self.write_volume(vol, series, ref)
         return self
     
-    def pixel_data(self, series:list, dims:list=None, coords=False, attr=None) -> np.ndarray:
-        """Read the pixel data from a DICOM series
-
-        Args:
-            series (list or str): DICOM series to read. This can also 
-                be a path to a folder containing DICOM files, or a 
-                patient or study to read all series in that patient or 
-                study. In those cases a list is returned.
-            dims (list, optional): Dimensions of the array.
-            coords (bool): If set to True, the coordinates of the 
-                arrays are returned alongside the pixel data
-            attr (list, optional): list of DICOM attributes that are 
-                read on the fly to avoid reading the data twice.
-
-        Returns:
-            numpy.ndarray or tuple: numpy array with pixel values, with 
-                at least 3 dimensions (x,y,z). If 
-                coords is set these are returned too as an array with 
-                coordinates of the slices according to dims. If include 
-                is provided the values are returned as a dictionary in the last 
-                return value. 
-        """
-        if isinstance(series, str): # path to folder
-            return [self.pixel_data(s, dims, coords, attr) for s in self.series(series)]
-        if len(series) < 4: # folder, patient or study
-            return [self.pixel_data(s, dims, coords, attr) for s in self.series(series)]
 
-        if dims is None:
-            dims = ['InstanceNumber']
-        elif np.isscalar(dims):
-            dims = [dims]
-        else:
-            dims = list(dims)
-
-        # Ensure return_vals is a list
-        if attr is None:
-            params = []
-        elif np.isscalar(attr):
-            params = [attr]
-        else:
-            params = list(attr)
-
-        files = register.files(self.register, series)
-        
-        # Read dicom files
-        coords_array = []
-        arrays = np.empty(len(files), dtype=dict)
-        if attr is not None:
-            values = np.empty(len(files), dtype=dict)
-        for i, f in tqdm(enumerate(files), desc='Reading pixel data..'):
-            ds = pydicom.dcmread(f)  
-            coords_array.append(get_values(ds, dims))
-            # save as dict so numpy does not stack as arrays
-            arrays[i] = {'pixel_data': dbdataset.pixel_data(ds)}
-            if attr is not None:
-                values[i] = {'values': get_values(ds, params)}
-
-        # Format as mesh
-        coords_array = np.stack([v for v in coords_array], axis=-1)
-        coords_array, inds = dbdicom.utils.arrays.meshvals(coords_array)
-
-        arrays = arrays[inds].reshape(coords_array.shape[1:])
-        arrays = np.stack([a['pixel_data'] for a in arrays.reshape(-1)], axis=-1)
-        arrays = arrays.reshape(arrays.shape[:2] + coords_array.shape[1:])
-
-        if attr is None:
-            if coords:
-                return arrays, coords_array
-            else:
-                return arrays
-
-        # Return values as a dictionary
-        values = values[inds].reshape(-1)
-        values_dict = {}
-        for p in range(len(params)):
-            # Get the type from the first value
-            vp0 = values[0]['values'][p]
-            # Build an array of the right type
-            vp = np.zeros(values.size, dtype=type(vp0))
-            # Populate the array with values for parameter p
-            for i, v in enumerate(values):
-                vp[i] = v['values'][p]
-            # Reshape values for parameter p
-            vp = vp.reshape(coords_array.shape[1:])
-            # Eneter in the dictionary
-            values_dict[params[p]] = vp
-
-        # If only one, return as value
-        if len(params) == 1:
-            values_return = values_dict[attr[0]]
-        else:
-            values_return = values_dict
-        
-        # problem if the values are a list. Needs an array with a prespeficied dtype
-        # values = values[inds].reshape(coords_array.shape[1:])
-        # values = np.stack([a['values'] for a in values.reshape(-1)], axis=-1) 
-        # values = values.reshape((len(params), ) + coords_array.shape[1:])
-
-        if coords:
-            return arrays, coords_array, values_return
-        else:
-            return arrays, values_return
         
 
 
@@ -1120,7 +1149,7 @@ def infer_slice_spacing(vols):
         distances = np.around(distances, 2)
         slice_spacing_d = np.unique(distances)
 
-        # Check if unique - otherwise this is not a volume
+        # Check if slice spacings are unique - otherwise this is not a volume
         if len(slice_spacing_d) > 1:
             raise ValueError(
                 'Cannot build a volume - spacings between slices are not unique.'
@@ -1135,6 +1164,7 @@ def infer_slice_spacing(vols):
         slice_spacing[d] = slice_spacing_d
 
     # Check slice_spacing is the same across dimensions
+    # Not sure if this is possible as volumes are sorted by slice location
     slice_spacing = np.unique(slice_spacing)
     if len(slice_spacing) > 1:
         raise ValueError(
@@ -1143,7 +1173,3 @@ def infer_slice_spacing(vols):
 
     return vols.reshape(shape)
 
-
-
-
-

{dbdicom-0.3.11 → dbdicom-0.3.12/src/dbdicom.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbdicom
-Version: 0.3.11
+Version: 0.3.12
 Summary: A pythonic interface for reading and writing DICOM databases
 Author-email: Steven Sourbron <s.sourbron@sheffield.ac.uk>, Ebony Gunwhy <e.gunwhy@sheffield.ac.uk>
 Project-URL: Homepage, https://openmiblab.github.io/dbdicom/

{dbdicom-0.3.11 → dbdicom-0.3.12}/tests/test_api.py

@@ -11,6 +11,8 @@ shutil.rmtree(tmp)
 os.makedirs(tmp, exist_ok=True)
 
 
+
+
 def test_write_volume():
 
     values = 100*np.random.rand(128, 192, 20).astype(np.float32)
@@ -24,11 +26,84 @@ def test_write_volume():
     series = [tmp, '007', 'dbdicom_test', 'dixon']
     db.write_volume(vol, series)
 
+    # Writing to an existing series returns an error by default
+    try:
+        db.write_volume(vol, series)
+    except:
+        assert True
+    else:
+        assert False
+
+    # Translate the volume in the z-direction over 10mm and append to the series
+    # This creates a series with two volumes separated by a gap of 5 mm
+    vol2 = vol.translate([0,0,20], coords='volume')
+    db.write_volume(vol2, series, append=True)
+
+    # Reading now throws an error as there are multiple volumes in the series
+    try:
+        db.volume(series, dims=['ImageType'])
+    except:
+        assert True
+    else:
+        assert False
+
+
+    shutil.rmtree(tmp)
+
+
+def test_volumes_2d():
+
+    # Write one volume
+    values = 100*np.random.rand(128, 192, 5).astype(np.float32)
+    vol = vreg.volume(values)
+    series = [tmp, '007', 'dbdicom_test', 'ax']
+    db.write_volume(vol, series)
+
+    # Shift it up to leave a gap and write to the same series
+    vol2 = vol.translate([0,0,10], coords='volume')
+    db.write_volume(vol2, series, append=True)
+
+    # Trying to read as a single volume throws an error because of the gap
+    try:
+        db.volume(series)
+    except:
+        assert True
+    else:
+        assert False
+
+    # But we can read them as 2D volumes, returning 10 2D volumes
+    vols = db.volumes_2d(series)
+    assert len(vols) == 10
+
+    # Now 4D
+    values = np.zeros((256, 256, 5, 2))
+    affine = np.eye(4)
+    vol = vreg.volume(values, affine, coords=(['INPHASE', 'OUTPHASE'], ), dims=['ImageType'])
+    series = [tmp, '007', 'dbdicom_test', 'dixon']
+    db.write_volume(vol, series)
+
+    vol2 = vol.translate([0,0,10], coords='volume')
+    db.write_volume(vol2, series, append=True)
+
+    vols = db.volumes_2d(series, dims=['ImageType'])
+    assert len(vols) == 10
+    assert vols[-1].shape == (256, 256, 1, 2)
+
     shutil.rmtree(tmp)
 
 
 def test_volume():
 
+    # One slice
+    values = 100*np.random.rand(128, 192, 1).astype(np.float32)
+    vol = vreg.volume(values)
+    series = [tmp, '007', 'test', 'slice']
+    db.write_volume(vol, series)
+    vol2 = db.volume(series)
+    assert np.linalg.norm(vol2.values-vol.values) < 0.0001*np.linalg.norm(vol.values)
+    assert np.linalg.norm(vol2.affine-vol.affine) == 0
+
+    # 3D volume
     values = 100*np.random.rand(128, 192, 20).astype(np.float32)
     vol = vreg.volume(values)
     series = [tmp, '007', 'test', 'ax']
@@ -37,6 +112,7 @@ def test_volume():
     assert np.linalg.norm(vol2.values-vol.values) < 0.0001*np.linalg.norm(vol.values)
     assert np.linalg.norm(vol2.affine-vol.affine) == 0
 
+    # 4D volume
     values = 100*np.random.rand(256, 256, 3, 2).astype(np.float32)
     vol = vreg.volume(values, dims=['ImageType'], coords=(['INPHASE', 'OUTPHASE'], ), orient='coronal')
     series = [tmp, '007', 'dbdicom_test', 'dixon']
@@ -120,6 +196,8 @@ def test_edit():
     assert np.array_equal(tr, new_tr)
     assert np.array_equal(pn, new_pn)
 
+    shutil.rmtree(tmp)
+
 
 def test_write_database():
     values = 100*np.random.rand(16, 16, 4).astype(np.float32)
@@ -215,9 +293,10 @@ def test_copy():
 
 if __name__ == '__main__':
 
+    test_write_volume()
+    test_volumes_2d()
     test_values()
     test_edit()
-    test_write_volume()
     test_volume()
     test_write_database()
     test_copy()