Commit 2149f9db authored by Luke Campagnola's avatar Luke Campagnola
Browse files

Added documentation on 3D graphics system

parent 41bc951a
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)
GLAxisItem
==========
.. autoclass:: pyqtgraph.opengl.GLAxisItem
:members:
.. automethod:: pyqtgraph.opengl.GLAxisItem.__init__
GLGraphicsItem
==============
.. autoclass:: pyqtgraph.opengl.GLGraphicsItem
:members:
.. automethod:: pyqtgraph.GLGraphicsItem.__init__
GLGridItem
==========
.. autoclass:: pyqtgraph.opengl.GLGridItem
:members:
.. automethod:: pyqtgraph.opengl.GLGridItem.__init__
GLMeshItem
==========
.. autoclass:: pyqtgraph.opengl.GLMeshItem
:members:
.. automethod:: pyqtgraph.opengl.GLMeshItem.__init__
GLViewWidget
============
.. autoclass:: pyqtgraph.opengl.GLViewWidget
:members:
.. automethod:: pyqtgraph.opengl.GLViewWidget.__init__
GLVolumeItem
============
.. autoclass:: pyqtgraph.opengl.GLVolumeItem
:members:
.. automethod:: pyqtgraph.opengl.GLVolumeItem.__init__
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
MeshData
========
.. autoclass:: pyqtgraph.opengl.MeshData.MeshData
:members:
.. automethod:: pyqtgraph.opengl.MeshData.MeshData.__init__
.. automethod:: pyqtgraph.opengl.MeshData.MeshData.__iter__
......@@ -9,4 +9,5 @@ Contents:
functions
graphicsItems/index
widgets/index
graphicsscene/index
\ No newline at end of file
3dgraphics/index
graphicsscene/index
......@@ -16,6 +16,7 @@ Contents:
how_to_use
plotting
images
3dgraphics
style
region_of_interest
parametertree
......
......@@ -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:**
......
......@@ -3,12 +3,13 @@ import pyqtgraph.functions as fn
class MeshData(object):
"""
Class for storing 3D mesh data. May contain:
- list of vertex locations
- list of edges
- list of triangles
- colors per vertex, edge, or tri
- normals per vertex or tri
Class for storing and operating on 3D mesh data. May contain:
- list of vertex locations
- list of edges
- list of triangles
- 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)
*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* = [ (p1, p2, p3), ... ]
*vertexes* = [ (x, y, z), ... ]
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 = [ (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):
"""
Reverses the direction of all normal vectors.
"""
pass
#def reverseNormals(self):
#"""
#Reverses the direction of all normal vectors.
#"""
#pass
def generateEdgesFromFaces(self):
"""
Generate a set of edges by listing all the edges of faces and removing any duplicates.
Useful for displaying wireframe meshes.
"""
pass
#def generateEdgesFromFaces(self):
#"""
#Generate a set of edges by listing all the edges of faces and removing any duplicates.
#Useful for displaying wireframe meshes.
#"""
#pass
def save(self):
"""Serialize this mesh to a string appropriate for disk storage"""
......
......@@ -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:
......
......@@ -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:
......
......@@ -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:
......
......@@ -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
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment