dicom_parser package¶
Subpackages¶
- dicom_parser.utils package
- Subpackages
- Submodules
- dicom_parser.utils.choice_enum module
- dicom_parser.utils.peek module
- dicom_parser.utils.read_file module
- dicom_parser.utils.value_representation module
- Module contents
Submodules¶
dicom_parser.header module¶
Definition of the Header class, which extends the functionality of pydicom.
-
class
dicom_parser.header.
Header
(raw, parser=<class 'dicom_parser.parser.Parser'>, sequence_detector=<class 'dicom_parser.utils.sequence_detector.sequence_detector.SequenceDetector'>)¶ Bases:
object
Facilitates access to DICOM header information from pydicom’s FileDataset.
-
detect_sequence
() → str¶ Returns the detected imaging sequence using the modality’s sequence identifying header information.
- Returns
Imaging sequence name
- Return type
-
get
(tag_or_keyword, default=None, parsed: bool = True, missing_ok: bool = True)¶ Returns the value of a pydicom data element, selected by tag (tuple) or keyword (str). Input may also be a list of such identifiers, in which case a dictionary will be returned with the identifiers as keys and header information as values.
- Parameters
- Returns
The requested data element value (or a dict for multiple values)
- Return type
-
get_element
(tag_or_keyword) → pydicom.dataelem.DataElement¶ Returns a pydicom DataElement from the associated FileDataset either by tag (passed as a tuple) or a keyword (passed as a string). If none found or the tag or keyword are invalid, returns None.
-
get_element_by_keyword
(keyword: str) → pydicom.dataelem.DataElement¶ Returns a pydicom DataElement from the header (FileDataset isntance) by keyword.
- Parameters
keyword (str) – The keyword representing the DICOM data element in pydicom
- Returns
The requested data element
- Return type
DataElement
-
get_element_by_tag
(tag: tuple) → pydicom.dataelem.DataElement¶ Returns a pydicom DataElement from the header (FileDataset isntance) by tag.
- Parameters
tag (tuple) – The DICOM tag of the desired data element
- Returns
The requested data element
- Return type
DataElement
-
get_parsed_value
(tag_or_keyword)¶ Returns the parsed value of pydicom data element using the this class’s parser attribute. The data element may be represented by tag or by its pydicom keyword. If none is found will return None.
-
get_private_tag
(keyword: str) → tuple¶ Returns a vendor-specific private tag corresponding to the provided keyword, if the tag is registered (see the
private_tags
module). This is required because pydicom does not offer keyword access to private tags.
-
get_raw_value
(tag_or_keyword)¶ Returns the raw value for the requested data element, as returned by pydicom. If none is found will return None.
-
sequence_identifiers
= {'Magnetic Resonance': ['ScanningSequence', 'SequenceVariant']}¶
-
dicom_parser.image module¶
Definition of the Image class, representing a single pair of
Header
and data (3D NumPy array).
-
class
dicom_parser.image.
Image
(raw, parser=<class 'dicom_parser.parser.Parser'>)¶ Bases:
object
This class represents a single DICOM image (i.e. .dcm file) and provides unified access to it’s header information and data.
-
property
data
¶ Returns the pixel data array after having applied any required transformations.
- Returns
Pixel data array.
- Return type
np.ndarray
-
fix_data
() → numpy.ndarray¶ Applies any required transformation to the data.
- Returns
Pixel array data
- Return type
np.ndarray
-
property
is_fmri
¶ Returns True for fMRI images according to their header information.
- Returns
Whether this image represents fMRI data.
- Return type
-
property
is_mosaic
¶ Checks whether a 3D volume is encoded as a 2D Mosaic. For more information, see the
Mosaic
class.- Returns
Whether the image is a mosaic encoded volume
- Return type
-
read_raw_data
() → numpy.ndarray¶ Reads the pixel array data as returned by pydicom.
- Returns
Pixel array data
- Return type
np.ndarray
-
property
dicom_parser.parser module¶
Definition of the Parser
class, used to parse
the raw DataElement
values into “pythonic” types.
-
class
dicom_parser.parser.
Parser
(verbose_code_strings: bool = True)¶ Bases:
object
A default parser to be used by the
Header
class. This class can easily be replaced with custom parser classes, as long as they expose the expectedparse()
method.-
CODE_STRINGS_DICT
= {'(0008, 0060)': <enum 'Modality'>, '(0010, 0040)': <enum 'Sex'>, '(0018, 0020)': <enum 'ScanningSequence'>, '(0018, 0021)': <enum 'SequenceVariant'>, '(0018, 5100)': <enum 'PatientPosition'>}¶
-
N_IN_YEAR
= {'D': 365.2422, 'M': 12, 'W': 52.1429, 'Y': 1}¶
-
PARSING_METHOD
= {<ValueRepresentation.AGE_STRING: 'AS'>: 'parse_age_string', <ValueRepresentation.DATE: 'DA'>: 'parse_date', <ValueRepresentation.TIME: 'TM'>: 'parse_time', <ValueRepresentation.DATE_TIME: 'DT'>: 'parse_datetime', <ValueRepresentation.INTEGER_STRING: 'IS'>: 'parse_integer_string', <ValueRepresentation.DECIMAL_STRING: 'DS'>: 'parse_decimal_string', <ValueRepresentation.UNKNOWN: 'UN'>: 'parse_unknown', <ValueRepresentation.CODE_STRING: 'CS'>: 'parse_code_string'}¶
-
SINGLE_VALUE_CODE_STRINGS
= ('(0010, 0040)', '(0018, 5100)', '(0008, 0060)')¶
-
call_parsing_method
(element: pydicom.dataelem.DataElement, value_representation: dicom_parser.utils.value_representation.ValueRepresentation)¶ Calls the appropriate parsing method for the
DataElement
based on the providedValueRepresentation
.- Parameters
element (
DataElement
) – DICOM data elementvalue_representation (
ValueRepresentation
) – Data element’s value representation
- Returns
Parsed value
- Return type
[type]
-
get_code_string_representation
(name: str, enum: enum.Enum) → str¶ Returns a Code String (CS) data element value’s according to the class’s verbose_code_strings attribute value. If True, returns the corresponding Enum’s value. Otherwise, simply returns the name itself (raw value).
-
get_value_representation
(element: pydicom.dataelem.DataElement) → dicom_parser.utils.value_representation.ValueRepresentation¶ Gets the given
DataElement
’sValueRepresentation
.- Parameters
element (
DataElement
) – DICOM data element- Returns
Corresponding data representation enum
- Return type
- Raises
NotImplementedError – Unknown value represenation
-
parse
(element: pydicom.dataelem.DataElement)¶ Tries to parse a pydicom DICOM data element using its value-representation (VR) attribute. If no parser method is registered for the VR under the PARSING_METHOD dictionary, will simply return the raw value.
- Parameters
element (DataElement) – DICOM data element as represented by pydicom.
- Returns
Parsed DICOM data element value.
- Return type
-
parse_age_string
(element: pydicom.dataelem.DataElement) → float¶ Parses Age String (AS) data elements into a float representation of the age in years.
- Parameters
element (
DataElement
) – DICOM Age String (AS) data element.- Returns
The age in years.
- Return type
-
parse_code_string
(element: pydicom.dataelem.DataElement)¶ Parses Code String (CS) data elements to a more readable string or set of strings. This method relies on an Enum representation of the data element’s possible values to be registered in the Parser’s CODE_STRINGS_DICT by tag. If no Enum is registered, will return try to parse out a value or a set of values.
- Parameters
element (
DataElement
) – DICOM Code String (CS) data element.- Returns
Parsed value/s.
- Return type
-
parse_code_string_with_enum
(element: pydicom.dataelem.DataElement, enum: enum.Enum)¶ Parses a Code String (CS) data element using
- Parameters
element (
DataElement
) – Code String (CS) data elementenum (enum.Enum) – An Enum representing the element’s valid values
- Returns
Parsed value/s.
- Return type
-
parse_code_string_without_enum
(element: pydicom.dataelem.DataElement)¶ Parses a Code String (CS) data element without an Enum representing its valid values. Strings representing arrays are parsed out as sets.
- Parameters
element (
DataElement
) – DICOM Code String (CS) data element.- Returns
Parsed value/s.
- Return type
-
parse_date
(element: pydicom.dataelem.DataElement) → None.datetime.date¶ Parses Date (DA) data elements to date objects.
- Parameters
element (
DataElement
) – DICOM Date (DA) data element.- Returns
Native python date object.
- Return type
-
parse_decimal_string
(element: pydicom.dataelem.DataElement)¶ Parses Decimal String (DS) data elements to floats. In case the Value Multiplicity (VM) is greater than one, returns a list of floats.
- Parameters
element (
DataElement
) – DICOM Decimal String (DS) data element.- Returns
Data element value/s.
- Return type
-
parse_integer_string
(element: pydicom.dataelem.DataElement) → int¶ Parses DICOM Integer String (IS) data elements to integers.
- Parameters
element (
DataElement
) – DICOM Integer String (IS) data element.- Returns
Data element value.
- Return type
-
parse_multiple_code_string_with_enum
(element: pydicom.dataelem.DataElement, enum: enum.Enum) → set¶ Parses a
pydicom.multival.MultiValue
data element value to set of valid representations.- Parameters
element (
DataElement
) – Code String (CS) data elementenum (enum.Enum) – An Enum representing the element’s valid values
- Returns
Parsed values
- Return type
-
parse_siemens_gradient_direction
(value: bytes) → list¶ Parses a SIEMENS MR image’s B-vector as represented in the private (0019, 100E) DiffusionGradientDirection DICOM tag.
-
parse_siemens_slice_timing
(value: bytes) → list¶ Parses a SIEMENS MR image’s slice timing as saved in the private (0019, 1029) MosaicRefAcqTimes tag to a list of floats representing slice times in milliseconds.
-
parse_single_code_string_with_enum
(element: pydicom.dataelem.DataElement, enum: enum.Enum)¶ Parses a Code String (CS) data element with a value-multiplicity (VM) of 1. The parsed value is returned as a
set
unless it the element is listed in theSINGLE_VALUE_CODE_STRINGS
attribute, in which case it is returned as astr
.- Parameters
element (
DataElement
) – Code String (CS) data elementenum (enum.Enum) – An Enum representing the element’s valid values
- Returns
Parsed value
- Return type
-
parse_time
(element: pydicom.dataelem.DataElement) → None.datetime.time¶ Parses Time (TM) data elements to time objects.
- Parameters
element (
DataElement
) – DICOM Time (TM) data element.- Returns
Native python time object.
- Return type
-
parse_unknown
(element: pydicom.dataelem.DataElement)¶ Parses private tags and other Unknown (UN) data elememts.
- Parameters
element (
DataElement
) – DICOM Unknown (UN) data element.
-
dicom_parser.series module¶
Definition of the Series class, representing a collection of Image instances ordered by the header’s InstanceNumber data element.
-
class
dicom_parser.series.
Series
(path: pathlib.Path)¶ Bases:
object
This class represents a complete collection of Image instances originating from a single directory and ordered by InstanceNumber.
-
check_path
(path) → pathlib.Path¶ Converts to a
Path
instance if required and checks that it represents an existing directory.- Parameters
path (str or Path) – The provided path.
- Returns
A pathlib.Path instance representing an existing directory.
- Return type
Path
- Raises
ValueError – If the provided path is not an existing directory.
-
property
data
¶ Caches the stacked 3D array containing the entire series’ data.
- Returns
Series 3D data.
- Return type
np.ndarray
-
get
(tag_or_keyword, default=None, parsed: bool = True, missing_ok: bool = True)¶ Returns header information from the
Image
that compose this series. If one distinct value is returned from all the images’ headers, returns that value. Otherwise, returns a list of the values (ordered the same as the images attribute, by instance number).
-
get_dcm_paths
() → generator¶ Returns a generator of .dcm files within the provided directory path.
- Returns
DICOM images (.dcm files) generator.
- Return type
GeneratorType
- Raises
FileNotFoundError – No DICOM images found under provided directory.
-