Skip to content

Seg utils

seg_utils #

Functions:

Name Description
seg_reference_uids

Get the ReferencedSeriesInstanceUID or ReferencedSOPInstanceUIDs from a SEG file

SEGRefSOPs #

Bases: list[str]

A list representing all the ReferencedSOPInstanceUIDs for a SEG file

SEGRefSeries #

Bases: str

A single string to store the ReferencedSeriesInstanceUID for a SEG file

get_seg_direction #

get_seg_direction(
    seg: pydicom.dataset.Dataset,
) -> list[float] | None

Get the direction cosines (orientation) from a SEG file.

Parameters:

Name Type Description Default

seg #

 pydicom.dataset.Dataset

Input DICOM segmentation object as a pydicom Dataset.

 required

Returns:

Type Description
list[float] | None

A list of six floats representing the direction cosines if available, or None if the orientation information is not found.
Source code in src/imgtools/dicom/dicom_metadata/modality_utils/seg_utils.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
def get_seg_direction(seg: Dataset) -> list[float] | None:
    """
    Get the direction cosines (orientation) from a SEG file.

    Parameters
    ----------
    seg : Dataset
        Input DICOM segmentation object as a pydicom Dataset.

    Returns
    -------
    list[float] | None
        A list of six floats representing the direction cosines if available,
        or None if the orientation information is not found.
    """
    if not (
        (sharedseq := seg.SharedFunctionalGroupsSequence)
        and (pos := sharedseq[0].PlaneOrientationSequence)
        and (direction := pos[0].get("ImageOrientationPatient"))
    ):
        return None
    return [float(v) for v in direction]

get_seg_spacing #

get_seg_spacing(
    seg: pydicom.dataset.Dataset,
) -> list[float] | None

Get the pixel spacing and slice spacing or thickness from a SEG file.

Parameters:

Name Type Description Default

seg #

 pydicom.dataset.Dataset

Input DICOM segmentation object as a pydicom Dataset.

 required

Returns:

Type Description
list[float] | None

A list of three floats representing [x_spacing, y_spacing, z_spacing] if available, or None if the spacing information is not found.
Source code in src/imgtools/dicom/dicom_metadata/modality_utils/seg_utils.py 
 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
def get_seg_spacing(seg: Dataset) -> list[float] | None:
    """
    Get the pixel spacing and slice spacing or thickness from a SEG file.

    Parameters
    ----------
    seg : Dataset
        Input DICOM segmentation object as a pydicom Dataset.

    Returns
    -------
    list[float] | None
        A list of three floats representing [x_spacing, y_spacing, z_spacing] if available,
        or None if the spacing information is not found.
    """
    if not (
        (sharedseq := seg.SharedFunctionalGroupsSequence)
        and (pms := sharedseq[0].PixelMeasuresSequence)
        and (pixelspacing := pms[0].PixelSpacing)
        and (
            spacing := pms[0].get("SpacingBetweenSlices")
            or pms[0].get("SliceThickness")
        )
    ):
        return None

    return [
        float(pixelspacing[0]),
        float(pixelspacing[1]),
        float(spacing),
    ]

seg_reference_uids #

seg_reference_uids(
    seg: pydicom.dataset.Dataset,
) -> tuple[
    imgtools.dicom.dicom_metadata.modality_utils.seg_utils.SEGRefSeries,
    imgtools.dicom.dicom_metadata.modality_utils.seg_utils.SEGRefSOPs,
]

Get the ReferencedSeriesInstanceUID or ReferencedSOPInstanceUIDs from a SEG file

Modern Segmentation objects have a ReferencedSeriesSequence attribute which contains the SeriesInstanceUID of the referenced series and a ReferencedInstanceSequence attribute which contains the SOPInstanceUIDs of the referenced instances.

Older Segmentation objects have a SourceImageSequence attribute which only contains the SOPInstanceUIDs of the referenced instances.

Parameters:

Name Type Description Default

seg #

 pydicom.dataset.Dataset

Input DICOM segmentation object as a pydicom Dataset.

 required

Returns:

Type Description
tuple[imgtools.dicom.dicom_metadata.modality_utils.seg_utils.SEGRefSeries, imgtools.dicom.dicom_metadata.modality_utils.seg_utils.SEGRefSOPs]

Always returns a tuple containing: - ReferencedSeriesInstanceUID (empty string if not available) - ReferencedSOPInstanceUIDs (empty list if not available)
Source code in src/imgtools/dicom/dicom_metadata/modality_utils/seg_utils.py 
22
23
24
25
26
27
28
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
73
74
75
76
77
78
79
80
81
82
83
def seg_reference_uids(
    seg: Dataset,
) -> tuple[SEGRefSeries, SEGRefSOPs]:
    """Get the ReferencedSeriesInstanceUID or ReferencedSOPInstanceUIDs from a SEG file

    Modern Segmentation objects have a `ReferencedSeriesSequence` attribute
    which contains the `SeriesInstanceUID` of the referenced series and
    a `ReferencedInstanceSequence` attribute which contains the SOPInstanceUIDs
    of the referenced instances.

    Older Segmentation objects have a `SourceImageSequence` attribute which
    only contains the `SOPInstanceUIDs` of the referenced instances.

    Parameters
    ----------
    seg : Dataset
        Input DICOM segmentation object as a pydicom Dataset.

    Returns
    -------
    tuple[SEGRefSeries, SEGRefSOPs]
        Always returns a tuple containing:
        - ReferencedSeriesInstanceUID (empty string if not available)
        - ReferencedSOPInstanceUIDs (empty list if not available)
    """

    assert seg.Modality == "SEG", (
        "Input DICOM file is not a Segmentation object"
    )

    if "ReferencedSeriesSequence" in seg:
        ref_series: list[SEGRefSeries] = [
            SEGRefSeries(ref_series.SeriesInstanceUID)
            for ref_series in seg.ReferencedSeriesSequence
        ]
        ref_sop = SEGRefSOPs(
            [
                seq.ReferencedSOPInstanceUID
                for seq in seg.ReferencedSeriesSequence[
                    0
                ].ReferencedInstanceSequence
            ]
        )
        # Check if there is only one ReferencedSeriesInstanceUID
        if len(ref_series) == 1:
            return ref_series[0], ref_sop
        else:
            errmsg = (
                "Multiple ReferencedSeriesInstanceUIDs found in ReferencedSeriesSequence"
                " This is unexpected and may cause issues. "
                f"Found {len(ref_series)} ReferencedSeriesInstanceUIDs."
            )
            raise ValueError(errmsg)
    elif "SourceImageSequence" in seg:
        ref_sop_list = [
            seq.ReferencedSOPInstanceUID for seq in seg.SourceImageSequence
        ]

        return SEGRefSeries(""), SEGRefSOPs(ref_sop_list)

    # Return empty values if no reference information is found
    return SEGRefSeries(""), SEGRefSOPs([])