Updated data processing and viz documentation to include examples

docs/source/usersguide/input.rst

@@ -1052,7 +1052,7 @@ sub-elements:
               the PNG format can often times reduce the file size by orders of
               magnitude without any loss of image quality. Likewise,
               high-resolution voxel files produced by OpenMC can be quite large,
-              but the equivalent SILO files will by significantly smaller.
+              but the equivalent SILO files will be significantly smaller.
 
     *Default*: "slice"
 

docs/source/usersguide/processing.rst

@@ -5,11 +5,11 @@ Data Processing and Visualization
 =================================
 
 This section is intended to explain in detail the recommended procedures for
-carrying out common tasks with OpenMC. While several utilities of varying
-complexity are provided to help automate the process, in many cases it will be
-extremely beneficial to do some coding in Python to quickly obtain results.  In
-these cases, and for many of the provided utilities, it is necessary for your
-Python installation to contain:
+carrying out common post-processing tasks with OpenMC. While several utilities
+of varying complexity are provided to help automate the process, in many cases
+it will be extremely beneficial to do some coding in Python to quickly obtain
+results. In these cases, and for many of the provided utilities, it is necessary
+for your Python installation to contain:
 
 * [1]_ `Numpy <http://www.numpy.org/>`_
 * [1]_ `Scipy <http://www.scipy.org/>`_
@@ -41,6 +41,55 @@ Plotting in 2D
 .. image:: ../_images/atr.png
    :height: 200px
 
+See below for a simple example of a plots xml file that demonstrates the
+capabilities of 2D slice plots. Here we assume that there is a ``geometry.xml``
+file containing 7 cells.
+
+.. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8"?>
+        <plots>
+
+          <plot id="1" type="slice" color="cell" basis="xy">
+              <filename> myplot </filename>
+              <origin> 0 0 </origin>
+              <width> 10 10 </width>
+              <pixels> 2000 2000 </pixels>
+              <background> 0 0 0 </background>
+              <col_spec id="1" rgb="198 226 255"/>
+              <col_spec id="2" rgb="255 218 185"/>
+              <col_spec id="3" rgb="255 255 255"/>
+              <col_spec id="4" rgb="101 101 101"/>
+              <col_spec id="7" rgb="123 123 231"/>
+              <mask background="255 255 255">
+                <components> 1 3 4 5 6 </components>
+              </mask>
+          </plot>
+
+        </plots>
+
+
+In this example, OpenMC will produce a plot named ``myplot.ppm`` when run in
+plotting mode. The picture will be on the xy-plane, depicting the rectangle
+between points (-5,-5) and (5,5) with 2000 pixels along each dimension. The
+color of each pixel is determined by placing a particle at the center of that
+pixel and using OpenMC's internal ``find_cell`` routine (the same one used for
+particle tracking during simulation) to determine the cell and material at that
+location. In this example, pixels are 10/2000=0.005 cm wide, so points will be
+at (-4.9975,-4.9975), (-4.9950,-4.9975), (-4.9925,-4.9975), etc. This is pointed
+out to demonstrate that this plot may miss any features smaller than 0.005 cm,
+since they could exist between pixel centers. More pixels can be used to resolve
+finer features, but could result in larger files.
+
+The ``background``, ``col_spec``, and ``mask`` elements define how to set pixel
+colors based on the cell ids at each pixel center. In this example, RGB colors
+are specified for cells 1,2,3,4, and 7, a random color will be assigned to cells
+5 and 6, and a black background color (``rgb="0 0 0"``) will be applied to
+locations where no cell is defined. However, the ``mask`` element here says that
+only cells 1,3,4,5, and 6 should be displayed, with other cells taking a white
+color (``rgb="255 255 255"``), which overrides the ``col_spec`` for cell 2 and
+the random color assigned to cell 7.
+
 After running OpenMC to obtain PPM files, images should be saved to another
 format before using them elsewhere. This cuts down the size of the file by
 orders of magnitude.  Most image viewers and editors that can view PPM images
@@ -53,7 +102,7 @@ Ubuntu: ``sudo apt-get install imagemagick``).  Images are then converted like:
 
 .. code-block:: sh
 
-    convert plot.ppm plot.png
+    convert myplot.ppm myplot.png
 
 Plotting in 3D
 --------------
@@ -61,10 +110,37 @@ Plotting in 3D
 .. image:: ../_images/3dgeomplot.png
    :height: 200px
 
+See below for a simple example of a plots xml file that demonstrates the
+capabilities of 3D voxel plots.
+
+.. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8"?>
+        <plots>
+
+          <plot id="1" type="voxel" color="mat">
+              <filename> myplot </filename>
+              <origin> 0 0 0 </origin>
+              <width> 10 10 10 </width>
+              <pixels> 500 500 500 </pixels>
+          </plot>
+
+        </plots>
+
+Voxel plots are built the same way 2D slice plots are, by determining the cell
+or material id of a particle at the center of each voxel. In this example, the
+space covered is the cube between the points (-5,-5,-5) and (5,5,5), with voxel
+centers 10/500 = 0.02 cm apart. The binary VOXEL files that are produced do not
+specify any color - instead containing only material or cell ids (material id
+in this example) - and thus the ``background``, ``col_spec``, and ``mask``
+elements are not used. If no cell is found at a voxel center, an id of -1 is
+stored.
+
 The binary VOXEL files output by OpenMC can not be viewed directly by any
 existing viewers. In order to view them, they must be converted into a standard
-mesh format that can be viewed in ParaView, Visit, etc. The provided utility
-voxel.py accomplishes this for SILO:
+mesh format that can be viewed in ParaView, Visit, etc. This typically will
+compress the size of the file significantly. The provided utility voxel.py
+accomplishes this for SILO:
 
 .. code-block:: sh
 
@@ -88,13 +164,21 @@ or
 Users can process the binary into any other format if desired by following the
 example of voxel.py.  For the binary file structure, see :ref:`devguide_voxel`.
 
+Once processed into a standard 3D file format, colors and masks can be defined
+using the stored id numbers to better explore the geometry. The process for
+doing this will depend on the 3D viewer, but should be straightforward.
+
+.. image:: ../_images/3dba.png
+   :height: 200px
+
 .. note:: 3D voxel plotting can be very computer intensive for the viewing
           program (Visit, Paraview, etc.) if the number of voxels is large (>10
           million or so).  Thus if you want an accurate picture that renders
           smoothly, consider using only one voxel in a certain direction. For
-          instance, the 3D pin lattice figure above was generated with a
-          500x500x1 voxel mesh, which allows for resolution of the cylinders
-          without wasting too many voxels on the axial dimension.
+          instance, the 3D pin lattice figure at the beginning of this section
+          was generated with a 500x500x1 voxel mesh, which allows for resolution
+          of the cylinders without wasting too many voxels on the axial
+          dimension.
 
 
 -------------------