glucifer module

The glucifer module provides visualisation algorithms for Underworld.

Visualisation data is generated in parallel, with each processes generating the necessary data for its part of the domain. This data is written into a data file.

Actual rendering is performed in serial using the LavaVu rendering engine.

glucifer provides many flexible rendering options, including client-server based operation for remote usage. Users may choose to renderer outputs to raster images, or save a database file for later rendering. For those working in the Jupyter environment, glucifer will inline rendered images or even interactive webgl frames (still experimental).

Module Summary

submodules:

• glucifer.objects module

classes:

glucifer.Store	The Store class provides a database which stores gLucifer drawing objects as they are rendered in figures.
glucifer.Figure	The Figure class provides a window within which gLucifer drawing objects may be rendered.

Module Details

classes:

class glucifer.Store(filename=None, split=False, **kwargs)

Bases: underworld._stgermain.StgCompoundComponent

The Store class provides a database which stores gLucifer drawing objects as they are rendered in 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 revisualisation

Example

Create a database:

>>> import glucifer
>>> store = glucifer.Store()

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

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

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

>>> fig = glucifer.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()

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

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

empty()

Empties all the cached drawing objects

save(filename)

Saves the database to the provided filename.

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

class glucifer.Figure(store=None, name=None, figsize=None, boundingBox=None, facecolour='white', edgecolour='black', title='', axis=False, quality=1, *args, **kwargs)

Bases: dict

The Figure class provides a window within which gLucifer 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 (glucifer.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 glucifer
>>> fig = glucifer.Figure()

We need a mesh

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

Add drawing objects:

>>> fig.append(glucifer.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)

Add a drawing object to the figure.

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

axis

Axis enabled if true.

Type:axis

close_viewer()

Close the viewer.

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

open_viewer(args=[], background=True)

Open the external viewer.

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')

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

script(cmd=None)

Append to or get contents of the saved script.

Parameters:cmd (str) – Command to add to script.

send_command(cmd, retry=True)

Run command on an open viewer instance.

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

show(type='Image')

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) –

step

current timestep

Type:step (int)

title

a title for the image.

Type:title

viewer(new=False, *args, **kwargs)

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)

Open an inline viewer.

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