# Figures, legends, camera and decorations

## Handling several figures

All mlab functions operate on the current scene, that we also call `figure()`, for compatibility with matlab and pylab. The different figures are indexed by key that can be an integer or a string. A call to the `figure()` function giving a key will either return the corresponding figure, if it exists, or create a new one. The current figure can be retrieved with the `gcf()` function. It can be refreshed using the `draw()` function, saved to a picture file using `savefig()` and cleared using `clf()`.

## Figure decorations

Axes can be added around a visualization object with the `axes()` function, and the labels can be set using the `xlabel()`, `ylabel()` and `zlabel()` functions. Similarly, `outline()` creates an outline around an object. `title()` adds a title to the figure.

Color bars can be used to reflect the color maps used to display values (LUT, or lookup tables, in VTK parlance). `colorbar()` creates a color bar for the last object created, trying to guess whether to use the vector data or the scalar data color maps. The `scalarbar()` and `vectorbar()` function scan be used to create color bars specifically for scalar or vector data.

A small xyz triad can be added to the figure using `orientation_axes()`.

Warning

The `orientation_axes()` was named orientationaxes before release 3.2.

## Moving the camera

The position and direction of the camera can be set using the `view()` function. They are described in terms of Euler angles and distance to a focal point. The `view()` function tries to guess the right roll angle of the camera for a pleasing view, but it sometimes fails. The `roll()` explicitly sets the roll angle of the camera (this can be achieve interactively in the scene by pressing down the control key, while dragging the mouse, see Interaction with the scene).

The `view()` and `roll()` functions return the current values of the different angles and distances they take as arguments. As a result, the view point obtained interactively can be stored and reset using:

    # Store the information
    view = mlab.view()
    roll = mlab.roll()

    # Reposition the camera
    mlab.view(*view)
    mlab.roll(roll)

Rotating the camera around itself

> You can also rotate the camera around itself using the roll, yaw and pitch methods of the camera object. This moves the focal point:

>     f = mlab.gcf()
>     camera = f.scene.camera
>     camera.yaw(45)

Unlike the `view()` and `roll()` function, the angles are incremental, and not absolute.

Modifying zoom and view angle

The camera is entirely defined by its position, its focal point, and its view angle (attributes ‘position’, ‘focal_point’, ‘view_angle’). The camera method ‘zoom’ changes the view angle incrementally by the specify ratio, where as the method ‘dolly’ translates the camera along its axis while keeping the focal point constant. The `move()` function can also be useful in these regards.

Note

Camera parallel scale

In addition to the information returned and set by mlab.view and mlab.roll, a last parameter is needed to fully define the view point: the parallel scale of the camera, that control its view angle. It can be read (or set) with the following code:

    f = mlab.gcf()
    camera = f.scene.camera
    cam.parallel_scale = 9