Package: dicom-parser
dicom_parserDocumentationCodeTestingPackagingUsagedicom_parseris a utility python package meant to facilitate access toDICOMheader information by extending the
functionality ofpydicom.Essentially,dicom_parseruses DICOM'sdata-elementvalue-representation (VR),
as well as prior knowledge on vendor-specific private tags or encoding schemes,
in order to transform them to more "pythonic" data structures when possible.InstallationQuickstartDocumentationTestsFor more information, please seethe documentation site.InstallationTo install the latest stable release ofdicom_parser, simply run:pipinstalldicom_parserOr, to install the latest development version:pipinstallhttps://github.com/open-dicom/dicom_parser/archive/main.zipQuickstartThe most basic usage case is reading a single DICOM image (.dcmfile) as
anImageinstance.>>>fromdicom_parserimportImage>>>image=Image('/path/to/dicom/file.dcm')Coversion to Python's native typesdicom_parserprovidesdict-like access to the parsed values of theheader's
data-elements. The raw values as read bypydicomremain accessible
through therawattribute.ExamplesDecimal String (DS) tofloatusing theHeaderclass'sgetmethod:>>>raw_value=image.header.raw['ImagingFrequency'].value>>>raw_value"123.25993">>>type(raw_value)str>>>parsed_value=image.header.get('ImagingFrequency')>>>parsed_value123.25993>>>type(parsed_value)floatAge String (AS) tofloat:>>>raw_value=image.header.raw['PatientAge'].value>>>raw_value"027Y">>>type(raw_value)str>>>parsed_value=image.header.get('PatientAge')>>>parsed_value27.0>>>type(parsed_value)floatDate String (DA) todatetime.dateusing theHeaderclass's indexing operator/subscript notation:>>>raw_value=image.header.raw['PatientBirthDate'].value>>>raw_value"19901214">>>type(raw_value)str>>>parsed_value=image.header['PatientBirthDate']>>>parsed_valuedatetime.date(1990,12,14)>>>type(parsed_value)datetime.dateCode String (CS) to a verbose value or set of values:>>>raw_value=image.header.raw['SequenceVariant'].value>>>raw_value['SP','OSP']>>>type(raw_value)pydicom.multival.MultiValue>>>parsed_value=image.header['SequenceVariant']>>>parsed_value{'Oversampling Phase','Spoiled'}>>>type(parsed_value)setEt cetera.Thedict-like functionality also includes safe getting:>>>image.header.get('MissingKey')None>>>image.header.get('MissingKey','DefaultValue')'DefaultValue'As well as raising a KeyError for missing keys with the indexing operator:>>>image.header['MissingKey']KeyError:"The keyword: 'MissingKey' does not exist in the header!"Read DICOM series directory as aSeriesAnother useful class this package offers is theSeriesclass:>>>fromdicom_parserimportSeries>>>series=Series('/some/dicom/series/')TheSeriesinstance allows us to easily query the underlying images' headers
using itsgetmethod:# Single value>>>series.get('EchoTime')3.04# Multiple values>>>series.get('InstanceNumber')[1,2,3]# No value>>>series.get('MissingKey')None# Default value>>>series.get('MissingKey','default_value')'default_value'Similarly to theImageclass, we can also use the indexing operator:# Single value>>>series['RepetitionTime']7.6# Multiple values>>>series['SOPInstanceUID']["1.123.1241.123124124.12.1","1.123.1241.123124124.12.2","1.123.1241.123124124.12.3"]# No value>>>series['MissingKey']KeyError:"The keyword: 'MissingKey' does not exist in the header!"Another useful feature of the indexing operator is for querying anImageinstance based on its index in the series:>>>series[6]dicom_parser.image.Image>>>series[6].header['InstanceNumber]7# InstanceNumber is 1-indexedThedataproperty returns a stacked volume of the images' data:>>>type(series.data)numpy.ndarray>>>series.data.shape(224,224,208)Siemens 4D dataReading Siemens 4D dataencoded as mosaicsis also supported:>>>fmri_series=Series('/path/to/dicom/fmri/')>>>fmri_series.data.shape(96,96,64,200)DocumentationDependenciesThedocumentation siteis built usingSphinx, to build the HTML pages locally, make sure you
have the required dependencies by using thedocsmodifier for
the installation. Assuming you have cloned the repository and
created a virtual environment, run:pipinstall-e.[docs]from within your cloned project's root.BuildBuild the site by running:makehtmlfrom within the<root>/docs/directory.The generated HTML will be found under<root>/docs/_build/html. Openindex.htmlin your browser to view the site.TestsDependenciesTests are executed usingpytestandtox, and coverage is measured using
thecoveragepackage. Make sure you have the required dependencies by
using thetestmodifier for the installation. Assuming you have cloned the
repository and created a virtual environment, run:pipinstall-e.[test]from within your cloned project's root.ExecutionpytestTo run the tests within your virtual environment, run:pytestteststoxTo run the tests in a number of dedicated virtual environments, simply execute
thetoxcommand from within the project's root directory. This will test all
supported Python versions, and therefore will only be successful in an
environment in which all supported Python versions are installed.Usetox -pto run the tests in parallel, andtox -e py3?,py3?to run a
subset of environments (replace?with the desired version number).CoverageTo check code coverage usingcoverage, simply run:coveragerun&&coveragehtmlOpen<root>/htmlcov/index.htmlin the browser to view the report.