7.3. pyopus.plotter.interface — Functional interface to the plot window manager

Interface to the plot window manager

The plotting happens in a separate thread (process) so the plot windows remain responsive even if the main thread does some computation. No additional user intervention is needed (like calling some refresh function from time-to time).

An example will explain more than ten paragraphs of text:

from pyopus.plotter import interface as pyopl
from numpy import arange, sin, cos, exp, pi, e

# Plot data - sin(x), cos(x), exp(x/pi) .. for x in [0, 2pi] with 0.2 step. 
x = arange(0.0, 2*pi, 0.2)
y1 = sin(x)
y2 = cos(x)
y3 = exp(x/pi)

# Create first figure (plot window). This is now the active figure. 
# Tag is assigned automatically by the system. 
fig=pyopl.figure(windowTitle="Figure - single axes", figpx=(600,400), dpi=100)  

# Lock the main GUI event loop. This implicitly disables repainting. 
pyopl.lock(True)

# If the window is closed accessing any attribute results in an exception.
# To check if the window is still there, simply use an 'if' statement. 
if pyopl.alive(fig):
        ax=fig.add_axes((0.12,0.12,0.76,0.76))
        #ax=fig.gca()
        ax.plot(x, y1, '-o', label='sin(x)', color=(1,0,0))
        ax.plot(x, y2, 'rx', label='cos(x)')
        ax.plot(x, y3, '--k|', label='exp(x/pi)')
        ax.legend()
        ax.set_xlabel("x-axis")
        ax.set_ylabel("y-axis")
        ax.set_title("Axes title")
        ax.grid(True)
        fig.suptitle("Figure title")
        # Paint the changes on the screen. 
        pyopl.draw(fig)

# Now unlock the main GUI event loop
pyopl.lock(False)

# Handle keyboard interrupts properly. 
pyopl.join()

1. You obtain the Matplotlib Figure object as the return value of figure().

2. Next you have to lock the GUI event loop (call lock() with True). Now the GUI stops and the window is not refreshed anymore thus preventing any interference from the GUI while API calls are being made.

3. Before making API calls you have to verify that the window is not closed. This can be done by calling alive() and passing it the Figure object.

4. Do your Matplotlib API stuff on the Figure object.

5. Request a manual redraw of the plot window by calling draw() and passing it the Figure object.

6. Unlock the GUI event loop by calling lock() with False.

7. At the end of your program call join(). The program exits when you close the Control Window.

pyopus.plotter.interface.alive(fig)

Returns True if the figure fig is alive (window is not closed).

The GUI must be locked when this function is called. See lock().

pyopus.plotter.interface.close(fig=None)

Closes a plot window corresponding to figure fig.

If no fig is given, closes all plot windows.

Returns True on success.

The GUI must not be locked when this function is called. See lock().

pyopus.plotter.interface.draw(fig)

Redraws figure fig. Does nothing if figure is not alive.

The GUI must be locked when this function is called. See lock().

pyopus.plotter.interface.figure(*args, **kwargs)

Calling convention: figure(windowTitle, show, inFront, figpx, dpi, figsize, …)

Create a new plot window.

windowTitle specifies the title of the window.

If show is True (default) the window will be visible as soon as it is created.

If inFront is True (default) the window will show up on top of all other windows.

figsize is a tuple specifying the horizontal and vertical figure size in inches. dpi is used for obtaining the size in pixels (for the screen).

figpx is a tuple specifying the horizontal and vertical figure size in pixels. dpi is used for obtaining the figure size in inches (i.e. for saving the figure in a Postscript file). When specified, figpx overrides figsize.

All remaining arguments are passed to the constructor of the pyopus.plotter.plotwidget.QPPlotWindow object which passes them on to the constructor of the pyopus.plotter.plotwidget.QPFigureCanvas object.

Returns the tag of the newly created plot window which is actually the Matplotlib Figure object corresponding to the plot window.

The GUI must not be locked when this function is called. See lock().

pyopus.plotter.interface.init()

This is an obsolete function present only for compatibility reasons.

pyopus.plotter.interface.join()

Calling convention: join()

Joins the GUI thread. Usually called at the end of the main thread so the windows don’t close immediately after the main thread is finished. The waiting can be interrupted by a keyboard interrupt.

The GUI must not be locked when this function is called. See lock().

pyopus.plotter.interface.lock(state=True)

Calling convention: lock(state)

Locks the main event loop so Matplotlib API calls can be made using the matplotlib Figure objects without interfering with the repainting of the plot window.

If state is False the main event loop is unlocked and can proceed with handling GUI events.

Multiple calls with state set to True (or False) are equivalent to a single call.

pyopus.plotter.interface.raiseFigure(fig)

Raises the plot window corresponding to figure fig.

Returns True on success.

The GUI must not be locked when this function is called. See lock().

pyopus.plotter.interface.saveFigure(fig, fileName)

Saves the contents of a plot window corresponding to figure fig to a file named fileName.

See the FigureCanvas.print_figure() method. The available file types are listed in the FigureCanvas.filetypes dictionary.

Returns True on success.

The GUI must not be locked when this function is called. See lock().

pyopus.plotter.interface.showFigure(fig, on=True)

Shows (on is True) or hides the plot window corresponding to figure fig.

Returns True on success.

The GUI must not be locked when this function is called. See lock().

pyopus.plotter.interface.shutdown()

Exits the graphical thread. Equivalent to closing the Control window.

The GUI must not be locked when this function is called. See lock().

pyopus.plotter.interface.title(fig, title)

Sets the window title of figure fig to title.

This title appears in the title bar of the plot window.

The GUI must not be locked when this function is called. See lock().

pyopus.plotter.interface.updateRCParams(*args, **kwargs)

Calling convention: updateRCParams(dict)

Updates the rcParams structure of Matplotlib with the dictionary given by dict. Returns True on success.

The GUI must not be locked when this function is called. See lock().