underworld.visualisation module¶

This module provides visualisation tools for Underworld.

Visualisation data is generated in parallel, with each processes generating the necessary data for its part of the domain. Rendering is performed in serial using the LavaVu rendering engine.

Users may choose to render outputs to raster images, or save a database file for later rendering. For those working in the Jupyter environment, results may be displayed inline.

The following environment variables are available for the tuning of rendering configuration:

Parameters¶

UW_USE_XVFB: bool: Set this flag to true to use Xvfb for off-screen rendering. Xvfb will need to be installed, as will pyvirtualdisplay.
UW_VIS_PORT: int: Set which port to use for rendering server. Set to zero to disable server.

Submodules¶

underworld.visualisation.objects This module provides different drawing objects for visualisation in Underworld.

Classes¶

`underworld.visualisation.Figure`	The Figure class provides a window within which drawing objects may be rendered.
`underworld.visualisation.Store`	The Store class provides a database which records the drawing object data required by a figures.
`underworld.visualisation.Viewer`	The Viewer class provides an interface to load stored figures and revisualise them This is a wrapper of the LavaVu Viewer object

class underworld.visualisation.Figure(store=None, name=None, figsize=None, boundingBox=None, facecolour='white', edgecolour='black', title='', axis=False, quality=3, *args, **kwargs)[source]¶

Bases: dict

The Figure class provides a window within which drawing objects may be rendered. It also provides associated routines for image generation and visualisation.

In addition to parameter specification below, see property docstrings for further information.

Parameters:

store (underworld.visualisation.Store) – Database to collect visualisation data, this may be shared among figures to collect their data into a single file.
name (str) – Name of this figure, optional, used for revisualisation of stored figures.
resolution (tuple) – Image resolution provided as a tuple.
boundingBox (tuple) – Tuple of coordinate tuples defining figure bounding box. For example ( (0.1,0.1), (0.9,0.9) )
facecolour (str) – Background colour for figure.
edgecolour (str) – Edge colour for figure.
title (str) – Figure title.
axis (bool) – Bool to determine if figure axis should be drawn.
quality (unsigned) – Antialiasing oversampling quality. For a value of 2, the image will be rendered at twice the resolution, and then downsampled. Setting this to 1 disables antialiasing, values higher than 3 are not recommended..
properties (str) – Further properties to set on the figure.

Example

Create a figure:

>>> import underworld.visualisation as vis
>>> fig = vis.Figure()

We need a mesh

>>> import underworld as uw
>>> mesh = uw.mesh.FeMesh_Cartesian()

Add drawing objects:

>>> fig.append(vis.objects.Surface( mesh, 1.))

Draw image. Note that if called from within a Jupyter notebook, image will be rendered inline. Otherwise, image will be saved to disk.

>>> fig.show()

Save the image

>>> imgfile = fig.save("test_image")

Clean up:

>>> if imgfile:
...     import os;
...     os.remove( imgfile )

append(drawingObject)[source]¶

Add a drawing object to the figure.

Parameters:	drawingObject (visualisation.objects.Drawing) – The drawing object to add to the figure

axis¶

Axis enabled if true.

Type:	axis

edgecolour¶

colour of figure border.

Type:	edgecolour

facecolour¶

colour of face background.

Type:	facecolour

objects¶

list of objects to be drawn within the figure.

Type:	objects

properties¶

visual properties of viewport, passed to LavaVu to control rendering output of figure.

When using the property setter, new properties are set, overwriting any duplicate keys but keeping existing values otherwise.

Type:	properties (dict)

resolution¶

size of window in pixels.

Type:	resolution (tuple(int,int))

save(filename=None, size=(0, 0), type='Image')[source]¶

Saves the generated image to the provided filename or the figure to the database.

Parameters:	filename (str) – Filename to save file to. May include an absolute or relative path. (tuple(int,int)) (size) – If omitted, simply saves the figure data without generating an image type (str) – Type of visualisation to save (‘Image’ or ‘WebGL’).
Returns:	filename – The final filename (including extension) used to save the image will be returned. Note that only the root process will return this filename. All other processes will not return anything.
Return type:	str

send_command(cmd, retry=True)[source]¶

Run command on an open viewer instance.

Parameters:	cmd (str) – Command to send to open viewer.

show(type='Image')[source]¶

Shows the generated image inline within an ipython notebook.

Parameters:	type (str) – Type of visualisation to display (‘Image’ or ‘WebGL’). IPython is installed, displays the result image or WebGL content inline (If) – IPython is not installed, this method will call the default image/web (If) – routines to save the result with a default filename in the current directory (output) –

static show_grid(*rows)[source]¶

Shows a set of Figure objects in a grid. Note that this method currently only supports rendering images within a Jupyter Notebook, and saving gridded images to a file is not currently supported.

Parameters:	rows (set of tuples) – Each provided tuple represents a row of Figures, and should only contain Figure class objects.

Example

Create a bunch of figures:

>>> import underworld.visualisation as vis
>>> fig1 = vis.Figure()
>>> fig2 = vis.Figure()
>>> fig3 = vis.Figure()
>>> fig4 = vis.Figure()
>>> fig5 = vis.Figure()
>>> fig6 = vis.Figure()

We need a mesh

>>> import underworld as uw
>>> mesh = uw.mesh.FeMesh_Cartesian()

Add drawing objects as usual:

>>> r = uw.function.input()
>>> fig1.append(vis.objects.Surface( mesh, 1.))
>>> fig2.append(vis.objects.Mesh( mesh ))
>>> fig3.append(vis.objects.Mesh( mesh, nodeNumbers=True ))
>>> fig4.append(vis.objects.Surface( mesh, r[0]))
>>> fig5.append(vis.objects.Surface( mesh, r[1]))
>>> fig6.append(vis.objects.VectorArrows( mesh, r ))

Draw images in a grid. Note that in a Jupyter notebook, this will render the image within the notebook, though it will not be rendered in this example. Also note that show_grid() is a static method, and so we call it directly as below (instead of as a method on a Figure instance).

>>> vis.Figure.show_grid( (fig1,fig2,fig3),
...                            (fig4,fig5,fig6)  )
<IPython.core.display.HTML object>

The above should generate a 2x3 (row x col) grid. For a 3x2 grid we would instead call:

>>> vis.Figure.show_grid( (fig1,fig2),
...                            (fig3,fig4),
...                            (fig5,fig6)  )
<IPython.core.display.HTML object>

step¶

current timestep

Type:	step (int)

title¶

a title for the image.

Type:	title

viewer(new=False, *args, **kwargs)[source]¶

Return viewer instance.

Parameters:	new (boolean) – If True, a new viewer instance will always be returned Otherwise the existing instance will be used if available

window(*args, **kwargs)[source]¶

Open an inline viewer.

This returns a new LavaVu instance to display the figure and opens it as an interactive viewing window.

class underworld.visualisation.Store(filename=None, split=False, compress=True, **kwargs)[source]¶

Bases: underworld._stgermain.StgCompoundComponent

The Store class provides a database which records the drawing object data required by a figures. It also provides associated routines for saving and reloading this database to external files

In addition to parameter specification below, see property docstrings for further information.

Parameters:	filename (str) – Filename to use for a disk database, default is to create a temporary database filename. split (bool) – Set to true to write a separate database file for each timestep visualised view (bool) – Set to true and pass filename if loading a saved database for re-visualisation compress (bool) – Set to true to enable database compression.

Example

Create a database:

>>> import underworld.visualisation as vis
>>> store = vis.Store()

Optionally provide a filename so you don’t need to call save later (no extension)

>>> store = vis.Store('myvis')

Pass to figures when creating them (Providing a name allows you to revisualise the figure from the name)

>>> fig = vis.Figure(store, name="myfigure")

When figures are rendered with show() or save(imgname), they are saved to storage If you don’t need to render an image but still want to store the figure to view later, just call save() without a filename

>>> fig.save()

To create a timeseries of each figure you must increment the stores’s internal ‘timestep’ manually before calling the next save()/show().

>>> store.step += 1
>>> fig.save()

Save the database (only necessary if no filename provided when created)

>>> dbfile = store.save("myvis")

empty()[source]¶: Empties all the cached drawing objects

save(filename)[source]¶

Saves the database to the provided filename.

Parameters:	filename (str) – Filename to save file to. May include an absolute or relative path.

class underworld.visualisation.Viewer(filename, *args, **kwargs)[source]¶

Bases: underworld.visualisation.lavavu_null.Viewer

The Viewer class provides an interface to load stored figures and revisualise them This is a wrapper of the LavaVu Viewer object

In addition to parameter specification below, see property docstrings and lavavu.Viewer help for further information.

Parameters:	filename (str) – Filename of database used to previously store the visualisation figures

Example

Create database to use

>>> import underworld.visualisation as vis
>>> store = vis.Store('myvis')
>>> fig = vis.Figure(store, name="myfigure")
>>> import underworld as uw
>>> mesh = uw.mesh.FeMesh_Cartesian()
>>> fig.append(vis.objects.Mesh(mesh))
>>> fig.save()

Now reopen database:

>>> viewer = vis.Viewer('myvis')

Iterate over the figures, print their names

>>> for name in viewer.figures:
...     print(name)
myfigure

Get a figure by name and display (A chosen name can be provided when creating the figures to make this easier)

>>> viewer.figure("myfig")
>>> viewer.show()

Display all figures at each timestep

>>> for step in viewer.steps:
...    viewer.step = step
...    for name in viewer.figures:
...        viewer.figure(name)
...        viewer.show()