Writing Module#

Module: pyradise.fileio.writing

General#

The writing module provides functionality to write Subject instances in a structured way to disk. Furthermore, the module provides also writers for writing DICOM-RTSS Dataset s (see pydicom Dataset).

Class Overview#

The following writer classes are provided:

Class	Description
`SubjectWriter`	A writer class for the serialization of a `Subject` and its content.
`DirectorySubjectWriter`	A writer class for the serialization of `Dataset` s and copy functionality based on a source path.
`DicomSeriesSubjectWriter`	A writer class for the serialization of `Dataset` s and copy functionality based on `DicomSeriesInfo` instances.

Details#

class SubjectWriter(file_format=ImageFileFormat.NIFTI_GZ, intensity_file_name_fn=<function default_intensity_file_name_fn>, segmentation_file_name_fn=<function default_segmentation_file_name_fn>, allow_override=False)[source]#

Bases: object

A class for writing the content of a Subject instance to a directory.

Notes

This writer provides interfaces for file name generation functions which can be used to customize the file names of the intensity and segmentation images. Please be aware that certain patterns may cause problems if the data should be reloaded again (e.g. separation of information by underline while separating the annotators name also with underline). Thus, check carefully if the file name generation function is suitable for your use case.

Currently, the serialization of IntensityImage s, SegmentationImage s, and transformations from the TransformTape is supported. Other data types may be added in the future.

Parameters:

file_format (ImageFileFormat) – The output file format (default: ImageFileFormat.NIFTI_GZ).
intensity_file_name_fn (Callable[[Subject, IntensityImage], str]) – The function for generating the file names of the intensity images (default: default_intensity_file_name_fn).
segmentation_file_name_fn (Callable[[Subject, SegmentationImage], str]) – The function for generating the file names of the segmentation images (default: default_segmentation_file_name_fn).
allow_override (bool) – If True the writer can overwrite existing files, otherwise not (default: False).

write(path, subject, write_transforms=True)[source]#

Write a Subject instance to the specified directory.

Parameters:

path (str) – The path to the subject directory.
subject (Subject) – The Subject to be written.
write_transforms (bool) – If True writes the transformation files for each IntensityImage and SegmentationImage instance, otherwise not (default: True).

Return type:

None

Returns:

None

write_to_subject_folder(base_dir_path, subject, write_transforms=True)[source]#

Write a Subject instance to a separate subject directory within the specified base directory. The newly created subject directory will be named with the subjects name.

Notes

This is function is just a wrapper around the write function and reduces the amount of code which is required to write each subject to a separate directory.

Parameters:

base_dir_path (str) – The path to the base directory where the subject directory will be placed.
subject (Subject) – The Subject to be written.
write_transforms (bool) – If True writes the transformation files for each IntensityImage and SegmentationImage instance, otherwise not (default: True).

Return type:

None

Returns:

None

class DirectorySubjectWriter(as_zip=False)[source]#

Bases: object

A writer class for writing DICOM Dataset instances to disk. In addition, it is feasible to copy data (specified by a directory path) from a source directory to the target directory. This writer is also feasible to save all data within a zip file instead of a directory.

Note

In contrast to the DicomSeriesSubjectWriter the DirectorySubjectWriter provides a different interface which takes a directory path instead of a tuple of DicomSeriesInfo instances for copying existing data.

The additional copying functionality is useful if the input DICOM data should be copied to the output directory as it is often the case when building processing pipelines.

Parameters:: as_zip (bool) – Indicates if the output should be a zip file or a normal directory (default: False).

write(datasets, output_path, folder_name=None, copy_dir_path=None)[source]#

Write the provided data to a directory or a zip file.

Parameters:

datasets (Tuple[Tuple[str, Dataset], ...]) – The Dataset instances to write and its file names.
output_path (str) – The path to the output base directory.
folder_name (Optional[str]) – The name of the folder or the zip file (default: None).
copy_dir_path (str) – The path to the directory from which all data should be copied (default: None).

Return type:

None

Returns:

None

class DicomSeriesSubjectWriter(as_zip=False)[source]#

Bases: object

A writer class for writing DICOM Dataset instances to disk. In addition, it is feasible to copy DICOM data (specified by DicomSeriesInfo entries) from a source directory to the target directory. This writer is also feasible to save all data within a zip file instead of a directory.

Note

In contrast to the DirectorySubjectWriter the DicomSeriesSubjectWriter provides a different interface which takes a tuple of DicomSeriesInfo instead of a directory path for copying existing data.

The additional copying functionality is useful if the input DICOM data should be copied to the output directory as it is often the case when building processing pipelines.

Parameters:: as_zip (bool) – Indicates if the output should be a zip file or a normal directory (default: False).

write(datasets, output_path, folder_name=None, series_infos=None)[source]#

Write the provided data to a directory or a zip file.

Parameters:

datasets (Tuple[Tuple[str, Dataset], ...]) – The Dataset instances to write and its file names.
output_path (str) – The output path.
folder_name (str) – The name of the output folder or the zip file (default: None).
series_infos (Optional[Tuple[SeriesInfo, ...]]) – The DicomSeriesInfo instances containing the path for DICOM files to copy (default: None).

Return type:

None

Returns:

None

class ImageFileFormat(value)[source]#

Bases: Enum

An enumeration of possible output image file formats.

Notes

The current implementation supports the following formats:

NIFTI (.nii, .nii.gz)

NRRD (.nrrd)

MHA (.mha)

More image file formats will be added in the future.

NIFTI = '.nii'#: Image format NIFTI / extension .nii

NIFTI_GZ = '.nii.gz'#: Image format NIFTI GZ / extension .nii.gz

NRRD = '.nrrd'#: Image format NRRD / extension .nrrd

MHA = '.mha'#: Image format MHA / extension .mha

default_intensity_file_name_fn(subject, image)[source]#

The default intensity file name generation function.

Important

The file name must not contain the file extension because this is provided by the writer.

Parameters:

subject (Subject) – The subject.
image (IntensityImage) – The intensity image.

Returns:

The file name.

Return type:

str

default_segmentation_file_name_fn(subject, image)[source]#

The default segmentation file name generation function.

Important

The file name must not contain the file extension because this is provided by the writer.

Parameters:

subject (Subject) – The subject.
image (SegmentationImage) – The segmentation image.

Returns:

The file name.

Return type:

str