.. _using_real_data:

Using real patient data in your pipeline
*****************************************

One of the pipeline's core features is that it can generate organ-like structures and scenes automatically. However, to test whether your applications could also work with real meshes, the simulations can also be run on meshes extracted from patient data.
Testing on such a simulated scenario doesn't replace testing on phantom or real data, but it may give insights into the strengths and weaknesses the developped downstream methods.

Note: The "src/run_nonrigid.py" sample shows how examples of how to set up a full pipeline to optionally use real data by passing a :code:`--mesh_source_folder`, however we recommend reading through the following first.

Step 1: Prepare your input meshes
-----------------------------------

We support loading surface meshes as input. You should create a source mesh directory which contains a sub-folder for each patient. Example:

* mesh_source
    * patient_1
        * liver.stl
        * spleen.stl
        * gallbladder.stl
    * patient_2
        * liver.stl
        * spleen.stl
    * ...


We recommend to make sure meshes are water-tight.

Step 2: Let the pipeline use your meshes:
------------------------------------------

Once a :class:`~blocks.scene_objects.scene_object_generator_block.SceneObjectGeneratorBlock` has been added to your pipeline, you can call its method :meth:`~blocks.scene_objects.scene_object_generator_block.SceneObjectGeneratorBlock.set_mesh_source_folder` and pass the folder in which your meshes lie. This will attempt to fill the surface meshes from ones that it finds within this folder. This is done by first identifying "patient" folders within your path and then assigning the first patient to DataSample 0, the second patient meshes to DataSample 1 and so on. If you have setup your DataSet to use more DataSamples than you have organ meshes of the same type here, it will restart from the beginning until all DataSamples have a patient assigned.

By default, file names will be searched for which match the object's unique name given through the corresponding SceneObjectFactory.unique_object_name property. If you want more control over this, see :meth:`~blocks.scene_objects.scene_object_generator_block.SceneObjectGeneratorBlock.set_surface_filename_regex` .

You should also take care of scales in this step. We recommend to use SI units. Since most patient meshes tend to be represented in millimeters, we usually call set_mesh_source_folder with a scale of 1e-3.

This whole process may seem rather complicated, but the nice thing about it is that it allows the generated scenes to be partially random, i.e. you can use a real liver mesh and let the pipeline generate random surrounding organs and boundary conditions.