

.. currentmodule:: enthought.mayavi.mlab

.. note::

    This section is only a reference describing the function, please see
    the chapter on :ref:`simple-scripting-with-mlab` for an introduction to 
    mlab and how to interact with and assemble the functions of `mlab`.

    Please see the section on :ref:`running-mlab-scripts` for
    instructions on running the examples.

Figure handling functions
=========================

clf
~~~

.. function:: clf(figure=None)

    Clear the current figure.
    
    You can also supply the figure that you want to clear.
    

    


close
~~~~~

.. function:: close(scene=None, all=False)

    Close a figure window
    
    close() by itself closes the current figure.
    
    close(num) closes figure number num.
    
    close(name) closes figure named name.
    
    close(figure), where figure is a scene instance, closes that
    figure.
    
    close(all=True) closes all figures controlled by mlab
    

    


draw
~~~~

.. function:: draw(figure=None)

    Forces a redraw of the current figure.
    

    


figure
~~~~~~

.. function:: figure(figure=None, bgcolor=None, fgcolor=None, engine=None, size=(400, 350))

    Creates a new scene or retrieves an existing scene. If the mayavi
    engine is not running this also starts it.
    
    **Keyword arguments**
    
        :figure: The name of the figure, or handle to it.
    
        :bgcolor: The color of the background (None is default).
    
        :fgcolor: The color of the foreground, that is the color of all text
                  annotation labels (axes, orientation axes, scalar bar
                  labels). It should be sufficiently far from `bgcolor`
                  to see the annotation texts. (None is default).
    
        :engine: The mayavi engine that controls the figure.
    
        :size: The size of the scene created, in pixels. May not apply
               for certain scene viewer.
    

    


gcf
~~~

.. function:: gcf(engine=None)

    Return a handle to the current figure.
    
    You can supply the engine from which you want to retrieve the
    current figure, if you have several mayavi engines.
    

    


savefig
~~~~~~~

.. function:: savefig(filename, size=None, figure=None, magnification='auto', **kwargs)

    Save the current scene.
    The output format are deduced by the extension to filename.
    Possibilities are png, jpg, bmp, tiff, ps, eps, pdf, rib (renderman),
    oogl (geomview), iv (OpenInventor), vrml, obj (wavefront)
    
    **Parameters**
    
    :size: the size of the image created (unless magnification is
           set, in which case it is the size of the window used
           for rendering).
    
    :figure: the figure instance to save to a file.
    
    :magnification: the magnification is the scaling between the
                    pixels on the screen, and the pixels in the
                    file saved. If you do not specify it, it will be
                    calculated so that the file is saved with the
                    specified size. If you specify a magnification,
                    Mayavi will use the given size as a screen size,
                    and the file size will be 'magnification * size'.
    
    **Notes**
    
    If the size specified is larger than the window size, and no
    magnification parameter is passed, the magnification of the scene
    is changed so that the image created has the requested size.
    Please note that if you are trying to save images with sizes
    larger than the window size, there will be additional computation
    cost.
    
    Any extra keyword arguments are passed along to the respective
    image format's save method.
    

    


sync_camera
~~~~~~~~~~~

.. function:: sync_camera(reference_figure, target_figure)

    Synchronise the camera of the target_figure on the camera of the
    reference_figure.
    

    

