How to understand Makie.jl functions signatures

General Usage
,
1

I want to draw 3D mesh using Makie.jl.

I try to inspect mesh function

julia> using GLMakie

help?> mesh

  mesh(x, y, z)
  mesh(mesh_object)
  mesh(x, y, z, faces)
  mesh(xyz, faces)

For me it is not clear what are the types of (x, y, z) or what is the type of mesh_object. OK I try to inspect manually

julia> methods(mesh)
# 2 methods for generic function "mesh":
[1] mesh() in AbstractPlotting at C:\Users\aleck\.julia\packages\AbstractPlotting\3UpN6\src\recipes.jl:130
[2] mesh(args...; attributes...) in AbstractPlotting at C:\Users\aleck\.julia\packages\AbstractPlotting\3UpN6\src\recipes.jl:11

Nothing clear here too, what are the args and what are the attributes.

How to to understand in the clear way the API for the mesh function, what kind of data types it can accept?

3 Likes
2

These signatures seem very unclear indeed.

  • One of the signatures for image seems to be image(image). Well, sure, the floor is made out of floor, but this doesn’t tell me what type of argument image expects.
  • One of the signatures for lines is lines(positions). What are positions? A vector of tuples? A 2xN matrix? An Nx2 matrix? A vector of Pair?
  • The documentation for series(curves) actually explains what curves is supposed to be, which is magnificent
  • The signature of volume is volume(volume_data). Again, the volume data is made of volume data, sure, but what’s the expected type of volume_data? According to the example in the docs, it’s supposed to be Array{Float64, 3}, but ?CairoMakie.volume just says volume(volume_data), so I have to go online to see what types this function accepts.

methods(some_plotting_function) isn’t helpful either:

julia> methods(CairoMakie.volume)
# 2 methods for generic function "volume":
[1] volume() in MakieCore at MakieCore/S8PkO/src/recipes.jl:170
[2] volume(args...; attributes...) in MakieCore at MakieCore/S8PkO/src/recipes.jl:30

julia> methods(Makie.image)
# 2 methods for generic function "image":
[1] image() in MakieCore at MakieCore/S8PkO/src/recipes.jl:170
[2] image(args...; attributes...) in MakieCore at MakieCore/S8PkO/src/recipes.jl:30

julia> methods(Makie.lines)
# 2 methods for generic function "lines":
[1] lines() in MakieCore at MakieCore/S8PkO/src/recipes.jl:170
[2] lines(args...; attributes...) in MakieCore at MakieCore/S8PkO/src/recipes.jl:30

Apparently, all of these functions accept args..., which is even more confusing than the documentation, because it suggests that I can pass multiple arguments. What are these arguments?

3

Maybe the creator and maintainers of Makie can offer more information about this decision, but AFAICT it was a conscious one, in order to have methods as general as possible, allowing several ways to plot the same thing.

All the post-processing of the arguments is done internally instead of at dispatch-time.

4

The reason why it’s not clearly documented is that there are sometimes so many conversion methods that apply to one plot object, that the set of possible inputs is very large. So we’ve concentrated on other issues that needed to be fixed, although this one is a good one, too. Ideally, the conversion traits that apply to one plot object should also be automatically included in the docstring, because those increase the set of possibilities again. That’s why you have these nondescript image or volume_data placeholders, as they can be so many different things usually.

1 Like
5

Is it possible to see what arguments these functions support somewhere?

6

https://github.com/JuliaPlots/Makie.jl/blob/master/src/conversions.jl

This is where most conversion logic is defined

2 Likes