1.. _usersguide_plots:
2
3======================
4Geometry Visualization
5======================
6
7.. currentmodule:: openmc
8
9OpenMC is capable of producing two-dimensional slice plots of a geometry as well
10as three-dimensional voxel plots using the geometry plotting :ref:`run mode
11<usersguide_run_modes>`. The geometry plotting mode relies on the presence of a
12:ref:`plots.xml <io_plots>` file that indicates what plots should be created. To
13create this file, one needs to create one or more :class:`openmc.Plot`
14instances, add them to a :class:`openmc.Plots` collection, and then use the
15:class:`Plots.export_to_xml` method to write the ``plots.xml`` file.
16
17-----------
18Slice Plots
19-----------
20
21.. image:: ../_images/atr.png
22   :width: 300px
23
24By default, when an instance of :class:`openmc.Plot` is created, it indicates
25that a 2D slice plot should be made. You can specify the origin of the plot
26(:attr:`Plot.origin`), the width of the plot in each direction
27(:attr:`Plot.width`), the number of pixels to use in each direction
28(:attr:`Plot.pixels`), and the basis directions for the plot. For example, to
29create a :math:`x` - :math:`z` plot centered at (5.0, 2.0, 3.0) with a width of
30(50., 50.)  and 400x400 pixels::
31
32  plot = openmc.Plot()
33  plot.basis = 'xz'
34  plot.origin = (5.0, 2.0, 3.0)
35  plot.width = (50., 50.)
36  plot.pixels = (400, 400)
37
38The color of each pixel is determined by placing a particle at the center of
39that pixel and using OpenMC's internal ``find_cell`` routine (the same one used
40for particle tracking during simulation) to determine the cell and material at
41that location.
42
43.. note:: In this example, pixels are 50/400=0.125 cm wide. Thus, this plot may
44          miss any features smaller than 0.125 cm, since they could exist
45          between pixel centers. More pixels can be used to resolve finer
46          features but will result in larger files.
47
48By default, a unique color will be assigned to each cell in the geometry. If you
49want your plot to be colored by material instead, change the
50:attr:`Plot.color_by` attribute::
51
52  plot.color_by = 'material'
53
54If you don't like the random colors assigned, you can also indicate that
55particular cells/materials should be given colors of your choosing::
56
57  plot.colors = {
58      water: 'blue',
59      clad: 'black'
60  }
61
62  # This is equivalent
63  plot.colors = {
64      water: (0, 0, 255),
65      clad: (0, 0, 0)
66  }
67
68Note that colors can be given as RGB tuples or by a string indicating a valid
69`SVG color <https://www.w3.org/TR/SVG11/types.html#ColorKeywords>`_.
70
71When you're done creating your :class:`openmc.Plot` instances, you need to then
72assign them to a :class:`openmc.Plots` collection and export it to XML::
73
74  plots = openmc.Plots([plot1, plot2, plot3])
75  plots.export_to_xml()
76
77  # This is equivalent
78  plots = openmc.Plots()
79  plots.append(plot1)
80  plots += [plot2, plot3]
81  plots.export_to_xml()
82
83To actually generate the plots, run the :func:`openmc.plot_geometry`
84function. Alternatively, run the :ref:`scripts_openmc` executable with the
85``--plot`` command-line flag. When that has finished, you will have one or more
86``.ppm`` files, i.e., `portable pixmap
87<http://netpbm.sourceforge.net/doc/ppm.html>`_ files. On some Linux
88distributions, these ``.ppm`` files are natively viewable. If you find that
89you're unable to open them on your system (or you don't like the fact that they
90are not compressed), you may want to consider converting them to another format.
91This is easily accomplished with the ``convert`` command available on most Linux
92distributions as part of the `ImageMagick
93<http://www.imagemagick.org/script/convert.php>`_ package. (On Debian
94derivatives: ``sudo apt install imagemagick``).  Images are then converted like:
95
96.. code-block:: sh
97
98    convert myplot.ppm myplot.png
99
100Alternatively, if you're working within a `Jupyter <https://jupyter.org/>`_
101Notebook or QtConsole, you can use the :func:`openmc.plot_inline` to run OpenMC
102in plotting mode and display the resulting plot within the notebook.
103
104.. _usersguide_voxel:
105
106-----------
107Voxel Plots
108-----------
109
110.. image:: ../_images/3dba.png
111   :width: 200px
112
113The :class:`openmc.Plot` class can also be told to generate a 3D voxel plot
114instead of a 2D slice plot. Simply change the :attr:`Plot.type` attribute to
115'voxel'. In this case, the :attr:`Plot.width` and :attr:`Plot.pixels` attributes
116should be three items long, e.g.::
117
118  vox_plot = openmc.Plot()
119  vox_plot.type = 'voxel'
120  vox_plot.width = (100., 100., 50.)
121  vox_plot.pixels = (400, 400, 200)
122
123The voxel plot data is written to an :ref:`HDF5 file <io_voxel>`. The voxel file
124can subsequently be converted into a standard mesh format that can be viewed in
125`ParaView <https://www.paraview.org/>`_, `VisIt
126<https://wci.llnl.gov/simulation/computer-codes/visit>`_, etc. This typically
127will compress the size of the file significantly. The provided
128:ref:`scripts_voxel` script can convert the HDF5 voxel file to VTK formats. Once
129processed into a standard 3D file format, colors and masks can be defined using
130the stored ID numbers to better explore the geometry. The process for doing this
131will depend on the 3D viewer, but should be straightforward.
132
133.. note:: 3D voxel plotting can be very computer intensive for the viewing
134          program (Visit, ParaView, etc.) if the number of voxels is large (>10
135          million or so).  Thus if you want an accurate picture that renders
136          smoothly, consider using only one voxel in a certain direction.
137