Merge pull request #150 from UCL/149-add-voxelisation

149 add voxelisation

README.rst

@@ -35,7 +35,7 @@ Functionality includes:
 * `A widget to overlay <https://scikit-surgeryvtk.readthedocs.io/en/latest/widgets/index.html#module-sksurgeryvtk.widgets.vtk_overlay_window>`_ 3D models onto a background image e.g. from webcam/video file, useful for Augmented Reality (AR) overlays, using VTK.
 * Functions for working with `calibrated cameras <https://scikit-surgeryvtk.readthedocs.io/en/latest/camera/index.html>`_, and projecting points from 3D to 2D.
 * A widget to drive a `stereo interlaced monitor <https://scikit-surgeryvtk.readthedocs.io/en/latest/widgets/index.html#module-sksurgeryvtk.widgets.vtk_interlaced_stereo_window>`_.
-
+* Functions to `voxelise data and calculate distance fields <https://scikit-surgeryvtk.readthedocs.io/en/latest/widgets/index.html#module-sksurgeryvtk.models.voxelise>`_.
 
 .. features-end
 

docs/module_ref.rst

@@ -6,22 +6,30 @@ Overlay Widget
 ^^^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.widgets.vtk_overlay_window
    :members:
+   :undoc-members:
+   :show-inheritance:
 
 Stereo interlaced Widget
 ^^^^^^^^^^^^^^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.widgets.vtk_interlaced_stereo_window
    :members:
+   :undoc-members:
+   :show-inheritance:
 
 
 Rendering Generator
 ^^^^^^^^^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.widgets.vtk_rendering_generator
    :members:
+   :undoc-members:
+   :show-inheritance:
 
 Reslice Widget
 ^^^^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.widgets.vtk_reslice_widget
    :members:
+   :undoc-members:
+   :show-inheritance:
 
 VTK Model Data
 --------------
@@ -30,48 +38,68 @@ Base Model
 ^^^^^^^^^^
 .. automodule:: sksurgeryvtk.models.vtk_base_model
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 Surface Models
 ^^^^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.models.vtk_surface_model
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 .. automodule:: sksurgeryvtk.models.surface_model_loader
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 .. automodule:: sksurgeryvtk.models.surface_model_directory_loader
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 Image Model
 ^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.models.vtk_image_model
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 Point Model
 ^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.models.vtk_point_model
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 Geometric Primitives
 ^^^^^^^^^^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.models.vtk_sphere_model
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 .. automodule:: sksurgeryvtk.models.vtk_cylinder_model
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 
 Camera Utilities
 ----------------
 
 .. automodule:: sksurgeryvtk.camera.vtk_camera_model
    :members:
+   :undoc-members:
+   :show-inheritance:
 
 Text Overlay
 ------------
 
 .. automodule:: sksurgeryvtk.text.text_overlay
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 Misc Utilities
 --------------
@@ -80,17 +108,26 @@ Matrix Utilities
 ^^^^^^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.utils.matrix_utils
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 Projection Utilities
 ^^^^^^^^^^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.utils.projection_utils
     :members:
+   :undoc-members:
+   :show-inheritance:
 
 Polydata Utilities
 ^^^^^^^^^^^^^^^^^^
 .. automodule:: sksurgeryvtk.utils.polydata_utils
     :members:
+   :undoc-members:
+   :show-inheritance:
 
-
-
-
+Voxelisation & Distance Fields
+------------------------------
+.. automodule:: sksurgeryvtk.models.voxelise
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/tutorials/voxelisation.rst

@@ -0,0 +1,91 @@
+Distance Field Calcualtion & Voxelisation
+=========================================
+
+This tutorial demonstrates how to generate voxelised data and calculate distance fields, originally
+for use with the `Volume2SurfaceCNN <https://gitlab.com/nct_tso_public/Volume2SurfaceCNN>`_ model.
+
+We will use the example of a liver model and intraoperative surface, but this can be applied to any 3D
+model and partial surface. Data used for this example can be found in the `GitHub repository <https://github.com/UCL/scikit-surgeryvtk>`_.
+
+.. image:: ./voxelisation_images/voxelisation.png
+  :width: 50%
+
+**Figure 1 - Original model/surface (left) and voxelised model/surface (right)**
+
+Creating a signed distance field from a 3D model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setup parameters:
+
+.. literalinclude:: ../../tests/models/test_voxelise.py
+    :language: python
+    :start-after: #Tutorial-section-1-start
+    :end-before: #Tutorial-section-1-end
+
+The input mesh is expected to be in metres. If it is in mm, as above, we pass a scale factor of 0.001.
+Run voxelisation function:
+
+.. literalinclude:: ../../tests/models/test_voxelise.py
+    :language: python
+    :start-after: #Tutorial-section-2-start
+    :end-before: #Tutorial-section-2-end
+
+The `voxelise` function returns a vtkStructuredGrid, but it also writes the data
+to the file specified by `output_grid`, which now contains a 3D volume, and a
+data array `preoperativeSurface`, which stores the distance value for each
+voxel in the grid.
+
+Negative distance values indicate that the element is inside the surface. We can
+use this property to visualise the voxelised model using suitable software, e.g. ParaView.
+
+If we apply a threshold filter only showing negative values, this will show the model surface:
+
+.. image:: ./voxelisation_images/preop_threshold.png
+
+Creating an usigned distance field from a surface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The process for creating a distance field for a surface is similar, except we calculate
+the unsigned distance field, which will be stored in a data array 'intraoperativeSurface'.
+
+.. literalinclude:: ../../tests/models/test_voxelise.py
+    :language: python
+    :start-after: #Tutorial-section-3-start
+    :end-before: #Tutorial-section-3-end
+
+The distance field can be calculated from a file, as above, or from a numpy array:
+
+.. literalinclude:: ../../tests/models/test_voxelise.py
+    :language: python
+    :start-after: #Tutorial-section-4-start
+    :end-before: #Tutorial-section-4-end
+
+We can visualise the intraoperative surface, by using a threshold filter between
+0 and the (roughly) voxel size, which is equal to `size/grid_elements`
+
+.. image:: ./voxelisation_images/postop_threshold.png
+
+Applying a displacement field to a mesh
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Once a displacement field has been calcualted (e.g. by V2SNet in `scikit-surgerytorch <https://github.com/UCL/scikit-surgerytorch>`_),
+it can be used to displace an input mesh. This could be the orginal preoperative surface, or objects inside the surface model (e.g. vessels, tumors).
+Objects outside the surface of the preoperative mesh do not have a valid displacement defined.
+
+The output mesh can optionally be saved by specifying a file name for the save_mesh argument.
+
+.. literalinclude:: ../../tests/models/test_voxelise.py
+    :language: python
+    :start-after: #Tutorial-section-5-start
+    :end-before: #Tutorial-section-5-end
+
+Streamlined Workflow
+~~~~~~~~~~~~~~~~~~~~
+
+The above examples have been reading/writing vtk data to an output mesh on disk. However,
+this can be inefficient if we are repeatedly calling the function, and we can get the same results by just working with the vtk grid in memory instead.
+The voxelise function can take a vtkStructuredGrid, instead of a file path, as the `output_grid` agrument.
+
+.. literalinclude:: ../../tests/models/test_voxelise.py
+    :language: python
+    :start-after: #Tutorial-section-6-start
+    :end-before: #Tutorial-section-6-end