Added documentation on 3D graphics system

documentation/source/3dgraphics.rst

@@ -0,0 +1,48 @@
+3D Graphics
+===========
+
+Pyqtgraph uses OpenGL to provide a 3D scenegraph system. This system is functional but still early in development. 
+Current capabilities include:
+    
+* 3D view widget with zoom/rotate controls (mouse drag and wheel)
+* Scenegraph allowing items to be added/removed from scene with per-item transformations and parent/child relationships.
+* Triangular meshes
+* Basic mesh computation functions: isosurfaces, per-vertex normals
+* Volumetric rendering item
+* Grid/axis items
+
+See the :doc:`API Reference </3dgraphics/index>` and the Volumetric (GLVolumeItem.py) and Isosurface (GLMeshItem.py) examples for more information.
+
+Basic usage example::
+    
+    ## build a QApplication before building other widgets
+    import pyqtgraph as pg
+    pg.mkQApp()
+
+    ## make a widget for displaying 3D objects
+    import pyqtgraph.opengl as gl
+    view = gl.GLViewWidget()
+    view.show()
+
+    ## create three grids, add each to the view
+    xgrid = gl.GLGridItem()
+    ygrid = gl.GLGridItem()
+    zgrid = gl.GLGridItem()
+    view.addItem(xgrid)
+    view.addItem(ygrid)
+    view.addItem(zgrid)
+
+    ## rotate x and y grids to face the correct direction
+    xgrid.rotate(90, 0, 1, 0)
+    ygrid.rotate(90, 1, 0, 0)
+
+    ## scale each grid differently
+    xgrid.scale(0.2, 0.1, 0.1)
+    ygrid.scale(0.2, 0.1, 0.1)
+    zgrid.scale(0.1, 0.2, 0.1)
+
+
+
+
+
+

documentation/source/3dgraphics/glaxisitem.rst

@@ -0,0 +1,8 @@
+GLAxisItem
+==========
+
+.. autoclass:: pyqtgraph.opengl.GLAxisItem
+    :members:
+
+    .. automethod:: pyqtgraph.opengl.GLAxisItem.__init__
+

documentation/source/3dgraphics/glgraphicsitem.rst

@@ -0,0 +1,8 @@
+GLGraphicsItem
+==============
+
+.. autoclass:: pyqtgraph.opengl.GLGraphicsItem
+    :members:
+
+    .. automethod:: pyqtgraph.GLGraphicsItem.__init__
+

documentation/source/3dgraphics/glgriditem.rst

@@ -0,0 +1,8 @@
+GLGridItem
+==========
+
+.. autoclass:: pyqtgraph.opengl.GLGridItem
+    :members:
+
+    .. automethod:: pyqtgraph.opengl.GLGridItem.__init__
+

documentation/source/3dgraphics/glmeshitem.rst

@@ -0,0 +1,8 @@
+GLMeshItem
+==========
+
+.. autoclass:: pyqtgraph.opengl.GLMeshItem
+    :members:
+
+    .. automethod:: pyqtgraph.opengl.GLMeshItem.__init__
+

documentation/source/3dgraphics/glviewwidget.rst

@@ -0,0 +1,8 @@
+GLViewWidget
+============
+
+.. autoclass:: pyqtgraph.opengl.GLViewWidget
+    :members:
+
+    .. automethod:: pyqtgraph.opengl.GLViewWidget.__init__
+

documentation/source/3dgraphics/glvolumeitem.rst

@@ -0,0 +1,8 @@
+GLVolumeItem
+============
+
+.. autoclass:: pyqtgraph.opengl.GLVolumeItem
+    :members:
+
+    .. automethod:: pyqtgraph.opengl.GLVolumeItem.__init__
+

documentation/source/3dgraphics/index.rst

@@ -0,0 +1,24 @@
+Pyqtgraph's 3D Graphics System
+==============================
+
+The 3D graphics system in pyqtgraph is composed of a :class:`view widget <pyqtgraph.opengl.GLViewWidget>` and 
+several graphics items (all subclasses of :class:`GLGraphicsItem <pyqtgraph.opengl.GLGraphicsItem>`) which 
+can be added to a view widget.
+
+**Note:** use of this system requires python-opengl bindings. Linux users should install the python-opengl
+packages from their distribution. Windows/OSX users can download from `<http://pyopengl.sourceforge.net>`_.
+
+Contents:
+
+.. toctree::
+    :maxdepth: 2
+
+    glviewwidget
+
+    glgriditem
+    glmeshitem
+    glvolumeitem
+    glaxisitem
+    glgraphicsitem
+    meshdata
+

documentation/source/3dgraphics/meshdata.rst

@@ -0,0 +1,9 @@
+MeshData
+========
+
+.. autoclass:: pyqtgraph.opengl.MeshData.MeshData
+    :members:
+
+    .. automethod:: pyqtgraph.opengl.MeshData.MeshData.__init__
+    .. automethod:: pyqtgraph.opengl.MeshData.MeshData.__iter__
+

documentation/source/apireference.rst

@@ -9,4 +9,5 @@ Contents:
     functions
     graphicsItems/index
     widgets/index
-    graphicsscene/index
+    3dgraphics/index
+    graphicsscene/index

documentation/source/index.rst

@@ -16,6 +16,7 @@ Contents:
     how_to_use
     plotting
     images
+    3dgraphics
     style
     region_of_interest
     parametertree

graphicsItems/PlotCurveItem.py

@@ -34,7 +34,7 @@ class PlotCurveItem(GraphicsObject):
     sigPlotChanged = QtCore.Signal(object)
     sigClicked = QtCore.Signal(object)
     
-    def __init__(self, y=None, x=None, fillLevel=None, copy=False, pen=None, shadowPen=None, brush=None, parent=None, clickable=False):
+    def __init__(self, x=None, y=None, fillLevel=None, copy=False, pen=None, shadowPen=None, brush=None, parent=None, clickable=False):
         """
         ==============  =======================================================
         **Arguments:**

opengl/MeshData.py

@@ -3,12 +3,13 @@ import pyqtgraph.functions as fn
 
 class MeshData(object):
     """
-    Class for storing 3D mesh data. May contain:
+    Class for storing and operating on 3D mesh data. May contain:
-        - list of vertex locations
+    
-        - list of edges
+    - list of vertex locations
-        - list of triangles
+    - list of edges
-        - colors per vertex, edge, or tri
+    - list of triangles
-        - normals per vertex or tri
+    - colors per vertex, edge, or tri
+    - normals per vertex or tri
     """
 
     def __init__(self):
@@ -26,11 +27,15 @@ class MeshData(object):
     def setFaces(self, faces, vertexes=None):
         """
         Set the faces in this data set.
-        Data may be provided either as an Nx3x3 list of floats (9 float coordinate values per face)
+        Data may be provided either as an Nx3x3 list of floats (9 float coordinate values per face)::
-            *faces* = [ [(x, y, z), (x, y, z), (x, y, z)], ... ] 
+        
-        or as an Nx3 list of ints (vertex integers) AND an Mx3 list of floats (3 float coordinate values per vertex)
+            faces = [ [(x, y, z), (x, y, z), (x, y, z)], ... ] 
-            *faces* = [ (p1, p2, p3), ... ]
+            
-            *vertexes* = [ (x, y, z), ... ]
+        or as an Nx3 list of ints (vertex integers) AND an Mx3 list of floats (3 float coordinate values per vertex)::
+        
+            faces = [ (p1, p2, p3), ... ]
+            vertexes = [ (x, y, z), ... ]
+            
         """
         
         if vertexes is None:
@@ -147,18 +152,18 @@ class MeshData(object):
     def edgeColors(self):
         return self._edgeColors
         
-    def reverseNormals(self):
+    #def reverseNormals(self):
-        """
+        #"""
-        Reverses the direction of all normal vectors.
+        #Reverses the direction of all normal vectors.
-        """
+        #"""
-        pass
+        #pass
         
-    def generateEdgesFromFaces(self):
+    #def generateEdgesFromFaces(self):
-        """
+        #"""
-        Generate a set of edges by listing all the edges of faces and removing any duplicates.
+        #Generate a set of edges by listing all the edges of faces and removing any duplicates.
-        Useful for displaying wireframe meshes.
+        #Useful for displaying wireframe meshes.
-        """
+        #"""
-        pass
+        #pass
         
     def save(self):
         """Serialize this mesh to a string appropriate for disk storage"""

opengl/items/GLAxisItem.py

@@ -5,6 +5,13 @@ from pyqtgraph import QtGui
 __all__ = ['GLAxisItem']
 
 class GLAxisItem(GLGraphicsItem):
+    """
+    **Bases:** :class:`GLGraphicsItem <pyqtgraph.opengl.GLGraphicsItem>`
+    
+    Displays three lines indicating origin and orientation of local coordinate system. 
+    
+    """
+    
     def __init__(self, size=None):
         GLGraphicsItem.__init__(self)
         if size is None:

opengl/items/GLBoxItem.py

@@ -6,6 +6,11 @@ import pyqtgraph as pg
 __all__ = ['GLBoxItem']
 
 class GLBoxItem(GLGraphicsItem):
+    """
+    **Bases:** :class:`GLGraphicsItem <pyqtgraph.opengl.GLGraphicsItem>`
+    
+    Displays a wire-frame box.
+    """
     def __init__(self, size=None, color=None):
         GLGraphicsItem.__init__(self)
         if size is None:

opengl/items/GLGridItem.py

@@ -5,6 +5,12 @@ from pyqtgraph import QtGui
 __all__ = ['GLGridItem']
 
 class GLGridItem(GLGraphicsItem):
+    """
+    **Bases:** :class:`GLGraphicsItem <pyqtgraph.opengl.GLGraphicsItem>`
+    
+    Displays a wire-grame grid. 
+    """
+    
     def __init__(self, size=None, color=None):
         GLGraphicsItem.__init__(self)
         if size is None:

opengl/items/GLMeshItem.py

@@ -12,13 +12,13 @@ __all__ = ['GLMeshItem']
 
 class GLMeshItem(GLGraphicsItem):
     """
-    Displays a 3D triangle mesh. 
+    **Bases:** :class:`GLGraphicsItem <pyqtgraph.opengl.GLGraphicsItem>`
     
+    Displays a 3D triangle mesh. 
     """
     def __init__(self, faces, vertexes=None):
-        
         """
-        See MeshData for initialization arguments.
+        See :class:`MeshData <pyqtgraph.opengl.MeshData>` for initialization arguments.
         """
         if isinstance(faces, MeshData):
             self.data = faces

opengl/items/GLVolumeItem.py

@@ -6,7 +6,23 @@ import numpy as np
 __all__ = ['GLVolumeItem']
 
 class GLVolumeItem(GLGraphicsItem):
+    """
+    **Bases:** :class:`GLGraphicsItem <pyqtgraph.opengl.GLGraphicsItem>`
+    
+    Displays volumetric data. 
+    """
+    
+    
     def __init__(self, data, sliceDensity=1, smooth=True):
+        """
+        ==============  =======================================================================================
+        **Arguments:**
+        data            Volume data to be rendered. *Must* be 4D numpy array (x, y, z, RGBA) with dtype=ubyte.
+        sliceDensity    Density of slices to render through the volume. A value of 1 means one slice per voxel.
+        smooth          (bool) If True, the volume slices are rendered with linear interpolation 
+        ==============  =======================================================================================
+        """
+        
         self.sliceDensity = sliceDensity
         self.smooth = smooth
         self.data = data