Converting your data

See Querying your database on how to create a query used to plan out a conversion.

plan = db.plan('{patient_id}/prostateX_{series_description}_{instance_creation_time}', query_0000)

# ensure these properties are set
plan.target_dir = 'path/to/output_directory'
plan.extension = '.mha'
plan.max_workers = 4

# print out a detailed structure of our intended conversion
print(plan)

plan.execute()

The print gives:

dicomselect conversion plan

source_dir          C:\Repos\dicomselect\tests\input\ProstateX
target_dir          C:\Repos\dicomselect\tests\output\example
extension           .mha

.
└── ProstateX-0000
    ├── prostateX_ep2d_diff_tra_DYNDISTCALC_BVAL_120403.703.mha
    ├── prostateX_ep2d_diff_tra_DYNDIST_120403.515.mha
    ├── prostateX_ep2d_diff_tra_DYNDIST_ADC_120403.625.mha
    ├── prostateX_t2_tse_tra_115754.609.mha
    └── prostateX_tfl_3d PD ref_tra_1.5x1.5_t3_120615.109.mha

Conversion API

class dicomselect.convert.Plan(*args)

Bases: Logger

This object is created from Database.plan, ensure the target_dir property has a target prior to performing Plan.execute().

execute(max_workers: int = 4, reader_prefer_mode: int = None, postprocess_func: Callable[[DICOMImageReader], Image | Dict[str, Image]] | None = None, overwrite=False)

Execute the conversion plan.

Parameters:

• max_workers (int) – Max number of workers for parallel execution of this conversion.

• reader_prefer_mode (int) – By default, DICOM metadata and image data is read using SimpleITK. Set preference for which one to use during database creation, see DICOMImageReader.PreferMode.

• postprocess_func (Callable[[DICOMImageReader], Image | Dict[str, Image]] | None) – Postprocess function, providing a DICOMImageReader. If it returns False, the conversion is skipped. If it returns a SimpleITK.Image, the conversion is executed using the returned image. If it returns a dict of [str, SimpleITK.Image], it converts each entry, where key is attached to the end of the name template.

• overwrite – If overwrite is true, conversion will overwrite existing files.

Examples

>>> plan = Database(db_path).plan(template_str, query_000)
>>>
>>> def my_postprocess_func(reader: DICOMImageReader) -> DICOMImageReader:
>>>     dicom_slice_paths_per_bvalue = {}
>>>     for path in reader.dicom_slice_paths:
>>>         img = sitk.ReadImage(str(path))
>>>         bvalue = int(img.GetMetaData("0018|9087"))
>>>         (...)
>>>         dicom_slice_paths_per_bvalue[bvalue] = dicom_slice_paths_per_bvalue.get(bvalue, []) + [path]
>>>
>>>     # convert each b-value to a single image
>>>     diffusion_images = {}
>>>     for bvalue, dicom_slice_paths in dicom_slice_paths_per_bvalue.items():
>>>         with tempfile.TemporaryDirectory() as tmpdirname:
>>>             # copy DICOM slices to temporary directory
>>>              (...)
>>>
>>>             # read DICOM sequence
>>>             (...)
>>>
>>>             # read metadata from the last DICOM slice and set metadata
>>>             ifr = sitk.ImageFileReader()
>>>             (...)
>>>
>>>             # store image
>>>             diffusion_images[str(bvalue)] = image
>>>
>>>     return diffusion_images
>>>
>>> plan.execute(postprocess_func=my_postprocess_func)

property extension: str

The extension defines the converted filetype. See here for possible file formats to convert to.

property ignore_validation_errors: bool

Ignore validation errors. They will still be logged, but not raised. This is useful if you are handling all errors in the postprocess_func of your Plan.execute function.

property source_dir: Path

Source directory, containing your data that is to be converted. Defaults to the same directory used when the database was created, and so it is not recommended to change this value.

property target_dir: Path

Target directory, to contain the converted data.

to_string() → str

The conversion plan printed as a string, in a tree representation.

Return type:

str