gulp>> QQ>> 返回
项目作者： adam10514

项目描述 ：
I don'n know what's this? But I want to know what's this lol
高级语言： Matlab
项目地址: git://github.com/adam10514/QQ.git
创建时间： 2017-08-29T06:01:59Z
项目社区：https://github.com/adam10514/QQ
开源协议：GNU General Public License v3.0
下载


DICOM Manipulation Tools for MATLAB®

by Mark Geurts mark.w.geurts@gmail.com

Copyright © 2016, 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:

  • path: string containing the path to the DICOM files
  • names: cell array of strings containing all files to be loaded

The following variables are returned upon succesful completion:

  • image: structure containing the image data, dimensions, width, type, start coordinates, and key DICOM header values. The data is a three dimensional array of CT values, while the dimensions, width, and start fields are three element vectors. The DICOM header values are returned as a strings.

Below is an example of how this function is used:

  1. path = '/path/to/files/';
  2. names = {
  3.     '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.1.dcm'
  4.     '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.2.dcm'
  5.     '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.3.dcm'
  6. };
  7. 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:

  • varargin{1}: string containing the path to the DICOM files
  • varargin{2}: string containing the DICOM RTSS file to be loaded
  • varargin{3}: structure of reference image. Must include a frameRefUID field referencing the structure set, as well as dimensions, width, and start fields. See LoadDICOMImages() for more information.
  • varargin{4} (optional): cell array of atlas names, include/exclude regex statements, and load flags (if zero, matched structures will not be loaded)

The following variable is returned upon succesful completion:

  • structures: cell array of structure names, color, frameRefUID, and 3D mask array of same size as reference image containing fraction of voxel inclusion in structure

Below are examples of how this function is used:

  1. % Load DICOM images  
  2. path = '/path/to/files/';  
  3. names = { 
  4.     '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.1.dcm' 
  5.     '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.2.dcm'
  6.     '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.3.dcm'  
  7. };  
  8. image = LoadDICOMImages(path, names);
  10. % Load DICOM structure set   
  11. name = '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641579.747.dcm';  
  12. structures = LoadDICOMStructures(path, name, image);
  14. % Load structure set again, this time with atlas  
  15. atlas = LoadAtlas('atlas.xml');  
  16. 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:

  • path: string containing the path to the DICOM files
  • name: string containing the file name

The following variables are returned upon succesful completion:

  • dose: structure containing the image data, dimensions, width, start coordinates, and key DICOM header values. The data is a three dimensional array of dose values in the units specified in the DICOM header, while the dimensions, width, and start fields are three element vectors. The DICOM header values are returned as strings.

Below is an example of how this function is used:

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

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:

  • varargin{1}: structure containing the image data. Must contain start, width, and data fields. See LoadDICOMImages() for more information on the format of this object. Start and widths are in cm.
  • varargin{2}: string containing the path and prefix to write the DICOM CT files to. Names will be appended with _NUM.dcm, where NUM is the slice number. MATLAB must have write access to this location to execute successfully.
  • varargin{3} (optional): structure containing the following DICOM header fields: patientName, patientID, patientBirthDate, patientSex, patientAge, classUID, studyUID, seriesUID, frameRefUID, instanceUIDs, and seriesDescription. Note, not all fields must be provided to execute.

The following variables are returned upon successful completion:

  • varargout{1} (optional): cell array of image SOP instance UIDs

Below is an example of how this function is used:

  1. % Create a random array of dose values with 120 slices
  2. image.data = rand(512, 512, 120);
  4. % Specify start coordinates of array (in cm)
  5. image.start = [-25, -25, -15];
  7. % Specify voxel size (in cm)
  8. image.width = [0.098, 0.098, 0.25];
  10. % Declare file name prefix and path to write dose to
  11. dest = '/path_to_file/images';
  13. % Declare DICOM Header information
  14. info.patientName = 'DOE,JANE';
  15. info.patientID = '12345678';
  16. info.frameRefUID = ...
  17. '2.16.840.1.114362.1.6.4.3.141209.9459257770.378448688.100.4';
  19. % Execute WriteDICOMImage
  20. WriteDICOMImage(image, dest, info);

WriteDICOMStructures

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

The following variables are required for proper execution:

  • varargin{1}: structure containing the structures. Must contain name, color, and points fields. See LoadDICOMStructures() for more information on the format of this object. Point positions are in cm.
  • varargin{2}: string containing the path and name to write the DICOM RTSS file to. MATLAB must have write access to this location to execute successfully.
  • varargin{3} (optional): structure containing the following DICOM header fields: patientName, patientID, patientBirthDate, patientSex, patientAge, classUID, studyUID, seriesUID, frameRefUID, instanceUIDs, and seriesDescription. Note, not all fields must be provided to execute.

The following variables are returned upon successful completion:

  • varargout{1} (optional): structure set SOP instance UID

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:

  • varargin{1}: structure containing the calculated dose. Must contain start, width, and data fields. See LoadDICOMDose() for more information on the format of this object. Start and widths are in cm.
  • varargin{2}: string containing the path and name to write the DICOM RTDOSE file to. MATLAB must have write access to this location to execute successfully.
  • varargin{3} (optional): structure containing the following DICOM header fields: patientName, patientID, patientBirthDate, patientSex, patientAge, classUID, studyUID, seriesUID, frameRefUID, instanceUIDs, and seriesDescription. Note, not all fields must be provided to execute.

Below is an example of how this function is used:

  1. % Create a random array of dose values with 120 slices
  2. dose.data = rand(512, 512, 120);
  4. % Specify start coordinates of array (in cm)
  5. dose.start = [-25, -25, -15];
  7. % Specify voxel size (in cm)
  8. dose.width = [0.098, 0.098, 0.25];
  10. % Declare file name and path to write dose to
  11. dest = '/path_to_file/dose.dcm';
  13. % Declare DICOM Header information
  14. info.patientName = 'DOE,JANE';
  15. info.patientID = '12345678';
  16. info.frameRefUID = ...
  17.     '2.16.840.1.114362.1.6.4.3.141209.9459257770.378448688.100.4';
  19. % Execute WriteDICOMDose
  20. 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:

  • plan: structure containing the calculated plan information. See tomo_extract/LoadPlan.m for more information on the format of this structure.
  • file: string containing the path and name to write the DICOM RTDOSE file to. MATLAB must have write access to this location to execute successfully.

The following variables are returned upon successful completion:

  • varargout{1} (optional): RT plan SOP instance UID

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

  1. % Look for plans within a patient archive   
  2. plans = FindPlans('/path/to/archive', 'name_patient.xml');
  4. % Load the first plan   
  5. plan = LoadPlan('/path/to/archive', 'name_patient.xml', plans{1});
  7. % Execute WriteDICOMTomoPlan   
  8. dest = '/file/to/write/plan/to/info.dcm';   
  9. 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:

  • varargin{1}: structure containing the CT image data and structure set data. See LoadDICOMImages() and LoadDICOMStructures() for more information on the format of this object.
  • varargin{2}: structure containing the calculated dose. Must contain start, width, and data fields. See CalcDose for more information on the format of this object. Start and widths are in cm.
  • varargin{3} (optional): string containing the path and name to write the DVH .csv file to. MATLAB must have write access to this location to execute. If not provided, a DVH file will not be saved.

The following variables are returned upon succesful completion:

  • varargout{1} (optional): a 1001 by n+1 array of cumulative DVH values for n structures where n+1 is the x-axis value (separated into 1001 bins).

Below are examples of how this function is used:

  1. % Load DICOM images
  2. path = '/path/to/files/';
  3. names = {
  4.     '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.1.dcm'
  5.     '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.2.dcm'
  6.     '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641582.274.3.dcm'
  7. };
  8. image = LoadDICOMImages(path, names);
  10. % Load DICOM structure set into image structure
  11. name = '2.16.840.1.114362.1.5.1.0.101218.5981035325.299641579.747.dcm';
  12. image.structures = LoadDICOMStructures(path, name, image);
  14. % Create dose array with same dimensions and coordinates as image
  15. dose.data = rand(size(image.data));
  16. dose.width = image.width;
  17. dose.start = image.start;
  19. % Declare file name and path to write DVH to
  20. dest = '/path_to_file/dvh.csv';
  22. % Execute WriteDVH
  23. WriteDVH(image, dose, dest);
  25. % Execute WriteDVH again, this time returning the DVH as an array
  26. dvh = WriteDVH(image, dose, dest);
  28. % Compute but do not save the DVH to a file
  29. 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/.