Skip to content

GLVis/pyglvis

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PyGLVis

badge badge


PyGLVis is an interactive Jupyter widget for visualizing finite element meshes and functions, built on-top of the GLVis library.

📦 Installation

The GLVis Jupyter widget is installed using pip. To install the latest version from the repository:

git clone https://github.com/GLVis/pyglvis.git
cd pyglvis
pip install .

Or, install directly from PyPi,

pip install glvis

PyGLVis requires the Python wrapper for MFEM, PyMFEM, which can be installed with

pip install mfem

🚀 Usage

Basic usage

from glvis import glvis

# Create a `glvis` object
g = glvis(data, width=640, height=480)

# Run a cell with `g` as the last statement to display the widget
g

The data object can be one of:

Customization with key commands

GLVis has many keyboard commands that can be used to customize the visualization. A few of the most common are listed below. See the GLVis README for a full list.

  • r - reset the view
  • c - toggle the colorbar
  • j - toggle perspective
  • l - toggle the light
  • g - toggle the background color (white/black)
  • a - cycle through bounding box axes states
  • m - cycle through mesh states
  • p - cycle through color palettes
  • t - cycle through materials and lights
  • 0 - begin rotating around z-axis
  • . - pause rotation
  • *// - zoom in/out

These can be set using the keys argument when creating a glvis object.

glvis(data, keys='rljgac//0')

This combination of keys would: r reset the view, l toggle the light, j toggle perspective, g toggle the background color to black (default is white), a show the bounding box, c show the colorbar, // zoom out twice, and 0 begin rotating around the z-axis:

pyglvis_preset_keys

Alternatively, keys can be typed directly into the widget after it has been created:

pyglvis_using_keys

Other methods

Once you have a glvis object there are a few methods that can used to update the visualization, besides using keys:

# Show a new Mesh/GridFunction, resets keys
g.plot(data)
# Show an updated visualization with the same data, preserving keys
g.update(data)
# Change the image size
g.set_size(width, height)
# Force the widget to render. If the widget isn't the last statement in a cell it
# will not be shown without this. See ex9.ipynb
g.render()

See the examples directory for additional examples. To test those locally, start a Jupyter lab server with

jupyter lab

🐛 Troubleshooting

This widget was originally developed using the jupyter widget cookiecutter; however, recent changes to the Jupyter ecosystem have broken a lot of functionality, leading to a rewrite using anywidget. If you encounter any problems, please consider supporting development by opening an issue.

🤖 Development

PyGLVis dependencies

graph TD;
    A[mfem] --> B[pymfem];
    A --> C[glvis];
    C --> D[glvis-js];
    Ext1[emscripten] --> D;
    D-.-E["glvis-js\n(npm/esm mirror)"]
    B & E --> G[pyglvis];
    Ext2[jupyter] --> G;
Loading

pyglvis is most directly depednent on PyMFEM and glvis-js. PyMFEM is a Python wrapper of the finite element library, MFEM, while glvis-js is a JavaScript/WebAssembly port of glvis.

glvis-js is hosted on github and mirrored on npm. esm.sh allows pyglvis to pull the latest version of glvis-js directly from npm. This can be seen in the first line of glvis/widget.js:

import glvis from "https://esm.sh/glvis";

You can specify a different version of glvis-js by adding @x.y.z to the end of this import statement, where x.y.z matches a version number available on npm, e.g.

import glvis from "https://esm.sh/glvis@0.6.3";

Releasing a new version of glvis on NPM:

To publish a new version of glvis-js, follow the instructions on the repo.

Releasing a new version of glvis on PyPI:

  • Update __version__ in glvis/__about__.py

  • git add and git commit changes

You will need twine to publish to PyPI, install with pip.

python -m hatch build
twine upload dist/*
git tag -a X.X.X -m 'comment'
git push --tags

🌐 Links