update sphinx documentation.

11 files changed, 144 insertions, 25 deletions

diff --git a/camera.py b/camera.py
index f4f4b39..15b0916 100755
--- a/camera.py
+++ b/camera.py
@@ -78,6 +78,7 @@ def encode_movie(dir):
     print 'movie saved to %s.' % filename
 
 class Camera(multiprocessing.Process):
+    "The camera class is used to render a Geometry object."
     def __init__(self, geometry, size=(800,600), device_id=None):
         multiprocessing.Process.__init__(self)
         self.geometry = geometry
@@ -127,11 +128,14 @@ class Camera(multiprocessing.Process):
             pass
 
         lower_bound, upper_bound = self.geometry.mesh.get_bounds()
-        self.scale = np.linalg.norm(upper_bound-lower_bound)
+
+        self.mesh_diagonal_norm = np.linalg.norm(upper_bound-lower_bound)
+
+        self.scale = self.mesh_diagonal_norm
 
         self.nblocks = 64
 
-        self.point = np.array([0, -self.scale*1.0,
+        self.point = np.array([0, -self.mesh_diagonal_norm,
                                (lower_bound[2]+upper_bound[2])/2])
 
         self.axis1 = np.array([0,0,1], float)
@@ -160,8 +164,8 @@ class Camera(multiprocessing.Process):
         self.display3d = False
 
     def enable3d(self):
-        self.point1 = self.point-(self.scale/60)*self.axis2
-        self.point2 = self.point+(self.scale/60)*self.axis2
+        self.point1 = self.point-(self.mesh_diagonal_norm/60)*self.axis2
+        self.point2 = self.point+(self.mesh_diagonal_norm/60)*self.axis2
 
         self.viewing_angle = 0.0
 
@@ -472,28 +476,18 @@ class Camera(multiprocessing.Process):
                     self.rotate(phi, n)
 
         elif event.type == KEYDOWN:
-            if event.key == K_a:
-                v = self.scale*self.axis2/10.0
-                self.translate(v)
-
-            elif event.key == K_d:
-                v = -self.scale*self.axis2/10.0
-                self.translate(v)
-
-            elif event.key == K_w:
-                v = self.scale*np.cross(self.axis1,self.axis2)/10.0
-                self.translate(v)
-
-            elif event.key == K_s:
-                v = -self.scale*np.cross(self.axis1,self.axis2)/10.0
-                self.translate(v)
+            if event.key == K_LALT or event.key == K_RALT:
+                if self.scale == self.mesh_diagonal_norm:
+                    self.scale /= 20.0
+                else:
+                    self.scale = self.mesh_diagonal_norm
 
             elif event.key == K_F6:
                 self.clear_xyz_lookup()
                 self.clear_image()
                 self.source_position = self.point
 
-            elif event.key == K_p:
+            elif event.key == K_F7:
                 for i in range(100):
                     self.update_xyz_lookup(self.point)
                 self.source_position = self.point
diff --git a/doc/source/geometry.rst b/doc/source/geometry.rst
index 347e1d3..a3f7463 100644
--- a/doc/source/geometry.rst
+++ b/doc/source/geometry.rst
@@ -9,14 +9,67 @@ The Mesh Class
 .. autoclass:: Mesh
    :members:
 
+The Solid Class
+---------------
+
+.. autoclass:: Solid
+   :members:
+
+The Material Class
+------------------
+
+.. autoclass:: Material
+   :members:
+
+The Geometry Class
+------------------
+
+.. autoclass:: Geometry
+   :members:
+
 Importing from STL
 ------------------
 
-.. automodule:: chroma.stl
-   :members: mesh_from_stl
+.. autofunction:: chroma.mesh_from_stl
 
 Mesh Modelling Tools
 --------------------
 
-.. automodule:: chroma.make
-   :members: linear_extrude, rotate_extrude, box, cube, cylinder, segmented_cylinder, sphere, torus
+.. module:: chroma.make
+
+.. autofunction:: linear_extrude
+
+.. image:: images/hexagonal_prism.png
+   :height: 100px
+
+.. autofunction:: rotate_extrude
+
+.. image:: images/bipyramid.png
+   :height: 100px
+
+.. autofunction:: box
+
+.. image:: images/box.png
+   :height: 100px
+
+.. autofunction:: cube
+
+.. image:: images/cube.png
+   :height: 100px
+
+.. autofunction:: cylinder
+
+.. image:: images/cylinder.png
+   :height: 100px
+
+.. autofunction:: segmented_cylinder
+
+.. autofunction:: sphere
+
+.. image:: images/sphere.png
+   :height: 100px
+
+.. autofunction:: torus
+
+.. image:: images/torus.png
+   :height: 100px
diff --git a/doc/source/images/bipyramid.png b/doc/source/images/bipyramid.png
new file mode 100644
index 0000000..17f6f64
--- /dev/null
+++ b/doc/source/images/bipyramid.png
diff --git a/doc/source/images/box.png b/doc/source/images/box.png
new file mode 100644
index 0000000..c9ab226
--- /dev/null
+++ b/doc/source/images/box.png
diff --git a/doc/source/images/cube.png b/doc/source/images/cube.png
new file mode 100644
index 0000000..fff0c39
--- /dev/null
+++ b/doc/source/images/cube.png
diff --git a/doc/source/images/cylinder.png b/doc/source/images/cylinder.png
new file mode 100644
index 0000000..7574f0f
--- /dev/null
+++ b/doc/source/images/cylinder.png
diff --git a/doc/source/images/hexagonal_prism.png b/doc/source/images/hexagonal_prism.png
new file mode 100644
index 0000000..04b1341
--- /dev/null
+++ b/doc/source/images/hexagonal_prism.png
diff --git a/doc/source/images/sphere.png b/doc/source/images/sphere.png
new file mode 100644
index 0000000..bb1c8a5
--- /dev/null
+++ b/doc/source/images/sphere.png
diff --git a/doc/source/images/torus.png b/doc/source/images/torus.png
new file mode 100644
index 0000000..79bde5b
--- /dev/null
+++ b/doc/source/images/torus.png
diff --git a/doc/source/render.rst b/doc/source/render.rst
index 297c083..23b4735 100644
--- a/doc/source/render.rst
+++ b/doc/source/render.rst
@@ -1,2 +1,70 @@
 Rendering Tools
 ===============
+
+.. module:: chroma
+
+There are three different ways to render a geometry: you can explicitly create a :class:`Camera` instance, call the function :func:`view`, or use the script `chroma-cam`.
+
+Example:
+        >>> chroma.view(chroma.make.cube())
+
+.. image:: images/cube.png
+   :height: 100px
+
+To control the camera refer to the following table and :ref:`camera_hotkeys`.
+
+.. _camera_controls:
+
+============== =========== ===========================
+Thing You Do   Modifier    Thing That Happens
+============== =========== ===========================
+click and drag             rotate camera around object
+click and drag shift       translate camera
+click and drag control     rotate camera
+mouse wheel                zoom
+============== =========== ===========================
+
+
+.. _camera_hotkeys:
+
+Camera Hotkeys
+--------------
+
+========= ===============================
+Command   Thing That Happens
+========= ===============================
+alt       toggle fine motion
+F11       toggle fullscreen
+escape    quit
+=         increase the alpha depth by one
+\-        decrease the alpha depth by one
+pagedown  move down through the bounding volume hierarchy tree
+pageup    move up through the bounding volume hierarchy tree
+3         toggle 3d mode
+g         toggle 3d colors between red/cyan and green/magenta
+F12       take a screenshot
+m         make a movie
+F5 [#f1]_ toggle hybrid monte carlo rendering mode
+F6 [#f2]_ place a light source at the camera's current location
+F7 [#f2]_ add another light source at the camera's current location
+========= ===============================
+
+.. rubric:: Footnotes
+
+.. [#f1] The hybrid monte carlo rendering mode requires the geometry have surfaces with a non-zero diffuse reflection probability.
+
+.. [#f2] Only available in hybrid monte carlo rendering mode.
+
+The Camera Class
+----------------
+
+.. class:: Camera(geometry, size=(800,600), device_id=None)
+
+   The :class:`Camera` class uses :mod:`pygame` to render a geometry.
+   :class:`Camera` objects inherit from :class:`multiprocessing.Process` so
+   that you can render multiple geometries in separate windows at the same
+   time. 
+
+   .. method:: start()
+
+      Create a :mod:`pygame` window, intialize CUDA, and start the camera.
diff --git a/make.py b/make.py
index fa66c4d..0623b2b 100644
--- a/make.py
+++ b/make.py
@@ -20,7 +20,7 @@ def linear_extrude(x1, y1, height, x2=None, y2=None, center=None):
     Example:
         >>> # create a hexagon prism
         >>> angles = np.linspace(0, 2*np.pi, 6, endpoint=False)
-        >>> m = linear_extrude(np.cos(angles), np.sin(angles), 5.0)
+        >>> m = linear_extrude(np.cos(angles), np.sin(angles), 2.0)
     """
     if len(x1) != len(y1):
         raise Exception('`x` and `y` arrays must have the same length.')
@@ -56,6 +56,10 @@ def rotate_extrude(x, y, nsteps=64):
     .. note::
         The path traced by the points `x` and `y` should go counter-clockwise,
         otherwise the mesh will be inside out.
+
+    Example:
+        >>> # create a bipyramid
+        >>> m = rotate_extrude([0,1,0], [-1,0,1], nsteps=4)
     """
     if len(x) != len(y):
         raise Exception('`x` and `y` arrays must have the same length.')