Makie v0.21

We're happy to announce Makie's next minor version - v0.21!

Makie's community has been growing steadily over the last years, and we hope this new update will allow you all to create more and better visualizations than ever!

(Here's a small chart that reflects how Makie's usage is increasing, showing citations over time as indicated by google scholar alerts for our JOSS paper)


We're also excited to show off the redesign of our documentation using DocumenterVitepress.jl which improves overall clarity, benefits from new Documenter.jl features and has a better search functionality than our old custom Franklin.jl setup. We are determined to keep improving the documentation more and more, to really enable our users to tap into the vast range of features Makie offers today.


With that said, let's dive into the most important changes and additions in v0.21!

Unit and Categorical support

This feature has been requested countless times over the last years and has been finally implemented. It required a lot of work, due to Observables allowing anything to update dynamically at any time, the complex interaction of plot object creation with Axes and the feature itself being quite complex with lots of corner cases. But now, as of Makie 0.21, types like units, categorical values and dates are supported natively and we added an interface that can be extended for custom units.

Any type is converted to a plottable representation by the new dim_converts function, which changes a dimension of the axis to a new unit space. Once the conversion is set for a dimension, it can't be changed anymore to prohibit mixing units in that dimension. This is implemented by the Scene carrying a new DimConversions object, which tracks the conversions for each dimension, which it forwards to the Plot and Axis objects. While this is a more complex approach, it guarantees that these conversions are really treated as new unit spaces for the axis, rather than just a recipe which changes axis tick labels.

The basic usage is as easy as replacing numbers with any supported type, e.g. Dates.Second:

                using CairoMakie, Makie.Dates, Makie.Unitful
f, ax, pl = lines(Second(1):Second(60):Second(20*60), u"m" .* cumsum(randn(20)))
data = cumsum(randn(4, 100), dims=2)
barplot(f[1, 2], Categorical(["a", "b", "c"]), 1:3)
series(f[2, :], now() .+ Second.(1:100), data)

Integration with the conversion pipeline

One of the complications to implement dim converts was to enable convert_arguments to be able to return units and also make it work with the new SpecApi:

                import Makie.SpecApi as S
struct DateStruct end
function Makie.convert_arguments(::PointBased, ::DateStruct)
    return (1:5, DateTime.(1:5))
f, ax, pl = scatter(DateStruct())
bplot = S.BarPlot(Categorical(["a", "b", "c"]), 1:3; bar_labels=:y)
spec = S.GridLayout([S.Axis(; plots=[bplot])])
plot(f[1, 2], spec)

Current limitations

  • For now, dim conversions only works for vectors with supported types for the x and y arguments for the standard 2D Axis. It's setup to generalize to other Axis types, but the full integration hasn't been done yet.

  • Keywords like direction=:y in e.g. Barplot will not propagate to the Axis correctly, since the first argument is currently always x and second always y. We're still trying to figure out how to solve this properly

  • Categorical values need to be wrapped in Categorical, since it's hard to find a good type that isn't ambiguous when defaulting to a categorical conversion. You can find a work around in the docs.

  • Date Time ticks simply use PlotUtils.optimize_datetime_ticks which is also used by Plots.jl. It doesn't generate optimally readable ticks yet and can generate overlaps and goes out of axis bounds quickly. This will need more polish to create readable ticks as default.

  • To properly apply dim conversions only when applicable, one needs to use the new undocumented @recipe macro and define a conversion target type. This means user recipes only work if they pass through the arguments to any basic plotting type without conversion.

Plot Attribute Validation

One of Makie's biggest footguns has always been that you could pass arbitrary wrong keyword arguments to plotting functions without getting an error. For example, the following call would happily display a scatter plot, but not with the intended visual attributes - because none of them are defined for Scatter:

              scatter(x, y; colour = :red, marker_size = 3, stroke = :black)

It took a lot of work to remedy this situation, but we finally got it done. In v0.21, we have introduced a second internal variant of the @recipe macro and rewritten all our recipes to use it. This variant allows to declare at compile time which attributes are valid for a given plotting function, and also documenting these attributes in-place. We can now throw a helpful error for the example above:


There are more improvements to be made in this area, but this refactor is a big step forward in making Makie more robust and user-friendly.


Note that the new `@recipe` syntax is undocumented and considered internal for now. It could experience breaking changes in patch versions as we make further improvements to it. This also means that third party recipes written with the old `@recipe` syntax will continue to work as they are and not automatically receive the benefits of the new system.

Now that we have solidified how we deal with plot attributes internally, we also want to improve their public-facing documentation. In the future, we want to have visual examples for each plot attribute of each plot, so that users can more easily navigate what options are available to them. Once this process starts, we hope to get the community involved, too. The amount of examples to be written is large but at the same time requires no deep understanding of the code base, so this could be a fun way to contribute and get your feet wet in open source development!


With this new release we are adding a new (primitive) plot type - voxels. A voxel is the 3D equivalent of a pixel, i.e. a small cube of a constant size placed into a regular 3D grid. Given those restrictions voxels is generally much more efficient than meshscatter(pos, marker = Rect3f(Point3f(-0.5), Vec3f(1)), markersize = 1, color = colors), both with respect to computational cost (i.e. geometry rendered) and memory usage (i.e. data transfered to the GPU). The plot type currently has a dedicated implementation in GLMakie and WGLMakie, though WGLMakie still has some rendering issues.

A voxels plot takes an Array{3} as an input and optionally three intervals to specify the range of the voxel grid. Here is an example using voxels to show an isosurface by manipulating the visible colorrange:

                using GLMakie; GLMakie.activate!()
r = range(-2pi, 2pi, length = 101)
func(x, y, z) = exp(cos(x)) / (1 + abs(sin(y))) * cos(0.25 * z)
chunk = [func(x, y, z) for x in r, y in r, z in r]

fig = Figure(figure_size = (400, 400))
ax = LScene(fig[1, 1])
voxels!(ax, -2..2, -2..2, -2..2, chunk, colorrange = (0.1, 0.2), lowclip = :transparent, highclip = :transparent)

If you are interested in what's below the surface you can add transparency (via the colormap or alpha with transparency = true) or reduce the size of voxels by setting 1 > gap > 0:

transparency gap
voxel_isosurface_transparent voxel_isosurface_gapped

You can also render voxels with textures. Currently voxels are represented by UInt8 with 0x00 strictly being an invisible air block. This leaves you with 255 voxel ids to map to textures. This is done by specifying a uvmap as either a Vector uvs[id] = uv::Vec4f or Matrix uvs[id, side] = uv::Vec4f. Here is an example using

                using FileIO
# 9 wide, 10 tall
texture = FileIO.load(Makie.assetpath("voxel_spritesheet.png"))
uv_map = [
    Vec4f(x, x+1/10, y, y+1/9)
    for x in range(0.0, 1.0, length = 11)[1:end-1]
    for y in range(0.0, 1.0, length = 10)[1:end-1]

# all air
chunk = fill(0x00, 64, 64, 32)

# fill with other block types
for x in axes(chunk, 1), y in axes(chunk, 2)
    # fill columns bottom to top with stone, rocky dirt, dirt and grass
    height = floor(Int, 15 + 8 * sin(0.1 * x) * cos(0.1 * y))
    for z in 1:height
        rock, rocky_dirt, dirt = 1.3 .* abs.(1 .- randn(3))
        rock -= abs(height - 7 - z)
        rocky_dirt -= abs(height - 4 - z)
        dirt -= abs(height - 1 - z)

        choice = if rock > rocky_dirt
            rock > dirt ? UInt8(40) : UInt8(53)
            rocky_dirt > dirt ? UInt8(7) : UInt8(53)
        chunk[x, y, z] = choice
    choice = randn() + 0.2 * (height - 15)
    chunk[x, y, height+1] = choice > 0 ? UInt8(16) : UInt8(15) # light, dark grass

fig = Figure()
ax = LScene(fig[1, 1], show_axis = false)
voxels!(ax, chunk, uvmap = uv_map, color = texture)

# set camera position
cameracontrols(ax.scene) = false
update_cam!(ax.scene, Vec3f(35, 55, 10), Vec3f(2, 7, -9))