Image Reading and Writing

A collection of useful functions for reading and writing images are implemented. The supported image type are:

  • MetaImage format in double (*.mhd+*.raw) or single files (only *.mhd),

  • Map3D images, i.e. an obsolate format used by the FRED Monte Carlo engine for saving 3D images (not recommended),

  • Dicom format (reading only) for 3D/2D images (e.g. dose distribution), Structures (i.e. RS*.dcm), Proton treatment plans (i.e. RN*.dcm or RP*.dcm) and CT images.

MetaImage files (*.mhd, *.mha)

fredtools.readMHD(fileNames, displayInfo=False)

Read MetaImage image to SimpleITK image object.

The function reads a single MetaImage file or an iterable of MetaImage files and creates an instance or tuple of instances of a SimpleITK object.

Parameters:

  • fileNames (string or array_like) – A path or an iterable (list, tuple, etc.) of paths to MetaImage file.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Object or tuple of objects of a SimpleITK image.

Return type:

SimpleITK Image or tuple

See also

SimpleITK.ReadImage

SimpleITK routine for reading files.

fredtools.writeMHD(img, filePath, singleFile=True, overwrite=True, useCompression=False, compressionLevel=5, displayInfo=False)

Write image to MetaImage format.

The function writes a SimpleITK image object to the MetaImage file. The function extends the functionality of SimpleITK.WriteImage() to write a single file MetaImage instead of standard two-files MHD+RAW. It is recommended to use *.mhd extension when saving MetaImage.

Parameters:

  • img (SimpleITK Image) – Object of a SimpleITK image.

  • filePath (path) – Path to file to be saved.

  • singleFile (bool, optional) – Determine if the MHD is a single file of two files MHD+RAW. (def. True)

  • overwrite (bool, optional) – Overwrite the file if it exists, otherwise, raise an error. (def. True)

  • useCompression (bool, optional) – Determine if a compression will be used when saving the file. (def. False)

  • compressionLevel (unsigned int, optional) – Determine the compression level. For MHD files, the compression level above 10 does not have any effect. (def. 5)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

See also

SimpleITK.WriteImage

SimpleITK routine for writing files.

fredtools.convertMHDtoSingleFile(filePath, displayInfo=False)

Convert two-files MetaImage to two-files.

The function reads a MetaImage file (two- or single-file) and saves it as a single file MetaImage (only *.mhd) with the same file name.

Parameters:

  • filePath (path) – Path to file to be converted.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

See also

readMHD

reading MetaImage file.

writeMHD

writing MetaImage file.

fredtools.convertMHDtoDoubleFiles(filePath, displayInfo=False)

Convert single file MetaImage to double- file.

The function reads a MetaImage file (two- or single-file) and saves it as a two-file file MetaImage (*.mhd+*.raw) with the same file name.

Parameters:

  • filePath (path) – Path to file to be converted.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

See also

readMHD

reading MetaImage file.

writeMHD

writing MetaImage file.

Map3D images (*.m3d)

Caution

The Map3D file format is obsolete and it is not recommended to be used to store the image data. Use MetaImage file format instead.

fredtools.readMap3D(filePath, displayInfo=False)

Read image from Map3D file format.

The function reads a Map3D file to a SimpleITK image object. The Map3D file format is an obsolete format used by the FRED Monte Carlo engine and the implementation of reading images from files in this format was maintained here for compatibility.

Parameters:

  • filePath (path) – Path to Map3D file to read.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Object of a SimpleITK image.

Return type:

SimpleITK Image

See also

writeMHD

Writing MetaImage files.

readMHD

Reading MetaImage files.

fredtools.writeMap3D(img, filePath, displayInfo=False)

Write image to Map3D file format.

The function writes a SimpleITK image object to Map3D file. This format is an obsolete format used by the FRED Monte Carlo engine and the implementation of writing images in this format was maintained here for compatibility. It is recommended to use MetaImage file format (*.mhd) for saving the images. It is recommended to use *.m3d extension when saving Map3D.

Parameters:

  • img (SimpleITK Image) – Object of a SimpleITK image.

  • filePath (path) – Path to file to be saved.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

See also

writeMHD

Writing MetaImage files.

DICOM files (*.dcm, *.dicom)

fredtools.getDicomTypeName(dicomVar)

Check the type of the dicom given as a path or tags.

The function return the name of the SOP Class UID tag of a dicom file given as a file name or dicom tags. The description of the SOP Class UID names can be found in [1].

Parameters:

dicomVar (path or tags) – A string of path to a dicom file or a dicom tag structure read by pydicom.read_file.

Returns:

A string of the SOP Class UID name.

Return type:

string

See also

sortDicoms

sort dicom files in a folder by type.

References

fredtools.sortDicoms(searchFolder, recursive=False, displayInfo=False)

Sort dicom file names found in the search folder for CT, RS, RN, RD and Unknown.

The function sorts file names found in the searchFolder (and subfolders if requested) for:

  • CT - dicom files of CT Image Storage (“CT Image Storage”, “Enhanced CT Image Storage” or “Legacy Converted Enhanced CT Image Storage”)

  • RS - dicom files of RT Structure Set Storage

  • RN - dicom files of RT Plan Storage (“RT Plan Storage” or “RT Ion Plan Storage”)

  • RD - dicom files of 1D/2D/3D RT Dose Storage (for instance dose distribution)

  • PET - dicom files of PET Image Storage (“Positron Emission Tomography Image Storage”)

  • Unknown - files with *.dcm extension that were not recognized.

Parameters:

  • searchFolder (path) – The path to be searched.

  • recursive (bool, optional) – Search for files recursively. (def. False)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Dictionary with the sorted file names.

Return type:

dict

fredtools.getRNMachineName(fileName, displayInfo=False)

Get the machine name defined in the RN plan.

The function retrieves the machine name defined in the RN dicom file.

Parameters:

  • fileName (path) – Path to RN dicom file.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Treatment machine name.

Return type:

string

See also

getRNFields

get a summary of parameters for each field defined in the RN plan.

getRNSpots

get a summary of parameters for each spot defined in the RN plan.

getRNInfo

get some basic information from the RN plan.

fredtools.getRNIsocenter(fileName, displayInfo=False)

Get the isocenter position defined in the RN plan.

The function retrieves the isocenter position defined in the RN dicom file. The isocenter is defined for each field separately but usually, it is the same for all fields. If it is not the same then a warning is raised and a geometrical center is returned.

Parameters:

  • fileName (path) – Path to RN dicom file.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

3-elements list of XYZ isocenter coordinates

Return type:

list

See also

getRNFields

get a summary of parameters for each field defined in the RN plan.

getRNSpots

get a summary of parameters for each spot defined in the RN plan.

getRNInfo

get some basic information from the RN plan.

fredtools.getRNInfo(fileName, displayInfo=False)

Get some information from the RN plan.

The function retrieves some useful information from a RN dicom of a treatment plan. Following information are saved to a dictionary:

  • RNFileName : absolute path to the RN file.

  • dosePrescribed : dose prescribed to the target (see notes below).

  • fractionNo : number of the fractions planned.

  • targetStructName : name of the structure which the plan was prepared for (dose not work for all RN dicoms).

  • planLabel : name of the treatment plan (can be empty for anonymized DICOM).

  • planDate : date of the plan creation (can be empty for anonymized DICOM).

  • planTime : time of the plan creation (can be empty for anonymized DICOM).

  • patientName : name of the patient (can be empty for anonymized DICOM).

  • patientBirthDate : birth date of the patient (can be empty for anonymized DICOM).

  • patientID : ID of the patient (can be empty for anonymized DICOM).

  • manufacturer : manufacturer of the treatment planning system.

  • softwareVersions : version of the treatment planning system.

  • stationName : name of the station on which the plan has been prepared.

  • machineName : name of the treatment machine for which the plan was prepared.

  • totalFieldsNumber : total number of fields including setup, treatment and other fields.

  • treatmentFieldsNumber : total number of treatment fields.

  • setupFieldsNumber : total number of setup fields.

  • otherFieldsNumber : total number of other fields.

Parameters:

  • fileName (path) – Path to RN dicom file.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Dictionary with the RN treatment plan parameters.

Return type:

dict

See also

getRNFields

get a summary of parameters for each field defined in the RN plan.

getRNSpots

get a summary of parameters for each spot defined in the RN plan.

Notes

The prescribed dose, dosePrescribed, is read from TargetPrescriptionDose in DoseReferenceSequence, but if this is not available it is calculated as the sum of BeamDose in FractionGroupSequence[0].ReferencedBeamSequence multiplied by the number of fractions.

fredtools.getRNFields(fileName, raiseWarning=True, displayInfo=False)

Get the parameters of each field defined in the RN file.

The function retrieves information for each field defined in the RN dicom file. A consistency check is performed to check the correctness of the parameters written in the RN dicom file.

Parameters:

  • fileName (path) – Path to RN dicom file.

  • raiseWarning (bool, optional) – Raise warnings if the consistency check fails. (def. False)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

DataFrame with the fields’ parameters.

Return type:

pandas DataFrame

See also

getRNSpots

get a summary of parameters for each spot defined in the RN plan.

getRNInfo

get some basic information from the RN plan.

fredtools.getRNSpots(fileName, displayInfo=False)

Get the parameters of each spot defined in the RN file.

The function retrieves information for each spot defined in the RN dicom file. All spots are listed in the results, including the spots with zero meterset weights.

Parameters:

  • fileName (path) – Path to RN dicom file.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

DataFrame with the spots’ parameters.

Return type:

pandas DataFrame

See also

getRNFields

get a summary of parameters for each field defined in the RN plan.

getRNInfo

get some basic information from the RN plan.

fredtools.getRSInfo(fileName, displayInfo=False)

Get some information from the RS structures from the RS dicom file.

The function retrieves some basic information about structures from an RS dicom file.

Parameters:

  • fileName (path) – Path to RS dicom file.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Pandas DataFrame with structures and properties.

Return type:

DataFrame

fredtools.getExternalName(fileName, displayInfo=False)

Get the name of the EXTERNAL structure from RS dicom file.

The function retrieves the name of the structure of type EXTERNAL from an RS dicom file. If more than one structure of type EXTERNAL exists in the RS dicom file, then the first one is returned.

Parameters:

  • fileName (path) – Path to RS dicom file.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

String with the name of the structure of type EXTERNAL.

Return type:

string

See also

getRSInfo

getting information about all structures on the RS dicom file.

fredtools.getCT(fileNames, displayInfo=False)

Get a CT image from dicom series.

The function reads a series of dicom files containing a CT scan and creates an instance of a SimpleITK object. The dicom files should come from the same Series and have the same frame of reference.

Parameters:

  • fileNames (array_like) – An iterable (list, tuple, etc.) of paths to dicoms.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

An object of a SimpleITK image of sitk.sitkInt16 (int16) type.

Return type:

SimpleITK Image

See also

sortDicoms

get names of dicoms in a folder sorted by the dicom type.

fredtools.getPET(fileNames, SUV=True, displayInfo=False)

Get a PET image from dicom series.

The function reads a series of dicom files containing a PET scan and creates an instance of a SimpleITK object. The dicom files should come from the same Series and have the same frame of reference.

Parameters:

  • fileNames (array_like) – An iterable (list, tuple, etc.) of paths to dicoms.

  • SUV (bool, optional) – Determine if the image should be recalculated with the Standardized Uptake Value (SUV). (def. True)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

An object of a SimpleITK image of 16-bit integer type.

Return type:

SimpleITK Image

See also

sortDicoms

get names of dicoms in a folder sorted by the dicom type.

fredtools.getRD(fileNames, displayInfo=False)

Get an image from dicom.

The function reads a single dicom file or an iterable of dicom files and creates an instance or tuple of instances of a SimpleITK object.

Parameters:

  • fileNames (string or array_like) – A path or an iterable (list, tuple, etc.) of paths to dicoms.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

An Object or tuple of objects of a SimpleITK image.

Return type:

SimpleITK Image or tuple

See also

sortDicoms

get names of dicoms in a folder sorted by the dicom type.

fredtools.getRDFileNameForFieldNumber(fileNames, fieldNumber, displayInfo=False)

Get the file name of the RD dose dicom of for the given field number.

The function searches for the RD dose dicom file for a given field number (beam number) and returns its file name.

Parameters:

  • fileNames (array_like) – An iterable (list, tuple, etc.) of paths to RD dicoms.

  • fieldNumber (scalar, int) – Field number to find the dicom for.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Path to the RD dose file for the given beam number.

Return type:

Path string

fredtools.anonymizeDicoms(fileNames, removePrivateTags=False, displayInfo=False)

Anonymize dicom files.

The function anonymizes dicom files given as an iterable of file paths. The function overwrites the original files.

Parameters:

  • fileNames (array_like) – An iterable (list, tuple, etc.) of paths to DICOM files.

  • removePrivateTags (bool, optional) – Determine if the private tags should be removed. (def. False)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Other formats

fredtools.readOPG(fileName, depth=0, displayInfo=False)

Read OPG files from OmniPro software.

The function reads a single OPG file exported from OmniPro software (IBA) and creates an instance of a SimpleITK object.

Parameters:

  • fileName (string) – A path to OPG file.

  • depth (scalar, optional) – A scalar defining the depth of a 3D image. Usually, it is the depth of the measurement. (def. 0)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

An object a SimpleITK image.

Return type:

SimpleITK Image