Skip to content

DICOM Modality-Specific Metadata Extraction#

extract_metadata #

extract_metadata(
    dicom: imgtools.dicom.DicomInput,
    modality: str | None = None,
    extra_tags: list[str] | None = None,
) -> dict[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedValue,
]

Extract metadata from a DICOM file based on its modality.

Parameters:

Name Type Description Default

dicom #

 imgtools.dicom.DicomInput

DICOM input source (path, bytes, or pydicom Dataset)

 required

modality #

 str | None

Explicitly specify the modality to use, by default None. If None, the modality is extracted from the DICOM file.

 None

extra_tags #

 list[str] | None

Additional DICOM tags to extract, by default None. If None, no extra tags are extracted.

 None

Returns:

Type Description
dict[str, imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]

Dictionary of metadata fields with their values extracted from the DICOM.
Notes

Be aware that using extra_tags may lead to unexpected results if the extra tags are not compatible with the modality or if they are not present in the DICOM file. The extractor will not validate the extra tags against the modality, so it's the user's responsibility to ensure that the extra tags are relevant and valid for the given DICOM file.

Source code in src/imgtools/dicom/dicom_metadata/__init__.py 
29
30
31
32
33
34
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
def extract_metadata(
    dicom: DicomInput,
    modality: str | None = None,
    extra_tags: list[str] | None = None,
) -> dict[str, ComputedValue]:
    """
    Extract metadata from a DICOM file based on its modality.

    Parameters
    ----------
    dicom : DicomInput
        DICOM input source (path, bytes, or pydicom Dataset)
    modality : str | None, optional
        Explicitly specify the modality to use, by default None.
        If None, the modality is extracted from the DICOM file.
    extra_tags : list[str] | None, optional
        Additional DICOM tags to extract, by default None.
        If None, no extra tags are extracted.

    Returns
    -------
    dict[str, ComputedValue]
        Dictionary of metadata fields with their values extracted from the DICOM.

    Raises
    ------
    ValueError
        If no modality can be determined.

    Notes
    -----
    Be aware that using extra_tags may lead to unexpected results if the
    extra tags are not compatible with the modality or if they are not
    present in the DICOM file. The extractor will not validate the extra tags
    against the modality, so it's the user's responsibility to ensure that
    the extra tags are relevant and valid for the given DICOM file.
    """
    ds = load_dicom(dicom)
    modality = modality or ds.get("Modality")
    if not modality:
        raise ValueError("No modality found in DICOM")

    extractor_cls = get_extractor(modality)
    return extractor_cls.extract(ds, extra_tags=extra_tags)

ModalityMetadataExtractor #

Bases: abc.ABC

Abstract base class for modality-specific DICOM metadata extractors.

This class supports both standard DICOM tag retrieval and more complex field computations based on the full DICOM dataset. Subclasses must specify the modality they support and define additional metadata fields either as DICOM tag names or as custom computation functions.

Attributes:

Name Type Description
base_tags typing.ClassVar[set[str]]

Standard DICOM tags to always extract, regardless of modality.
modality_tags typing.ClassVar[set[str]]

Tags specific to the subclass's modality. These are merged with base_tags to form the list of tags to retrieve directly from the dataset.
computed_fields typing.ClassVar[collections.abc.Mapping[str, imgtools.dicom.dicom_metadata.extractor_base.ComputedField]]

A mapping of metadata field names to callables that compute values from the loaded pydicom.Dataset.

Methods:

Name Description
metadata_keys

Returns a predictable, sorted list of all metadata field names produced by this extractor.
extract

Extracts metadata tags and computed fields from a DICOM dataset. Returns a dictionary mapping metadata field names to values.
Notes

Subclasses MUST implement the following abstract methods/properties: - modality() -> str: A class method that returns the DICOM modality string handled (e.g., "CT", "MR", "RTDOSE"). - modality_tags -> set[str]: A class property that defines the set of DICOM attribute names (tags) specific to the modality. - computed_fields -> Mapping[str, Callable[[pydicom.Dataset], ComputedValue]]: A class property that defines a mapping of metadata field names to callables which compute their values.

Examples:

>>> class CTExtractor(ModalityMetadataExtractor):
>>>     @classmethod
>>>     def modality(cls) -> str:
>>>         return "CT"
>>>     @classproperty
>>>     def modality_tags(cls) -> set[str]:
>>>         return {"KVP", "ReconstructionAlgorithm"}
>>>     @classproperty
>>>     def computed_fields(cls) -> Mapping[str, ComputedField]:
>>>         return {
>>>             "CustomValue": lambda ds: str(float(ds.SliceThickness) * 2),
>>>             "DoublePatientAge": lambda ds: str(ds.PatientAge * 2)
>>>         }

>>> # Using the extractor
>>> metadata = CTExtractor.extract("file.dcm")
>>> # Returns: {'PatientID': '123', 'KVP': '120', 'CustomValue': '5.0', ...}

computed_fields abstractmethod #

computed_fields() -> collections.abc.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, typing.Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
Source code in src/imgtools/dicom/dicom_metadata/extractor_base.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
@classproperty
@abstractmethod
def computed_fields(cls) -> Mapping[str, ComputedField]:  # noqa: N805
    """
    A mapping of metadata field names to callables that compute their values.

    The callable should accept a pydicom Dataset and return a value.

    Returns
    -------
    dict[str, Callable[[pydicom.Dataset], ComputedValue]]
        Mapping of field names to computation functions.
    """
    pass

extract classmethod #

extract(
    dicom: imgtools.dicom.DicomInput,
    extra_tags: list[str] | None = None,
) -> (
    imgtools.dicom.dicom_metadata.extractor_base.ExtractedFields
)

Extract metadata tags and computed fields from a DICOM dataset.

Parameters:

Name Type Description Default

dicom #

 imgtools.dicom.DicomInput

A path, byte stream, or pydicom FileDataset.

 required

extra_tags #

 list[str] | None

Additional DICOM tags to extract, by default None

 None

Returns:

Type Description
dict[str, imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]

A dictionary mapping metadata field names to values. Values may be strings, numbers, dictionaries, or lists of these types. Missing tags or errors during computation will result in an empty string.
Notes

Be aware that using extra_tags may lead to unexpected results if the extra tags are not compatible with the modality or if they are not present in the DICOM file. The extractor will not validate the extra tags against the modality, so it's the user's responsibility to ensure that the extra tags are relevant and valid for the given DICOM file.

Source code in src/imgtools/dicom/dicom_metadata/extractor_base.py 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
@classmethod
def extract(
    cls, dicom: DicomInput, extra_tags: list[str] | None = None
) -> ExtractedFields:
    """
    Extract metadata tags and computed fields from a DICOM dataset.

    Parameters
    ----------
    dicom : DicomInput
        A path, byte stream, or pydicom FileDataset.
    extra_tags : list[str] | None, optional
        Additional DICOM tags to extract, by default None

    Returns
    -------
    dict[str, ComputedValue]
        A dictionary mapping metadata field names to values.
        Values may be strings, numbers, dictionaries, or lists of these types.
        Missing tags or errors during computation will result in an empty string.

    Notes
    -----
    Be aware that using extra_tags may lead to unexpected results if the
    extra tags are not compatible with the modality or if they are not
    present in the DICOM file. The extractor will not validate the extra tags
    against the modality, so it's the user's responsibility to ensure that
    the extra tags are relevant and valid for the given DICOM file.
    """
    ds = load_dicom(dicom)
    output: ExtractedFields = {}

    # Extract base and modality-specific tags
    tags_to_extract = cls.base_tags.union(cls.modality_tags)
    if extra_tags:
        tags_to_extract = tags_to_extract.union(extra_tags)

    for tag in tags_to_extract:
        output[tag] = str(ds.get(tag, ""))

    # Compute advanced fields
    for key, fn in cls.computed_fields.items():
        try:
            # Store computed value directly without conversion to string
            output[key] = fn(ds)
        except Exception as e:
            warnmsg = (
                f"Failed to compute field '{key}' for modality '{cls.modality()}'. "
                "This may be due to missing or malformed data in the DICOM file."
            )
            warnmsg += f" Error: {e}"
            logger.warning(warnmsg, file=str(dicom))
            output[key] = ""

    # sort all keys
    return {k: output[k] for k in sorted(output.keys())}

metadata_keys classmethod #

metadata_keys() -> list[str]

Return a predictable, sorted list of metadata field names.

This includes both direct DICOM tag names and any computed metadata keys.

Returns:

Type Description
list[str]

All metadata keys produced by this extractor.
Source code in src/imgtools/dicom/dicom_metadata/extractor_base.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
@classmethod
def metadata_keys(cls) -> list[str]:
    """
    Return a predictable, sorted list of metadata field names.

    This includes both direct DICOM tag names and any computed metadata keys.

    Returns
    -------
    list[str]
        All metadata keys produced by this extractor.
    """
    # if no modality_tags or computed_fields are defined, return base_tags
    if not cls.modality_tags and not cls.computed_fields:
        return sorted(cls.base_tags)

    all_tags = cls.base_tags.union(cls.modality_tags)
    all_keys = all_tags.union(cls.computed_fields.keys())
    return sorted(all_keys)

modality abstractmethod classmethod #

modality() -> str

The DICOM modality handled by this extractor (e.g., "CT", "MR").

Returns:

Type Description
str

Modality name.
Source code in src/imgtools/dicom/dicom_metadata/extractor_base.py 
152
153
154
155
156
157
158
159
160
161
162
163
@classmethod
@abstractmethod
def modality(cls) -> str:
    """
    The DICOM modality handled by this extractor (e.g., "CT", "MR").

    Returns
    -------
    str
        Modality name.
    """
    pass

modality_tags abstractmethod #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
Source code in src/imgtools/dicom/dicom_metadata/extractor_base.py 
165
166
167
168
169
170
171
172
173
174
175
176
@classproperty
@abstractmethod
def modality_tags(cls) -> set[str]:  # noqa: N805
    """
    A set of DICOM tags specific to the modality handled by this extractor.

    Returns
    -------
    set[str]
        Set of DICOM tag names.
    """
    pass

FallbackMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Generic fallback extractor for unsupported or uncommon DICOM modalities.

This extractor uses only the base tags defined in the superclass and defines no modality-specific tags or computed fields. It allows graceful handling of modalities not yet explicitly supported.

Methods:

Name Description
modality_tags

A set of DICOM tags specific to the modality handled by this extractor.
computed_fields

A mapping of metadata field names to callables that compute their values.

modality_tags #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
Returns an empty set since no modality-specific tags are defined.

Returns:

Type Description
set[str]

Empty set.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
37
38
39
40
41
42
43
44
45
46
47
@classproperty
def modality_tags(cls) -> set[str]:
    """
    Returns an empty set since no modality-specific tags are defined.

    Returns
    -------
    set[str]
        Empty set.
    """
    return set()

computed_fields #

computed_fields() -> typing.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
Returns an empty mapping since no computed fields are defined.

Returns:

Type Description
typing.Mapping[str, imgtools.dicom.dicom_metadata.extractor_base.ComputedField]

Empty mapping.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
49
50
51
52
53
54
55
56
57
58
59
@classproperty
def computed_fields(cls) -> Mapping[str, ComputedField]:
    """
    Returns an empty mapping since no computed fields are defined.

    Returns
    -------
    Mapping[str, ComputedField]
        Empty mapping.
    """
    return {}

CTMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Metadata extractor for CT modality DICOM datasets.

This subclass defines modality-specific tags and computed fields relevant to CT (Computed Tomography) imaging. It extends the base metadata extractor with CT-specific acquisition and reconstruction parameters.

Methods:

Name Description
modality_tags

A set of DICOM tags specific to the modality handled by this extractor.
computed_fields

A mapping of metadata field names to callables that compute their values.

modality_tags #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
CT-specific DICOM tag names.

Returns:

Type Description
set[str]

CT acquisition and reconstruction-related DICOM tags.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
 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
@classproperty
def modality_tags(cls) -> set[str]:
    """
    CT-specific DICOM tag names.

    Returns
    -------
    set[str]
        CT acquisition and reconstruction-related DICOM tags.
    """
    return {
        # Contrast & Enhancement
        "ContrastFlowDuration",
        "ContrastFlowRate",
        "ContrastBolusAgent",
        "ContrastBolusVolume",
        "ContrastBolusStartTime",
        "ContrastBolusStopTime",
        "ContrastBolusIngredient",
        "ContrastBolusIngredientConcentration",
        # X-ray Exposure & Dose
        "KVP",
        "XRayTubeCurrent",
        "ExposureTime",
        "Exposure",
        "ExposureModulationType",
        "CTDIvol",
        # Image Reconstruction & Processing
        "ReconstructionAlgorithm",
        "ReconstructionDiameter",
        "ReconstructionMethod",
        "ReconstructionTargetCenterPatient",
        "ReconstructionFieldOfView",
        "ConvolutionKernel",
        # Scan & Acquisition Parameters
        "SpiralPitchFactor",
        "SingleCollimationWidth",
        "TotalCollimationWidth",
        "TableSpeed",
        "TableMotion",
        "GantryDetectorTilt",
        "DetectorType",
        "DetectorConfiguration",
        "DataCollectionCenterPatient",
    }

computed_fields #

computed_fields() -> typing.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
CT-specific computed fields.

Returns:

Type Description
typing.Mapping[str, imgtools.dicom.dicom_metadata.extractor_base.ComputedField]

Mapping of field names to functions that compute values from DICOM datasets.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
122
123
124
125
126
127
128
129
130
131
132
@classproperty
def computed_fields(cls) -> Mapping[str, ComputedField]:
    """
    CT-specific computed fields.

    Returns
    -------
    Mapping[str, ComputedField]
        Mapping of field names to functions that compute values from DICOM datasets.
    """
    return {}

MRMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Methods:

Name Description
modality_tags

A set of DICOM tags specific to the modality handled by this extractor.
computed_fields

A mapping of metadata field names to callables that compute their values.

modality_tags #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
@classproperty
def modality_tags(cls) -> set[str]:
    return {
        # Magnetic Field & RF Properties
        "MagneticFieldStrength",
        "ImagingFrequency",
        "TransmitCoilName",
        # Sequence & Acquisition Parameters
        "SequenceName",
        "ScanningSequence",
        "SequenceVariant",
        "AcquisitionContrast",
        "AcquisitionType",
        "EchoTime",
        "RepetitionTime",
        "InversionTime",
        "EchoTrainLength",
        "NumberOfAverages",
        "FlipAngle",
        "PercentSampling",
        "PercentPhaseFieldOfView",
        "PixelBandwidth",
        "SpacingBetweenSlices",
        # Diffusion Imaging
        "DiffusionGradientDirectionSequence",
        "DiffusionBMatrixSequence",
        # Parallel Imaging & Acceleration
        "ParallelAcquisitionTechnique",
        "ParallelReductionFactorInPlane",
        "ParallelReductionFactorOutOfPlane",
        # Functional MRI (fMRI)
        "NumberOfTemporalPositions",
        "TemporalResolution",
        "FrameReferenceTime",
    }

computed_fields #

computed_fields() -> typing.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
MR-specific computed fields.

Returns:

Type Description
typing.Mapping[str, imgtools.dicom.dicom_metadata.extractor_base.ComputedField]

Mapping of field names to functions that compute values from DICOM datasets.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
177
178
179
180
181
182
183
184
185
186
187
@classproperty
def computed_fields(cls) -> Mapping[str, ComputedField]:
    """
    MR-specific computed fields.

    Returns
    -------
    Mapping[str, ComputedField]
        Mapping of field names to functions that compute values from DICOM datasets.
    """
    return {}

PTMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Methods:

Name Description
modality_tags

A set of DICOM tags specific to the modality handled by this extractor.
computed_fields

A mapping of metadata field names to callables that compute their values.

modality_tags #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
@classproperty
def modality_tags(cls) -> set[str]:
    return {
        # Radiotracer & Injection Information
        "Radiopharmaceutical",
        "RadiopharmaceuticalStartTime",
        "RadionuclideTotalDose",
        "RadionuclideHalfLife",
        "RadionuclidePositronFraction",
        "RadiopharmaceuticalVolume",
        "RadiopharmaceuticalSpecificActivity",
        "RadiopharmaceuticalStartDateTime",
        "RadiopharmaceuticalStopDateTime",
        "RadiopharmaceuticalRoute",
        "RadiopharmaceuticalCodeSequence",
        # PET Image Quantification
        "DecayCorrection",
        "DecayFactor",
        "AttenuationCorrectionMethod",
        "ScatterCorrectionMethod",
        "DecayCorrected",
        "DeadTimeCorrectionFlag",
        "ReconstructionMethod",
        # SUV (Standardized Uptake Value) Calculation
        "SUVType",
        # Acquisition Timing & Dynamics
        "FrameReferenceTime",
        "FrameTime",
        "ActualFrameDuration",
        "AcquisitionStartCondition",
        "AcquisitionTerminationCondition",
        "TimeSliceVector",
        # PET Detector & Calibration
        "DetectorType",
        "CoincidenceWindowWidth",
        "EnergyWindowLowerLimit",
        "EnergyWindowUpperLimit",
    }

computed_fields #

computed_fields() -> typing.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
PET-specific computed fields.

Returns:

Type Description
typing.Mapping[str, imgtools.dicom.dicom_metadata.extractor_base.ComputedField]

Mapping of field names to functions that compute values from DICOM datasets.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
235
236
237
238
239
240
241
242
243
244
245
@classproperty
def computed_fields(cls) -> Mapping[str, ComputedField]:
    """
    PET-specific computed fields.

    Returns
    -------
    Mapping[str, ComputedField]
        Mapping of field names to functions that compute values from DICOM datasets.
    """
    return {}

SEGMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

See Also

https://dicom.nema.org/medical/dicom/current/output/chtml/part03/sect_C.8.20.2.html

Methods:

Name Description
modality_tags

A set of DICOM tags specific to the modality handled by this extractor.
computed_fields

A mapping of metadata field names to callables that compute their values.

modality_tags #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
262
263
264
265
266
267
268
269
270
271
@classproperty
def modality_tags(cls) -> set[str]:
    return {
        # DICOM-SEG tags
        # BINARY, FRACTIONAL, or LABELMAP
        # https://dicom.nema.org/medical/dicom/current/output/chtml/part03/sect_C.8.20.2.3.html
        "SegmentationType",
        "SegmentationFractionalType",
        "MaximumFractionalValue",
    }

computed_fields #

computed_fields() -> typing.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
SEG-specific computed fields.
Each computed field is a function that takes a pydicom.Dataset as input
and returns a computed value. The functions are defined to extract
relevant information from the DICOM dataset.

Returns:

Type Description
typing.Mapping[str, imgtools.dicom.dicom_metadata.extractor_base.ComputedField]

Mapping of field names to functions that compute values from DICOM datasets.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
@classproperty
def computed_fields(cls) -> Mapping[str, ComputedField]:
    """
    SEG-specific computed fields.

    Each computed field is a function that takes a pydicom.Dataset as input
    and returns a computed value. The functions are defined to extract
    relevant information from the DICOM dataset.

    Returns
    -------
    Mapping[str, ComputedField]
        Mapping of field names to functions that compute values from DICOM datasets.
    """
    from imgtools.dicom.dicom_metadata.modality_utils.seg_utils import (
        get_seg_direction,
        get_seg_spacing,
        seg_reference_uids,
    )

    def get_seg_ref_series(seg: Dataset) -> str:
        """Get the reference series UID for the segmentation."""
        return seg_reference_uids(seg)[0]

    def get_seg_ref_sop_uids(seg: Dataset) -> list[str]:
        """Get the reference SOP instance UIDs for the segmentation."""
        return seg_reference_uids(seg)[1]

    def get_seg_segmentlabels(seg: Dataset) -> list[str]:
        """Get the segment labels from the segmentation."""
        return [
            desc.get("SegmentLabel", "")
            for desc in seg.get("SegmentSequence", [])
        ]

    def get_seg_descriptions(seg: Dataset) -> list[str]:
        """Get the segment descriptions from the segmentation."""
        return [
            desc.get("SegmentDescription", "")
            for desc in seg.get("SegmentSequence", [])
        ]

    return {
        # prefix with "Seg" to avoid collision sitk computed attrbutes
        "SegSpacing": lambda ds: get_seg_spacing(ds) or "",
        "SegDirection": lambda ds: get_seg_direction(ds) or "",
        "ROINames": get_seg_segmentlabels,
        "ROIDescriptions": get_seg_descriptions,
        "ReferencedSeriesUID": get_seg_ref_series,
        "ReferencedSOPUIDs": get_seg_ref_sop_uids,
    }

RTSTRUCTMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Metadata extractor for RTSTRUCT modality DICOM datasets.

This class uses computed fields to extract ROI metadata and reference UIDs.

Methods:

Name Description
modality_tags

A set of DICOM tags specific to the modality handled by this extractor.
computed_fields

A mapping of metadata field names to callables that compute their values.

modality_tags #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
RTSTRUCT-specific direct tags (generally minimal).

Returns:

Type Description
set[str]

A set of directly accessible RTSTRUCT tag names.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
@classproperty
def modality_tags(cls) -> set[str]:
    """
    RTSTRUCT-specific direct tags (generally minimal).

    Returns
    -------
    set[str]
        A set of directly accessible RTSTRUCT tag names.
    """
    return {
        "StructureSetLabel",
        "StructureSetName",
        "StructureSetDate",
        "StructureSetTime",
    }

computed_fields #

computed_fields() -> typing.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
RTSTRUCT-specific computed fields.

Returns:

Type Description
typing.Mapping[str, imgtools.dicom.dicom_metadata.extractor_base.ComputedField]

Field names mapped to functions that extract computed values.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
@classproperty
def computed_fields(cls) -> Mapping[str, ComputedField]:
    """
    RTSTRUCT-specific computed fields.

    Returns
    -------
    Mapping[str, ComputedField]
        Field names mapped to functions that extract computed values.
    """

    from imgtools.dicom.dicom_metadata.modality_utils.rtstruct_utils import (
        extract_roi_names,
        rtstruct_reference_uids,
    )

    return {
        "ReferencedSeriesUID": lambda ds: rtstruct_reference_uids(ds)[0],
        "ReferencedSOPUIDs": lambda ds: rtstruct_reference_uids(ds)[1],
        "ROINames": extract_roi_names,
        "NumROIs": lambda ds: len(extract_roi_names(ds)),
    }

RTDOSEMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Metadata extractor for RTDOSE modality DICOM datasets.

Extracts direct and computed reference UIDs from dose DICOM files.

Methods:

Name Description
modality_tags

A set of DICOM tags specific to the modality handled by this extractor.
computed_fields

A mapping of metadata field names to callables that compute their values.

modality_tags #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
391
392
393
394
395
396
397
398
@classproperty
def modality_tags(cls) -> set[str]:
    return {
        "DoseType",
        "DoseUnits",
        "DoseSummationType",
        "DoseGridScaling",
    }

computed_fields #

computed_fields() -> typing.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
400
401
402
403
404
405
406
407
408
409
410
411
412
413
@classproperty
def computed_fields(cls) -> Mapping[str, ComputedField]:
    from imgtools.dicom.dicom_metadata.modality_utils.rtdose_utils import (
        rtdose_reference_uids,
    )

    def get_sop_uids(ds: Dataset) -> list[str]:
        ref_pl, ref_struct, ref_series = rtdose_reference_uids(ds)
        return [ref_struct or ref_pl]

    return {
        "ReferencedSeriesUID": lambda ds: rtdose_reference_uids(ds)[2],
        "ReferencedSeriesSOPUIDs": get_sop_uids,
    }

RTPLANMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Metadata extractor for RTPLAN modality DICOM datasets.

Extracts basic DICOM tags and reference to an RTSTRUCT UID.

Methods:

Name Description
modality_tags

A set of DICOM tags specific to the modality handled by this extractor.
computed_fields

A mapping of metadata field names to callables that compute their values.

modality_tags #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
428
429
430
431
432
433
434
435
436
437
@classproperty
def modality_tags(cls) -> set[str]:
    return {
        "SeriesInstanceUID",
        "StudyInstanceUID",
        "RTPlanLabel",
        "RTPlanName",
        "RTPlanDate",
        "RTPlanTime",
    }

computed_fields #

computed_fields() -> typing.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
439
440
441
442
443
444
445
@classproperty
def computed_fields(cls) -> Mapping[str, ComputedField]:
    from imgtools.dicom.dicom_metadata.modality_utils.rtplan_utils import (
        rtplan_reference_uids,
    )

    return {"ReferencedSOPUIDs": lambda ds: [rtplan_reference_uids(ds)]}

SRMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Metadata extractor for SR (Structured Report) modality DICOM datasets.

Extracts referenced SeriesInstanceUIDs and SOPInstanceUIDs from structured reports.

Methods:

Name Description
modality_tags

A set of DICOM tags specific to the modality handled by this extractor.
computed_fields

A mapping of metadata field names to callables that compute their values.

modality_tags #

modality_tags() -> set[str]

A set of DICOM tags specific to the modality handled by this extractor.

Returns:

Type Description
set[str]

Set of DICOM tag names.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
460
461
462
463
464
465
466
467
468
469
470
@classproperty
def modality_tags(cls) -> set[str]:
    return {
        "SeriesInstanceUID",
        "StudyInstanceUID",
        "Modality",
        "Manufacturer",
        "ContentDate",
        "ContentTime",
        "SeriesDescription",
    }

computed_fields #

computed_fields() -> typing.Mapping[
    str,
    imgtools.dicom.dicom_metadata.extractor_base.ComputedField,
]

A mapping of metadata field names to callables that compute their values.

The callable should accept a pydicom Dataset and return a value.

Returns:

Type Description
dict[str, Callable[[pydicom.Dataset], imgtools.dicom.dicom_metadata.extractor_base.ComputedValue]]

Mapping of field names to computation functions.
Source code in src/imgtools/dicom/dicom_metadata/extractors.py 
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
@classproperty
def computed_fields(cls) -> Mapping[str, ComputedField]:
    from imgtools.dicom.dicom_metadata.modality_utils.sr_utils import (
        sr_reference_uids,
    )

    def get_series_uids(ds: Dataset) -> list[str]:
        series, _ = sr_reference_uids(ds)
        return list(series)

    def get_sop_uids(ds: Dataset) -> list[str]:
        _, sops = sr_reference_uids(ds)
        return list(sops)

    return {
        "ReferencedSeriesUIDs": get_series_uids,
        "ReferencedSOPUIDs": get_sop_uids,
    }