dbdicom.DataBaseDicom#

class dbdicom.DataBaseDicom(path)[source]#

Class to read and write a DICOM folder.

Parameters:

path (str) – path to the DICOM folder.

Methods

__init__(path)

archive(archive_path)

close()

Close the DICOM folder

copy(from_entity[, to_entity])

Copy a DICOM entity (patient, study or series)

delete(entity)

Delete a DICOM entity from the database

edit(series, new_values[, dims, verbose])

Edit attribute values in a new DICOM series

files(entity)

Read the files in a DICOM entity

from_nifti(file, series[, ref])

Create a DICOM series from a nifti file.

move(from_entity, to_entity)

Move a DICOM entity

patients([name, contains, isin])

Return a list of patients in the DICOM folder.

pixel_data(series[, dims, coords, attr])

Read the pixel data from a DICOM series

print()

Print the contents of the DICOM folder

read()

Read the DICOM folder again

series([entity, desc, contains, isin])

Return a list of series in the DICOM folder.

split_series(series, attr[, key])

Split a series into multiple series

studies([entity, desc, contains, isin])

Return a list of studies in the DICOM folder.

summary()

Return a summary of the contents of the database.

to_nifti(series, file[, dims, verbose])

Save a DICOM series in nifti format.

unique(pars, entity)

Return a list of unique values for a DICOM entity

values(series, *attr[, dims, verbose])

Read the values of some attributes from a DICOM series

volume(entity[, dims, verbose])

Read volume.

write_volume(vol, series[, ref])

Write a vreg.Volume3D to a DICOM series
close()[source]#

Close the DICOM folder

This also saves changes in the header file to disk.

copy(from_entity, to_entity=None)[source]#

Copy a DICOM entity (patient, study or series)

Parameters:

  • from_entity (list) – entity to copy

  • to_entity (list, optional) – entity after copying. If this is not provided, a copy will be made in the same study and returned

Returns:

the copied entity. If th to_entity is provided, this is returned.

Return type:

entity

delete(entity)[source]#

Delete a DICOM entity from the database

Parameters:

entity (list) – entity to delete

edit(series: list, new_values: dict, dims: list | None = None, verbose=1)[source]#

Edit attribute values in a new DICOM series

Parameters:

  • series (list) – DICOM series to edit

  • new_values (dict) – dictionary with attribute: value pairs to write to the series

  • 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.

files(entity: list) → list[source]#

Read the files in a DICOM entity

Parameters:

entity (list or str) – DICOM entity to read. This can be a path to a folder containing DICOM files, or a patient or study to read all series in that patient or study.

Returns:

list of valid dicom files.

Return type:

list

from_nifti(file: str, series: list, ref: list | None = None)[source]#

Create a DICOM series from a nifti file.

Parameters:

  • file (str) – file path of the nifti file.

  • series (list) – DICOM series to create

  • ref (list) – DICOM series to use as template.

move(from_entity, to_entity)[source]#

Move a DICOM entity

Parameters:

entity (list) – entity to move

patients(name=None, contains=None, isin=None)[source]#

Return a list of patients in the DICOM folder.

Parameters:

  • name (str, optional) – value of PatientName, to search for individuals with a given name. Defaults to None.

  • contains (str, optional) – substring of PatientName, to search for individuals based on part of their name. Defaults to None.

  • isin (list, optional) – List of PatientName values, to search for patients whose name is in the list. Defaults to None.

Returns:

list of patients fulfilling the criteria.

Return type:

list

pixel_data(series: list, dims: list | None = None, coords=False, attr=None) → ndarray[source]#

Read the pixel data from a DICOM series

Parameters:

  • 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 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.

Return type:

numpy.ndarray or tuple

print()[source]#

Print the contents of the DICOM folder

read()[source]#

Read the DICOM folder again

series(entity=None, desc=None, contains=None, isin=None)[source]#

Return a list of series in the DICOM folder.

Parameters:

  • entity (str or list) – path to a DICOM folder (to search in the whole folder), or a list identifying a patient or a study (to search series of a given patient or study).

  • 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. Defaults to None.

  • isin (list, optional) – List of SeriesDescription values, to search for series whose description is in a list. Defaults to None.

Returns:

list of series fulfilling the criteria.

Return type:

list

split_series(series: list, attr: str | tuple, key=None) → list[source]#

Split a series into multiple series

Parameters:

  • series (list) – series to split.

  • attr (str or tuple) – dicom attribute to split the series by.

  • key (function) – split by by key(attr)

Returns:

list of two-element tuples, where the first element is is the value and the second element is the series corresponding to that value.

Return type:

list

studies(entity=None, desc=None, contains=None, isin=None)[source]#

Return a list of studies in the DICOM folder.

Parameters:

  • 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).

  • 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. Defaults to None.

  • isin (list, optional) – List of StudyDescription values, to search for studies whose description is in a list. Defaults to None.

Returns:

list of studies fulfilling the criteria.

Return type:

list

summary()[source]#

Return a summary of the contents of the database.

Returns:

Nested dictionary with summary information on the database.

Return type:

dict

to_nifti(series: list, file: str, dims=None, verbose=1)[source]#

Save a DICOM series in nifti format.

Parameters:

  • series (list) – DICOM series to read

  • file (str) – file path of the nifti file.

  • 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.

unique(pars: list, entity: list) → dict[source]#

Return a list of unique values for a DICOM entity

Parameters:

  • pars (list, str/tuple) – attribute or attributes to return.

  • entity (list) – DICOM entity to search (Patient, Study or Series)

Returns:

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.

Return type:

dict

values(series: list, *attr, dims: list | None = None, verbose=1) → dict | tuple[source]#

Read the values of some attributes from a DICOM series

Parameters:

  • series (list) – DICOM series to read.

  • attr (tuple, optional) – DICOM attributes 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:

arrays with values for the attributes.

Return type:

tuple

volume(entity: list | str, dims: list | None = None, verbose=1) → Volume3D[source]#

Read volume.

Parameters:

  • 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.

Return type:

vreg.Volume3D

write_volume(vol: Volume3D | tuple, series: list, ref: list | None = None)[source]#

Write a vreg.Volume3D to a DICOM series

Parameters:

  • vol (vreg.Volume3D) – Volume to write to the series.

  • series (list) – DICOM series to read

  • ref (list) – Reference series