User's Guide


Current for CERR version 2.1

(This instruction manual was last modified on 4-Nov-03)

Latest modifications [top]

  1. Mar 28, 2007 Version: 3.0 beta 4
    DICOM import now Matlab 6.5 compatible.

  2. Mar 28, 2007 Version: 3.0 beta 4
    Fixed bug where dose scaled did not work - dose management.

  3. Mar 28, 2007 Version: 3.0 beta 4
    Fixed bug where DICOM import broke when deleting segments with less than 3 points - dicomrt_validatevoi.m.

  4. Mar 28, 2007 Version: 3.0 beta 4
    Fixed bug where Navigation montage did not refresh on merging plan.

  5. Mar 28, 2007 Version: 3.0 beta 4
    Fixed bug where showing new structure-set by right mouse click did not work.

  6. Mar 28, 2007 Version: 3.0 beta 4
    Added NTCP modeling tool – accessible via “Metrics” drop-down menu.

  7. Mar 28, 2007 Version: 3.0 beta 4
    Added support for transformation matrices for dose addition / subtraction – accessible via “Dose” drop-down menu.

  8. Mar 28, 2007 Version: 3.0 beta 4
    Added feature to convert iso-dose level to structure – accessible via CERR command line.

  9. Dec 22, 2006 Version: 3.0 beta 3
    Description: Error using showIMDose (IMRTP) function due to duplicate dose2CERR file. CERR Versions Affected: CERR 3.0 beta2 and below. Fix : Removed dose2CERR.m from CERR distribution.

  10. Dec 22, 2006 Version: 3.0 beta 3
    Description: CERR produced incorrect results (DVH, IVH..) for scans with unequal x and y dimensions. CERR Versions Affected: CERR 3.0 beta2 and below. Fix : Corrected getRasterSegs.m, getDVH.m, getIVH.m, poly2Edges.m, createDummyScan.m functions.

  11. May 17, 2006 Version: 2.6.8
    Error in RTOG import Description: Incorrect input parameters to deduceVoxelThicknesses.m and getDSHPoints.m from importRTOGDir.m. For example, deduceVoxelThicknesses has input parameter planC in CERR2 while it has input parameters structNum and planC in CERR3 (under development). The input parameters similar to CERR3 were erroneously used in the above two functions in CERR2.6.7 Effects: CERR broke down during RTOG import. CERR Versions Affected: CERR 2.6.7 Fix: Corrected input parameters to deduceVoxelThickness.m and getDSHPoints.m from importRTOGDir.m

  12. May 17, 2006 Version: 2.6.8
    Error in contouring the first structure Description: Length of planC{indexS.structures} is equal to 1 when this field is initialized. This made CERR think that there is one structure present and hence, an empty structure was shown. Note that planC{indexS.structures}(structNum).contour is initialized for each structure when created. This was not done for the 1st structure as it was never created, but was just initialized during CERR initialization. Effects: CERR broke when the 1st contour was saved. CERR Versions Affected: 2.6.7 and below Fix: Check if length of planC{indexS.structures} equals to 1. If it is equal to 1, then check if contour field of this first structure is empty. If it is empty, this means there are no structures in planC and hence assign planC{indexS.structures}(1) = [ ]; This is done in putStructMenu.

  13. May 17, 2006 Version: 2.6.8
    Error in importing old archives Description: Plans converted by CERR2.1 have two extra slices after uniformization. Effects: CERR broke down during loading this plan CERR Versions Affected: CERR 2.6.1 to 2.6.7 broke down although 2.6.7 and below the previous versions had incorrect uniformization even if they did not break. Fix: added code inside isUniformized.m function to check for correctness of uniformization. Hence, every time a plan is loaded or we use isUniformized function, we go through this check.

  14. May 17, 2006 Version: 2.6.8
    Error in DICOM import for MATLAB version 7.0.0 Description: MATLAB 7.0.0 does not support 32 Bit dose Import for multiframe data Effects: CERR broke down during DICOM import. CERR Versions Affected: -- Fix: use MATLAB 7.0.4

  15. May 17, 2006 Version: 2.6.8
    Error in importing DICOM for MATLAB version 7.1 Description: MATLAB 7.1 does not support DICOM structure import Effects: CERR broke down during DICOM import. CERR Versions Affected: -- Fix: Contact Mathworks for replacement file.

  16. May 17, 2006 Version: 2.6.8
    Error in DICOM import of empty structures Description: study_array{i,2} variable is empty for empty structure in dicomrt_d2c_voi.m. Hence, accessing its contour points caused this bug. Effects: DICOM import breaks when empty structure present CERR Versions Affected: -- 2.6.7 and below Fix: Used “try” statement to access study_array{i,2} contour points.

  17. May 17, 2006 Version: 2.6.8
    Error in DICOM import of dose when patient position is FFS Description: 1. Function askZmesh imports Z value for dose. It gives an option to the user to import dose with/without offset. This function was acting same irrespective of patient position 2. Function dicomrt_d2c_coordsystem.m creates x and y coordinates and offsets. The X coordinate system had to be reoriented for FFS position. Note: Since we don’t have more examples for HFP and FFP position it has still to be tested Effects: Dose does not show up correctly when patient position is other than FFS CERR Versions Affected: -- 2.6.7 and below Fix: adding z – offset based on patient position and reoriented X-coordinate.

  18. May 17, 2006 Version: 2.6.8
    Error in RTOG import of scan for Linux system Description: The dimensions for MAC system is flipped for fread command where as for PC and Linux were not flipped. The isunix command returned true for all OS other than Windows and did not differentiate between MAC, Linux. Therefore variable scanSize was having dimension mismatch. Effects: RTOG import breaks CERR Versions Affected: -- 2.6.7 and below Fix: Added check for OS using command “computer” instead of ispc/isunix in function “ctin”.

  19. May 17, 2006 Version: 2.6.8
    DICOM dose fraction addition Description: RT Dose/ RTPlan can have different number fieldname in each structure. Effects: DICOM Import breaks while dose importing for structure with dissimilar fieldname lengths are present CERR Versions Affected: 2.6.7 and below Fix: Using Function dissimilarInsert.m when appending Dose/Beam information.

  20. May 17, 2006 Version: 2.6.8
    getIMDose breaks while down sampling dose whose indices become non-integers after down sampling Description: Eg. Dose of size 341 x 512 becomes 170.5 x 256 after downsampling. This is not handled correctly in getIMDose (line 100). Effects: Downsampling such doses broke IMRT dose calculations. CERR Versions Affected: 2.6.7 and below Fix: returns error if the size of the matrix is non-integer after downsampling

  21. May 17, 2006 Version: 2.6.8
    Description: sizeOfDimension1 refers to number of columns and sizeOfDimension2 refers to number of rows for dose. This was assigned incorrectly. Effects: CERR broke while a adding new dose. CERR Versions Affected: 2.6.7 and below Fix: Crrected assignments for number of rows and columns.

  22. May 17, 2006 Version: 2.6.8
    ImageWidht was used in calculations irrespective of square/ rectangular image. Description: ImageWidth was used in functions getPBRayData, dose2CERR and getRayTraceSingleROI for various calculations irrespective of square/rectangular image set. Effects: Incorrect dose calculation for rectangular imageSets. CERR Versions Affected: 2.6.7 and below Fix: Used ImageWidth and ImageHeight to be compatible with rectangular imageSets.

  23. May 17, 2006 Version: 2.6.8
    Incorrect Dimensions used inside getUniformStr.m Description: numRows were assigned a value of planC{indexS.scan}.scanInfo(1).sizeOfDimension2 which should have been planC{indexS.scan}.scanInfo(1).sizeOfDimension1 and same for numCols Effects: Dose Calculation broke for dissimilar size of dimensions in x and y CERR Versions Affected: 2.6.7 and below Fix: corrected dimensions

  24. May 17, 2006 Version: 2.6.8
    Added slider bar to scroll through selected structures in IMRTP Description: When more than 12 structures are selected, the panel is overfull Effects: Cannot access or see all of the structures. CERR Versions Affected: 2.6.7 and below Fix: Added a scrollbar to scroll through all selected structures

  25. May 17, 2006 Version: 2.6.8
    Incorrect input parameters to rasterToMask Description: The x and y dimensions were interchanged. Effects: No critical effect since the mask obtained from this function is input to fitDoseToCT which checks if the input mask dimensions with that of original CT scan. If they don’t match, the input mask is ignored. But this mask is needed to cutoff dose lying outside skin, which did not work. CERR Versions Affected: 2.6.7 and below Fix: Corrected the input parameters.

  26. May 17, 2006 Version: 2.6.8
    getIMDose breaks while down sampling dose whose indices become non-integers after down sampling Description: Eg. Dose of size 341 x 512 becomes 170.5 x 256 after downsampling. This is not handled correctly in getIMDose (line 100). Effects: Downsampling such doses broke IMRT dose calculations. CERR Versions Affected: 2.6.7 and below Fix: returns error if the size of the matrix is non-integer after downsampling

  27. May 17, 2006 Version: 2.6.8
    sizeOfDimension1, sizeOfDimension2 not assigned correctly for new dose Description: sizeOfDimension1 refers to number of columns and sizeOfDimension2 refers to number of rows for dose. This was assigned incorrectly. Effects: CERR broke while a adding new dose. CERR Versions Affected: 2.6.7 and below Fix: Crrected assignments for number of rows and columns.

  28. May 17, 2006 Version: 2.6.8
    ImageWidht was used in calculations irrespective of square/ rectangular image. Description: ImageWidth was used in functions getPBRayData, dose2CERR and getRayTraceSingleROI for various calculations irrespective of square/rectangular image set. Effects: Incorrect dose calculation for rectangular imageSets. CERR Versions Affected: 2.6.7 and below Fix: Used ImageWidth and ImageHeight to be compatible with rectangular imageSets.

  29. May 17, 2006 Version: 2.6.8
    MATLAB 6.5 does not support mathematical operations between single Description: Line 86, 90, 231 and 333 doseShadowGUI. Effects: Dose shadow breaks on matlab version 6.5 CERR Versions Affected: 2.6.7 and below Fix: Changing to from single to double

  30. May 17, 2006 Version: 2.6.8
    MATLAB 6.5 does not support mathematical operations between uint data type Description: line 416, 429 dicomrt_DICOMimport () Effects: DIOCM import breaks on matlab version 6.5 CERR Versions Affected: 2.6.7 and below Fix: “item2_1_dose=uint16 (item2_1_dose – 1)” changed to “item2_1_dose=uint16 (item2_1_dose);”

  31. May 17, 2006 Version: 2.6.8
    Description: Delay in importing caused while determining VR for attribute (0028, 0120). This is specifically found in Tomotherapy DICOM data. Effects: DIOCM import slows down tremendously. CERR Versions Affected: 2.6.7 and below Fix: Added line 21 “warning off Images: genericDICOM” in file “CERRImportDICOM.m”

  32. May 17, 2006 Version: 2.6.8
    Description: while importing structures if the structure names have non - English characters then MATLAB hangs. Effects: DIOCM import breaks on matlab version 6.5 for linux CERR Versions Affected: 2.6.7 and below Fix: No fix from MATLAB. Don’t import structures with non – English characters.

  33. Mar 17, 2006 Version: 2.6.7
    Fixed a bug in uniformization where sliceThickness (which comes directly from scanner) was used to set slice thickness for uniform slices. Fixed a bug in "maskToRaster" function in order to obtain single-point raster segments. Added an option to fill slice gaps under "Derive new structure".

  34. Feb 28, 2006 Version: 2.6.6
    Corrected a bug in input parameters to 'finterp3.m' from 'getDVH.m' that caused incorrect calculation of DVH. Reverted back to scanPoly.m for filling-up polygon (instead of fastPolyfill.m)

  35. Feb 22, 2006 Version: 2.6.5
    Fixed bug in metrics Comparison. DVHBinWIdth is set automatically if not previously set in old archives. Found thanks to Elinore Wieslander. Fixed bug and recommissioned 'fastPolyfill' that generates masks for structures

  36. Oct 25, 2005 Version: 2.6 beta 6
    Just a notice that we have had a change of personnel. James Alaly who did a fantastic job for us the last two years, has now moved on to the University of Missourri's School of Medicine. We now have two new able programmers filling his shoes: Divya Khullar and Aditya Apte (aapte@radonc.wustl.edu). Aditya will be the main contact person for CERR email, though we will all consider feedback.

  37. Jan 05, 2005 Version: 2.6 beta 6
    Fixed bug in DVH display, where an incorrect value was used to find the middle of each bin. Found thanks to Jeff Craig.

    Fixed bug when creating DVH of old plans that caused a crash when accessing field fractGroupIDOfOrigin.

  38. Nov 15, 2004 Version: 2.6 beta 5
    Added new colorbar options, accessible from the View menu.

    Added fields to CERROptions.m and a GUI that controls downsampling of large dose distributions at import. (Ex. Corvus).

    Fixed bug in doseSubtraction interpolation size. Found thanks to Elinore Wieslander.

    Fixed bug in IMRT, where pencil beams with no influence contribution would crash. Found thanks to Michael Merritt.

    Fixed bug where isodose lines displayed incorrectly in Matlab 7.0.1+. Found thanks to Chris Peters.

    Fixed bug where importing RTOG dose arrays without the same number of x, y elements crashed. Found thanks to Jong Kung.

    Fixed several bugs that caused crashes when using CERR in Matlab 6.1.

    Speed improvements in code that updates uniform structure data.

  39. Oct 21, 2004 Version: 2.6 beta 4
    Fixed a bug where "Derive New Structure" crashed in ML7.

    Fixed a bug where the IMRT GUI crashed when loading old IMSetup.m files.

CERR Bug and defect list [top]

Bugs and defects are rated according to severity:  1 - program operates but gives the wrong answer; 2 - program fails; 3 - inconsistent or unexpected operation; 4 - Program functionality is missing or inappropriate; 5 - inconsistent or incorrect documentation; 6 - missing documentation (these defects are not always listed here).

  1. Severity 3.  Some old plans without raster segments or uniformized data may not function properly in functions that require this data. Raster segments should be dynamically generated but uniformized data will not. Fix will be released soon.

  2. Severity 3.  If the DVH plot grid lines are turned off, and then the plots are closed, and new DVH plots are created, the grid lines may be missing.

  3. Severity 6.  Many m-files have incomplete or inconsistent header information.

  4. Severity 2.  3-d doens't work if there is no 'skin' structure.

  5. Severity 3.  After finishing contouring, sometimes contours are not updated, and contours from new and old slice are both shown.

Why you shouldn't use CERR version 1:  There were several bugs and small inaccuracies in the slice viewer and DVH calculator.  We are now testing CERR against commercial planning systems, and have seen good results thus far.

About License and copyright issues [top]

As stated in many of the main m-files and the 'about CERR' message, the license reads as follows:

"This software is copyright J. O. Deasy and Washington University in St Louis.  A free license is granted to use or modify but only for uses which are non-commercial and non-clinical.  In particular, clinical decisions should not be made based on the use of CERR.  Use of CERR to design or test commercial products is not granted without an agreement with Washington University.  Any user-modified software must retain the original copyright and notice of changes if redistributed.  Any user-contributed software (not modifications of existing files) will retain the copyright terms of the contributor.  No warranty or fitness is expressed or implied for any purpose whatsoever--use at your own risk."  

In other words, research use is completely free from fees or restrictions on code use with the limitations stated above. Use for making clinical patient care decisions is explicitly forbidden.

Use to design or test commercial products is explicitly forbidden without an agreement with Washington University.

Although users are granted the right to modify any CERR routine in any way, this right does not include commercial or clinical use, as outlined above.

The philosophy here is that institutions should not feel that contributing 'open source' code and tools to interoperate with CERR compromises potential commercial rights.

All the files supplied from Washington University have these same copyright terms, whether explicitly written in the file or not.

System and software requirements [top]

Q.  What version of Matlab do I need?

A. CERR works with Matlab ver. 6.5 and has (nearly) bug-free operation with ver. 6.1.  CERR does not require any 'Toolboxes'.  CERR will not work with Matlab ver. 5 as it uses ver. 6 data structures.  

Q.  What systems does it run on?  

A.  This release only runs on Matlab and Windows NT, 2000, or XP.  We are currently working on a Linux release (there currently are two users who have run CERR on Linux as-is with very minor issues).

Q.  How much memory do I need?  

A.  To operate comfortably, we estimate that you will need memory equal to the archive size you want to view plus at least 100 MB.

Q.  What systems has CERR successfully imported from?

A.  (1)  NOMOS Peacock (2) ADAC Pinnacle (3) MIR old 3D system (4) HELAX - TMS V. 6.  (5) Computerized Medical Systems, Inc., Xeo.  We are trying to grow this list.  Please contact us if you have another academic or commercial system which you would like to try.

Installation and quick start instructions [top]

Q. How do I install CERR?

A. Unzip the CERR program archive. Then put it on your path using the usual setpath GUI or command line path tool in Matlab.

Q. How do I view stored CERR archives?

A. Type 'CERR', select Viewer, and select the .mat or .bz2 archive.

Q.  How do I close CERR?

A. Close the transverse viewer window in the usual way for that operating system.  All the other CERR windows should close automatically, except for the CERR main menu.

Arrow keys will change the slice for all three slice viewers (transverse, sagittal and coronal). The correct arrow to push is the one aligned with the slider-bar direction desired.

Changing slices on the transverse view, with the colorwash option and the structures and scan on, takes about one second on a fast (2 GHz) PC for 512x512 plans and .25 seconds for 256x256. Cached slices display much faster.

Many of the program options are described and set in the file CERROptions.m.  The options and their selectable values are documented there. This file is automatically loaded when CERRSliceViewer is invoked. You can change any options and reload them by issuing the 'reload options' command at the transverse viewer command line, and then selecting the (possibly different) options file desired.

The CERR directory structure [top]

Note:  directories which are appended 'beta' are, well, beta.

Directory Holds
3D Volumetric viewer including transparent structures/dose surfaces
CommandLine CERR command line command definitions
Compiled Build directory for compiled version.
Compression Compression files based on the use of bzip2
Contouring Structure contouring-related m-files
CrossListing CERR code crosslisting and getDirFunInfo.m, which creates the crosslisting
Documentation cerr_user_instructions.html, this file.
Extras Miscellaneous directories, including some script examples
ImageRegistration BETA tools for registering images. Very Incomplete.
Importing Importing tools for RTOG archives
Labbook Tool to capture annotate and build CERR images into html files.
PlanAnalysis Dose volume histograms, dose surface histograms, and other analysis tools
PlanMetrics Various metrics and a template to create new metrics.
RTOG Specification An ASCII text file describing the RTOG specification used for CERR.
ScanConversion m-files which convert polygonal contours into 0-1 masks and then into the stored scan format
Uniformization m-files related to creation of CT scan set with uniform z-spacing, and registered voxel masks of structures
UserDefined A directory for users to put commands
Utilities Various utility routines, including several text parsing tools.
Viewers GUI-related m-files
WindowsMex Windows mex code

Importing RTOG/DICOM archives [top]

Q. How do I read in and convert an AAPM/RTOG or DICOM archive formatted directory into CERR format?

A. RTOG: First look at the file CERROptions.m. In the section labeled 'importing' are several self-explanatory options concerning what will be read in, etc. Then type 'CERR' and click RTOG. Then select the aapm0000 (or other '000') file to get started. After conversion, you will be asked what to name the resulting file and whether to compress the archive.

DICOM: CERR can now import via the DICOM-RT mechanism (in Matlab 65.) using Emiliano Spezi's DICOM-RT toolbox. Type 'CERR' and click DICOM. Then select a directory to scan for DICOM files. Once the scan is complete a text prompt will ask what studies/scans/doses to import. See DICOM-RT-toolbox-v2/docs directory for more information.

About compressed archives [top]

Why does CERR use compression with bzip2?  Because it can save up to 90% of disk space (for 256 x 256 CT scan images, somewhat less for plans with standard 512 x 512 CT scan sets). This is significantly more than what zip or gzip gives.

Q.  I opened a compressed archive in CERR and it is now uncompressed. I would like a compressed version. How can I get it?

A. Select the 'Save' button on the transverse slice viewer. It will ask you if you want to compress the archive.

Q.  I opened a .bz2 (bzipped) CERR archive, but now it has disappeared. What happened?

A. The current default behavior is to unzip and create the corresponding .mat file. The assumption is that the compressed file is primarily for transfer, and it will be more convenient to have the unzipped version for actual use.

Q.  I tried to create a new compressed archive, but it failed. Why?  

A.  Compression will fail if a compressed archive with the same name already eixsts in the target directory.  Look for a message to this effect on the console. We feel this is safer than automatically overwriting an existing directory (which is the only other option).

About dose display [top]

There are three principle methods of dose display (see table of options):

  1. Isodose lines.

  2. Colorwash.

  3. Visual reference colorwash.  This is a colorwash where the colormap is rescaled for every new dose distribution:  doses above a visual reference dose are shown in inverted gray scale (black the highest dose, white the reference dose), whereas doses below that level are shown in another colormap.  This orients the viewer as to what doses are above some 'prescription' reference.

CERR is currently not very fast at slice paging to the next dose display:  when colorwash is on on, it takes about 1 second to change slices on a 2 GHz Pentium IV machine.  We have made efforts, though limited, to speed up slice paging.  Faster computers will make this unirritating fast, even on laptops (well, in a few years).  Alternatively, sophisticated methods could be used to speed things up, such as more compiled code, or 'look ahead' computing in preparation for the next slice before the user requests it, etc. UPDATE: we have made good progress in speeding up paging.

Contouring anatomical structures [top]

Q.  How do I contour a new or old structure?

A. CERR contains a relatively complete set of contouring tools under the assumption that new anatomical regions may need to be defined or previous geometrical definitions may need to be adjusted.

The typical contouring process is as follows:

  1. From the 'Structures' pull-down menu on the transverse slice viewer, choose either an already defined structure or the 'New structure' item.

  2. The 'Edit structure fields' window is then raised, which contains editable text boxes showing the values of the structure keyword fields as stored in CERR.

  3. You can start with an existing structure, but change one or more contours.

  4. You may also select the 'Copy to new' button to create a new structure with the same (editable) contours as the structure you started with.

  5. For a completely new structure, select 'New structure,' on the structure pull-down menu in the transverse viewer.  

  6. Typically, the only field which will need to be modified on the structure window is the 'structureName' box (highlighted in red). The new value is stored as soon as it is entered.  Select the 'Contour' button to begin contouring.

Q.  How do the contouring tools work?

A. Of all the contour segments in a structure being contoured, only one is defined as 'active'. It will have a solid linestyle, whereas the non-active contours for that structure will have a dashed linestyle.  Here are descriptions of the contouring tools options:

Dose volume histograms [top]

Q.  How are dose volume histograms computed?

A.  Each CT voxel has associated with it a volume equal to it's cuboid volume.  Voxel widths in the z direction are determined to leave no gaps between CT slices.  Half the inter-slice space belongs to the voxel of the next slice and half belongs to the voxel of the last slice.  We do this even on the 'end cap' slices which are the most superior and inferior of the defined volume of interest.  Dose is linearly interpolated to the voxel center in the slice plane.  Thus determined, the doses and volumes are histogrammed up. If the option ROISampleRate is not equal to 1, voxels are re-weighted to higher volumes.  Generally, the DVH calculator is fast enough to leave ROISampleRate = 1.

How do I plot a dose-volume histogram (DVH)?

Steps:

  1. Click the 'DVH' button on the transverse viewer.

  2. On the DVH menu window, all the previously stored DVHs will be listed in color.

  3. To make a new DVH (for example after a new dose distribution has been chosen), select the 'Add DVH' menu, then the structure.

  4. Then select the type of plot (DVH or DSH (dose-surface histogram)).

  5. Select 'Abs' if you also want an additional plot showing absolute volume or surface area.

Notes:

3-D [top]

The 3-D viewer menu can be raised by entering '3D', or '3-D' or '3-d' in the command line.  The menu has boxes for selecting structures to be included, as well as transparency factors (0 is completely transparent and 1 is completely opaque).  There is a line to select a dose level to be shown as well.  An 'L'-shaped object defines directions:  the red bar points up and the green bar points to the patients left (assuming a head-to-feet scan position).  Currently, the 3-D viewer downsamples images to 128 x 128 in the transverse plane.  To rotate the image, select the 'move camera' option from the figure's  'tools' menu.  Then grab the figure with mouse button 1 to rotate it. 

Dose Shadow [top]

A tool to view the projection of dose within a given structure can be accessed by clicking metrics, dose Shadow and selecting a structure. The max, min, and mean values along every column of pixels within the selected structure is calculated and displayed. The user can then easily see hot or cold spots and by selecting "GOTO SLICE" can force the transverse viewer to display the slice contributing the displayed dose at a point selected with the mouse.

Dose Subtraction [top]

The difference between two doses may be calculated, in order to better visualize what regions one dose effects that another does not. Select dose distributions in the transverse viewer's menubar and choose Dose Subtraction. Select the two doses to be subtracted. The new dose is calculated and stored as (FirstDose - SecondDose), which is displayed in the current window. Dose colors displayed with diagonal hatching are negative, and represent dose included in SecondDose but not FirstDose. Dose colors without hatching represent dose included in FirstDose but not SecondDose. DVHs may be calculated on the difference between two doses, though the max/min/mean values will not reflect reality.

Metrics [top]

A beta tool to compare metrics graphically is included in this version of CERR. Select metrics in the transverse viewer's menubar and choose Metric Comparison. The left hand box contains a list of available metrics. Choose a metric by double clicking it or clicking and using the add arrow. Edit a metric's parameters in the right hand listbox. After the desired metrics have been chosen and their parameters defined, select the doses to be compared by the metrics and click Evaluate. After the metric's values are calculated, a graphical comparison of the doses is displayed.

Structure Combination [top]

A tool to combine, expand or contract structures can be accessed by clicking structures on the toolbar and selecting "derive new structure". Choose an operation on the left, either Union, intersect, subtraction, expansion by x cm or contraction by x cm. Then select the appropriate number of structures from the right. An intermediate structure will appear which can then be used to create structures composed of nested expressions. When you have a function you are happy with and want to add it to the plan, click GO and then click that structure.

User-controlled options settings [top]

All user-controlled option settings are fixed in the CERROptions.m file, which is automatically read at the beginning of every CERRSliceViewer session.  Table 1 contains a list of the options, example values, their purpose, and their valid settings.  The options can be changed and reloaded at any time by typing 'reload options' at the command line.

Table 1.  CERR options read from CERROptions.m [top]

Option field name Valid settings Description
loadCT 'yes' or 'no' Load CT scans into planC?
loadDoseSet 'any' or other string Fraction Group ID (will match with any Fx Grp ID with the same initial letters, independent of case); or to load all this should be 'any'.
loadStructures {'any'} or cell array of structure name strings To load all this should be {'any'}.  E.g., {'lung','spinal','esophagus'}

scanStructures

{'any'} or {'none'} or a cell array of structure name strings structure names to convert to raster/scan segment format for DVH calculations and sagittal/coronal display.  Typically, 'any'.  Any structure whose name matches this name, up to the number of letters given, will have scan segments generated during import. That is, 'lun' will match structures 'lung' or 'lung_all'.
CTEndian 'big' or 'little' Byte ordering of CT scans and digital films.
loadFilm 'any' or 'none' Load digital films?
zipSave 'yes' or 'no' Compress imported plans with bzip2?
createUniformizedDataset 'yes' or 'no' Create uniformized & registered CT and structures datasets during import. The uniformized scan set has a uniform axial (z) spacing and the same transverse resolution as the normal CT-scan (usually, but not always, 512 x 512). The axial spacing is at least as large as optS.smallestUniformCTSliceSpacing. If some part of the original scan has a slice spacing larger than this value, the section with the smallest such slice spacing will be used as part of the 'uniformized' CT dataset.
uniformizedDataType 'uint8' or 'uint16'. Datatype for uniformized dataset.
lowerLimitUniformCTSliceSpacing number, e.g., 0.3 Smallest allowed uniformized slice spacing
upperLimitUniformCTSliceSpacing number, e.g., 0.5 Largest allowed uniformized slice spacing
alternateLimitUniformCTSliceSpacing number, e.g., 0.4 If there are no initial CT slices between the largest and smallest slice width allowed, make a uniformized dataset with this width.
uniformizeExcludeStructs a cell array of structures, e.g., {'skin','normaltissue'} Do not create bit maps of these registered to the uniformized dataset.  Excluding large structures, such as 'normaltissue' can save significant memory.
useDoseScale 'yes' or 'no' (normally 'yes'). Use the key word dose scale on import and multiply the stored dose values times the dose scale to create the doseArray. Note: Some systems, such as one version of the NOMOS planning system, include a 'dose scale' keyword even though the true dose is the 'unscaled' raw doses.
isodoseLevels [L1, L2,...], e.g., [10,20,60] Isodose levels
isodoseThickness number, e.g., 1.5 Thickness of isodose lines
structureThickness number, e.g., 1.5 Thickness of structure lines
isodoseLevelType 'percent' or 'absolute' Meaning of isodoseLevels
displayDoseSet name string The fractionGroupID of the dose distribution to be displayed initially. Defaults to the first dose distribution if this is not available.
tickInterval number, e.g., 1 Ruler tick interval in cm
CTLevel number, e.g., 0 Midpoint of the initial CT window in Hounsfield units
CTWidth number, e.g., 300 Width of the initial CT window in Hounsfield units
fontsize integer, e.g., 8 Default user-interface fontsize
UIColor [num,num,num] [r,g,b] default user-interface color
colorOrder see options file Set color of contours and isodose lines. Each 3 number triple is r, g, b. Note: do not put commas into the colorOrder.
inactiveSegStyle valid Matlab linestyle, e.g., '--' Style for inactive contouring segments
activeSegStyle valid Matlab linestyle, e.g., '-' Style for active contouring segments
displayPatientName 0 ('off') or 1 ('on') Display patient name if available?
initialZoomTrans number, e.g., 1.7 Initial transverse zoom factor
initialZoomSag number, e.g., 1.7 Initial saggital zoom factor
initialZoomCor number, e.g., 1.7 Initial coronal zoom factor
zoomFactor number, e.g., 2.0 x-y scale factor when zooming
rulerColor [num,num,num] [r,g,b] ruler color
dosePlotType 'colorwash' or 'isodose' Method of dose distribution display
boneShadow 'on' or 'off' When colorwash dose is displayed a 'shadow' (actually a brightening) shows bone
doseColormap 'jetmod' (modified jet); 'full' (full rainbow); 'star' 14 non-blending colors); 'gray' or 'gray256' (64 or 256 level grayscale) Colormap for dose colorwash. The map is read from CERRColormap.m.
CTColormap same as above, but usually 'gray256' CT colormap, usually grayscale.
colorbarMarks [L1,L2,...], e.g., [45, 70] Ticks on colorbar to indicate these doses, in Gy.
doseDisplayCutoff [0-any pos number], e.g., 2 In colorwash display, do not display doses below this value in units of Gy.  Ignored if the value is 0.
visualRefColormapRows integer, e.g., 256 Number of rows in visual reference colorwash colormap.
visualRefDoseMode 'on' or 'off' Improved identification of regions above the reference dose.  If 'on', the color in the dose colorwash at optS.visualReferenceDose will be white (using 'full2' colormap).  The colormap above this dose to the maximum value will be the visualRefTopColormap.
visualRefDose dose in Gy, e.g., 70 (prescription dose ) If optS.visualReferenceDoseMode is 'on', the color in the dose colorwash at this dose will be that of the highest visualRefBottomColormap color.  The colormap above this dose to the maximum value will be the visualRefTopColormap.
visualRefTopColormap Usually 'grayud64' Colormap between optS.visualRefDose and max dose.
visualRefBottomColormap Usually 'full2', but can be any doseColormap Colormap between zero dose and optS.visualRefDose.
optS.visual3DxyDownsampleIndex 2^n, for example, 128.  128 seems to work well, and is the default Downsample to this resolution in the transverse plane for 3D display.
ROISampleRate integer >= 1, e.g., 2. Rate of ROI sampling compared to CT spacing, for DVH computations.  
DSHMaxPointInterval Maximum interval (in cm), e.g., 0.1 Maximum interval (in cm) between surface sampling points for dose-surface histograms.
surfPtStructures {'structure1', 'structure2',...} Any structure whose name matches this name, up to the number of letters given, will have surface points generated during import. That is, 'lun' will match 'lung' or 'lung_all'.
DVHBinWidth number, e.g., 0.1 Store and display DVHs with this width, in units of Gy.
DVHBlockSize integer, e.g. 5000 Block processing parameter. 5000 is the initial suggested value. This results in much less temporary storage for large structure  DVH computations. If there is disk-thrashing during the DVH calculation, try reducing this number.
DVHLineWidth number, e.g., 1.5 Line thickness of DVH and DSH lines.
nudgeDistance number, e.g., 0.5 Number of voxel widths to nudge the active contour.
navigationMontageColormap string, e.g., 'grayCenter0Width300' Colormap to use for montage.
navigationMontageOnImport string, e.g., 'yes' Do or do not create thumbnails on import.
navigationMontage string, e.g., 'yes' Turn navigation montage on or off at startup.
wavletcompresthreshpersent number, e.g., 1 Thresh percent
wavletcompressiondecomplevel number, e.g., 5 Decompression level
planMetrics cell array of strings, e.g., {'meanDose',...,'EUD'} Names of metrics in PlanMetrics folder
windowPresets Array of structs, e.g. [struct('name', 'Abd/Med', 'center', -10, 'width', 330)...] Values for CT window presets
cachingEnabled 1 or 0. 1 is yes. Turn on slice image caching.
colorWashCacheSize 32 Size in megabytes to dedicate towards slice caching.

The command line [top]

The CERR command line, shown as a button in the slice review tool, is meant to be a powerful mechanism for adding sophisticated user options. The current valid CERR commands can always be determined by typing 'help' at the command line.   Users can add commands to the command line.  To do this, look at /CommandLine/runCERRCommand.m to for an example. In a later version we will add the ability to just put a new function on the path and call it from the command line.

Table 2. Valid CERR commands (brackets indicate user-defined variables)

Command syntax Description
3D, 3d, or 3-D, or 3-d Raise 3D viewer menu
list header List header fields
list comment List comment fields
list slice [num] List CT scan data about slice [num]
list structure [num] List data for structure [num] (the numbering is that of the structure pull-down menu on the transverse image viewer)
list beam geometry [num] List field data on beam geometry [num]
list dose [num] List field data on dose distribution [num]
list dvh [num] List field data on stored DVH [num]
list options List the current options in optS
list structure [structnum] points [slicenum] List points in a structure
show film [num] Show a digital film
mask [num] Show the points included in an ROI
set [optionName] Reset and use a new option value (i.e., optS.optionName)
reload options Reload all option settings in CERROptions.m
go to [slicenum] To go to a slice number
go to z [z value] Go to a z value (or nearest slice)
go to max Go to the slice with the maximum dose
pick Pick sagittal and/or coronal slice positions from transverse view (then use the mouse to select position)
pos Get the position of a point on the transverse viewer chosen with the mouse
loop [command] Loop through the images but run a command line command on each slice
del dvh [num] Delete a DVH
del structure [num] delete an anatomical structure
dose Get dose at point on transverse viewer chosen with the mouse
dose-distance plot ddp [structNum] [maximum distance of plot] [resolution in cm] [''max'' or ''min'' dose].  
func arg1 arg2... (user defined) This is a user-defined function.  If the command entry is not built-in, CERR attempts to run 'func.m'  with the argument list.  ('func' must be on the path.)

Manipulating CERR archives in Matlab scripts or functions [top]

All treatment plan information is contained in the cell-array typically named 'planC.'  As an example of accessing of the CERR plan object, the command

planC{4}(1).contour(27).segments.points

returns, in this case, the points associated with the first (only) segment of the first contour on the 27th slice. See the CERRSliceViewer code for many more examples of how to properly access information stored in CERR format.  

Q.  How can I get access to the underlying plan archive data in Matlab?

A. You can either load the archive file or start CERRSliceViewer.  To load it as a .mat file, just use the usual 'load *.mat' command. After loading (with or without the GUI) type 'global planC' at the Matlab prompt. planC{end} gives the index to where (and what) things are stored in the cell array.  General 'state' information is stored in the global variable stateS.  Type 'global stateS' for access.

Q.  Where are things stored in the plan archive?

A.  The different cells of the cell array contain data objects according to the value of the structure indexS which is loaded from initializeCERR.m. For example we have:

indexS.header = 1;

indexS.comment = 2;

indexS.scan = 3;

indexS.structures = 4;

indexS.structuresArray = 5;

indexS.beamGeometry = 6;

indexS.dose = 7;

indexS.DVH = 8;

indexS.digitalFilm = 9;

indexS.CERROptions = 10;

indexS.indexS = 11;

This means that the scan information is all contained in the 3rd element of the scan (planC{3}), the dose information is all contained in the 7th element, etc. The import options are all stored in cell 10 (however, the user may change them during execution), and cell 11 contains this list of cell contents.  This index is always stored as the last element in planC.  Hence, we always have

indexS = planC{end}

New elements can be added to any plan archive merely by redefining the field values of planC{end}, and moving the cell array elements around accordingly.

Q.  Can I add arbitrary new fields to structures without breaking any code?

A.  Yes, without exception.

Investigating CERR source code [top]

Q.  How can I learn how CERR works?

A.  Matlab has a fantastic debugger which can be used to great advantage.  Following Matlab's instructions, set desired break points and watch changes to, say, the transverse slice viewer as each command is executed.  The debugger has many features as described in the Matlab manual.  Also, the global structure variable stateS contains a great deal of state information.  Type 'global stateS' to make it available.  All figure handles are stored under stateS.handle...  

Q.  How can I tell which functions call which other functions?

A. We wrote a Matlab function, coded by Vanessa Clark, to produce a detailed cross-listing of the code: /CrossListing/getDirFunInfo.m. See the current cross-lising under: /CrossListing/.  The cross-listing is about 9,000 lines long and lists which functions call which other functions along with all the variables of each m-file.  Note that getDirFunInfo.m can be re-run at any time.  Here is an example of its use:

getDirFunInfo('c:\tmp\cerr_30dec02_cross_listing.txt', 'y', 'CERR Cross Listing', 'e:\cerr\cerr_current')

Coding conventions [top]

Meaningful variable and function names are used wherever possible. The naming convention is 'small/large caps,' whereby the first letter of a variable name is not capitalized unless it is an abbreviation (e.g., CT). Hence, we use variables like sizeOfDimension1, etc.

Typically, though not always, the last letter is capitalized and used to distinguish data object types:

A few data objects are passed around as global variables. This facilitates interactive use with Matlab: typing global planC gives the Matlab user access to a plan being viewed using the CERRSliceViewer tool. However, it may have drawbacks in the future because any part of the program may modify any part of the treatment plan.

When selecting some cell of planC, please use indexS as the indexer, e.g., 'planC{indexS.scan}' instead of 'planC{3}.' The actual indices may change in the future to accommodate more cell elements. If the indexS structure is always used then more elements can be added, and others moved, with a trivial modification to the initial value of indexS.

Modifications to working source code are logged briefly near the top of the m-file.

Leftovers [top]

Q.  How can I 'anonymize' a treatment plan archive to remove protected health information?

A. See the function anonymize.m under /Extras/Anonymize/. Be sure to identify all the fieldnames that may contain protected health information.  Of course, we make no guarantees about the results. 

Q.  How does the zoom work?

A. Select the zoom button. Then place the mouse cross-hairs on the location to become the center of the zoom, and click mouse button 1. To unzoom just click unzoom.

Q.  How do I change dose distributions?

A. Just select the new dose distribution from the 'Dose distribution' pull down menu on the transverse viewer.

Q.  What does 'scan uniformization' and the Uniformization subdirectory refer to?

A. This is the process of building a CT dataset with uniform axial (z) spacing. This is useful for sagittal and coronal viewing and will be useful for future projects such as dose computation. The uniformized scan set has a uniform axial (z) spacing and the same transverse resolution as the normal CT-scan (usually, but not always, 512 x 512). Superior and inferior 'bookends' will be created in addition, via 3-D linear interpolation, to complete the uniformized CT dataset. Encoded masks (0/1) of structure locations are stored registered to this uniformized dataset.  Given a set of CT values, we choose the largest block which CT slice spacing which falls within the limits of optS.lowerLimitUniformCTSliceSpacing and optS.upperLimitUniformCTSliceSpacing.  Otherwise we create a set with a spacing equal to optS.alternateUniformCTSliceSpacing. If the user desires a uniformized scan with a spacing of exactly optS.alternateUniformCTSliceSpacing, then set optS.lowerLimitUniformCTSliceSpacing to be larger than optS.upperLimitUniformCTSliceSpacing.

Q.  What is a dose-distance plot?

A.  This is a simple plot, for a given structure, of d vs. x, where d is the minimum or maximum dose which can be found at a shortest-distance x from the structure boundary.  It can be produced at the command line (see the command line listing).  Also see the header of doseDistancePlot.m for more information.  This is a simple way of summarizing how close hot or cold spots are to a structure, or how far hot or cold spots penetrate into a structure.

Updates and more information [top]

Q.  Where can I get updates and more information?

A.  Our web-page:  http://deasylab.info (this always redirects to the current home of CERR as hosted on Washington University computers).

Q.  Is there an email mailing list for CERR?  

A.  Yes.  We have created a yahoo groups mailing list and archive for users of CERR.  Send me an email and I will put you on it.

Q. Will the documentation get better?

A. Yes, but the timetable is undocumented.

Q. Will CERR bugs get fixed?

A. Yes they will -- including those to make the import tool work for a wider variety of planning systems.  It is often the case that vendors don't follow the RTOG specification exactly.  We have always been able to correct (i.e. translate) or workaround variant implementations.

Q.  What other documentation is available with the system?

  1. Many widgets have tips which appear if the mouse hovers over the widget.

  2. A preprint of an article to appear in Medical Physics will be placed on the webpage and in the CERR distribution when it becomes available. An earlier version is included in this distribution.  The article describes the general architecture and features of CERR.

  3. Look at the CERROptions.m file to see descriptions of the many options settings.

  4. Type 'help' at the command prompt on the transverse viewer to see a listing of valid commands.

  5. This file, which will be updated on our webpage (deasylab.info)

Please email us with any questions or comments. We especially want to hear about bugs as we are committed to bug-free code.

Credits: [top]

Ongoing projects and future plans [top]

At Washington University, we have ongoing diverse projects which use CERR, including

We are open to collaborating on projects that use CERR.  We want CERR to fill a need for a convenient environment for developing, demonstrating, and sharing radiotherapy research.

© All rights reserved. | Terms of Use | Hosted by GoDaddy | Managed, in individual capacity, by aditya.apte@gmail.com