Add ImageDeformActor

[ylemarechal]

Add ImageDeformActor

[djboersma]

First: thank you, this looks very interesting! I have been thinking about making a similar thing for my studies in pencil beam scanning (PBS) proton therapy. But I also have many questions and (probably) misunderstandings, probably due to some big differences in how photon and proton RT simulations are done in Gate.

When I first saw the name of your actor, I thought that it would actively deform dose distributions with a DVF. That is NOT what it does (but I'll come back to it very soon). If I understand the code correctly, it finds the dose actor in the actor list, then updates the image attached to the corresponding volume to the image that is assigned to the current clock time, according to a simple time-phase list in a text file.

In my understanding of photon RT simulation (remember, I'm a proton RT guy) you actually have a running time, so during a run you may change from one phase to another. This suggests that for every event you need to check the clock time and decide whether to do a "phase transition" or not. But the phase/image selection only happens during the BeginOfRun method. This suggests that you "deform" the image only at the start of the run, and not during the rest of the simulation.

So could you confirm that the intended use for this actor is to run the simulation only for a short time slice of the treatment, during which the patient stays within one phase? And then maybe you do many runs, one run per time slice? (I am exposing my ignorance about photon RT simulation here.)

If I am actually wrong, and you do simulate the whole duration (or a larger fraction of the whole duration) of the treatment, then I do not understand how the image is updated between phases, because I only see "begin of run action". I also would not understand how the dose actor would deal with this situation, because the dose cannot be simply summed between phases, it needs to be deformed into a reference image.

[djboersma]

Now some nitpicks:

1. I wonder why you call the file with the time-vs-phase list a "PDF" file. In simulation/statistics the acronym PDF usually stands for "probability distribution function", sometimes "particle distribution function". I do not think that this is the intended meaning here, so I would suggest a more distinctive name. If PDF is supposed to mean something like "PhaseDistributionFile" then I suggest that you call it like that, instead of using the confusing acronym.
2. Do not try to delete the actor manager (lines 153-154 in GateImageDeformActor.cc)! You are not the owner. Fortunately you do not really do it, because you first set the pointer to nullptr and then you delete it, so this does exactly nothing. But you should not even try. Remove those lines...
3. lines 157-162 in that same source file: I think it is confusing to use variable i twice for totally different things with different types within the same scope. Earlier in that file it's an int used to loop over something, very natural, but here it is a double representing a time! Please give this variable a long and descriptive name, something like currentClockTime, instead of the sneaky i. :)
4. I see that your deformation example script (line 33 in mac/detectors.mac) uses a data/pdf.txt file, but this is not included in the pull request. Is that intentional, or did you forget to git add it?

Time is up for today for me. I hope this comments are somehow useful. I suspect that there will be more. :)