Extractors

extractors #

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
`computed_fields`	A mapping of metadata field names to callables that compute their values.
`extract`	Extract metadata tags and computed fields from a DICOM dataset.
`metadata_keys`	Return a predictable, sorted list of metadata field names.
`modality`	The DICOM modality handled by this extractor (e.g., "CT", "MR").
`modality_tags`	A set of DICOM tags specific to the modality handled by this extractor.

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

@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 {}

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

@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

@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 `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/extractors.py

@classmethod
def modality(cls) -> str:
    return "CT"

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

@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",
    }

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
`computed_fields`	A mapping of metadata field names to callables that compute their values.
`extract`	Extract metadata tags and computed fields from a DICOM dataset.
`metadata_keys`	Return a predictable, sorted list of metadata field names.
`modality`	The DICOM modality handled by this extractor (e.g., "CT", "MR").
`modality_tags`	A set of DICOM tags specific to the modality handled by this extractor.

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

@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 {}

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

@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

@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 `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/extractors.py

@classmethod
def modality(cls) -> str:
    return "UNKNOWN"

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

@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()

MRMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Methods:

Name	Description
`computed_fields`	A mapping of metadata field names to callables that compute their values.
`extract`	Extract metadata tags and computed fields from a DICOM dataset.
`metadata_keys`	Return a predictable, sorted list of metadata field names.
`modality`	The DICOM modality handled by this extractor (e.g., "CT", "MR").
`modality_tags`	A set of DICOM tags specific to the modality handled by this extractor.

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

@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 {}

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

@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

@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 `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/extractors.py

@classmethod
def modality(cls) -> str:
    return "MR"

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

@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",
    }

PTMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

Methods:

Name	Description
`computed_fields`	A mapping of metadata field names to callables that compute their values.
`extract`	Extract metadata tags and computed fields from a DICOM dataset.
`metadata_keys`	Return a predictable, sorted list of metadata field names.
`modality`	The DICOM modality handled by this extractor (e.g., "CT", "MR").
`modality_tags`	A set of DICOM tags specific to the modality handled by this extractor.

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

@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 {}

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

@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

@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 `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/extractors.py

@classmethod
def modality(cls) -> str:
    return "PT"

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

@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",
    }

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
`computed_fields`	A mapping of metadata field names to callables that compute their values.
`extract`	Extract metadata tags and computed fields from a DICOM dataset.
`metadata_keys`	Return a predictable, sorted list of metadata field names.
`modality`	The DICOM modality handled by this extractor (e.g., "CT", "MR").
`modality_tags`	A set of DICOM tags specific to the modality handled by this extractor.

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

@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,
    }

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

@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

@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 `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/extractors.py

@classmethod
def modality(cls) -> str:
    return "RTDOSE"

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

@classproperty
def modality_tags(cls) -> set[str]:
    return {
        "DoseType",
        "DoseUnits",
        "DoseSummationType",
        "DoseGridScaling",
    }

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
`computed_fields`	A mapping of metadata field names to callables that compute their values.
`extract`	Extract metadata tags and computed fields from a DICOM dataset.
`metadata_keys`	Return a predictable, sorted list of metadata field names.
`modality`	The DICOM modality handled by this extractor (e.g., "CT", "MR").
`modality_tags`	A set of DICOM tags specific to the modality handled by this extractor.

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

@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)]}

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

@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

@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 `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/extractors.py

@classmethod
def modality(cls) -> str:
    return "RTPLAN"

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

@classproperty
def modality_tags(cls) -> set[str]:
    return {
        "SeriesInstanceUID",
        "StudyInstanceUID",
        "RTPlanLabel",
        "RTPlanName",
        "RTPlanDate",
        "RTPlanTime",
    }

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
`computed_fields`	A mapping of metadata field names to callables that compute their values.
`extract`	Extract metadata tags and computed fields from a DICOM dataset.
`metadata_keys`	Return a predictable, sorted list of metadata field names.
`modality`	The DICOM modality handled by this extractor (e.g., "CT", "MR").
`modality_tags`	A set of DICOM tags specific to the modality handled by this extractor.

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

@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)),
    }

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

@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

@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 `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/extractors.py

@classmethod
def modality(cls) -> str:
    return "RTSTRUCT"

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

@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",
    }

SEGMetadataExtractor #

Bases: imgtools.dicom.dicom_metadata.extractor_base.ModalityMetadataExtractor

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

@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,
    }

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

@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

@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 `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/extractors.py

@classmethod
def modality(cls) -> str:
    return "SEG"

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

@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",
    }

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
`computed_fields`	A mapping of metadata field names to callables that compute their values.
`extract`	Extract metadata tags and computed fields from a DICOM dataset.
`metadata_keys`	Return a predictable, sorted list of metadata field names.
`modality`	The DICOM modality handled by this extractor (e.g., "CT", "MR").
`modality_tags`	A set of DICOM tags specific to the modality handled by this extractor.

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

@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 {
        "ReferencedSeriesUID": get_series_uids,
        "ReferencedSOPUIDs": get_sop_uids,
    }

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

@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

@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 `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/extractors.py

@classmethod
def modality(cls) -> str:
    return "SR"

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

@classproperty
def modality_tags(cls) -> set[str]:
    return {
        "SeriesInstanceUID",
        "StudyInstanceUID",
        "Modality",
        "Manufacturer",
        "ContentDate",
        "ContentTime",
        "SeriesDescription",
    }

Extractors

extractors #

CTMetadataExtractor #

computed_fields #

extract classmethod #

dicom #

extra_tags #

metadata_keys classmethod #

modality classmethod #

modality_tags #

FallbackMetadataExtractor #

computed_fields #

extract classmethod #

dicom #

extra_tags #

metadata_keys classmethod #

modality classmethod #

modality_tags #

MRMetadataExtractor #

computed_fields #

extract classmethod #

dicom #

extra_tags #

metadata_keys classmethod #

modality classmethod #

modality_tags #

PTMetadataExtractor #

computed_fields #

extract classmethod #

dicom #

extra_tags #

metadata_keys classmethod #

modality classmethod #

modality_tags #

RTDOSEMetadataExtractor #

computed_fields #

extract classmethod #

dicom #

extra_tags #

metadata_keys classmethod #

modality classmethod #

modality_tags #

RTPLANMetadataExtractor #

computed_fields #

extract classmethod #

dicom #

extra_tags #

metadata_keys classmethod #

modality classmethod #

modality_tags #

RTSTRUCTMetadataExtractor #

computed_fields #

extract classmethod #

dicom #

extra_tags #

metadata_keys classmethod #

modality classmethod #

modality_tags #

SEGMetadataExtractor #

computed_fields #

extract classmethod #

dicom #

extra_tags #

metadata_keys classmethod #

modality classmethod #

modality_tags #

SRMetadataExtractor #

computed_fields #

extract classmethod #

dicom #

extra_tags #

metadata_keys classmethod #

modality classmethod #

modality_tags #

extract `classmethod` #

`dicom` #

`extra_tags` #

metadata_keys `classmethod` #

modality `classmethod` #

extract `classmethod` #

`dicom` #

`extra_tags` #

metadata_keys `classmethod` #

modality `classmethod` #

extract `classmethod` #

`dicom` #

`extra_tags` #

metadata_keys `classmethod` #

modality `classmethod` #

extract `classmethod` #

`dicom` #

`extra_tags` #

metadata_keys `classmethod` #

modality `classmethod` #

extract `classmethod` #

`dicom` #

`extra_tags` #

metadata_keys `classmethod` #

modality `classmethod` #

extract `classmethod` #

`dicom` #

`extra_tags` #

metadata_keys `classmethod` #

modality `classmethod` #

extract `classmethod` #

`dicom` #

`extra_tags` #

metadata_keys `classmethod` #

modality `classmethod` #

extract `classmethod` #

`dicom` #

`extra_tags` #

metadata_keys `classmethod` #

modality `classmethod` #

extract `classmethod` #

`dicom` #

`extra_tags` #

metadata_keys `classmethod` #

modality `classmethod` #