Native plotting GUI for model design and verification

openmc-dev, updated πŸ•₯ 2023-02-10 21:40:02


OpenMC Plot Explorer


A graphical interface for visualizing and navigating OpenMC models.

Originally created by @landonjmitchell at the University of Chicago (original repository).




OpenMC, Matplotlib, NumPy, PySide2


This package is most easily installed by running

console pip install openmc-plotter


From a directory containing an OpenMC model run:

console $ openmc-plotter -d <path_to_openmc_model_dir>

or simply run

console $ openmc-plotter

from the directory containing the model.

Once the viewer has opened, press ? to view a variety of keyboard shortcuts.



Tally Visualization

The plotter also provides the ability to view tallies with spatial filters (mesh filter, cell filter, etc.). After loading a statepoint file from the "Edit" menu, tallies can be displayed on top of the geometry.


Filters, scores, and nuclides on the tally can be enabled/disabled to isolate data.

Color Manipulation

Cell and material colors can be customized in the color dialog menu. Overlap coloring can be enabled as well to debug problems in the geometry definition.


DAGMC Geometry Visualization

The plotter can also present the CAD-based tesellation geometry enabled by the Direct Accelerated Geometry Monte Carlo (DAGMC) toolkit. Below is the cross section of a tokamake model generated using paramak:


As well as a DAGMC model of the Advanced Test Reactor (ATR):


Saving and Exporting

  • Any image displayed in the plotter can be saved in any format supported by the user's Matplotlib installation.

  • Tally and geometry data (material/cell IDs) can be exported to a VTK file under "File->Export"


Menu Bar:

  • File→Save Image As... : Save an image file of the current plot.
  • File→Save View Settings... : Save a .pltvw pickle file containing the current plot settings.
  • File→Open View Settings... : Open and load a .pltvw pickle file containing a previously saved view.
  • File→Quit : Quit the application.

  • Edit→Apply Changes : Apply any un-applied plot setting changes, and reload plot image.

  • Edit→Undo : Undo last applied plot settings changes, and reload plot image.
  • Edit→Redo : Redo last applied plot settings changes, and reload plot image.
  • Edit→Restore Default Settings : Restore to default plot settings and reload plot image.

  • Edit→Basis→xy : Change plot basis to xy, apply changes, and reload plot.

  • Edit→Basis→xz : Change plot basis to xz, apply changes, and reload plot.
  • Edit→Basis→yz : Change plot basis to yz, apply changes, and reload plot.
  • Edit→Color By→Cell : Change plot settings to be colored by cell, apply changes, and reload plot.
  • Edit→Color By→Material : Change plot settings to be colored by material, apply changes, and reload plot.
  • Edit→Enable Masking : Enable/Disable masking, apply changes, and reload plot.
  • Edit→Enable Highlighting : Enable/Disable highlighting, apply changes, and reload plot.
  • Edit→Enable Overlap Coloring : Enable/Disable display of geometry overlaps, apply changes, and reload plot.

  • View→Hide[Show] Dock : Hide/Show Dock.

  • View→Zoom... : Open dialog to input new zoom value.

  • Window→Main Window : Activate, bring main window to front.

  • Window→Color Options : [Open], activate, bring color options dialog to front.



  • X, Y, Z : Set the active plot origin to the values entered for each dimension.


  • Width : Set the width of the active plot in plot units.
  • Height : Set the height of the active plot in plot units.
  • Basis : Set the basis of the active plot.
  • Color By : Select how the active plot is colored.
  • Color Options... : Open the color options dialog.


  • Fixed Aspect Ratio : Check to prevent plot image stretching/warping.
  • Pixel Width: Set width in pixels of active plot.
  • Pixel Height : Set height in pixels of active plot.


  • Apply Changes : Apply changes made to active plot, reload plot image.
  • Zoom : Set zoom level of plot image.

Plot Image


  • Mouse Hover : Display plot coordinates in bottom-right of status bar. Display cell/material ID and name (if any) in bottom-left of status bar.

  • Left Mouse Button Drag : Crop active plot to selection, apply changes, and reload plot image.

  • Shift + Left Mouse Button Drag : De-crop active plot so that the current plot dimensions fit within selected area, apply changes, and reload plot image.
  • Note: To cancel selection, reduce selection size to less than 10 pixels in either dimension and release. Active plot Origin, width, and height values will be returned to current plot settings.

  • Double-Click Left Mouse Button : Set origin to point clicked, apply changes, and reload plot image.

  • Shift + Scroll : Increase/Decrease zoom level of plot image.

  • Right-Click on plot background → activate context menu:

    • Edit Background Color... : Select a new color for plot background, apply changes, and reload plot image.

    See menu bar for other context menu options. - Right-Click on plot overlap region → activate context menu: - Edit Overlap Color... : Select a new color for overlap regions, apply changes, and reload plot image.

  • Right-click on plot cell/material : Activate context menu:

    • Displays cell/material ID and name (if defined).
    • Edit Cell/Material Color... : Select a new color for the selected cell/material, apply changes, and reload plot image.
    • Mask Cell/Material : Mask/Unmask selected cell/material, apply changes, and reload plot image.
    • Highlight Cell/Material : Highlight/Unhighlight selected cell/material, apply changes, and reload plot image.

    See menu bar for other context menu options.

Color Options Dialog

General Tab:

  • Masking : Enable/Disable masking on active plot.
  • Mask Color : Select color of masked components on active plot.
  • Highlighting : Enable/Disable highlighting on active plot. Enabling highlighting will disable custom cell/material color selection.
  • Highlight Color : Select overlay color of non-highlighted cells/materials.
  • Highlight Alpha : Set alpha transparency level of non-highlighted color overlay.
  • Highlight Seed : Select seed for randomized colorization of cells/materials when highlighting is enabled.
  • Background Color : Select color of plot background for active plot.
  • Show Overlaps : Display overlap regions on the plot.
  • Overlap Color : Customize the displayed color of overlap regions.
  • Color Plot By : Select how the active plot is to be colored.

Cells/Materials Tabs:

  • Double-click Name field to edit cell/material name. Edited names will not be reflected in .xml files.
  • Double-click Color field to select a color for the cell/material in the active plot.
  • Double-click SVG/RBG field to enter a new color for the cell/material. May be entered as SVG color, or RGB value (with or without parentheses).
  • Right-click Color or SVG/RGB field to clear. This will reset the color to the default value.
  • Click Mask field to mask/unmask cell/material in active plot.
  • Click Highlight field to highlight/unhighlight cell/material in active plot.
  • Apply Changes : Apply changes made to active plot, reload plot image.
  • Close : Close the color options dialog.

Note: Fields appear dynamically based on whether Masking/Highlighting are enabled or disabled.

On Open:

Application windows are restored to their previous locations and sizes. If the .xml files match those of the previous sessions, the plot model will be restored to its previous state.

On Close:

Application status, including window size and location, will be saved. The current state of the plot model, including current plot and up to 10 previous/subsequent plots (i.e. for undo/redo) will be saved. Active plot changes that have not been applied will be lost.

Developer Notes


  • openmc-plotter: primary executable. contains the major program logic used to interact with the application.
  • contains the underlying data structure of the plot model and application state.
  • contains the bulk of the graphical elements of the application.
  • contains screen overlays seen in the GUI. Just keyboard shortcuts for now.
  • module with convenience functions for generating and modifying RGB/RGBA colors
  • assets: directory containing icons and images for the application


Plot Image

The plot slice image in the central area of the application.

Active Plot

Plot settings that are changed as dock and color dialog fields are changed. Not necessarily reflected in the plot image.

Current Plot

Plot settings currently displayed in the plot image.

Applying changes causes the active plot to become the current plot, and a new plot image to be generated.


"no Qt platform plugin could be initialised" - Can't run openmc-plotter

opened on 2023-02-22 16:46:13 by harrytilston

Hi, I'm having issues getting openmc-plotter to run. I was getting issues with pyside2, so i removed the environment I was using, and installed everything again. Openmc runs fine, but when I reinstalled openmc-plotter (using PIP), I get this error now.

"qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found. This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl, wayland-xcomposite-glx, webgl, xcb."

Any help would be much appreciated, I'm pretty lost.


Migrating functionality to openmc repo and different approaches

opened on 2023-02-02 15:38:20 by shimwell

Hi all

I've been exploring the landscape for plotting openmc materials, geometry and meshes.

I've got a few ideas about possible developments to the plotter that I wanted to share. and get peoples thoughts on.

  • :bug::bear: When plotting a just a geometry we currently need to also load up materials. I've started trying to decouple the two with this PR but further PRs are needed if we want to remove this requirement.

  • :bug::bear: When launching the plotter it loads up local xml files automatically. If we want to plot geometry or materials or meshtally we need openmc install and the openmc binary. For instance the plotter runs openmc in plot mode then loads up the resulting image. But there are other ways of finding the materials and geometry on a grid, using the openmc.Geometry.find() method I've written two functions that monkey patch openmc.Geometry to allow the materials or cells to be found on a grid and this grid becomes and image. These are not c++ based like the openmc plot but as there is no need to load nuclear data or run openmc the time to plot is comparable. Also the for loop could be parallelised if speed becomes an issue.


Regardless of if we make use of the Geometry.find method I think it makes sense to migrate all data extraction functionality to openmc and then call it from the plotter. This will help keep the code in the plotter minimal and avoid duplication with openmc. If we do this then users have the option of using the plotter and the python API to make batch plots. This issue has come up on the forum and I've put in a PR for slicing regular meshes. I think there are 3 data extraction functions we need (cells, materials, mesh tally result). I think there are also some axis manipulation needed as well but that varies across the plotting tools (imshow is different to contour and plotly is different to mpl).

  • add slicing to the openmc.geometry class for materials and cells that uses openmc.geometry.find function
  • add slicing to the openmc openmc.RegularMesh class
  • make use of both functions here in the plotter and remove local versions


Is this totally going in the wrong direction? Is the :snake: python based find method robust enough to rely on? Is it worth moving code to openmc so that it can be shared with API users?

feature request: user defined units

opened on 2023-01-13 11:48:08 by shimwell

There are some super useful units built into the plotter

However in some cases it might be handy if the user can specify the units.

My use case is when using an EnergyFunctionFilter the code can't be sure what units the function (with the current lack of units in tallies)

In this case it would be useful if the user can assign units to make use of on the colorbar

This could potentially be part of adding a scaling factor #105 as one could have a scaling factor units as well.

bug report: plot mesh with EnergyFunctionFilter shows zeros everywhere

opened on 2023-01-12 16:09:58 by shimwell

Really liking the plotting capabilities of this package

I think I stubbled across a small bug

When plotting regular mesh tallies that include a EnergyFunctionFilter the displayed result is all zeros.

This would be a useful feature as plotting dose maps could then be performed

feature request: mesh scaling options

opened on 2023-01-11 15:22:15 by shimwell

Making use of this super plotter and I'm keen to be able to plot RegularMesh results with a custom scaling factor.

I am also keen to be able to plot with the RegularMesh result normalised by the voxel size.

I would be happy to put in a couple of PRs if the request sounds reasonable

An Error In Openmc Plotter

opened on 2022-11-14 03:32:47 by Seamoon-Wang

Hi,Everyone! There is an error when I use the Openmc-Plotter through Ubuntu & Xming.Here is the error:

File β€œ/home/rookie/anaconda3/envs/openmc-env/lib/python3.10/site-packages/openmc_plotter/”, line 75, in getPlotCoords transform = AttributeError: β€˜PlotImage’ object has no attribute β€˜ax’. Did you mean: β€˜x’? Traceback (most recent call last): File β€œ/home/rookie/anaconda3/envs/openmc-env/lib/python3.10/site-packages/openmc_plotter/”, line 220, in mouseMoveEvent xPlotPos, yPlotPos = self.getPlotCoords(event.pos())

If you have some advices, Please text it,Thank You! Best Wishes!


OpenMC Plotter 0.2.0 2022-03-03 18:31:27

What's Changed

  • Ability to import properties (temperature/density) by @paulromano in
  • Support 2D meshes, energy function filter by @paulromano in
  • Removing unused matplotlib backend query. by @pshriwise in
  • Adding screenshots to the README by @pshriwise in
  • Remove unused import of is_pyqt5 by @paulromano in
  • Remove superfluous install of OpenMC Python API during CI by @paulromano in
  • v0.2.0 release by @pshriwise in

Full Changelog:

OpenMC Plotter 0.1.1 2021-06-24 15:58:48

First official release of the OpenMC plotting application.


Please see this version's README for the initial set of supported features.


  • @pshriwise
  • @landonjmitchell
  • @Shimwell
  • @landonjmitchell
  • @AI-Pranto
  • @billingsley-john

Community-developed Monte Carlo particle transport code

GitHub Repository

openmc particle-transport monte-carlo-simulation visualization geometry