Minor corrections for showing surfaces

dipy/io/vtk.py

@@ -15,10 +15,11 @@
     major_version = vtk.vtkVersion.GetVTKMajorVersion()
 
 
-# Input functions (load)
 def load_polydata(file_name):
     """ Load a vtk polydata to a supported format file
 
+    Supported file formats are OBJ, VTK, FIB, PLY, STL and XML
+
     Parameters
     ----------
     file_name : string
@@ -54,10 +55,11 @@ def load_polydata(file_name):
     return reader.GetOutput()
 
 
-# Output functions (save)
 def save_polydata(polydata, file_name, binary=False, color_array_name=None):
     """ Save a vtk polydata to a supported format file
 
+    Save formats can be VTK, FIB, PLY, STL and XML.
+
     Parameters
     ----------
     polydata : vtkPolyData

dipy/viz/utils.py

@@ -239,7 +239,8 @@ def get_polydata_lines(line_polydata):
 
     Returns
     -------
-    lines : list of N curves represented as 2D ndarrays
+    lines : list
+        List of N curves represented as 2D ndarrays
     """
     lines_vertices = ns.vtk_to_numpy(line_polydata.GetPoints().GetData())
     lines_idx = ns.vtk_to_numpy(line_polydata.GetLines().GetData())
@@ -266,7 +267,8 @@ def get_polydata_triangles(polydata):
 
     Returns
     -------
-    output : triangles, represented as 2D ndarrays (Nx3)
+    output : array (N, 3)
+        triangles
     """
     vtk_polys = ns.vtk_to_numpy(polydata.GetPolys().GetData())
     assert((vtk_polys[::4] == 3).all())  # test if its really triangles
@@ -282,7 +284,8 @@ def get_polydata_vertices(polydata):
 
     Returns
     -------
-    output : points, represented as 2D ndarrays (Nx3)
+    output : array (N, 3)
+        points, represented as 2D ndarrays
     """
     return ns.vtk_to_numpy(polydata.GetPoints().GetData())
 
@@ -296,8 +299,9 @@ def get_polydata_normals(polydata):
 
     Returns
     -------
-    output : normals, represented as 2D ndarrays (Nx3)
-             None (if no normals in the vtk polydata)
+    output : array (N, 3)
+        Normals, represented as 2D ndarrays (Nx3). None if there are no normals
+        in the vtk polydata.
     """
     vtk_normals = polydata.GetPointData().GetNormals()
     if vtk_normals is None:
@@ -315,8 +319,8 @@ def get_polydata_colors(polydata):
 
     Returns
     -------
-    output : colors, represented as 2D ndarrays (Nx3)
-             None (if no normals in the vtk polydata)
+    output : array (N, 3)
+        Colors. None if no normals in the vtk polydata.
     """
     vtk_colors = polydata.GetPointData().GetScalars()
     if vtk_colors is None:
@@ -325,16 +329,14 @@ def get_polydata_colors(polydata):
         return ns.vtk_to_numpy(vtk_colors)
 
 
-##########################################
-# Set PolyData properties with Numpy array
-##########################################
 def set_polydata_triangles(polydata, triangles):
     """ set polydata triangles with a numpy array (ndarrays Nx3 int)
 
     Parameters
     ----------
     polydata : vtkPolyData
-    triangles : triangles, represented as 2D ndarrays (Nx3)
+    triangles : array (N, 3)
+        triangles, represented as 2D ndarrays (Nx3)
     """
     vtk_triangles = np.hstack(np.c_[np.ones(len(triangles)).astype(np.int) * 3,
                                     triangles])
@@ -379,7 +381,7 @@ def set_polydata_colors(polydata, colors):
     ----------
     polydata : vtkPolyData
     colors : colors, represented as 2D ndarrays (Nx3)
-                colors are uint8 [0,255] RGB for each points
+        colors are uint8 [0,255] RGB for each points
     """
     vtk_colors = ns.numpy_to_vtk(colors, deep=True,
                                  array_type=vtk.VTK_UNSIGNED_CHAR)
@@ -390,7 +392,7 @@ def set_polydata_colors(polydata, colors):
 
 
 def update_polydata_normals(polydata):
-    """ generate and update polydata normal
+    """ generate and update polydata normals
 
     Parameters
     ----------
@@ -409,10 +411,6 @@ def update_polydata_normals(polydata):
     polydata.GetPointData().SetNormals(vtk_normals)
 
 
-##########################################
-# Transform vtkPolyData : vtkPolyDataMapper, vtkActor
-##########################################
-
 def get_polymapper_from_polydata(polydata):
     """ get vtkPolyDataMapper from a vtkPolyData
 

doc/examples/valid_examples.txt

@@ -49,4 +49,5 @@
  viz_widgets.py
  contextual_enhancement.py
  workflow_creation.py
- combined_workflow_creation.py
+ combined_workflow_creation.py
+ viz_surfaces.py

doc/examples/viz_surfaces.py

@@ -1,14 +1,23 @@
 """
-========================================
-Visualize surfaces; load/save, get/set and update vtkPolyData.
-========================================
+==================
+Visualize surfaces
+==================
+
+Here is a simple tutorial that shows how to visualize surfaces using DIPY. It
+also shows how to load/save, get/set and update vtkPolyData and show
+surfaces.
 
-import usefull functions and dipy utils
+vtkPolyData is a structure used by VTK to represent surfaces and other data
+structures. Here we show how to visualize a simple cube but the same idea
+should apply for any surface.
 """
-from __future__ import division, print_function, absolute_import
+
 import numpy as np
 
-# and dipy tools
+"""
+Import useful functions from dipy.viz.utils
+"""
+
 import dipy.io.vtk as io_vtk
 import dipy.viz.utils as ut_vtk
 from dipy.viz import window
@@ -19,13 +28,15 @@
 vtk, have_vtk, setup_module = optional_package('vtk')
 
 """
-generate a empty vtkPolyData
+Create an empty vtkPolyData
 """
+
 my_polydata = vtk.vtkPolyData()
 
 """
-generate a cube with vertices and triangles numpy array
+Create a cube with vertices and triangles as numpy arrays
 """
+
 my_vetices = np.array([[0.0,  0.0,  0.0],
                        [0.0,  0.0,  1.0],
                        [0.0,  1.0,  0.0],
@@ -50,26 +61,30 @@
 
 
 """
-set vertices and triangles in poly data
+Set vertices and triangles in poly data
 """
+
 ut_vtk.set_polydata_vertices(my_polydata, my_vetices)
 ut_vtk.set_polydata_triangles(my_polydata, my_triangles)
 
 """
-save polydata
+Save polydata
 """
+
 file_name = "my_cube.vtk"
 io_vtk.save_polydata(my_polydata, file_name)
-print("save surface :", file_name)
+print("Surface saved in " + file_name)
 
 """
-load polydata
+Load polydata
 """
+
 cube_polydata = io_vtk.load_polydata(file_name)
 
 """
 add color based on vertices position
 """
+
 cube_vertices = ut_vtk.get_polydata_vertices(cube_polydata)
 colors = cube_vertices * 255
 ut_vtk.set_polydata_colors(cube_polydata, colors)
@@ -80,6 +95,7 @@
 """
 Visualize surfaces
 """
+
 # get vtkActor
 cube_actor = ut_vtk.get_actor_from_polydata(cube_polydata)
 
@@ -92,3 +108,10 @@
 # display
 # window.show(renderer, size=(600, 600), reset_camera=False)
 window.record(renderer, out_path='cube.png', size=(600, 600))
+
+"""
+.. figure:: cube.png
+   :align: center
+
+   **An example of a simple surface visualized with DIPY**.
+"""

doc/examples_index.rst

@@ -209,6 +209,7 @@ Visualization (NEW)
 - :ref:`example_viz_slice`
 - :ref:`example_viz_bundles`
 - :ref:`example_viz_widgets`
+- :ref:`example_viz_surfaces`
 
 ---------------
 Workflows (NEW)