Issue #65: Add basic docs.

Author: MattClarkson

README.rst

@@ -54,7 +54,7 @@ Open a terminal, load your virtual environment and run the application as `pytho
 * sksurgeryreslice.py - DICOM reslice widget demo.
 * sksurgerytextoverlay.py - VTK text overlay demo.
 * sksurgerytransformpolydata.py - Read a surface mesh (.vtk,.vtp,.stl,.ply file), transform by 4x4 matrix and write as .vtk.
-* sksurgerystereorenderer.py - Reads a set of meshes, overlays on stereo video.
+* sksurgerystereorenderer.py - Reads a set of meshes, overlays on stereo video. `Documentation <stereo_renderer_demo.rst>`_.
 
 .. features-end
 
@@ -93,7 +93,7 @@ You can install dependencies and run the unit tests by installing and running to
     tox -e docs
     tox -e lint
 
-Tox will create a separate venv in ```.tox/test```. See ```tox.ini``` for commands that tox runs.
+Tox will create a separate venv in ``.tox/test``. See ``tox.ini`` for commands that tox runs.
 
 Encountering Problems?
 ^^^^^^^^^^^^^^^^^^^^^^

docs/index.rst

@@ -12,6 +12,7 @@ scikit-surgeryutils documentation
    :maxdepth: 2
 
    readme
+   stereo_renderer_demo
 
 .. toctree::
    :maxdepth: 2

docs/stereo_renderer_demo.rst

@@ -0,0 +1,157 @@
+Stereo Renderer Demo
+^^^^^^^^^^^^^^^^^^^^
+
+Features
+
+- Loads left intrinsics, right intrinsics, left-to-right extrinsics
+- Loads a set of models, using a single .json file
+- Plays video, or loads a single static image
+- Overlays models on top of video
+- Creates 2 windows.
+ - One for interacting
+ - One for a stereo display, either interlaced or stacked
+- Allows interacting with models, changing the model-to-world transform
+- Camera defaults to origin
+
+Usage
+^^^^^
+
+Create .json descriptor
+-----------------------
+
+A set of models (.vtk, .vtp, .stl, .ply) can be loaded.
+Rather than have many command line args, we use a .json file.
+The format is::
+
+    {
+        "surfaces": {
+            "kidney": {
+                "file": "kidney.vtk",
+                "colour": [213, 142, 119],
+                "opacity": 0.5,
+                "visibility": true,
+                "pickable": true
+            },
+            "artery": {
+                "file": "artery.vtk",
+                "colour": [203, 81, 54],
+                "opacity": 0.5,
+                "visibility": true,
+                "pickable": false
+            },
+            "cyst": {
+                "file": "cyst.vtk",
+                "colour": [144, 221, 157],
+                "opacity": 0.5,
+                "visibility": true,
+                "pickable": false
+            },
+            "renalsinusfat": {
+                "file": "renalSinusFat.vtk",
+                "colour": [161, 115, 220],
+                "opacity": 0.5,
+                "visibility": true,
+                "pickable": false
+            },
+            "vein": {
+                "file": "vein.vtk",
+                "colour": [54, 109, 188],
+                "opacity": 0.5,
+                "visibility": true,
+                "pickable": false
+            }
+        }
+    }
+
+Note: There should only ever be 1 "pickable" object.
+The pickable object is the one you interact with.
+
+You can set colour ``[R, G, B]``, opacity ``[0, 1]`` and visibility ``[true|false]``, as shown above.
+
+Calibration Files
+-----------------
+
+Camera calibration files should be plain text, ASCII files, as would
+be compatible with ``numpy.loadtxt(filename)``.
+
+- Intrinsics: [3x3]
+- Stereo extrinsics: [4x4]
+
+Note: We do not load distortion parameters. Therefore, video must be undistorted.
+
+
+Usage
+-----
+
+If you have ``pip install``-ed the whole package, you can see the usage message by
+running the ``sksurgerystereorenderer`` entry point with ``-h``.
+
+For example::
+
+    promt% sksurgerystereorenderer -h
+    usage: sksurgerystereorenderer [-h] -li LEFT_INTRINSICS -ri RIGHT_INTRINSICS -l2r LEFT_TO_RIGHT -m MODELS -r CLIPPING_RANGE -lv LEFT_VIDEO -rv RIGHT_VIDEO [-m2w MODEL_TO_WORLD] [-c2w CAMERA_TO_WORLD]
+                                   [-s {stacked,interlaced}] [-v]
+
+    sksurgerystereorenderer - Stereo augmented reality renderer with interactive model manipulation.
+
+    options:
+      -h, --help            show this help message and exit
+      -li, --left_intrinsics LEFT_INTRINSICS
+                            File path to left camera 3x3 intrinsics matrix.
+      -ri, --right_intrinsics RIGHT_INTRINSICS
+                            File path to right camera 3x3 intrinsics matrix.
+      -l2r, --left_to_right LEFT_TO_RIGHT
+                            File path to 4x4 stereo left-to-right extrinsic matrix.
+      -m, --models MODELS   Path to models .json configuration file.
+      -r, --clipping_range CLIPPING_RANGE
+                            Near,far clipping range (e.g. '1,1000').
+      -lv, --left_video LEFT_VIDEO
+                            Left video source: integer device index, video file path, or static image (.png/.jpg).
+      -rv, --right_video RIGHT_VIDEO
+                            Right video source: integer device index, video file path, or static image (.png/.jpg).
+      -m2w, --model_to_world MODEL_TO_WORLD
+                            File path to a 4x4 model-to-world matrix applied to all models on startup.
+      -c2w, --camera_to_world CAMERA_TO_WORLD
+                            File path to a 4x4 camera-to-world matrix for the initial camera pose.
+      -s, --stereo_mode {stacked,interlaced}
+                            Stereo display mode: 'stacked' (left=top, right=bottom) or 'interlaced'. Default: stacked.
+      -v, --version         show program's version number and exit
+
+Alternatively, if you are running a development environment::
+
+    prompt% source .tox/test/bin/activate
+    prompt% python sksurgerystereorenderer.py -h
+
+gives the same output as the above help message.
+
+An example would be::
+
+    prompt% source .tox/test/bin/activate
+    prompt% python sksurgerystereorenderer.py \
+      -m patient.json \
+      -li davinci_intrinsics_undistorted.txt \
+      -ri davinci_intrinsics_undistorted.txt \
+      -l2r left_to_right.txt \
+      -lv leftVideo_undistorted.avi \
+      -rv rightVideo_undistorted.avi \
+      -r 1,1000
+
+Screens
+-------
+
+The app can make use of a 2-monitor setup.
+
+- If you have 2 monitors, the primary (e.g. laptop) shows a window for interacting, and the secondary (e.g. external 3D monitor) shows the stereo display. Both maximised.
+- If you have 1 monitor, both windows appear on the same monitor, both unmaximised.
+
+
+Interation Controls
+-------------------
+
+Similar to standard VTK controls, and you need a 3-button mouse.
+
+- Left button and move left-right: Rotate about centroid, left-right
+- Left button and move up-down: Rotate about centroid, up-down
+- Scroll wheel: Zoom in/out, by moving the model towards/away from camera
+- Right button and move: spin about forward axis
+- Middle button and move: pan (i.e. translation)

setup.py

@@ -72,6 +72,7 @@
             'sksurgeryvideocalibration=sksurgeryutils.ui.sksurgeryvideocalibration_command_line:main',
             'sksurgeryvideocalibrationchecker=sksurgeryutils.ui.sksurgeryvideocalibrationchecker_command_line:main',
             'sksurgeryrenderoverlay=sksurgeryutils.ui.sksurgeryrenderoverlay_command_line:main',
+            'sksurgerystereorenderer=sksurgeryutils.ui.sksurgerystereorenderer_command_line:main',
         ],
     },
 )

sksurgeryutils/ui/sksurgerystereorenderer_demo.py

@@ -259,6 +259,7 @@ def __init__(self,
             self.set_model_to_world(model_to_world)
 
         # Apply initial camera pose if provided
+        self.camera_to_world = None
         if camera_to_world is not None:
             self.set_camera_to_world(camera_to_world)
         else:
@@ -345,6 +346,10 @@ def update(self):
             LOGGER.warning("Could not read frame from video source.")
             return
 
+        # For now, the camera is at the origin, and we move the model.
+        # So, we can also defend against the user interacting with the 3D window.
+        self.set_camera_to_world(np.eye(4))
+
         # Set left image on the interactive overlay
         self.overlay_window.set_video_image(left_frame)
         self.overlay_window.Render()
@@ -447,11 +452,12 @@ def set_camera_to_world(self, camera_to_world):
         :param camera_to_world: 4x4 numpy ndarray, left camera to world.
         """
         # Set left camera on overlay
+        self.camera_to_world = camera_to_world
         self.overlay_window.set_camera_pose(camera_to_world)
 
         # Set stereo cameras using the left-to-right extrinsic
         self.stereo_window.set_poses_from_left_camera(
-            camera_to_world, self.left_to_right)
+            self.camera_to_world, self.left_to_right)
 
     def set_model_to_world(self, model_to_world):
         """