MAJOR: reorganize internal modules and implement volume rendering (py…

…vista#272) * added volume rendering feature * changed faulty file destination * correct plotting.py destination * add_volume can now take pv.UniformGrid. Also now supports different blending modes * added input data type error * changed away f-string due to python version compatibility * Add `volume` option to plot function (pyvista#243) * add sigmoid opacity funcs and add minimal test for volume rendering * Enable scalar range for volume rendering * Move files * Updates after move * Migrate files to utilities module * Update utilities after move * Move core modules * Update core modules after move * Migrate plotting modules * Update plotting modules after move * Sort imports * Break up plotting module * Attemot fix testing issues * rename readers module * Close pyvista#229 * Attempt fix setup issues * Reduce notebooks in favor of examples gallery * Add scooby as a dependency * Handle numpy arrays in pyvista.wrap * Overhaul volume rendering code to favor UniformGrids * Fix numpy array wrapping bug * Add scalar bars for volume rendering * Enforce use of ImageData when volume rendering * Do not test any volume mappers as they are different per OS * Fix syntax issue * Fix typo * Update opacity and volume rendering examples * Fix plotting star imports * Sort utilities imports * Do not cast arrays to uint8 when volume rendering * Update volume render example * Move types->core in docs * Move filters into one doc page * More docs migrating * Move tools -> utilities * Update utilities docs * Overhaul utilities docs * Update core docs * Improve testing * Bump scooby * Add pytest wrapper to edl test * No test for EDL on windows * Allow users to specify panel height * Resolve pyvista#237 * Prevent use of panel when volume rendering * Add PyVista to scooby report * Update scooby report * Allow sort with scooby
hippo91 · Jun 30, 2019 · d7e791f · d7e791f
1 parent 9df30d8
commit d7e791f
Show file tree

Hide file tree

Showing 63 changed files with 3,122 additions and 1,367 deletions.
diff --git a/docs/core/common.rst b/docs/core/common.rst
@@ -0,0 +1,44 @@
+.. _ref_common:
+
+Datasets
+========
+
+Datasets are any spatially reference information and usually consist of
+geometrical representations of a surface or volume in 3D space.
+In VTK, this superclass is represented by the ``vtk.vtkDataSet`` abstract class.
+
+In VTK, datasets consist of geometry, topology, and attributes to which PyVista
+provides direct access:
+
+* Geometry is the collection of points and cells in 2D or 3D space.
+* Topology defines the structure of the dataset, or how the points are connected to each other to form a cells making a surface or volume.
+* Attributes are any data values that are associated to either the points or cells of the dataset
+
+All of the following data types are listed subclasses of a dataset and share a
+set of common functionality which we wrap into the base class
+:class:`pyvista.Common`.
+
+
+The Common Model
+----------------
+
+The :class:`pyvista.Common` class holds attributes that are *common* to all
+spatially referenced datasets in PyVista.
+This base class is analogous to VTK's ``vtk.vtkDataSet`` class.
+
+
+.. rubric:: Attributes
+
+.. autoautosummary:: pyvista.Common
+   :attributes:
+
+.. rubric:: Methods
+
+.. autoautosummary:: pyvista.Common
+   :methods:
+
+
+.. autoclass:: pyvista.Common
+   :show-inheritance:
+   :members:
+   :undoc-members:
diff --git a/docs/types/composite.rst → docs/core/composite.rst b/docs/types/composite.rst → docs/core/composite.rst
@@ -22,18 +22,3 @@ MultiBlock Datasets
    :show-inheritance:
    :members:
    :undoc-members:
-
-
-
-Composite Filters
------------------
-
-.. rubric:: Methods
-
-.. autoautosummary:: pyvista.CompositeFilters
-   :methods:
-
-.. autoclass:: pyvista.CompositeFilters
-   :show-inheritance:
-   :members:
-   :undoc-members:
diff --git a/docs/core/filters.rst b/docs/core/filters.rst
@@ -0,0 +1,45 @@
+.. _filters_ref:
+
+Filters
+-------
+
+
+.. automodule:: pyvista.filters
+
+
+Dataset Filters
+~~~~~~~~~~~~~~~
+
+The :class:`pyvista.DataSetFilters` is inherited by :class:`pyvista.Common` making
+all the the following filters available as callable methods directly from any
+PyVista dataset.
+
+
+.. rubric:: Methods
+
+.. autoautosummary:: pyvista.DataSetFilters
+   :methods:
+
+
+.. autoclass:: pyvista.DataSetFilters
+   :members:
+   :undoc-members:
+
+
+
+Composite Filters
+~~~~~~~~~~~~~~~~~
+
+These are filters that can be applied to composite datasets, i.e.
+:class:`pyvista.MultiBlock`. The :class:`pyvista.CompositeFilters` class
+inherits many but not all of the filters from :class:`pyvista.DataSetFilters`.
+
+.. rubric:: Methods
+
+.. autoautosummary:: pyvista.CompositeFilters
+   :methods:
+
+.. autoclass:: pyvista.CompositeFilters
+   :show-inheritance:
+   :members:
+   :undoc-members:
diff --git a/docs/types/grids.rst → docs/core/grids.rst b/docs/types/grids.rst → docs/core/grids.rst
diff --git a/docs/core/index.rst b/docs/core/index.rst
@@ -0,0 +1,41 @@
+Core API
+========
+
+The `Visualization Toolkit`_ (VTK), developed by Kitware_, has many mesh data
+types that PyVista wraps.
+This chapter is intended to describe these different mesh types and how we wrap
+and implement each of those mesh types in VTK. This chapter also highlights
+how all PyVista types have direct access to common VTK filters
+(see :ref:`filters_ref`).
+
+.. _Visualization Toolkit: https://vtk.org
+.. _Kitware: https://www.kitware.com
+
+
+All PyVista meshes inherit from the Common dataset type (see :ref:`ref_common`).
+PyVista has the following mesh types:
+
+- :class:`pyvista.PolyData` consists of any 1D or 2D geometries to construct vertices, lines, polygons, and triangles. We generally use ``PolyData`` to construct scattered points and closed/open surfaces (non-volumetric datasets). The :class:`pyvista.PolyData` class is an extension of ``vtk.vtkPolyData``.
+
+- An :class:`pyvista.UnstructuredGrid` is the most general dataset type that can hold any 1D, 2D, or 3D cell geometries. You can think of this as a 3D extension of ``PolyData`` that allows volumetric cells to be present. It's fairly uncommon to explicitly make unstructured grids but they are often the result of different processing routines that might extract subsets of larger datasets. The :class:`pyvista.UnstructuredGrid` class is an extension of ``vtk.UnstructuredGrid``.
+
+- A :class:`pyvista.StructuredGrid` is a regular lattice of points aligned with an internal coordinate axes such that the connectivity can be defined by a grid ordering. These are commonly made from :func:`np.meshgrid`. The cell types of structured grids must be 2D Quads or 3D Hexahedrons. The :class:`pyvista.StructuredGrid` class is an extension of ``vtk.vtkStructuredGrid``.
+
+- A :class:`pyvista.RectilinearGrid` defines meshes with implicit geometries along the axes directions that are rectangular and regular. The :class:`pyvista.RectilinearGrid` class is an extension of ``vtk.vtkRectilinearGrid``.
+
+- Image data, commonly referenced to as uniform grids, and defined by the :class:`pyvista.UniformGrid` class are meshes with implicit geometries where cell sizes are uniformly assigned along each axis and the spatial reference is built out from an origin point. The :class:`pyvista.UniformGrid` class is an extension of ``vtk.vtkImageData``.
+
+- :class:`pyvista.MultiBlock` datasets are containers to hold several VTK datasets in one accessible and spatially referenced object. The :class:`pyvista.MultiBlock` class is an extension of ``vtk.vtkMultiBlockDataSet``.
+
+
+
+
+.. toctree::
+   :maxdepth: 2
+
+   common
+   points
+   point-grids
+   grids
+   composite
+   filters
diff --git a/docs/types/point-grids.rst → docs/core/point-grids.rst b/docs/types/point-grids.rst → docs/core/point-grids.rst
diff --git a/docs/types/points.rst → docs/core/points.rst b/docs/types/points.rst → docs/core/points.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -183,8 +183,9 @@ Highlights of the API include:
    :caption: API Reference
    :hidden:
 
-   types/index
-   tools/index
+   core/index
+   plotting/index
+   utilities/index
 
 
 

diff --git a/docs/plotting/index.rst b/docs/plotting/index.rst
@@ -0,0 +1,12 @@
+Plotting
+========
+
+* Intuitive plotting routines with ``matplotlib`` similar syntax (see :ref:`plotting_ref`)
+* Plotting tools built for interactivity in Jupyter notebooks (see :ref:`ipy_tools_ref`)
+
+.. toctree::
+   :maxdepth: 2
+
+   plotting
+   ipy_tools
+   qt_plotting
diff --git a/docs/tools/ipy_tools.rst → docs/plotting/ipy_tools.rst b/docs/tools/ipy_tools.rst → docs/plotting/ipy_tools.rst
@@ -14,12 +14,12 @@ dataset. Simply call one of these tools on your object.
 
 .. rubric:: Attributes
 
-.. autoautosummary:: pyvista.ipy_tools.InteractiveTool
+.. autoautosummary:: pyvista.plotting.ipy_tools.InteractiveTool
    :attributes:
 
 .. rubric:: Methods
 
-.. autoautosummary:: pyvista.ipy_tools.InteractiveTool
+.. autoautosummary:: pyvista.plotting.ipy_tools.InteractiveTool
    :methods:
 
 

diff --git a/docs/tools/plotting.rst → docs/plotting/plotting.rst b/docs/tools/plotting.rst → docs/plotting/plotting.rst
diff --git a/docs/tools/qt_plotting.rst → docs/plotting/qt_plotting.rst b/docs/tools/qt_plotting.rst → docs/plotting/qt_plotting.rst
diff --git a/docs/tools/filters.rst b/docs/tools/filters.rst
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
diff --git a/docs/types/common.rst b/docs/types/common.rst
diff --git a/docs/types/index.rst b/docs/types/index.rst
diff --git a/docs/utilities/geometric.rst b/docs/utilities/geometric.rst
@@ -0,0 +1,19 @@
+Geometric Objects
+-----------------
+
+PyVista includes a few functions to generate simple geometric objects.
+The code documentation for these functions are on this page; to see what these
+functions create, check out the example: :ref:`ref_geometric_example`.
+
+.. autofunction:: pyvista.Sphere
+.. autofunction:: pyvista.Cylinder
+.. autofunction:: pyvista.Arrow
+.. autofunction:: pyvista.Plane
+.. autofunction:: pyvista.Line
+.. autofunction:: pyvista.Cube
+.. autofunction:: pyvista.Box
+.. autofunction:: pyvista.Cone
+.. autofunction:: pyvista.Polygon
+.. autofunction:: pyvista.Disc
+.. autofunction:: pyvista.Text3D
+.. autofunction:: pyvista.Spline
diff --git a/docs/utilities/index.rst b/docs/utilities/index.rst
@@ -0,0 +1,9 @@
+Utilities
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   geometric
+   parametric
+   utilities