Merge pull request #873 from e0404/rc/v3.2.0

Minor Update 3.2.0

Author: wahln

.gitattributes

@@ -0,0 +1,13 @@
+# Auto-detect text files and normalize (LF in repo).
+* text=auto
+
+# Force files to be binary
+*.mat binary
+*.pdf binary
+*.mex* binary
+*.zip binary
+*.dll binary
+*.exe binary
+
+# Ensure .m files are never marked as executable
+*.m -x

.github/actions/test-matlab/action.yml

@@ -15,7 +15,7 @@ runs:
       uses: matlab-actions/setup-matlab@v2
       with:
         release: ${{ inputs.matlab-version }}
-        products: Image_Processing_Toolbox Parallel_Computing_Toolbox Optimization_Toolbox
+        products: Image_Processing_Toolbox Parallel_Computing_Toolbox Optimization_Toolbox Global_Optimization_Toolbox
 
     # Runs test command
     - name: Run Tests

.github/workflows/coverage-report.yml

@@ -64,6 +64,7 @@ jobs:
                         
             - name: Add Coverage PR Comment
               uses: marocchino/sticky-pull-request-comment@v2
+              continue-on-error: true
               if: github.event_name == 'pull_request'
               with:
                   recreate: true

.gitignore

@@ -5,3 +5,4 @@ coverage.xml
 coverage.json
 *.asv
 build/
+.DS_Store

.gitlab-ci.yml

@@ -0,0 +1,51 @@
+variables:
+  GIT_SUBMODULE_STRATEGY: recursive
+  GIT_SUBMODULE_DEPTH: 1
+  GIT_SUBMODULE_PATH: submodules/MOxUnit submodules/MOcov
+
+.matlab_defaults:
+  image:
+    name: '${CUSTOM_MATLAB_IMAGE}:r2024b'  # Replace the value with the name of the MATLAB container image you want to use
+    entrypoint: [""]
+  variables:
+    MLM_LICENSE_FILE: $E040_MATLAB_LICENSE_SERVER  # Replace the value with the port number and DNS address for your network license manager
+  resource_group: matlab
+
+test:
+  stage: test
+  extends: .matlab_defaults
+  script: matlab -batch "assert(matRad_runTests('test',true));"
+  artifacts:
+    reports:
+      junit: "./testresults.xml"
+      coverage_report:
+        coverage_format: cobertura
+        path: "./coverage.xml"
+    paths:
+      - "./*.xml"
+      - "./*.json"
+  coverage: '/TOTAL.*? (100(?:\.0+)?%|[1-9]?\d(?:\.\d+)?%)/'
+
+
+package:
+  stage: deploy
+  extends: .matlab_defaults
+  script: 
+    - |
+      if [ -n "$CI_COMMIT_TAG" ]; then        
+        matlab -batch "matRad_buildStandalone('isRelease', true);"
+        PACKAGE_NAME="$CI_COMMIT_TAG"        
+      else
+        matlab -batch "matRad_buildStandalone();"
+        PACKAGE_NAME="$CI_COMMIT_BRANCH"
+      fi
+      INSTALLER_NAME="matRad_installerLinux64_$PACKAGE_NAME"
+    - tar -czvf $INSTALLER_NAME.tar.gz build/installer
+    - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file $INSTALLER_NAME.tar.gz "$CI_API_V4_URL/projects/$CI_PROJECT_ID/packages/generic/matRad_linux64/$CI_COMMIT_BRANCH/matRad/$PACKAGE_NAME/$INSTALLER_NAME.tar.gz"'
+    # - echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin
+    # - docker image tag matRad:develop $CI_REGISTRY/$CI_PROJECT_NAMESPACE/$CI_PROJECT_NAME/matRad:develop
+    # - docker push $CI_REGISTRY/$CI_PROJECT_NAMESPACE/$CI_PROJECT_NAME/matRad:develop
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_COMMIT_BRANCH == "dev"
+    - if: $CI_COMMIT_TAG

AUTHORS.txt

@@ -1,4 +1,4 @@
-List of all matRad developers that contributed code (alphabetical)
+List of all matRad developers that contributed code (alphabetical)
 
 * Nelly Abbani
 * Nabe Al-Hasnawi
@@ -11,8 +11,10 @@
 * Louis Charton
 * Eric Christiansen
 * Remo Cristoforetti
+* Fabio D'Andrea
 * Marios Dallas
 * Edgardo Doerner
+* Louis Ermeneux
 * Simona Facchiano
 * Hubert Gabrys
 * Josefine Handrack
@@ -26,6 +28,7 @@
 * Navid Khaledi
 * Thomas Klinge
 * Jeremias Kunz
+* Mariia Lapaeva
 * Paul Anton Meder
 * Henning Mescher
 * Lucas-Raphael Müller
@@ -36,6 +39,7 @@
 * Claus Sarnighausen
 * Carsten Scholz
 * Camilo Sevilla
+* Mateusz Sitarz
 * Alexander Stadler
 * Uwe Titt
 * Niklas Wahl

CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## Minor Update 3.2.0
+
+### New Features
+- FRED MC interface (if installed)
+- VHEE planning with a Generic (unfocused) beam and a focused beam. The Generic beam can be forwarded to TOPAS as well.
+- New matRad_plotSlice function with keyword / value synxtax for more intuitive plotting of slices
+
+### Bug Fixes & Performance
+- DICOM Import widget allow selection of multiple RTDose files.
+- DICOM Import Widget and importer handle selected patient more consistently and robustly. 
+- DICOM Exporter writes quantities beyond dose, importer tries to import them correctly.
+- DICOM Exporter now always writes ReferencedRTPlanSequence. Importer can now survive without it.
+- DVH widget does not throw a warning in updates, handle scenarios correctly / more robustly and missing xlabel axesHandle parameter.
+- GUI fixes regarding setting of gantry angles and other parameters in the PlanningWidget
+- EXTERNAL contours now correctly recognized
+- performance improvement for obtaining jacobian structure in optimization
+- Available Classes (e.g., dose engines) are now cached for faster loading
+
+### User Experience
+- Added new examples for usage of FRED & VHEE and a workflow example for comparing dose calculation on synthetic CT to planning CT
+- Updated examples to use matRad_plotSlice
+- GUI fixes for use in Matlab Online
+- The analyitcal functions from the Bortfeld Bragg Peak Model are now public and can be used to compute standard approximations (e.g. range-energy relationship)
+
+### Development and CI
+- Added a new `.gitlab-ci.yml` file to support GitLab CI/CD, including test and package stages, artifact handling, and configuration for MATLAB container images and licensing.
+- Added a `.gitattributes` file to standardize line endings, treat certain file types as binary, and ensure `.m` files are not marked as executable.
+- In `.github/actions/test-matlab/action.yml`, added `Global_Optimization_Toolbox` to the list of MATLAB products for testing.
+- In `.github/workflows/coverage-report.yml`, made the coverage PR comment step tolerant to errors to avoid workflow failures.
+- More comprehensive dose calculation tests
+- Added new contributors
+
 ## Version 3.1.0 - "Cleve"
 
 ### Major Changes and New Features

CITATION.cff

@@ -25,6 +25,8 @@ authors:
   given-names: "Eric"
 - family-names: "Cristoforetti"
   given-names: "Remo"
+- family-names: "D'Andrea"
+  given-names: "Fabio"
 - family-names: "Dallas"
   given-names: "Marios"
 - family-names: "Doerner"
@@ -33,6 +35,8 @@ authors:
   given-names: "Swantje"
 - family-names: "Ellerbrock"
   given-names: "Malte"
+- family-names: "Ermeneux"
+  given-names: "Louis"
 - family-names: "Facchiano"
   given-names: "Simona"
 - family-names: "Gabryś"
@@ -61,6 +65,8 @@ authors:
   given-names: "Thomas"
 - family-names: "Kunz"
   given-names: "Jeremias"
+- family-names: "Lapaeva"
+  given-names: "Mariia"
 - family-names: "Mairani"
   given-names: "Andrea"
 - family-names: "Meder"
@@ -85,6 +91,8 @@ authors:
   given-names: "Carsten"
 - family-names: "Sevilla"
   given-names: "Camilo"
+- family-names: "Sitarz"
+  given-names: "Mateusz"
 - family-names: "Stadler"
   given-names: "Alexander"
 - family-names: "Ulrich"

examples/matRad_example10_4DphotonRobust.m

@@ -192,7 +192,7 @@
 stf = matRad_generateStf(ct,cst,pln);
 
 %% Dose Calculation
-dij = matRad_calcPhotonDose(ct,stf,pln,cst);
+dij =  matRad_calcDoseInfluence(ct,cst,stf,pln);
 
 %% Inverse Optimization  for IMPT based on RBE-weighted dose
 % The goal of the fluence optimization is to find a set of bixel/spot 
@@ -241,30 +241,38 @@
 maxDose       = max([max(resultGUI.([pln.propOpt.quantityOpt])(:,:,slice)) max(resultGUIrobust.([pln.propOpt.quantityOpt])(:,:,slice))])+1e-4;
 doseIsoLevels = linspace(0.1 * maxDose,maxDose,10);
 figure,
-subplot(121),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUI.([pln.propOpt.quantityOpt '_' 'beam1'])      ,plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('conventional plan - beam1')
-subplot(122),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUI.([pln.propOpt.quantityOpt])      ,plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('conventional plan')
+subplot(121),matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', 1, 'dose', resultGUI.([pln.propOpt.quantityOpt '_' 'beam1'])    ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 maxDose], 'doseIsoLevels', doseIsoLevels);title('conventional plan - beam1')
+subplot(122),matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', 1, 'dose', resultGUI.([pln.propOpt.quantityOpt])                ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 maxDose], 'doseIsoLevels', doseIsoLevels);title('conventional plan')
+%subplot(121),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUI.([pln.propOpt.quantityOpt '_' 'beam1'])      ,plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('conventional plan - beam1')
+%subplot(122),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUI.([pln.propOpt.quantityOpt])      ,plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('conventional plan')
 
 figure
-subplot(121),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust.([pln.propOpt.quantityOpt '_' 'beam1']),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('robust plan - beam1')
-subplot(122),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust.([pln.propOpt.quantityOpt]),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('robust plan')
+subplot(121),matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', 1, 'dose', resultGUIrobust.([pln.propOpt.quantityOpt '_' 'beam1'])  ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 maxDose], 'doseIsoLevels', doseIsoLevels);title('robust plan - beam1')
+subplot(122),matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', 1, 'dose', resultGUIrobust.([pln.propOpt.quantityOpt])              ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 maxDose], 'doseIsoLevels', doseIsoLevels);title('robust plan')
+%subplot(121),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust.([pln.propOpt.quantityOpt '_' 'beam1']),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('robust plan - beam1')
+%subplot(122),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust.([pln.propOpt.quantityOpt]),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('robust plan')
 
 
 figure
-subplot(131),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust4D.([pln.propOpt.quantityOpt]),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('robust plan')
-subplot(132),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust4D.('accPhysicalDose'),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('robust plan dose accumulation')
+subplot(131),matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', 1, 'dose', resultGUIrobust4D.([pln.propOpt.quantityOpt])  ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 maxDose], 'doseIsoLevels', doseIsoLevels);title('robust plan')
+subplot(132),matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', 1, 'dose', resultGUIrobust4D.('accPhysicalDose')  ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 maxDose], 'doseIsoLevels', doseIsoLevels);title('robust plan dose accumulation')
+%subplot(131),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust4D.([pln.propOpt.quantityOpt]),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('robust plan')
+%subplot(132),matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust4D.('accPhysicalDose'),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);title('robust plan dose accumulation')
 
 % create an interactive plot to slide through individual scnearios
 f       = figure; title('individual scenarios');
 numScen = 1;
 maxDose       = max(max(resultGUIrobust.([pln.propOpt.quantityOpt '_scen' num2str(round(numScen))])(:,:,slice)))+0.2;
 doseIsoLevels = linspace(0.1 * maxDose,maxDose,10);
-matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust.([pln.propOpt.quantityOpt '_scen' num2str(round(numScen))]),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);
+matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', 1, 'dose', resultGUIrobust.([pln.propOpt.quantityOpt '_scen' num2str(round(numScen))]) ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 maxDose], 'doseIsoLevels', doseIsoLevels);
+%matRad_plotSliceWrapper(gca,ct,cst,1,resultGUIrobust.([pln.propOpt.quantityOpt '_scen' num2str(round(numScen))]),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels);
 
 [env,envver] = matRad_getEnvironment();
 if strcmp(env,'MATLAB') || str2double(envver(1)) >= 5
     b = uicontrol('Parent',f,'Style','slider','Position',[50,5,419,23],...
         'value',numScen, 'min',1, 'max',pln.multScen.totNumScen,'SliderStep', [1/(pln.multScen.totNumScen-1) , 1/(pln.multScen.totNumScen-1)]);
-    set(b,'Callback',@(es,ed)  matRad_plotSliceWrapper(gca,ct,cst,round(get(es,'Value')),resultGUIrobust.([pln.propOpt.quantityOpt '_scen' num2str(round(get(es,'Value')))]),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels));
+    set(b,'Callback',@(es,ed)  matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', round(get(es,'Value')), 'dose', resultGUIrobust.([pln.propOpt.quantityOpt '_scen' num2str(round(get(es,'Value')))]) ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 maxDose], 'doseIsoLevels', doseIsoLevels)); 
+    %matRad_plotSliceWrapper(gca,ct,cst,round(get(es,'Value')),resultGUIrobust.([pln.propOpt.quantityOpt '_scen' num2str(round(get(es,'Value')))]),plane,slice,[],[],colorcube,[],[0 maxDose],doseIsoLevels));
 end
 
 %% Indicator calculation and show DVH and QI
@@ -282,10 +290,12 @@
 [cstStatRob, resultGUISampRob, metaRob]                = matRad_samplingAnalysis(ct,cst,plnSampRob,caSampRob, mSampDoseRob, resultGUInomScen);
 
 figure,title('std dose cube based on sampling - conventional')
-matRad_plotSliceWrapper(gca,ct,cst,1,resultGUISamp.stdCube,plane,slice,[],[],colorcube,[],[0 max(resultGUISamp.stdCube(:))]);
+matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', 1, 'dose', resultGUISamp.stdCube     ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 max(resultGUISamp.stdCube(:))]);
+%matRad_plotSliceWrapper(gca,ct,cst,1,resultGUISamp.stdCube,plane,slice,[],[],colorcube,[],[0 max(resultGUISamp.stdCube(:))]);
 
 figure,title('std dose cube based on sampling - robust')
-matRad_plotSliceWrapper(gca,ct,cst,1,resultGUISampRob.stdCube,plane,slice,[],[],colorcube,[],[0 max(resultGUISampRob.stdCube(:))]);
+matRad_plotSlice(ct, 'axesHandle', gca, 'cst', cst, 'cubeIdx', 1, 'dose', resultGUISampRob.stdCube  ,'plane', plane, 'slice', slice, 'contourColorMap', colorcube, 'doseWindow', [0 max(resultGUISampRob.stdCube(:))]);
+%matRad_plotSliceWrapper(gca,ct,cst,1,resultGUISampRob.stdCube,plane,slice,[],[],colorcube,[],[0 max(resultGUISampRob.stdCube(:))]);
 
 
 

examples/matRad_example15_brachy.m

@@ -84,14 +84,12 @@
 % Here we will use HDR. By this means matRad will look for 'brachy_HDR.mat'
 % in our root directory and will use the data provided in there for 
 % dose calculation.
-
 pln.radiationMode   = 'brachy'; 
 pln.machine         = 'HDR';    % 'LDR' or 'HDR' for brachy
 
 pln.bioModel        = 'none';
 pln.multScen        = 'nomScen';
 
-
 %% II.1 - needle and template geometry
 % Now we have to set some parameters for the template and the needles. 
 % Let's start with the needles: Seed distance is the distance between
@@ -110,6 +108,7 @@
 % The needles will be positioned right under the target volume pointing up.
 
 
+pln.propStf.visMode      = 1; %Enable visualization for stf generation
 pln.propStf.bixelWidth   = 5; % [mm] template grid distance
 
 %Template Type
@@ -151,16 +150,12 @@
 % needles.
 % Calculation time will be reduced by one tenth when we define a dose
 % cutoff distance.
-
-
 pln.propDoseCalc.TG43approximation = '2D'; %'1D' or '2D' 
 
 pln.propDoseCalc.doseGrid.resolution.x = 5; % [mm]
 pln.propDoseCalc.doseGrid.resolution.y = 5; % [mm]
 pln.propDoseCalc.doseGrid.resolution.z = 5; % [mm]
 
-
-
 % We can also use other solver for optimization than IPOPT. matRad 
 % currently supports simulannealbnd from the MATLAB Global Optimization Toolbox. First we
 % check if the simulannealbnd-Solver is available, and if it is, we set in in the
@@ -172,7 +167,6 @@
     pln.propOpt.optimizer = 'IPOPT';
 end
 
-pln.propOpt.optimizer = 'IPOPT';
 %% II.1 - book keeping
 % Some field names have to be kept although they don't have a direct
 % relevance for brachy therapy.
@@ -182,14 +176,12 @@
 % Et voila! Our treatment plan structure is ready. Lets have a look:
 disp(pln);
 
-
 %% II.2 Steering Seed Positions From STF
 % The steering file struct contains all needls/catheter geometry with the
 % target volume, number of needles, seeds and the positions of all needles
 % The one in the end enables visualization.
 stf = matRad_generateStf(ct,cst,pln);
 
-
 %% II.2 - view stf
 % The 3D view is interesting, but we also want to know how the stf struct
 % looks like.