OpenGATE / opengate

Gate 10 (beta)
http://www.opengatecollaboration.org
GNU Lesser General Public License v3.0
46 stars 40 forks source link

Implement dynamic parametrisation #319

Closed nkrah closed 9 months ago

nkrah commented 10 months ago

The purpose of this PR is to implement a generic mechanism to handle dynamic simulations, i.e. simulations whose configurations changes over time. This could be for example moving volumes, but also moving patients modeled via 4D CT images, or sources with time dependent parameters such as energy.

The idea is that the user specifies for a given object how some of its parameters are supposed to evolve over time. This is done via an add_dynamic_parametrisation method. The user passes lists of parameters as keyword argument, each entry corresponding to one time sampling point. The object's class should implement a initialize_dynamic_parametrisation method which takes the necessary steps to actually have the requested dynamic changes happen. This can be achieved for example via actors, e.g. a MotionActor, to be attached to the volume. User info which are allowed to change over time should be marked by the keyword 'dynamic': True in the class's user_info_defaults.

In a first step, the new mechanism should faithfully handle what is up to now done directly via MotionActors. The PR currently implements dynamic parametrization in the VolumeBase class for the user infos 'translation' and 'rotation'. A new variant of test030, called test030_dose_motion_dynamic_param.py demonstrates the use of the mechanism.

The next step will be to implement an ImageVolumeChangeActor which allows the user to make an ImageVolume's image time-dependent.

UPDATE: This PR now also implements 4D image support, meaning an ImageVolume whose voxel values evolve over time.

UPDATE: This PR also improved the processing of image input in an ImageVolume, i.e. the creation of a label_image to assign materials to voxels. The code now relies on bumpy.digitize() which is much faster than manual iteration.

nkrah commented 10 months ago

You can now easily implement a 4D volumetric image by providing a list of image filenames to be used for the run timing intervals of the simulation. Example:

patient.add_dynamic_parametrisation(image=[paths.data / "patient-4mm.mhd", paths.data / "patient-4mm_2.mhd"])
nkrah commented 10 months ago

I still need to put together a proper example based on a 4D dataset.

nkrah commented 9 months ago

I still need to put together a proper example based on a 4D dataset.

This is done. See test070

nkrah commented 9 months ago

From my side, this PR is ready. We can discuss about it this upcoming week.

Note: The code in the alternative versions of test069 (and the original tests) could still be cleaned, but I opted to make minimal changes only to switch to the new dynamic parametrization method.