Examples

Examples are located in the examples directory. To build them, set the option BUILD_EXAMPLES=ON.

2D gamma index using classic method for simple images

This example shows how to use YAGIT even without any input files.

  1/**
  2 * @file gammaSimple.cpp
  3 * @brief This file provides a simple example of using yagit - 2D gamma index for any images.
  4 * 
  5 * @example{lineno}
  6 * Example demonstrating the 2D gamma index for any images.
  7 * 1. Create two 2D images - a reference image and an evaluated image.
  8 * 2. Calculate the 2D gamma index of those two images using the classic method.
  9 *    The parameters are: 3%G/3mm,
 10 *    normalization dose is set to max value of the reference image,
 11 *    and dose cutoff is set to 10% of max value of the reference image.
 12 * 3. Print the gamma index image, gamma index passing rate, and other statistics.
 13 */
 14
 15#include <string>
 16#include <iostream>
 17#include <sstream>
 18
 19#include <yagit/yagit.hpp>
 20
 21void printImage2D(const yagit::Image2D& img){
 22    std::ostringstream oss;
 23    oss << "[";
 24    for(size_t i = 0; i < img.size(); i++){
 25        oss << (i == 0 ? "[" : " [");
 26        for(size_t j = 0; j < img[i].size() - 1; j++){
 27            oss << img[i][j] << ", ";
 28        }
 29        oss << img[i].back();
 30        oss << (i < img.size() - 1 ? "],\n" : "]");
 31    }
 32    oss << "]\n";
 33    std::cout << oss.str();
 34}
 35
 36void printImageData(const yagit::ImageData& imageData){
 37    printImage2D(imageData.getImage2D(0));
 38
 39    yagit::DataSize size = imageData.getSize();
 40    yagit::DataOffset offset = imageData.getOffset();
 41    yagit::DataSpacing spacing = imageData.getSpacing();
 42    std::cout << "size: (" << size.frames << ", " << size.rows << ", " << size.columns << ")\n"
 43              << "offset: (" << offset.frames << ", " << offset.rows << ", " << offset.columns << ")\n"
 44              << "spacing: (" << spacing.frames << ", " << spacing.rows << ", " << spacing.columns << ")\n";
 45}
 46
 47int main(){
 48    // set values of images
 49    yagit::Image2D refImg = {
 50        {0.93, 0.95},
 51        {0.97, 1.00}
 52    };
 53    yagit::Image2D evalImg = {
 54        {0.93, 0.96},
 55        {0.90, 1.02}
 56    };
 57
 58    // set the offset and the spacing of the images
 59    yagit::DataOffset refOffset{0, 0, -1};
 60    yagit::DataOffset evalOffset{0, 1, 0};
 61    yagit::DataSpacing refSpacing{2, 2, 2};
 62    yagit::DataSpacing evalSpacing{2, 2, 2};
 63
 64    // create the reference image and the evaluated image
 65    yagit::ImageData refImgDose(refImg, refOffset, refSpacing);
 66    yagit::ImageData evalImgDose(evalImg, evalOffset, evalSpacing);
 67
 68    // print info about the reference image and the evaluated image
 69    std::cout << "Reference image:\n";
 70    printImageData(refImgDose);
 71    std::cout << "------------------------------\n";
 72    std::cout << "Evaluated image:\n";
 73    printImageData(evalImgDose);
 74    std::cout << "------------------------------\n";
 75
 76    // set gamma index parameters
 77    yagit::GammaParameters gammaParams;
 78    gammaParams.ddThreshold = 3.0;   // [%]
 79    gammaParams.dtaThreshold = 3.0;  // [mm]
 80    gammaParams.normalization = yagit::GammaNormalization::Global;
 81    gammaParams.globalNormDose = refImgDose.max();
 82    gammaParams.doseCutoff = 0;
 83
 84    // calculate the 2D gamma index using the classic method
 85    const yagit::GammaResult gammaRes = yagit::gammaIndex2D(refImgDose, evalImgDose, gammaParams,
 86                                                            yagit::GammaMethod::Classic);
 87
 88    // print the gamma index image
 89    // expected:
 90    // [[0.471405, 0.57735],
 91    //  [1.10554, 0.816496]]
 92    std::cout << "Gamma index image:\n";
 93    printImage2D(gammaRes.getImage2D(0));
 94
 95    // print gamma index statistics
 96    std::cout << "GIPR: " << gammaRes.passingRate() * 100 << "%\n"
 97              << "Gamma mean: " << gammaRes.meanGamma() << "\n"
 98              << "Gamma min: " << gammaRes.minGamma() << "\n"
 99              << "Gamma max: " << gammaRes.maxGamma() << "\n";
100}

3D gamma index using Wendling method

This example shows the most useful use case – 3D gamma index using the Wendling method. The Wendling method is more preferred than the classic method because it computes the gamma index faster and provides more accurate results, thanks to the ability to set a small step size.

 1/**
 2 * @file gamma3D.cpp
 3 * @brief This file provides a simple example of using yagit - 3D gamma index.
 4 * 
 5 * @example{lineno}
 6 * Example demonstrating the 3D gamma index.
 7 * 1. Read a reference image and an evaluated image from DICOM files.
 8 * 2. Calculate the 3D gamma index of those images using the Wendling method.
 9 *    The parameters are: 3%G/3mm,
10 *    normalization dose is set to max value of the reference image,
11 *    and dose cutoff is set to 10% of max value of the reference image.
12 * 3. Print gamma index passing rate and other statistics.
13 * 4. Save the result to a MetaImage file.
14 */
15
16#include <string>
17#include <iostream>
18#include <sstream>
19
20#include <yagit/yagit.hpp>
21
22std::string floatToString(float d){
23    std::ostringstream oss;
24    oss << d;
25    return oss.str();
26}
27
28std::string gammaParametersToString(const yagit::GammaParameters& gammaParams){
29    std::string dd = floatToString(gammaParams.ddThreshold);
30    std::string dta = floatToString(gammaParams.dtaThreshold);
31    char norm = gammaParams.normalization == yagit::GammaNormalization::Global ? 'G' : 'L';
32    return dd + "%" + norm + "/" + dta + "mm";
33}
34
35int main(int argc, char** argv){
36    if(argc <= 2){
37        std::cerr << "too few arguments\n";
38        std::cerr << "Usage: gamma3D refImgPath evalImgPath\n";
39        return 1;
40    }
41
42    const std::string refImgPath{argv[1]};
43    const std::string evalImgPath{argv[2]};
44
45    try{
46        // read a reference image and an evaluated image from DICOM files
47        const yagit::ImageData refImg = yagit::DataReader::readRTDoseDicom(refImgPath);
48        const yagit::ImageData evalImg = yagit::DataReader::readRTDoseDicom(evalImgPath);
49
50        // set gamma index parameters
51        float refMaxDose = refImg.max();
52        yagit::GammaParameters gammaParams;
53        gammaParams.ddThreshold = 3.0;   // [%]
54        gammaParams.dtaThreshold = 3.0;  // [mm]
55        gammaParams.normalization = yagit::GammaNormalization::Global;
56        gammaParams.globalNormDose = refMaxDose;
57        gammaParams.doseCutoff = 0.1 * refMaxDose;  // 10% * ref_max
58        // two parameters below are exclusively used by the Wendling method
59        gammaParams.maxSearchDistance = 10;                    // [mm]
60        gammaParams.stepSize = gammaParams.dtaThreshold / 10;  // [mm]
61
62        // print the gamma index parameters
63        std::cout << "Calculating 3D gamma index using Wendling method with parameters: "
64                  << gammaParametersToString(gammaParams) << "\n";
65
66        // calculate the 3D gamma index using the Wendling method
67        const yagit::GammaResult gammaRes = yagit::gammaIndex3D(refImg, evalImg, gammaParams,
68                                                                yagit::GammaMethod::Wendling);
69
70        // print gamma index statistics
71        std::cout << "GIPR: " << gammaRes.passingRate() * 100 << "%\n"
72                  << "Gamma mean: " << gammaRes.meanGamma() << "\n"
73                  << "Gamma min: " << gammaRes.minGamma() << "\n"
74                  << "Gamma max: " << gammaRes.maxGamma() << "\n"
75                  << "NaN values: " << gammaRes.size() - gammaRes.nansize() << " / " << gammaRes.size() << "\n";
76
77        // save the result containing the gamma index image to a MetaImage file
78        yagit::DataWriter::writeToMetaImage(gammaRes, "gamma_index_3d.mha");
79    }
80    catch(const std::exception &e){
81        std::cerr << "ERROR: " << e.what() << "\n";
82    }
83}

2D gamma index using classic method with interpolation

This example demonstrates the classic method with interpolation of the evaluated image to achieve more accurate results (though at the expense of longer computations). In this example, the 2D version is used instead of the 3D version because the classic method for the 3D version can take a very long time to compute.

 1/**
 2 * @file gammaWithInterp.cpp
 3 * @brief This file provides a simple example of using yagit - 2D gamma index with interpolation of eval image.
 4 * 
 5 * @example{lineno}
 6 * Example demonstrating the 2D gamma index with interpolation of an evaluated image.
 7 * 1. Read a reference image and an evaluated image from DICOM files.
 8 * 2. Take 2D frames from the middle of the images in the coronal plane.
 9 * 3. Interpolate the evaluated image to have a spacing set to 1/3
10 *    of the DTA criterion or lower.
11 * 4. Calculate the 2D gamma index of those 2D images using the classic method.
12 *    The parameters are: 2%G/2mm,
13 *    normalization dose is set to max value of the reference image,
14 *    and dose cutoff is set to 1% of max value of the reference image.
15 * 5. Print gamma index passing rate and other statistics.
16 * 6. Save the result to a MetaImage file.
17 */
18
19#include <string>
20#include <iostream>
21
22#include <yagit/yagit.hpp>
23
24int main(int argc, char** argv){
25    if(argc <= 2){
26        std::cerr << "too few arguments\n";
27        std::cerr << "Usage: gammaWithInterp refImgPath evalImgPath\n";
28        return 1;
29    }
30
31    const std::string refImgPath{argv[1]};
32    const std::string evalImgPath{argv[2]};
33
34    try{
35        // read a reference image and an evaluated image from DICOM files
36        yagit::ImageData refImg = yagit::DataReader::readRTDoseDicom(refImgPath);
37        yagit::ImageData evalImg = yagit::DataReader::readRTDoseDicom(evalImgPath);
38
39        // take 2D frames from the middle of the images in the coronal plane
40        uint32_t yframe = refImg.getSize().rows / 2;
41        refImg = refImg.getImageData2D(yframe, yagit::ImagePlane::Coronal);
42        evalImg = evalImg.getImageData2D(yframe, yagit::ImagePlane::Coronal);    
43
44        // set gamma index parameters
45        float refMaxDose = refImg.max();
46        yagit::GammaParameters gammaParams;
47        gammaParams.ddThreshold = 2.0;   // [%]
48        gammaParams.dtaThreshold = 2.0;  // [mm]
49        gammaParams.normalization = yagit::GammaNormalization::Global;
50        gammaParams.globalNormDose = refMaxDose;
51        gammaParams.doseCutoff = 0.01 * refMaxDose;  // 1% * ref_max
52
53        // interpolate the evaluated image to have a spacing set to 1/3 of the DTA criterion or lower
54        float newSpacingY = std::min(gammaParams.dtaThreshold / 3, evalImg.getSpacing().rows);
55        float newSpacingX = std::min(gammaParams.dtaThreshold / 3, evalImg.getSpacing().columns);
56        evalImg = yagit::Interpolation::bilinearOnPlane(evalImg, newSpacingY, newSpacingX, yagit::ImagePlane::YX);
57
58        // calculate the 2D gamma index using the classic method
59        std::cout << "Calculating 2D gamma index using classic method with interpolated evaluated image\n";
60        const yagit::GammaResult gammaRes = yagit::gammaIndex2D(refImg, evalImg, gammaParams,
61                                                                yagit::GammaMethod::Classic);
62
63        // print gamma index statistics
64        std::cout << "GIPR: " << gammaRes.passingRate() * 100 << "%\n"
65                  << "Gamma mean: " << gammaRes.meanGamma() << "\n"
66                  << "Gamma min: " << gammaRes.minGamma() << "\n"
67                  << "Gamma max: " << gammaRes.maxGamma() << "\n"
68                  << "NaN values: " << gammaRes.size() - gammaRes.nansize() << " / " << gammaRes.size() << "\n";
69
70        // save the result containing gamma index image to a MetaImage file
71        yagit::DataWriter::writeToMetaImage(gammaRes, "gamma_index_2d.mha");
72    }
73    catch(const std::exception &e){
74        std::cerr << "ERROR: " << e.what() << "\n";
75    }
76}