Makie.jl Documentation

The SpecApi (introduced in version 0.20) allows for declarative plotting using "spec" objects. Instead of mutating an existing figure, you create lightweight descriptions of plots and layouts. These specs are then converted into full Makie objects.

Key Concepts:

• PlotSpec: Describes a plot object (e.g., Scatter, Heatmap, Lines).
• BlockSpec: Describes a container or structural object (e.g., Axis, Colorbar, GridLayout).
• Composition: Complex layouts are built by nesting simpler specs.
• Observables: You can pass an observable spec to a Figure. When the spec description changes, Makie uses diffing to automatically rebuild or update the figure content.

Warning: The SpecApi is under active development and may introduce breaking changes. It is generally slower than the standard mutating API because it performs diffing and re-creates plots to maintain the declarative structure.

import Makie.SpecApi as S

# Create specs using the S prefix convention
scatterspec = S.Scatter(1:4) 
axspec = S.Axis(plots=[scatterspec]) 
layout_spec = S.GridLayout(axspec) 

# Instantiate the spec into a Figure
f, _, pl = plot(layout_spec)

# Update the entire figure by updating the observable 'pl'
pl[1] = S.GridLayout(S.Axis(; title="Lines", plots=[S.Lines(1:4)]))

The shape attribute allows you to define a custom background for text labels. The shape is transformed to fit the text bounding box plus padding.

Using Geometry Primitives

You can pass objects like Circle, GeometryPrimitive, or BezierPath. To control how the shape scales relative to the text, use the shape_limits attribute. shape_limits defines a bounding box that is scaled to match the text bounding box.

Using a Function for Shapes

You can pass a function to shape that constructs a vector of points. This function receives origin and size (where size is the text bounding box plus padding) and should return a transformed vector of points.

Example of a function-based shape for a tight circle:

function build_shape(origin, size)
    radius = norm(0.5 * size)
    center = Point2f(origin + 0.5 * size)
    return coordinates(Circle(center, radius))
end

using CairoMakie
using GeometryBasics
using LinearAlgebra

# Example using a function to create a tight circular background
function build_shape(origin, size)
    radius = norm(0.5 * size)
    center = Point2f(origin + 0.5 * size)
    return coordinates(Circle(center, radius))
end

f, a, p = textlabel(
    [-1, 0, 1], [1, 1, 1], ["long label", "A", "t\na\nl\nl"],
    shape = build_shape, 
    fontsize = 20, 
    padding = 0
)

To create a custom plot type in Makie, follow these steps:

1. Define a Plot Type: Use the @recipe macro to define a new plot type and its default attributes.
2. Overload Makie.plot!: Implement the actual visualization by overloading Makie.plot! for your new type. Because Makie processes arguments dynamically, your plot! method should use map! to connect input nodes (converted arguments) to output nodes (data for child plots).
3. Use map! for dynamic updates: Use map!(attributes, input_nodes, output_nodes) do ... end to register computations in the Makie graph. This ensures that if input arguments (like Observables) change, the plot updates automatically.
4. Compose with existing plots: Inside your plot! method, call existing plotting functions (like lines! or barplot!) passing the current plot object sc and the computed nodes.

# 1. Define the plot type and attributes
@recipe StockChart begin
    downcolor = :red
    upcolor = :green
end

# 2. Implement the plotting logic
function Makie.plot!(sc::StockChart{<:Tuple{AbstractVector{<:Real}, AbstractVector{<:StockValue}}})
    input_nodes = [:converted_1, :converted_2]
    output_nodes = [:linesegments, :bar_tos, :color, :barpos]

    # Register computation for dynamic updates
    map!(sc.attributes, input_nodes, output_nodes) do times, stockvalues
        # ... compute linesegments, barpos, etc ...
        return (linesegments, bar_tos, colors, barpos)
    end

    # 3. Visualize using existing plots
    linesegments!(sc, sc.linesegments, color = sc.color, colormap = sc.colormap)
    barplot!(sc, sc.attributes, sc.barpos, fillto = sc.bar_tos, strokewidth = 0)

    return sc
end