Scenes

What is a Scene?

Scenes are fundamental building blocks of Makie figures. A Scene is like a container for Plots and other Scenes. Scenes have Plots (including an Axis if show_axis = true) and Subscenes associated with them. Every Scene also has a transformation, made up of scale, translation, and rotation.

Note

Before the introduction of the Figure workflow, Scenes used to be the main container object which was returned from all plotting functions. Now, scenes are mostly an implementation detail for many users, unless they want to build custom solutions that go beyond what the default system offers.

A Scene's plots can be accessed via scene.plots.

A Scene's subscenes (also called children) can be accessed through scene.children. This will return an Array of the Scene's child scenes. A child scene can be created by childscene = Scene(parentscene).

Any Scene with an axis also has a camera associated with it; this can be accessed through scene.camera, and its controls through scene.camera.cameracontrols. More documentation about these is in the Cameras section.

Scene's also have configurable size/resolution. You can set the size in pixels by doing Scene(resolution = (500, 500)).

Any keyword argument given to the Scene will be propagated to its plots; therefore, you can set the palette or the colormap in the Scene itself.

Subscenes

A subscene is no different than a normal Scene, except that it is linked to a "parent" Scene. It inherits the transformations of the parent Scene, but can then be transformed independently of it.

Modifying A Scene

Makie offers mutation functions to scale, translate and rotate your Scenes on the fly.

Makie.translate!Function
translate!(scene::Transformable, xyz::VecTypes)
translate!(scene::Transformable, xyz...)

Apply an absolute translation to the Scene, translating it to x, y, z.

source
translate!(Accum, scene::Transformable, xyz...)

Translate the scene relative to its current position.

source
Makie.rotate!Function
rotate!(Accum, scene::Transformable, axis_rot...)

Apply a relative rotation to the Scene, by multiplying by the current rotation.

source
rotate!(scene::Transformable, axis_rot::Quaternion)
rotate!(scene::Transformable, axis_rot::AbstractFloat)
rotate!(scene::Transformable, axis_rot...)

Apply an absolute rotation to the Scene. Rotations are all internally converted to Quaternions.

source
Makie.scale!Function
scale!(t::Transformable, x, y)
scale!(t::Transformable, x, y, z)
scale!(t::Transformable, xyz)
scale!(t::Transformable, xyz...)

Scale the given Transformable (a Scene or Plot) to the given arguments. Can take x, y or x, y, z. This is an absolute scaling, and there is no option to perform relative scaling.

source

Updating the Scene

When the Scene is changed, you may need to update several aspects of it. Makie provides three main updating functions:

Makie.update!Function
`update!(p::Scene)`

Updates a Scene and all its children. Update will perform the following operations for every scene:

if !scene.raw[]
    scene.update_limits[] && update_limits!(scene)
    scene.scale_plot[] && scale_scene!(scene)
    scene.center[] && center!(scene)
end
source
Makie.update_limits!Function
update_limits!(scene::Scene, limits::Union{Automatic, Rect} = scene.limits[], padding = scene.padding[])

This function updates the limits of the Scene passed to it based on its data. If an actual limit is set by the theme or its attributes (scene.limits !== automatic), it will not update the limits. Call update_limits!(scene, automatic) for that.

source
update_limits!(scene::Scene, new_limits::Rect, padding = Vec3f0(0))

This function updates the limits of the given Scene according to the given Rect.

A Rect is a generalization of a rectangle to n dimensions. It contains two vectors. The first vector defines the origin; the second defines the displacement of the vertices from the origin. This second vector can be thought of in two dimensions as a vector of width (x-axis) and height (y-axis), and in three dimensions as a vector of the width (x-axis), breadth (y-axis), and height (z-axis).

Such a Rect can be constructed using the FRect or FRect3D functions that are exported by Makie.jl. See their documentation for more information.

source
Makie.update_cam!Function
update_cam!(scene::SceneLike, area)

Updates the camera for the given scene to cover the given area in 2d.

source
update_cam!(scene::SceneLike)

Updates the camera for the given scene to cover the limits of the Scene. Useful when using the Node pipeline.

source
update_cam!(scene::Scene, eyeposition, lookat, up = Vec3f0(0, 0, 1))

Updates the camera's controls to point to the specified location.

source

In general, update! is to be used to keep data in sync, and update_cam! and update_limits! update the camera and limits respectively (to show all the data).

Events

Scenes have several pre-created event "hooks" (through Observables) that you can handle. These can be accessed through scene.events, which returns an Events struct.