Scenes
What is a Scene
?
A Scene
is basically a container for Plot
s and other Scene
s. Scenes
have Plot
s (including an Axis
if show_axis = true
) and Subscenes
associated with them. Every Scene has a transformation, made up of scale, translation, and rotation.
Plots associated with a Scene can be accessed through scene.plots
, which returns an Array of the plots associated with the Scene
. Note that if scene
has no plots (if it was created by layouting, or is an empty scene), then scene.plots
will be a 0-element array!
If a scene is not explicitly declared prior to one of the plot!
commands being called, a Scene
will be created by default as follows: lines(args...) = lines!(Scene(), args...)
.
In this example, lines
becomes the parent of all of the following plot!
commands since it was called prior to a Scene
being explicitly created.
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.
<!–TODO add universe example here–>
Current Scene
Knowing what Scene you are working with at any given moment is paramount as you work with more complex Makie implementations containing multiple Scenes. You can check your current scene by doing AbstractPlotting.current_scene()
which will return the current active scene (the last scene that got created).
Modifying the Scene
Makie offers mutation functions to scale, translate and rotate your Scenes on the fly.
AbstractPlotting.translate!
— Functiontranslate!(scene::Transformable, xyz::VecTypes)
translate!(scene::Transformable, xyz...)
Apply an absolute translation to the Scene, translating it to x, y, z
.
translate!(Accum, scene::Transformable, xyz...)
Translate the scene relative to its current position.
AbstractPlotting.rotate!
— Functionrotate!(Accum, scene::Transformable, axis_rot...)
Apply a relative rotation to the Scene, by multiplying by the current rotation.
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 Quaternion
s.
AbstractPlotting.scale!
— Functionscale!(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.
Updating the Scene
When the Scene is changed, you may need to update several aspects of it. Makie provides three main updating functions:
AbstractPlotting.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
AbstractPlotting.update_limits!
— Functionupdate_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.
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 AbstractPlotting.jl
. See their documentation for more information.
AbstractPlotting.update_cam!
— Function`update_cam!(scene::SceneLike, area)`
Updates the camera for the given scene
to cover the given area
in 2d.
`update_cam!(scene::SceneLike)`
Updates the camera for the given scene
to cover the limits of the Scene
. Useful when using the Node
pipeline.
update_cam!(scene::Scene, eyeposition, lookat, up = Vec3f0(0, 0, 1))
Updates the camera's controls to point to the specified location.
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:
Missing docstring for Events
. Check Documenter's build log for details.