Bugfix/ignore outside densities

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - possible negative doses in finesampling engine due to extrapolation in kernel interpolation
 - correct parsing of all optional arguments of the `traceCube` function for `matRad_RayTracer`
+- corrected an inconsistency where analytical dose calculations used an RSP cube wit `ignoreOutsideDensities` applied, while MC dose engines often converted materials directly from the HU cube without the same masking. Added the variables `ignoreOutsideDensities` and `useGivenEqDensityCube` to  handle this also consistently between STF generation and dose engines.
 - CheckGradients option for fmincon dropped due to change in Matlab 2026
 - `dij.ax` and `dij.bx` are correctly handled as cell arrays in weight initialization
 - `matRad_GriddedScenariosAbstract` now correctly allows single grid point (collapse to nominal value) for a specific error type

docs/datastructures/pln.rst

@@ -89,9 +89,12 @@ pln.propOpt
 
     Setting this value to ``true`` will enable sequencing algorithms run.
 
+.. _pln_additional_properties:
+
 Additional adjustable properties
 --------------------------------
 
+
 The following properties of the pln struct can additionally be adjusted. If they are not explicitly set, default values are used. The default values are handled by the `MatRad_Config class <https://github.com/e0404/matRad/blob/master/MatRad_Config.m>`_.
 
 **pln.propStf.longitudinalSpotSpacing**
@@ -102,6 +105,18 @@ The following properties of the pln struct can additionally be adjusted. If they
 
     If this property is set to *true*, the target is expanded for beamlet finding. Default: *true*.
 
+**pln.propStf.ignoreOutsideDensities**
+    If this property is set to *true*, the stf generation will ignore densities outside of the patient, this is important for the selection of energies for the particles. Default: *false*.
+
+**pln.propStf.useGivenEqDensityCube**
+    If this property is set to *true*, the stf generation calculation will use the given equivalent density cube. Default: *false*.
+
+**pln.propDoseCalc.ignoreOutsideDensities**
+    If this property is set to *true*, the dose calculation will ignore densities outside of the patient. This should be the same as **pln.propStf.ignoreOutsideDensities**. Default: *false*.
+
+**pln.propDoseCalc.useGivenEqDensityCube**
+    If this property is set to *true*, the dose calculation will use the given equivalent density cube. This should be the same as **pln.propStf.useGivenEqDensityCube**. Default: *false*.
+
 **pln.propDoseCalc.doseGrid.resolution**
 
     Specifies the resolution for the dose calculation. Default: x direction: *3* mm, y direction: *3* mm, z direction: *3* mm.

docs/datastructures/stf.rst

@@ -34,7 +34,8 @@ Screenshot of the stf structure:
       - *Photons*: each ray is a single bixel. *Particles*: :ref:`number of bixels / dose spots along each ray <numOfBixels>`.
     * - **total number of bixels**
       - Total number of bixels for each beam.
-
+    * - **props**
+      - Additional properties used during generation of the stf struct, used to check consistency to the dose calculation.
 .. _ray:
 
 stf.ray substructure
@@ -92,3 +93,10 @@ Screenshot of the stf.numOfBixelsPerRay field:
 
 .. image:: /images/stfStructNumOfBixelsScreenshot.png
    :alt: stf.numOfBixelsPerRay field screenshot
+
+
+stf.props field
+===========================
+
+The *stf.props* field contains additional properties used during generation of the stf struct, used to check consistency to the dose calculation.
+The parameters ignoreOutsideDensities and useGivenEqDensityCube are saved (:ref:`pln_additional_properties`)