dbdicom 0.2.6__tar.gz → 0.3.1__tar.gz

dbdicom-0.3.1/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: dbdicom
+Version: 0.3.1
+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/
+Keywords: python,medical imaging,DICOM
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tqdm
+Requires-Dist: importlib-resources
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: vreg
+Requires-Dist: pydicom
+Requires-Dist: python-gdcm
+Requires-Dist: pylibjpeg-libjpeg
+Dynamic: license-file

dbdicom-0.3.1/README.rst

@@ -0,0 +1,71 @@
+dbdicom
+=======
+
+.. image:: https://img.shields.io/badge/License-Apache_2.0-blue.svg
+  :target: https://opensource.org/licenses/Apache-2.0
+
+
+A python interface for reading and writing DICOM databases
+----------------------------------------------------------
+
+- **Documentation:** https://openmiblab.github.io/dbdicom/
+- **Source code:** https://github.com/openmiblab/dbdicom
+
+
+Installation
+------------
+
+.. code-block:: console
+
+    pip install dbdicom
+
+
+Aim
+---
+
+Simplify import and export of medical imaging data in DICOM format, 
+increase the transparancy of post-processing pipelines for medical 
+imaging biomarkers and improving standardization by avoiding the 
+need for multiple data formats.
+
+Status
+------
+
+`dbdicom` version 0.2 (lates 0.2.6) is stable and has been rolled 
+out in image processing pipelines of ongoing studies 
+`iBEAt <https://bmcnephrol.biomedcentral.com/articles/10.1186/s12882-020-01901-x>`_
+and
+`AFiRM <ttps://www.uhdb.nhs.uk/afirm-study/>`_,
+but is no longer supported and will be phased out.
+
+Version 0.3 is a major rewrite based on these experiences aiming to 
+simplify the code base and the API, and improve efficiency and 
+coverage of DICOM SOP classes. Version 0.3 is currently *work in 
+progress* and changes are not backwards compatible with version 0.2.
+
+The API reference shows version 0.3 functionality but the user guide 
+is for version 0.2. Updates are expected shortly.
+
+Citing
+------
+
+When you use ``dbdicom``, please cite: 
+
+Steven Sourbron, Joao Almeida e Sousa, Alexander Daniel, 
+Charlotte Buchanan, Ebony Gunwhy, Eve Lennie, Kevin Teh, 
+Steve Shillitoe, David Morris, Andrew Priest, David Thomas, and 
+Susan Francis. dbdicom: an open-source python interface for reading 
+and writing DICOM databases. `Proc Intl Soc Mag Reson Med 
+(Toronto, Canada) <https://www.ismrm.org/23m/>`_, #3248, 2023.
+
+
+License
+-------
+
+``dbdicom`` is distributed under the 
+`Apache 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_ license - a 
+permissive, free license that allows users to use, modify, and 
+distribute the software without restrictions::
+
+  Copyright (C) 2023-2025 dbdicom developers
+

dbdicom-0.3.1/pyproject.toml

@@ -0,0 +1,65 @@
+# https://python-poetry.org/docs/pyproject
+# minimal required information
+
+[build-system]
+build-backend = 'setuptools.build_meta'
+requires = ['setuptools>=61.2']
+
+[project]
+name = "dbdicom"
+version = "0.3.1"
+dependencies = [ 
+    "tqdm",
+    "importlib-resources",
+    "numpy",
+    "pandas", # make obsolete
+    'vreg', 
+    "pydicom", 
+    "python-gdcm",
+    "pylibjpeg-libjpeg",
+]
+
+# optional information
+
+description = "A pythonic interface for reading and writing DICOM databases"
+readme = "README.md"
+authors = [
+  { name = "Steven Sourbron", email = "s.sourbron@sheffield.ac.uk" },
+  { name = "Ebony Gunwhy", email = "e.gunwhy@sheffield.ac.uk" }, 
+  ]
+#license = "Apache-2.0"
+classifiers = [
+  # How mature is this project? Common values are
+  #   3 - Alpha
+  #   4 - Beta
+  #   5 - Production/Stable
+  'Development Status :: 3 - Alpha',
+
+  # Indicate who your project is intended for
+  'Intended Audience :: Developers',
+  'Intended Audience :: Science/Research',
+  'Topic :: Scientific/Engineering',
+  'Environment :: Console',
+  'Operating System :: OS Independent',
+
+  'License :: OSI Approved :: Apache Software License',
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3"
+]
+keywords = ['python', "medical imaging", "DICOM"]
+
+requires-python = ">=3.6"
+
+[project.urls]
+"Homepage" = "https://openmiblab.github.io/dbdicom/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+
+
+
+
+
+
+

dbdicom-0.3.1/src/dbdicom/__init__.py

@@ -0,0 +1 @@
+from dbdicom.api import *

dbdicom-0.3.1/src/dbdicom/api.py

@@ -0,0 +1,287 @@
+
+import numpy as np
+import vreg
+
+from dbdicom.dbd import DataBaseDicom
+
+
+def open(path:str) -> DataBaseDicom:
+    """Open a DICOM database
+
+    Args:
+        path (str): path to the DICOM folder
+
+    Returns:
+        DataBaseDicom: database instance.
+    """
+    return DataBaseDicom(path)
+
+def print(path):
+    """Print the contents of the DICOM folder
+
+    Args:
+        path (str): path to the DICOM folder
+    """
+    dbd = open(path)
+    dbd.print()
+    dbd.close()
+
+
+def summary(path) -> dict:
+    """Return a summary of the contents of the database.
+
+    Args:
+        path (str): path to the DICOM folder
+
+    Returns:
+        dict: Nested dictionary with summary information on the database.
+    """
+    dbd = open(path)
+    s = dbd.summary()
+    dbd.close()
+    return s
+
+
+def patients(path, name:str=None, contains:str=None, isin:list=None)->list:
+    """Return a list of patients in the DICOM folder.
+
+    Args:
+        path (str): path to the DICOM folder
+        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: list of patients fulfilling the criteria.
+    """
+    dbd = open(path)
+    p = dbd.patients(name, contains, isin)
+    dbd.close()
+    return p
+
+
+def studies(entity:str | list, name: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 
+            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: list of studies fulfilling the criteria.
+    """
+    if isinstance(entity, str): # path = folder
+        dbd = open(entity)
+        s = dbd.studies(entity, name, contains, isin)
+        dbd.close()
+        return s
+    elif len(entity)==2: # path = patient
+        dbd = open(entity[0])
+        s = dbd.studies(entity, name, contains, isin)
+        dbd.close()
+        return s
+    else:
+        raise ValueError(
+            "The path must be a folder or a 2-element list "
+            "with a folder and a patient name."
+        )
+
+def series(entity:str | list, name:str=None, contains:str=None, isin:list=None)->list:
+    """Return a list of series in the DICOM folder.
+
+    Args:
+        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).
+        name (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: list of series fulfilling the criteria.
+    """
+    if isinstance(entity, str): # path = folder
+        dbd = open(entity)
+        s = dbd.series(entity, name, contains, isin)
+        dbd.close()
+        return s
+    elif len(entity) in [2,3]:
+        dbd = open(entity[0])
+        s = dbd.series(entity, name, contains, isin)
+        dbd.close()
+        return s
+    else:
+        raise ValueError(
+            "To retrieve a series, the entity must be a database, patient or study."
+        )
+    
+def copy(from_entity:list, to_entity:list):
+    """Copy a DICOM entity (patient, study or series)
+
+    Args:
+        from_entity (list): entity to copy
+        to_entity (list): entity after copying.
+    """
+    dbd = open(from_entity[0])
+    dbd.copy(from_entity, to_entity)
+    dbd.close()
+
+
+def delete(entity:list):
+    """Delete a DICOM entity
+
+    Args:
+        entity (list): entity to delete
+    """
+    dbd = open(entity[0])
+    dbd.delete(entity)
+    dbd.close()
+
+
+def move(from_entity:list, to_entity:list):
+    """Move a DICOM entity
+
+    Args:
+        entity (list): entity to move
+    """
+    dbd = open(from_entity[0])
+    dbd.copy(from_entity, to_entity)
+    dbd.delete(from_entity)
+    dbd.close()
+
+
+def volume(series:list, dims:list=None, multislice=False) -> vreg.Volume3D:
+    """Read a vreg.Volume3D from a DICOM series
+
+    Args:
+        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.
+
+    Returns:
+        vreg.Volume3D: vole read from the series.
+    """
+    dbd = open(series[0])
+    vol = dbd.volume(series, dims, multislice)
+    dbd.close()
+    return vol
+
+def write_volume(vol:vreg.Volume3D, series:list, ref:list=None, 
+                 multislice=False):
+    """Write a vreg.Volume3D to a DICOM series
+
+    Args:
+        vol (vreg.Volume3D): 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.close()
+
+def to_nifti(series:list, file:str, dims:list=None, multislice=False):
+    """Save a DICOM series in nifti format.
+
+    Args:
+        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.
+        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.close()
+
+def from_nifti(file:str, series:list, ref:list=None, multislice=False):
+    """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.close()
+
+def pixel_data(series:list, dims:list=None, include:list=None) -> tuple:
+    """Read the pixel data from a DICOM series
+
+    Args:
+        series (list): DICOM series to read
+        dims (list, optional): Dimensions of the array.
+        include (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.
+    """
+    dbd = open(series[0])
+    array = dbd.pixel_data(series, dims, include)
+    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
+
+    Args:
+        pars (list): attributes to return.
+        entity (list): DICOM entity to search (Patient, Study or Series)
+
+    Returns:
+        dict: dictionary with unique values for each attribute.
+    """
+    dbd = open(entity[0])
+    u = dbd.unique(pars, entity)
+    dbd.close()
+    return u
+
+
+
+
+
+
+if __name__=='__main__':
+
+    pass

dbdicom-0.3.1/src/dbdicom/const.py

@@ -0,0 +1,144 @@
+
+
+PATIENT_MODULE = [
+    'ReferencedPatientSequence',
+    'PatientName',
+    'PatientID',
+    'IssuerOfPatientID',
+    'TypeOfPatientID',
+    'IssuerOfPatientIDQualifiersSequence',
+    'SourcePatientGroupIdentificationSequence',
+    'GroupOfPatientsIdentificationSequence',
+    'PatientBirthDate',
+    'PatientBirthTime',
+    'PatientBirthDateInAlternativeCalendar',
+    'PatientDeathDateInAlternativeCalendar',
+    'PatientAlternativeCalendar',
+    'PatientSex',
+    'QualityControlSubject',
+    'StrainDescription',
+    'StrainNomenclature',
+    'StrainStockSequence',
+    'StrainAdditionalInformation',
+    'StrainCodeSequence',
+    'GeneticModificationsSequence',
+    'OtherPatientNames',
+    'OtherPatientIDsSequence',
+    'ReferencedPatientPhotoSequence',
+    'EthnicGroup',
+    'PatientSpeciesDescription',
+    'PatientSpeciesCodeSequence',
+    'PatientBreedDescription',
+    'PatientBreedCodeSequence',
+    'BreedRegistrationSequence',
+    'ResponsiblePerson',
+    'ResponsiblePersonRole',
+    'ResponsibleOrganization',
+    'PatientComments',
+    'PatientIdentityRemoved',
+    'DeidentificationMethod',
+    'DeidentificationMethodCodeSequence',
+    'ClinicalTrialSponsorName',
+    'ClinicalTrialProtocolID',
+    'ClinicalTrialProtocolName',
+    'ClinicalTrialSiteID',
+    'ClinicalTrialSiteName',
+    'ClinicalTrialSubjectID',
+    'ClinicalTrialSubjectReadingID',
+    'ClinicalTrialProtocolEthicsCommitteeName',
+    'ClinicalTrialProtocolEthicsCommitteeApprovalNumber',
+]
+
+
+
+STUDY_MODULE = [
+    'StudyDate',
+    'StudyTime',
+    'AccessionNumber',
+    'IssuerOfAccessionNumberSequence',
+    'ReferringPhysicianName',
+    'ReferringPhysicianIdentificationSequence',
+    'ConsultingPhysicianName',
+    'ConsultingPhysicianIdentificationSequence',
+    'StudyDescription',
+    'ProcedureCodeSequence',
+    'PhysiciansOfRecord',
+    'PhysiciansOfRecordIdentificationSequence',
+    'NameOfPhysiciansReadingStudy',
+    'PhysiciansReadingStudyIdentificationSequence',
+    'ReferencedStudySequence',
+    'StudyInstanceUID',
+    'StudyID',
+    'RequestingService',
+    'RequestingServiceCodeSequence',
+    'ReasonForPerformedProcedureCodeSequence',
+    'AdmittingDiagnosesDescription',
+    'AdmittingDiagnosesCodeSequence',
+    'PatientAge',
+    'PatientSize',
+    'PatientSizeCodeSequence',
+    'PatientBodyMassIndex',
+    'MeasuredAPDimension',
+    'MeasuredLateralDimension',
+    'PatientWeight',
+    'MedicalAlerts',
+    'Allergies',
+    'Occupation',
+    'SmokingStatus',
+    'AdditionalPatientHistory',
+    'PregnancyStatus',
+    'LastMenstrualDate',
+    'PatientSexNeutered',
+    'ReasonForVisit',
+    'ReasonForVisitCodeSequence',
+    'AdmissionID',
+    'IssuerOfAdmissionIDSequence',
+    'ServiceEpisodeID',
+    'ServiceEpisodeDescription',
+    'IssuerOfServiceEpisodeIDSequence',
+    'PatientState',
+    'ClinicalTrialTimePointID',
+    'ClinicalTrialTimePointDescription',
+    'LongitudinalTemporalOffsetFromEvent',
+    'LongitudinalTemporalEventType',
+    'ConsentForClinicalTrialUseSequence',
+]   
+
+
+
+SERIES_MODULE = [
+    'SeriesDate',
+    'SeriesTime',
+    'Modality',
+    'SeriesDescription',
+    'SeriesDescriptionCodeSequence',
+    'PerformingPhysicianName',
+    'PerformingPhysicianIdentificationSequence',
+    'OperatorsName',
+    'OperatorIdentificationSequence',
+    'ReferencedPerformedProcedureStepSequence',
+    'RelatedSeriesSequence',
+    'AnatomicalOrientationType',
+    'BodyPartExamined',
+    'ProtocolName',
+    'PatientPosition',
+    'ReferencedDefinedProtocolSequence',
+    'ReferencedPerformedProtocolSequence',
+    'SeriesInstanceUID',
+    'SeriesNumber',
+    'Laterality',
+    'SmallestPixelValueInSeries',
+    'LargestPixelValueInSeries',
+    'PerformedProcedureStepStartDate',
+    'PerformedProcedureStepStartTime',
+    'PerformedProcedureStepEndDate',
+    'PerformedProcedureStepEndTime',
+    'PerformedProcedureStepID',
+    'PerformedProcedureStepDescription',
+    'PerformedProtocolCodeSequence',
+    'RequestAttributesSequence',
+    'CommentsOnThePerformedProcedureStep',
+    'ClinicalTrialCoordinatingCenterName',
+    'ClinicalTrialSeriesID',
+    'ClinicalTrialSeriesDescription',
+]