Documentation doesn't explain well the model matrix things

[Zou-Bo]

Many plotting functions(e.g. heatmap) have this attribute:
"model::Makie.Mat4f sets a model matrix for the plot. This replaces adjustments made with translate! , rotate! and scale! ."
I don't understand this description and cannot find any explanations in detail or any examples about how to use this attribute.

[ffreyer]

I would personally prefer if we pushed against using model as an attribute since working with a translation-rotation-scale matrix makes some things a lot easier internally than a completely general Mat4f. So maybe instead of documenting model better we should document translate!, rotate! & scale! better and push plot.model into a footnote.

[bjarthur]

+1 for better documentation for rotate!. specifically, if i render a Toggle in the middle of a figure, how do i rotate it about it's center? see #4445 (comment) for a failed attempt of mine.

[EdsterG]

Another +1 for better documentation (and maybe even an updated implementation). Following up on #4445, I too can't figure out what the origin is for those toggles. I looked at all of the parent models and they are all identity matrices implying that the toggle should be drawn at the origin (0, 0), but it obviously isn't. So what transform is translating it to the middle of the screen?

t2.blockscene.transformation.model[]
t2.blockscene.parent.transformation.model[]
t2.blockscene.transformation.parent_model[]
t2.blockscene.transformation.parent[].model[]
t2.blockscene.transformation.parent[].parent_model[]
t2.parent.scene.transformation.model[]

I would expect at least one of the above matrices to contain the translation. Am I missing one?

As a suggestion to the translate/roatate API's, it would be helpful to have the following:

1. document the reference point
2. allow users to specify the reference point (see Unity API for example Rotate/Translate, both have a relativeTo parameter which defaults to self)

[ffreyer]

Transformations affect plots, not scenes. At least not directly. Effectively Makie ends up calculating

plot.model * apply_transform(plot.transformation.transform_func, plot.converted)

where things default as

t = plot.transformation
plot.model = t.model = t.parent.model * transformationmatrix(t.translation, t.scale, t.rotation)
t.transform_func = t.parent.transform_func

So if you translate/rotate/scale a scene and a plot in that scene those transformation will accumulate.

The origin of rotation etc is 0 in your plot input data (well technically after transform_func). For Toggle you're rendering to a pixel space scene (blockscene) with no transform_func. The plots that make up the toggle (poly, scatter) are therefore also in pixel space. (0, 0, 0) is at the bottom left of the window (or more specifically the blockscene, which is the same size as the window).