autods_pet.imaging.dicom#

DICOM discovery, tag extraction, and NIfTI conversion for autods_pet.

Provides functions to find DICOM files, extract PET/CT metadata tags, and convert DICOM series to NIfTI format using pydicom and SimpleITK.

autods_pet.imaging.dicom.resolve_patient_folder(basepath, patient_id)[source]#

Case-insensitive lookup for a patient subfolder.

Returns the resolved Path or None if no match is found.

Return type:

Path | None

Parameters:
autods_pet.imaging.dicom.find_dicom_files(patient_dir, size_threshold_kb=100)[source]#

Recursively find .dcm files above a size threshold.

Parameters:

  • patient_dir (str | Path) – Root directory to search.

  • size_threshold_kb (int (default: 100)) – Minimum file size in KB. Files smaller than this are skipped (e.g. tiny overlay or presentation-state files).

Returns:

Sorted list of matching file paths.

Return type:

list[Path]

autods_pet.imaging.dicom.find_series_by_modality(patient_dir, size_threshold_kb=100)[source]#

Find the primary CT and PT DICOM series in a patient directory.

Groups .dcm files by (Modality, SeriesInstanceUID), then picks the series with the most files for each modality.

Note

This function reads DICOM headers for every .dcm file sequentially (O(n) disk reads, no parallelism). For directories with 1000+ files on network-attached storage this may be slow. Consider parallel header reads for high-throughput deployments.

Returns:

{"CT": [Path, ...], "PT": [Path, ...]}. Empty lists for modalities that are not found.

Return type:

dict[str, list[Path]]

Parameters:

  • patient_dir (str | Path)

  • size_threshold_kb (int)

autods_pet.imaging.dicom.extract_pet_tags(dicom_path)[source]#

Extract PET metadata tags from a single DICOM file.

Handles nested RadiopharmaceuticalInformationSequence with top-level fallback for dose and half-life tags.

Returns:

Keys match the metadata expected by normalize_pet(): PatientID, StudyDate, AcquisitionTime, Units, DecayCorrection, RadiopharmaceuticalStartTime, RadionuclideTotalDose, RadionuclideHalfLife, SeriesInstanceUID, StudyInstanceUID. Missing tags are set to None.

Return type:

dict[str, Any]

Parameters:

dicom_path (str | Path)

autods_pet.imaging.dicom.extract_ct_tags(dicom_path)[source]#

Extract CT metadata tags from a single DICOM file.

Returns:

CT-relevant tags. Missing tags are set to None.

Return type:

dict[str, Any]

Parameters:

dicom_path (str | Path)

autods_pet.imaging.dicom.extract_patient_weight(dicom_path)[source]#

Extract patient weight (kg) from a DICOM file.

Returns:

Weight in kg, or None if the tag is absent or zero.

Return type:

float | None

Parameters:

dicom_path (str | Path)

autods_pet.imaging.dicom.dicom_series_to_nifti(dicom_files, output_path)[source]#

Convert a DICOM series to a NIfTI file.

Uses SimpleITK’s ImageSeriesReader with GDCM-based spatial ordering to ensure correct slice order.

Parameters:

  • dicom_files (Sequence[str | Path]) – File paths belonging to a single DICOM series.

  • output_path (str | Path) – Where to write the NIfTI file.

Returns:

The loaded image (also written to output_path).

Return type:

Image