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"
-    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.
+    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 :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:
+      The attenuation coefficient for volume rendering of color in units of
+      inverse centimeters. Zero corresponds to transparency. Only for plot type
+      "projection".
+
     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:
 
@@ -152,17 +163,17 @@ attributes or sub-elements.  These are not used in "voxel" plots:
     *Default*: 255 255 255 (white)
 
   :show_overlaps:
-    Indicates whether overlapping regions of different cells are shown. 
+    Indicates whether overlapping regions of different cells are shown.
 
     *Default*: None
 
   :overlap_color:
-    Specifies the RGB color of overlapping regions of different cells. Does not 
-    do anything if ``show_overlaps`` is "false" or not specified. Should be 3 
+    Specifies the RGB color of overlapping regions of different cells. Does not
+    do anything if ``show_overlaps`` is "false" or not specified. Should be 3
     integers separated by spaces.
 
     *Default*: 255 0 0 (red)
-  
+
   :meshlines:
     The ``meshlines`` sub-element allows for plotting the boundaries of a
     regular mesh on top of a plot. Only one ``meshlines`` element is allowed per
@@ -191,3 +202,79 @@ 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,57 @@ 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 it is recommended to use the slice plot approach for
+geometry debugging.
+
+Only a few inputs are required for a Phong plot. The camera location, where the
+camera is 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 that 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,14 +182,18 @@ Projection Plots
    .. image:: ../_images/hexlat_anim.gif
      :width: 200px
 
-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
-be employed to capture detailed geometric features. Projection plots perform
-volume rendering on material or cell volumes, with colors specified in the same
-manner as slice plots. This is done using 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 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 the 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.
 
 One drawback of projection plots is that particle tracks cannot be overlaid on
 them at present. Moreover, checking for overlap regions is not currently
@@ -186,22 +241,22 @@ Two camera projections are available when using these plots, perspective and
 orthographic. The default, perspective projection, is a cone of rays passing
 through each pixel which radiate from the camera position and span the field of
 view in the x and y positions. The horizontal field of view can be set with the
-:attr: `ProjectionPlot.horizontal_field_of_view` attribute, which is to be
+:attr:`ProjectionPlot.horizontal_field_of_view` attribute, which is to be
 specified in units of degrees. The field of view only influences behavior in
 perspective projection mode.
 
 In the orthographic projection, rays follow the same angle but originate from
 different points. The horizontal width of this plane of ray starting points may
-be set with the :attr: `ProjectionPlot.orthographic_width` element. If this
+be set with the :attr:`ProjectionPlot.orthographic_width` attribute. If this
 element is nonzero, the orthographic projection is employed. Left to its default
 value of zero, the perspective projection is employed.
 
 Lastly, projection plots come packaged with wireframe generation that can target
 either all surface/cell/material boundaries in the geometry, or only wireframing
 around specific regions. In the above example, we have set only the fuel region
 from the hexagonal lattice example to have a wireframe drawn around it. This is
-accomplished by setting the :attr: `ProjectionPlot.wireframe_domains`, which may
-be set to either material IDs or cell IDs. The
+accomplished by setting the :attr:`ProjectionPlot.wireframe_domains` attribute,
+which may be set to either material IDs or cell IDs. The
 :attr:`ProjectionPlot.wireframe_thickness` attribute sets the wireframe
 thickness in units of pixels.
 

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/dagmc.h

@@ -49,7 +49,8 @@ class DAGSurface : public Surface {
   double evaluate(Position r) const override;
   double distance(Position r, Direction u, bool coincident) const override;
   Direction normal(Position r) const override;
-  Direction reflect(Position r, Direction u, GeometryState* p) const override;
+  Direction reflect(
+    Position r, Direction u, GeometryState* p = nullptr) const override;
 
   inline void to_hdf5_inner(hid_t group_id) const override {};
 

include/openmc/particle.h

@@ -39,10 +39,6 @@ class Particle : public ParticleData {
 
   double speed() const;
 
-  //! moves the particle by the distance length to its next location
-  //! \param length the distance the particle is moved
-  void move_distance(double length);
-
   //! create a secondary particle
   //
   //! stores the current phase space attributes of the particle in the

include/openmc/particle_data.h

@@ -191,6 +191,13 @@ struct BoundaryInfo {
   array<int, 3>
     lattice_translation {}; //!< which way lattice indices will change
 
+  void reset()
+  {
+    distance = INFINITY;
+    surface = SURFACE_NONE;
+    coord_level = 0;
+    lattice_translation = {0, 0, 0};
+  }
   // TODO: off-by-one
   int surface_index() const { return std::abs(surface) - 1; }
 };
@@ -226,6 +233,12 @@ class GeometryState {
     n_coord_last_ = 1;
   }
 
+  //! moves the particle by the specified distance to its next location
+  //! \param distance the distance the particle is moved
+  void move_distance(double distance);
+
+  void advance_to_boundary_from_void();
+
   // Initialize all internal state from position and direction
   void init_from_r_u(Position r_a, Direction u_a)
   {
@@ -563,7 +576,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_; }