# 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](https://joss.theoj.org/papers/10.21105/joss.03349))


We're also excited to show off the redesign of our documentation using [DocumenterVitepress.jl](https://github.com/LuxDL/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)
f


### 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`:

struct DateStruct end
function Makie.convert_arguments(::PointBased, ::DateStruct)
    return (1:5, DateTime.(1:5))
end
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],)
f


### 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.

:::warning
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!

## Voxel

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:

r = range(-2pi, 2pi, length = 101)
f(x, y, z) = exp(cos(x)) / (1 + abs(sin(y))) * cos(0.25 * z)
chunk = [f(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)
fig


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 |
|:---:|:--:|
|  |  |

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 https://www.kenney.nl/assets/voxel-pack:

# 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)
        else
            rocky_dirt > dirt ? UInt8(7) : UInt8(53)
        end
        chunk[x, y, z] = choice
    end
    
    choice = randn() + 0.2 * (height - 15)
    chunk[x, y, height+1] = choice > 0 ? UInt8(16) : UInt8(15) # light, dark grass
end

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

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


## Lines

#### Internal/Backend changes

The line rendering code for GLMakie and WGLMakie has been reworked to bring both backends to the same standard. The major changes are that WGLMakie now renders line joints and supports linestyles. Here is a quick before and after:

| Before | After |
|:---:|:---:|
|  |  |

As part of this GLMakie had some changes to its colormap and color interpolation. It used to sample the colormap at line points and then interpolate the result to color the line. This can lead to unexpected colors appearing along a segment. Now GLMakie interpolates the `plot.color` values and samples the actual colors from the colormap in the fragment shader. In some cases this change can be very obvious, e.g. in the example below.
On the other hand, the color interpolation change (i.e. `plot.color::Vector{RGBAf}`) is subtle. Rather than interpolating `plot.color` on the triangles making up a line segment we now interpolate based on segment length. This cleans up the purple spike you can see in the top left segment in the example.

fig = Figure(size = (400, 400))
a, p = lines(
    fig[1, 1], [-1, -1, 0, 0, 1, 1], [0, 1, 0.8, 0.25, 0, 1], linewidth = 40, 
    color = [0, 1, 0, 1, 0, 1],
    colormap = [:red, :yellow, :blue]
)
hidedecorations!(a)
xlims!(a, -1.2, 1.2)
ylims!(a, -0.1, 1.15)
fig

| Before | After | without yellow |
|:---:|:---:|:---:|
|  |  |  |

Tangentially to these changes we also fixed issue where lines would invert in a 3D LScene (i.e. with perspective projection) when zooming in too far.

#### Linecaps and joinstyles

We have added support for different line caps and join styles across CairoMakie, GLMakie and WGLMakie. Line caps can be set with the `linecap` attribute for `lines` and `linesegments` to either `:butt` (default), `:square` or `:round`. Join styles apply only to `lines` and use the `joinstyle` attribute which can be either `:miter`, `:bevel` or `:round`. `joinstyle = :miter` further depends on `miter_limit` which sets the minimum corner angle below which `:bevel` joints are used.


## Float64 Precision in Axis (Beta)

The first Makie backend was GLMakie, and because GPUs are much more efficient working in 32 bit floating point this influenced the early design of Makie to favor 32 bit precision in its conversion pipeline.

This resulted in some unfortunate limitations when plotting data which could not be resolved well enough in `Float32`. For example, note how this line of scatter dots was quantized very visibly in Makie 0.20 because the values are close together relative to their magnitude:

data = 10_000 .+ range(0, 0.01, length = 50)
scatter(data)


In Makie 0.21, an additional step was inserted in the conversion pipeline for `Axis` which rescales data before handing it off to the backends in reduced precision, thereby mostly circumventing quantization problems. The same plot in Makie 0.21 shows a nice straight line and the limits are also not shifted incorrectly anymore:


In a large amount of internal code, we could move from `Float32` by default to `Float64` which also removed some common sources of errors, for example if axis limits were too close together in `Float32`. Supporting `Float64` precision also made it easier to implement support for `DateTime` because typical timestamps suffer from quantization when converted to numbers as they become large numbers that are very close to each other.

#### For Developers

The changes should be mostly isolated from custom plot recipes and `convert_arguments()` methods. You should be fine as long as you don't convert arguments to `Float32` types (e.g. use `Point2d` or `Point2` over `Point2f`). If you have a custom `data_limits()` method you should follow the points outlined below. If you still have issues after this you can check `plot.input_args` and `plot.converted` (including for child plots in `plot.plots`) to find out when/if a `Float32` conversion occurs.

If you are projecting data yourself and, for example, plot in `:pixel` space things get a bit more complicated. To deal with Float64 precision we have added a linear transformation `scene.float32convert` acting after `plot.model[]` or before `Makie.patch_model(scene plot.model[])`. This step is likely to be missing and will cause wrong results when the conversion takes effect. You currently have a few options:
- Use `Makie.plot_to_screen(plot, data)` which transforms a point of vector points from `plot.space[]` to `:pixel` space using the information contained in the given plot (or scene).
- Use `project(scene, input_space, output_space, point)` to project between any two spaces. Note that you will need to handle `transform_func` yourself here.
- Handle it yourself. If you can't use `plot_to_screen()` (i.e. your target space is not `:pixel`) you will see better performance by adapting `plot_to_screen()` than by using `project()` repeatedly. You can check "basic_recipes/error_and_rangebars.jl" and "camera/projection_math.jl" for the definitions of these functions.

### data_limits and boundingbox changes

As part of dealing with `Float32` precision issues we have updated the `data_limits` and `boundingbox` functions.

Previously `data_limits()` considered `Mat3f(plot.model[])`, i.e. rotation and scaling applied to a plot, while ignoring the plots transform_func and translation. With that the result is in an unnatural coordinate system. `boundingbox(x)` was given by `parent_transform(x) * data_limits(x)`, where parent_transform is the model matrix of the parent plot or scene, with `boundingbox(p::Text)` being an exception producing limits in `p.markerspace[]`.

After the changes `data_limits()` is now strictly in input space, i.e. it applies no transformations. It is however allowed to consider the size of markers if the markers are in the same space as the user data. So for example, `meshscatter` considers the size of the scattered mesh and `text` considers the size of the string if `space[] == markerspace[]`.

`boundingbox()` on the other hand considers a full transformation to world space, i.e. it applies `transform_func(plot)` and the full `plot.model[]` matrix. For the future we have also added a (target) `space` argument here which is largely ignored for now. The exception being `boundingbox(p::Text, space)` which requires the argument to differentiate the new functionality (`space = :data`) from the old (`space = p.markerspace[]`).

#### For Developers

By default `boundingbox(plot)` is derived from the `data_limits(plot)` using `apply_transform(func, bbox::Rect3d)`, and `data_limits(plot)` default to the combined limits of the child plots. This will usually be enough to calculate reasonable limits, but there are some edge cases which may need your attention:
- If you a define a plot with child plots in different spaces, then you must implement `data_limits(plot)` and `boundingbox(plot, space = :data)` to get the correct limits. Some examples of this are [errorbars](https://github.com/MakieOrg/Makie.jl/blob/dd64632f07e5c3f630c64968f5d0c6eeef2f15c4/src/basic_recipes/error_and_rangebars.jl#L305-L307) which use pixel space for whiskers, [h/vlines](https://github.com/MakieOrg/Makie.jl/blob/dd64632f07e5c3f630c64968f5d0c6eeef2f15c4/src/basic_recipes/hvlines.jl#L88-L98) which are partially in relative scale and [voronoiplot](https://github.com/MakieOrg/Makie.jl/blob/dd64632f07e5c3f630c64968f5d0c6eeef2f15c4/src/basic_recipes/voronoiplot.jl#L158-L169) which applies `transform_func` internally.
- If you define a custom `transform_func` which does not correctly transform a `Rect3d` by transforming its vertices, then you should implement a `apply_transform(my_transform_func, bbox::Rect3d)` method that does.

## Breaking Changes

- `data_limits(plot)` no longer considers part of the plots model matrix
- `boundingbox(plot)` now considers the plots `transform_func` and full model matrix
- `boundingbox(p::Text)` has been deprecated in favor of `boundingbox(p, p.markerspace[])` with `boundingbox(p, :data)` following the new `boundingbox()` logic
- `data_limits()` and `boundingbox()` now return `Rect{3, Float64}` types
- `project(cam, input_space, output_space, pos)` is no longer save to use for plots in an `Axis`. Use `project(scene, input_space, output_space, pos)` instead.
- deprecated `rotations` Attribute for `rotation` in `scatter` and `meshscatter` plots (both were valid before)