DICOMDownloader

DICOMDownloader is Fyron's DICOMweb acquisition helper. It downloads individual series or full studies, writes DICOM or NIfTI outputs, and returns result metadata that can be stored beside a cohort table.

When To Use It

• download a known StudyInstanceUID / SeriesInstanceUID,
• batch-download imaging rows from a CSV/DataFrame,
• fetch a full study when the relevant series is not known yet,
• create reproducible manifests before local image processing.

Use Imaging after files are already local. Use DICOM SEG for segmentation objects and Synthetic Export for generated intensity volumes.

Core Concepts

API Contract

The download_id can be reproduced without contacting the server:

from fyron.dicom import DICOMDownloader

download_id = DICOMDownloader.download_id(
    study_uid="1.2.3",
    series_uid="1.2.3.4",
)

Required Inputs

Optional Inputs

Minimal Example

from fyron import DICOMDownloader

downloader = DICOMDownloader(
    dicom_web_url="https://pacs.example.org/dicomweb",
    output_format="dicom",
)

result = downloader.download_series(
    study_uid="1.2.3",
    series_uid="1.2.3.4",
    output_dir="dicom_out",
)

result.download_id
result.path
result.error

NIfTI With One Metadata DICOM

When output_format="nifti", Fyron normally converts through a temporary DICOM folder and keeps only the NIfTI output. If you also need a source DICOM header for later metadata checks, set save_reference_dicom=True:

from fyron import DICOMDownloader

downloader = DICOMDownloader(
    dicom_web_url="https://pacs.example.org/dicomweb",
    output_format="nifti",
    save_reference_dicom=True,
    reference_dicom_name="reference.dcm",
)

result = downloader.download_series(
    study_uid="1.2.3",
    series_uid="1.2.3.4",
    output_dir="downloads",
)

The series folder then contains:

downloads/{download_id}/
  1.2.3.4.nii.gz
  reference.dcm

Use this when downstream tools work with NIfTI but you still want one original DICOM file for PatientID, acquisition metadata, frame of reference, or audit checks. If an existing NIfTI is skipped with skip_existing=True, Fyron does not contact the DICOMweb server and cannot backfill the reference file; rerun with skip_existing=False to create it.

For repeated download jobs, prefer constructor-level configuration:

downloader = DICOMDownloader(
    dicom_web_url="https://pacs.example.org/dicomweb",
    output_format="nifti",
    save_reference_dicom=True,
    reference_dicom_name="meta.dcm",
)

For one-off DataFrame downloads, you can override the reference-DICOM behavior directly on the batch call without mutating the downloader:

results = downloader.download_from_dataframe(
    df=imaging_df,
    output_dir="downloads",
    save_reference_dicom=True,
    reference_dicom_name="meta.dcm",
)

download_from_df(...) accepts the same arguments. Older scripts that use keep_reference_dicom=True still run with a DeprecationWarning, but new code should use save_reference_dicom=True.

Batch Example

results = downloader.download_from_df(
    imaging_df,
    output_dir="dicom_out",
    study_uid_col="study_instance_uid",
    series_uid_col="series_instance_uid",
    save_reference_dicom=True,
    reference_dicom_name="meta.dcm",
    results_csv="dicom_results.csv",
)

The input DataFrame should contain one row per requested series unless download_full_study=True.

Study Versus Series Downloads

Use output_format="dicom" when later writing DICOM SEG because SEG export needs source-referenced DICOM slices. Use output_format="nifti" when the next step is local image processing, BOA-like processing, or array-based analysis. Use output_format="nifti", save_reference_dicom=True when the analysis should run on NIfTI but metadata provenance still needs one original source DICOM.

Research Decision: DICOM Or NIfTI

Always keep the returned result table. It is the bridge between cohort rows, download_id, study/series UIDs, and local files.

CLI Workflow

fyron dicom-download \
  --csv imaging.csv \
  --study-col study_instance_uid \
  --series-col series_instance_uid \
  --output-dir dicom_out \
  --save-reference-dicom \
  --results-csv dicom_results.csv

Function Table

Return Values

DicomResult contains:

Common Pitfalls

• Use output_format="dicom" when later writing DICOM SEG; SEG needs original source images.
• Keep result manifests with the study cohort.
• Confirm UID columns before a batch download; UID mixups are expensive.
• Start with one test series before scaling to many studies.
• For BOA-style downstream extraction, keep a stable mapping between download_id, patient ID, study UID, and series UID.

Related Modules

• DICOM for the overview.
• Imaging for local DICOM/NIfTI reading and QC.
• Audit & Provenance for reproducibility manifests.