Skip to content

Read tags

read_tags #

DICOM Sorting Utilities.

This module provides utilities for truncating UIDs, and reading specific tags from DICOM files.

Functions:

Name Description
read_tags

Read specified tags from a DICOM file.

Examples:

Read tags from a DICOM file: >>> from pathlib import ( ... Path, ... ) >>> tags = [ ... "PatientID", ... "StudyInstanceUID", ... ] >>> read_tags( ... Path("sample.dcm"), ... tags, ... )

read_tags #

read_tags(
    file: pathlib.Path,
    tags: typing.List[str],
    truncate: int = 5,
    default: typing.Optional[str] = "",
    force: bool = False,
) -> typing.Dict[str, str]

Read the specified tags from a DICOM file.

Reads a set of tags from a DICOM file and applies optional sanitization and truncation for UIDs. Handles cases where specific tags may be missing.

Parameters:

Name Type Description Default

file #

 pathlib.Path

Path to the DICOM file.

 required

tags #

 list of str

List of DICOM tags to read.

 required

truncate #

 int

Number of characters to keep at the end of UIDs (default is 5). 0 or negative values will keep the entire UID.

 5

default #

 str

Default value to use for missing tags (default is "").

 ''

force #

 bool

If True, force reading the file even if it is not a valid DICOM file (default is False).

 False

Returns:

Type Description
dict of str : str

A dictionary mapping tags to their values.
Notes

For RTSTRUCT files, missing 'InstanceNumber' tags default to '1'.

Examples:

Read tags from a valid DICOM file with truncation:

>>> from pathlib import (
...     Path,
... )
>>> read_tags(
...     Path("sample.dcm"),
...     [
...         "PatientID",
...         "StudyInstanceUID",
...     ],
... )
{'PatientID': '12345', 'StudyInstanceUID': '1.2.3.4.5'}

Read tags without truncating UIDs:

>>> read_tags(
...     Path("sample.dcm"),
...     [
...         "PatientID",
...         "StudyInstanceUID",
...     ],
...     truncate=False,
... )
{'PatientID': '12345', 'StudyInstanceUID': '1.2.840.10008.1.2.1'}

Handle missing tags:

>>> read_tags(
...     Path("sample.dcm"),
...     ["NonexistentTag"],
... )
[warn] No value for tag: NonexistentTag in file: sample.dcm
{'NonexistentTag': 'UNKNOWN'}
Source code in src/imgtools/dicom/read_tags.py 
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
def read_tags(
    file: Path,
    tags: List[str],
    truncate: int = 5,
    default: Optional[str] = "",
    force: bool = False,
) -> Dict[str, str]:
    """
    Read the specified tags from a DICOM file.

    Reads a set of tags from a DICOM file and applies optional sanitization
    and truncation for UIDs. Handles cases where specific tags may be missing.

    Parameters
    ----------
    file : Path
        Path to the DICOM file.
    tags : list of str
        List of DICOM tags to read.
    truncate : int, optional
        Number of characters to keep at the end of UIDs (default is 5).
        0 or negative values will keep the entire UID.
    default : str, optional
        Default value to use for missing tags (default is "").
    force : bool, optional
        If True, force reading the file even if it is not a valid DICOM file
        (default is False).

    Returns
    -------
    dict of str : str
        A dictionary mapping tags to their values.

    Raises
    ------
    TypeError
        If there is a type error while reading the DICOM file.
    InvalidDicomError
        If the file is not a valid DICOM file.
    ValueError
        If there is a value error while reading the file.

    Notes
    -----
    For RTSTRUCT files, missing 'InstanceNumber' tags default to '1'.

    Examples
    --------
    Read tags from a valid DICOM file with truncation:
    >>> from pathlib import (
    ...     Path,
    ... )
    >>> read_tags(
    ...     Path("sample.dcm"),
    ...     [
    ...         "PatientID",
    ...         "StudyInstanceUID",
    ...     ],
    ... )
    {'PatientID': '12345', 'StudyInstanceUID': '1.2.3.4.5'}

    Read tags without truncating UIDs:
    >>> read_tags(
    ...     Path("sample.dcm"),
    ...     [
    ...         "PatientID",
    ...         "StudyInstanceUID",
    ...     ],
    ...     truncate=False,
    ... )
    {'PatientID': '12345', 'StudyInstanceUID': '1.2.840.10008.1.2.1'}

    Handle missing tags:
    >>> read_tags(
    ...     Path("sample.dcm"),
    ...     ["NonexistentTag"],
    ... )
    [warn] No value for tag: NonexistentTag in file: sample.dcm
    {'NonexistentTag': 'UNKNOWN'}
    """
    assert isinstance(file, Path)
    assert (
        isinstance(tags, list)
        and all(isinstance(tag, str) for tag in tags)
        and tags is not None
    )

    dicom = load_dicom(
        file, force=force, stop_before_pixels=True, specific_tags=tags
    )

    result = {}

    for tag in tags:
        value = str(dicom.get(tag, default=default))

        if tag.endswith("UID") and truncate > 0:
            value = truncate_uid(value, last_digits=truncate)

        result[tag] = value
    return result