Home

Awesome

DICOM Manipulation Tools for MATLAB®

by Mark Geurts mark.w.geurts@gmail.com <br>Copyright © 2016-2018, University of Wisconsin Board of Regents

The DICOM Manipulation Tools for MATLAB are a compilation of functions that read and write DICOM RT files. These tools are used in various applications, including exit_detector, systematic_error and mvct_dose. MATLAB is a registered trademark of MathWorks Inc.

Contents

Installation and Use

To install the DICOM Manipulation Tools, copy all MATLAB .m files from this repository into your MATLAB path. If installing as a submodule into another git repository, execute git submodule add https://github.com/mwgeurts/dicom_tools.

Compatibility and Requirements

The DICOM Manipulation Tools have been validated for MATLAB versions 8.3 through 8.5 on Macintosh OSX 10.8 (Mountain Lion) through 10.10 (Yosemite). These tools use the Image Processing Toolbox MATLAB functions dicominfo(), dicomread(), and dicomwrite() to read and write to the provided DICOM destination files.

Tools and Examples

The following subsections describe what inputs and return variables are used, and provides examples for basic operation of each tool. For more information, refer to the documentation within the source code.

LoadDICOMImages

LoadDICOMImages() loads a series of single-frame DICOM CT images and returns a formatted structure for dose calculation. See below for more information on the structure format. This function will display a progress bar while it loads (unless MATLAB was executed with the -nodisplay, -nodesktop, or -noFigureWindows flags).

Note, non-HFS and multi-frame datasets have not currently been tested, so their compatibility with this function is unknown.

The following variables are required for proper execution:

The following variables are returned upon succesful completion:

Below is an example of how this function is used:

path = '/path/to/files/';
names = {
    '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.1.dcm'
    '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.2.dcm'
    '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.3.dcm'
};
image = LoadDICOMImages(path, names);

LoadDICOMStructures

LoadDICOMStructures() loads a DICOM RT Structure Set (RTSS) file andextracts the structure information into a MATLAB cell array. See below for more information on the structure format. This function mayoptionally also be passed with an atlas, whereby only structures matchingthe atlas include/exclude statements are returned. This function will display a progress bar while it loads (unless MATLAB was executed with the -nodisplay, -nodesktop, or -noFigureWindows flags).

The following variables are required for proper execution:

The following variable is returned upon succesful completion:

Below are examples of how this function is used:

% Load DICOM images  
path = '/path/to/files/';  
names = { 
    '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.1.dcm' 
    '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.2.dcm'
    '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.3.dcm'  
};  
image = LoadDICOMImages(path, names);

% Load DICOM structure set   
name = '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641579.747.dcm';  
structures = LoadDICOMStructures(path, name, image);

% Load structure set again, this time with atlas  
atlas = LoadAtlas('atlas.xml');  
structures = LoadDICOMStructures(path, name, image, atlas);

LoadDICOMDose

LoadDICOMDose() loads a DICOM RTDose object into a MATLAB structure that can be used for manipulation with other functions in this library.

The following variables are required for proper execution:

The following variables are returned upon succesful completion:

Below is an example of how this function is used:

path = '/path/to/files/';
name = '1.2.826.0.1.3680043.2.200.1679117636.903.83681.339.dcm';
dose = LoadDICOMDose(path, name);

Load3ddose

Load3ddose loads a DOSEXYZnrc .3ddose file into a MATLAB structure that can be used for manipulation with other functions in this library. The file format was obtained from the DOSEXYZnrc user manual for version PIRS-794revB, https://nrc-cnrc.github.io/EGSnrc/doc/pirs794-dosxyznrc.pdf

The following variables are required for proper execution:

The following variables are returned upon succesful completion:

Below is an example of how this function is used:

path = '/path/to/files/';
name = 'example.3ddose';
dose = Load3ddose(path, name);

ScanDICOMPath

ScanDICOMPath recursively searches a provided path for DICOM data and returns a cell array of DICOM images, RT structure sets, RT plan, and RT dose files along with basic header information found within the directory. DICOM files must contain the following minimum tags: SOPInstanceUID, MediaStorageSOPClassUID, Modality, PatientName, and PatientID.

This function will display a progress bar while it loads unless MATLAB was executed with the -nodisplay, -nodesktop, or -noFigureWindows flags or if a Progress input option is set to false. If the DOSEXYZnrc input option is set to true, this function will also identify DOSEXYZnrc Monte Carlo calculated dose files with a .3ddose extension and add them as RTDOSE options.

The following variables are required for proper execution:

Upon successful completion, the function will return an n x 11 cell array, where n is the number of files returned and the columns correspond to the following values:

Below are examples of how this function is used:

% Scan test_directory for DICOM files
list = ScanDICOMPath('../test_directory');

% Re-scan, hiding the progress bar and including DOSEXYZnrc files
list = ScanDICOMPath('../test_directory', 'Progress', false, ...
    'DOSEXYZnrc', true);

% List all CT file names found within the list
list(ismember(t(:,3), 'CT'))

% List all unique Frame of Reference UIDs in the list
unique(list(:,7))

WriteDICOMImage

WriteDICOMImage() saves the provided image array to a series of DICOM CT files. If DICOM header information is provided in the third input argument, it will be used to populate the DICOM header for associating the image set with a DICOM RTDOSE file.

The following variables are required for proper execution:

The following variables are returned upon successful completion:

Below is an example of how this function is used:

% Create a random array of dose values with 120 slices
image.data = rand(512, 512, 120);

% Specify start coordinates of array (in cm)
image.start = [-25, -25, -15];

% Specify voxel size (in cm)
image.width = [0.098, 0.098, 0.25];

% Declare file name prefix and path to write dose to
dest = '/path_to_file/images';

% Declare DICOM Header information
info.patientName = 'DOE,JANE';
info.patientID = '12345678';
info.frameRefUID = ...
'2.16.840.1.114362.1.6.4.3.141209.9459257770.378448688.100.4';

% Execute WriteDICOMImage
WriteDICOMImage(image, dest, info);

WriteDICOMStructures

WriteDICOMStructures() saves the provided structure set to a DICOM file.

The following variables are required for proper execution:

The following variables are returned upon successful completion:

WriteDICOMDose

WriteDICOMDose() saves the provided dose array to a DICOM RTDOSE file. If DICOM header information is provided in the third input argument, it will be used to populate the DICOM header for associating the DICOM RTDOSE file with an image set.

The following variables are required for proper execution:

Below is an example of how this function is used:

% Create a random array of dose values with 120 slices
dose.data = rand(512, 512, 120);

% Specify start coordinates of array (in cm)
dose.start = [-25, -25, -15];

% Specify voxel size (in cm)
dose.width = [0.098, 0.098, 0.25];

% Declare file name and path to write dose to
dest = '/path_to_file/dose.dcm';

% Declare DICOM Header information
info.patientName = 'DOE,JANE';
info.patientID = '12345678';
info.frameRefUID = ...
    '2.16.840.1.114362.1.6.4.3.141209.9459257770.378448688.100.4';

% Execute WriteDICOMDose
WriteDICOMDose(dose, dest, info);

WriteDICOMTomoPlan

WriteDICOMTomoPlan() saves the provided tomotherapy plan structure to a DICOM RTPlan file. If the patient demographics (name, ID, etc) are not included in the plan structure, the user will be prompted to provide them.

The following variables are required for proper execution:

The following variables are returned upon successful completion:

Below is an example of how this function is used (the functions FindPlans() and LoadPlan() are from the tomo_extract repository:

% Look for plans within a patient archive   
plans = FindPlans('/path/to/archive', 'name_patient.xml');

% Load the first plan   
plan = LoadPlan('/path/to/archive', 'name_patient.xml', plans{1});

% Execute WriteDICOMTomoPlan   
dest = '/file/to/write/plan/to/info.dcm';   
WriteDICOMTomoPlan(plan, dest);

WriteDVH

WriteDVH() computes the DVH for each structure included in the image input variable given the dose input variable and writes the resulting DVHs to a comma-separated value file. The DVHs can also be optionally returned as an array. Note, if a DVH filename is not provided in the third input argument, WriteDVH will simply compute the DVH from the image, structures, and dose and optionally return the array.

The first row contains the file name, the second row contains column headers for each structure set (including the volume in cc in parentheses), with each subsequent row containing the percent volume of each structure at or above the dose specified in the first column (in Gy). The resolution is determined by dividing the maximum dose by 1001.

The following variables are required for proper execution:

The following variables are returned upon succesful completion:

Below are examples of how this function is used:

% Load DICOM images
path = '/path/to/files/';
names = {
    '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.1.dcm'
    '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.2.dcm'
    '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.3.dcm'
};
image = LoadDICOMImages(path, names);

% Load DICOM structure set into image structure
name = '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641579.747.dcm';
image.structures = LoadDICOMStructures(path, name, image);

% Create dose array with same dimensions and coordinates as image
dose.data = rand(size(image.data));
dose.width = image.width;
dose.start = image.start;

% Declare file name and path to write DVH to
dest = '/path_to_file/dvh.csv';

% Execute WriteDVH
WriteDVH(image, dose, dest);

% Execute WriteDVH again, this time returning the DVH as an array
dvh = WriteDVH(image, dose, dest);

% Compute but do not save the DVH to a file
dvh = WriteDVH(image, dose);

Event Calling

These functions optionally return execution status and error information to an Event() function. If available in the MATLAB path, Event() will be called with one or two variables: the first variable is a string containing the status information, while the second is the status classification (WARN or ERROR). If the status information is only informative, the second argument is not included. Finally, if no Event() function is available errors will still be thrown via the standard error() MATLAB function.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.