Raytrace plots

docs/source/io_formats/plots.rst

@@ -7,13 +7,18 @@ Geometry Plotting Specification -- plots.xml
 Basic plotting capabilities are available in OpenMC by creating a plots.xml file
 and subsequently running with the ``--plot`` command-line flag. The root element
 of the plots.xml is simply ``<plots>`` and any number output plots can be
-defined with ``<plot>`` sub-elements.  Two plot types are currently implemented
+defined with ``<plot>`` sub-elements.  Four plot types are currently implemented
 in openMC:
 
 * ``slice``  2D pixel plot along one of the major axes. Produces a PNG image
   file.
 * ``voxel``  3D voxel data dump. Produces an HDF5 file containing voxel xyz
   position and cell or material id.
+* ``projection``  2D pixel plot of a three-dimensional view of a geometry
+  using wireframes around cells or materials and coloring by depth through
+  each material.
+* ``phong``  2D pixel plot of a three-dimensional view of a geometry
+  with solid colored surfaces of a set of cells or materials.
 
 
 ------------------
@@ -66,21 +71,22 @@ sub-elements:
     *Default*: None - Required entry
 
   :type:
-    Keyword for type of plot to be produced. Currently only "slice" and "voxel"
+    Keyword for type of plot to be produced. Currently "slice", "voxel",
+    "projection", and "phong" 
     plots are implemented. The "slice" plot type creates 2D pixel maps saved in
     the PNG file format. The "voxel" plot type produces a binary datafile
     containing voxel grid positioning and the cell or material (specified by the
     ``color`` tag) at the center of each voxel. Voxel plot files can be
     processed into VTK files using the :ref:`scripts_voxel` script provided with
     OpenMC and subsequently viewed with a 3D viewer such as VISIT or Paraview.
-    See the :ref:`io_voxel` for information about the datafile structure.
+    See :ref:`io_voxel` for information about the datafile structure.
 
     .. note:: High-resolution voxel files produced by OpenMC can be quite large,
               but the equivalent VTK files will be significantly smaller.
 
     *Default*: "slice"
 
-``<plot>`` elements of ``type`` "slice" and "voxel" must contain the ``pixels``
+All ``<plot>`` elements must contain the ``pixels``
 attribute or sub-element:
 
   :pixels:
@@ -96,7 +102,7 @@ attribute or sub-element:
                  ``width``/``pixels`` along that basis direction may not appear
                  in the plot.
 
-    *Default*: None - Required entry for "slice" and "voxel" plots
+    *Default*: None - Required entry for all plots
 
 ``<plot>`` elements of ``type`` "slice" can also contain the following
 attributes or sub-elements.  These are not used in "voxel" plots:
@@ -125,6 +131,11 @@ attributes or sub-elements.  These are not used in "voxel" plots:
       Specifies the custom color for the cell or material. Should be 3 integers
       separated by spaces.
 
+    :xs:
+      Only for plot type "projection", the attenuation coefficient
+      for volume rendering of color in units of inverse
+      centimeters. Zero corresponds to transparency.
+
     As an example, if your plot is colored by material and you want material 23
     to be blue, the corresponding ``color`` element would look like:
 
@@ -179,3 +190,83 @@ attributes or sub-elements.  These are not used in "voxel" plots:
       *Default*: 0 0 0 (black)
 
     *Default*: None
+
+``<plot>`` elements of ``type`` "projection" or "phong" can contain the following
+attributes or sub-elements.
+
+  :camera_position:
+    Location in 3D Cartesian space the camera is at.
+
+
+    *Default*: None - Required for all phong or projection plots
+
+  :look_at:
+    Location in 3D Cartesian space the camera is looking at.
+
+
+    *Default*: None - Required for all phong or projection plots
+
+  :field_of_view:
+    The horizontal field of view in degrees. Defaults to roughly
+    the same value as for the human eye.
+
+    *Default*: 70
+
+  :orthographic_width:
+    If set to a nonzero value, an orthographic rather than
+    perspective projection for the camera is employed.
+    An orthographic projection puts out parallel rays from
+    the camera of a width prescribed here in the horizontal
+    direction, with the width in the vertical direction decided
+    by the pixel aspect ratio.
+
+    *Default*: 0
+
+``<plot>`` elements of ``type`` "phong" can contain the following
+attributes or sub-elements.
+
+  :opaque_ids:
+    List of integer IDs of cells or materials to be treated
+    as visible in the plot. Whether the integers are interpreted
+    as cell or material IDs depends on ``color_by``.
+
+
+    *Default*: None - Required for all Phong plots
+
+  :light_position:
+    Location in 3D Cartesian space of the light.
+
+
+    *Default*: Same location as ``camera_position``
+
+  :diffuse_fraction:
+    Fraction of light originating from non-directional
+    sources. If set to one, the coloring is not influenced
+    by surface curvature, and no shadows appear. If set to
+    zero, only regions illuminated by the light are not
+    black.
+
+
+    *Default*: 0.1
+
+``<plot>`` elements of ``type`` "projection" can contain the following
+attributes or sub-elements.
+
+  :wireframe_color:
+    RGB value of the wireframe's color
+
+    *Default*: 0, 0, 0 (black)
+
+  :wireframe_thickness:
+    Integer number of pixels that the wireframe takes up.
+    The value is a radius of the wireframe. Setting to zero
+    removes any wireframing.
+
+    *Default*: 0
+
+  :wireframe_ids:
+    Integer IDs of cells or materials of regions to draw
+    wireframes around. Whether the integers are interpreted
+    as cell or material IDs depends on ``color_by``.
+
+    *Default*: None

docs/source/usersguide/plots.rst

@@ -122,6 +122,60 @@ will depend on the 3D viewer, but should be straightforward.
           million or so).  Thus if you want an accurate picture that renders
           smoothly, consider using only one voxel in a certain direction.
 
+-----------
+Phong Plots
+-----------
+
+.. image:: ../_images/phong_triso.png
+   :width: 300px
+
+The :class:`openmc.PhongPlot` class allows three dimensional
+visualization of detailed geometric features without voxelization.
+The plot above visualizes a geometry created by :class:`openmc.TRISO`,
+with the materials in the fuel kernel distinguished by color. It was
+enclosed in a bounding box such that some kernels are cut off,
+revealing the inner structure of the kernel.
+
+The `Phong reflection model <https://en.wikipedia.org/wiki/Phong_reflection_model>`_
+approximates how light reflects off of a surface. On a diffusely
+light-scattering material, the Phong model prescribes the amount of light 
+reflected from a surface as proportional to the dot product between
+the normal vector of the surface and the vector between that point on
+the surface and the light. With this assumption, visually appealing
+plots of simulation geometries can be created.
+
+Phong plots use the same ray tracing functions that neutrons
+and photons do in OpenMC, so any input that does not leak
+particles can be visualized in 3D using a Phong plot.
+That being said, these plots are not useful for detecting
+overlap or undefined regions, so we recommend the slice
+plot approach for geometry debugging.
+
+Only a few inputs are required for a Phong plot. The camera
+location, where it's looking, and a set of opaque material or
+cell  IDs are required. The colors of materials or cells are
+prescribed in the same way as slice plots. The set of IDs
+which are opaque in the Phong plot must correspond to materials
+if coloring by material, or cells if coloring by cell.
+
+A minimal Phong plot input could be: ::
+
+  plot = openmc.PhongPlot()
+  plot.pixels = (600, 600)
+  plot.camera_position = (10.0, 20.0, -30.0)
+  plot.look_at = (4.0, 5.0, 1.0)
+  plot.color_by = 'cell'
+
+  # optional. defaults to camera_position
+  plot.light_position = (10, 20, 30) 
+
+  # controls ambient lighting. Defaults to 10%
+  plot.diffuse_fraction = 0.1
+  plot.opaque_domains = [cell2, cell3]
+
+These plots are then stored into a :class:`openmc.Plots` instance,
+just like the slice plots.
+
 ----------------
 Projection Plots
 ----------------
@@ -131,6 +185,21 @@ Projection Plots
    .. image:: ../_images/hexlat_anim.gif
      :width: 200px
 
+The :class:`openmc.ProjectionPlot` class also
+produces 3D visualizations of OpenMC geometries without voxelization,
+but is intended to show the inside of a model using wireframing
+of cell or material boundaries in addition to cell coloring based
+on path length of camera rays through the model. The coloring
+in these plots is a bit like turning the model into partially
+transparent colored glass that can be seen through, without any
+refractive effects. This is called volume rendering. The colors
+are specified in exactly the same interface employed by slice
+plots.
+
+Similar to Phong plots, these use the native ray tracing capabilities within
+OpenMC, so any geometry in which particles successfully run without overlaps
+or leaks will work with projection plots.
+
 The :class:`openmc.ProjectionPlot` class presents an alternative method of
 producing 3D visualizations of OpenMC geometries. It was developed to overcome
 the primary shortcoming of voxel plots, that an enormous number of voxels must

include/openmc/cell.h

@@ -115,7 +115,7 @@ class Region {
   //!
   //! Uses the comobination of half-spaces and binary operators to determine
   //! if short circuiting can be used. Short cicuiting uses the relative and
-  //! absolute depth of parenthases in the expression.
+  //! absolute depth of parentheses in the expression.
   bool contains_complex(Position r, Direction u, int32_t on_surface) const;
 
   //! BoundingBox if the paritcle is in a simple cell.

include/openmc/particle_data.h

@@ -543,7 +543,6 @@ class ParticleData : public GeometryState {
   int& cell_born() { return cell_born_; }
   const int& cell_born() const { return cell_born_; }
 
-  // index of the current and last material
   // Total number of collisions suffered by particle
   int& n_collision() { return n_collision_; }
   const int& n_collision() const { return n_collision_; }