PolarAxis improvements (full rlimits, thetalimits, improved controls, argument order)

NEWS.md

@@ -2,6 +2,9 @@
 
 ## master
 
+- [Breaking] Changed the default order Polar arguments to (theta, r). [#3154](https://github.com/MakieOrg/Makie.jl/pull/3154)
+- General improvements to `PolarAxis`: full rlimtis & thetalimits, more controls and visual tweaks. See pr for more details.[#3154](https://github.com/MakieOrg/Makie.jl/pull/3154)
+
 ## v0.19.9
 
 - Allow arbitrary reversible scale functions through `ReversibleScale`.

ReferenceTests/src/tests/examples2d.jl

@@ -1219,7 +1219,7 @@ end
 @reference_test "Triplot with nonlinear transformation" begin
     f = Figure()
     ax = PolarAxis(f[1, 1])
-    points = Point2f[(r, phi) for r in 1:10 for phi in range(0, 2pi, length=36)[1:35]]
+    points = Point2f[(phi, r) for r in 1:10 for phi in range(0, 2pi, length=36)[1:35]]
     tr = triplot!(ax, points)
     f
 end
@@ -1303,13 +1303,13 @@ end
 
 @reference_test "Voronoiplot with a nonlinear transform" begin
     f = Figure()
-    ax = PolarAxis(f[1, 1])
+    ax = PolarAxis(f[1, 1], theta_as_x = false)
     points = Point2f[(r, phi) for r in 1:10 for phi in range(0, 2pi, length=36)[1:35]]
     polygon_color = [r for r in 1:10 for phi in range(0, 2pi, length=36)[1:35]]
     polygon_color_2 = [phi for r in 1:10 for phi in range(0, 2pi, length=36)[1:35]]
     tr = voronoiplot!(ax, points, smooth = false, show_generators = false, color = polygon_color)
     Makie.rlims!(ax, 12) # to make rect clip visible if circular clip doesn't happen
-    ax = PolarAxis(f[1, 2])
+    ax = PolarAxis(f[1, 2], theta_as_x = false)
     tr = voronoiplot!(ax, points, smooth = true, show_generators = false, color = polygon_color_2)
     Makie.rlims!(ax, 12)
     f

ReferenceTests/src/tests/figures_and_makielayout.jl

@@ -140,24 +140,25 @@ end
 @reference_test "PolarAxis surface" begin
     f = Figure()
     ax = PolarAxis(f[1, 1])
-    zs = [r*cos(phi) for r in range(1, 2, length=100), phi in range(0, 4pi, length=100)]
-    p = surface!(ax, 0..10, 0..2pi, zs, shading = false, colormap = :coolwarm, colorrange=(-2, 2))
+    zs = [r*cos(phi) for phi in range(0, 4pi, length=100), r in range(1, 2, length=100)]
+    p = surface!(ax, 0..2pi, 0..10, zs, shading = false, colormap = :coolwarm, colorrange=(-2, 2))
+    rlims!(ax, 0, 11) # verify that r = 10 doesn't end up at r > 10
+    translate!(p, 0, 0, -200)
     Colorbar(f[1, 2], p)
     f
 end
 
 # may fail in WGLMakie due to missing dashes
 @reference_test "PolarAxis scatterlines spine" begin
     f = Figure(resolution = (800, 400))
-    ax1 = PolarAxis(f[1, 1], title = "No spine", spinevisible = false)
+    ax1 = PolarAxis(f[1, 1], title = "No spine", spinevisible = false, theta_as_x = false)
     scatterlines!(ax1, range(0, 1, length=100), range(0, 10pi, length=100), color = 1:100)
 
     ax2 = PolarAxis(f[1, 2], title = "Modified spine")
     ax2.spinecolor[] = :red
     ax2.spinestyle[] = :dash
     ax2.spinewidth[] = 5
-    scatterlines!(ax2, range(0, 1, length=100), range(0, 10pi, length=100), color = 1:100)
-
+    scatterlines!(ax2, range(0, 10pi, length=100), range(0, 1, length=100), color = 1:100)
     f
 end
 
@@ -174,14 +175,31 @@ end
         thetaminorgridwidth = 1.0, thetaminorgridstyle = :dash,
         rgridwidth = 2, rgridcolor = :red,
         thetagridwidth = 2, thetagridcolor = :blue,
-        rticklabelsize = 18, rticklabelcolor = :red,
+        rticklabelsize = 18, rticklabelcolor = :red, rtickangle = pi/6,
         rticklabelstrokewidth = 1, rticklabelstrokecolor = :white,
         thetaticklabelsize = 18, thetaticklabelcolor = :blue,
         thetaticklabelstrokewidth = 1, thetaticklabelstrokecolor = :white,
     )
     f
 end
 
+@reference_test "PolarAxis limits" begin
+    f = Figure(resolution = (800, 600))
+    for (i, theta_0) in enumerate((0, -pi/6, pi/2))
+        for (j, thetalims) in enumerate(((0, 2pi), (-pi/2, pi/2), (0, pi/12)))
+            po = PolarAxis(f[i, j], theta_0 = theta_0, thetalimits = thetalims, rlimits = (1 + 2(j-1), 7))
+            po.scene.backgroundcolor[] = RGBAf(1,0.5,0.5,1)
+            lines!(po, range(0, 20pi, length=201), range(0, 10, length=201), color = :white, linewidth = 5)
+
+            b = Box(f[i, j], color = (:blue, 0.2))
+            translate!(b.blockscene, 0, 0, 9001)
+        end
+    end
+    colgap!(f.layout, 5)
+    rowgap!(f.layout, 5)
+    f
+end
+
 @reference_test "Axis3 axis reversal" begin
     f = Figure(resolution = (1000, 1000))
     revstr(dir, rev) = rev ? "$dir rev" : ""
@@ -223,4 +241,4 @@ end
     Colorbar(fig[3, :][1, 2], hm; width=200)
 
     fig
-end
+end

docs/reference/blocks/polaraxis.md

@@ -1,8 +1,7 @@
 # PolarAxis
 
-The `PolarAxis` is an axis for data in polar coordinates `(radius, angle)`. It
-is currently an experimental feature, meaning that some functionality might be
-missing or broken, and that the `PolarAxis` is (more) open to breaking changes.
+The `PolarAxis` is an axis for data given in polar coordinates, i.e a radius and an angle.
+It is currently an experimental feature, meaning that some functionality might be missing or broken, and that the `PolarAxis` is (more) open to breaking changes.
 
 ## Creating a PolarAxis
 
@@ -23,29 +22,79 @@ f
 
 ## Plotting into an PolarAxis
 
-Like with an `Axis` you can use mutating 2D plot functions directly on a
-`PolarAxis`. The input arguments of the plot functions will then be interpreted
-in polar coordinates, i.e. as a radius and angle (in radians).
+Like with an `Axis` you can use mutating 2D plot functions directly on a `PolarAxis`.
+The input arguments of the plot functions will then be interpreted in polar coordinates, i.e. as an angle (in radians) and a radius.
+The order of a arguments can be changed with `ax.theta_as_x`.
 
 \begin{examplefigure}{svg = true}
 ```julia
-lineobject = lines!(ax, 0..10, sin, color = :red)
-scatobject = scatter!(0:0.5:10, cos, color = :orange)
+f = Figure(resolution = (800, 400))
+
+ax = PolarAxis(f[1, 1], title = "Theta as x")
+lineobject = lines!(ax, 0..2pi, sin, color = :red)
+
+ax = PolarAxis(f[1, 2], title = "R as x", theta_as_x = false)
+scatobject = scatter!(range(0, 10, length=100), cos, color = :orange)
 
 f
 ```
 \end{examplefigure}
 
-Note that not every plot type is compatible with polar transforms. For example
-`image` is not as it expects to be drawn on a rectangle. `heatmap` works to a
-degree in CairoMakie, but not GLMakie due to differences in the backend
-implementation.
-`surface` can be used as a replacement for `image` as it generates a triangle
-mesh. However it also has a component in z-direction which will affect drawing
-order. You can use `translate!(plot, 0, 0, z_shift)` to work around that.
-As a replacement for `heatmap` you can use `voronoiplot`, which generates cells
-of arbitrary shape around points given to it. Here you will generally need to
-set `rlims!(ax, rmax)` yourself.
+## PolarAxis Limits
+
+By default the PolarAxis will assume `po.rlimits[] = (0.0, nothing)` and `po.thetalimits[] = (0.0, 2pi)`, showing a full circle.
+You can adjust these limits to show different cut-outs of the PolarAxis.
+For example, we can limit `thetalimits` to a smaller range to generate a circle sector and further limit rmin through `rlimits` to cut out the center to an arc.
+
+\begin{examplefigure}{svg = true}
+```julia
+f = Figure(resolution = (600, 600))
+
+ax = PolarAxis(f[1, 1], title = "Default")
+lines!(ax, range(0, 8pi, length=300), range(0, 10, length=300))
+ax = PolarAxis(f[1, 2], title = "thetalimits", thetalimits = (-pi/6, pi/6))
+lines!(ax, range(0, 8pi, length=300), range(0, 10, length=300))
+
+ax = PolarAxis(f[2, 1], title = "rlimits", rlimits = (5, 10))
+lines!(ax, range(0, 8pi, length=300), range(0, 10, length=300))
+ax = PolarAxis(f[2, 2], title = "both")
+lines!(ax, range(0, 8pi, length=300), range(0, 10, length=300))
+thetalims!(ax, -pi/6, pi/6)
+rlims!(ax, 5, 10)
+
+f
+```
+\end{examplefigure}
+
+You can make further adjustments to the orientation of the PolarAxis by adjusting `ax.theta_0` and `ax.direction`.
+These adjust how angles are interpreted by the polar transform following the formula `output_angle = direction * (input_angle + theta_0)`.
+
+\begin{examplefigure}{svg = true}
+```julia
+f = Figure()
+
+ax = PolarAxis(f[1, 1], title = "Reoriented Axis", theta_0 = -pi/2, direction = -1)
+lines!(ax, range(0, 8pi, length=300), range(0, 10, length=300))
+thetalims!(ax, -pi/6, pi/6)
+rlims!(ax, 5, 10)
+
+f
+```
+\end{examplefigure}
+
+Note that by default translations in adjustments of rmin and thetalimits are blocked.
+These can be unblocked by calling `autolimits!(ax[, true])` which also tells the PolarAxis to derive r- and thetalimits freely from data, or by setting `ax.fixrmin[] = false` and `ax.thetazoomlock[] = false`.
+
+
+## Plot type compatability
+
+Not every plot type is compatible with the polar transform.
+For example `image` is not as it expects to be drawn on a rectangle.
+`heatmap` works to a degree in CairoMakie, but not GLMakie due to differences in the backend implementation.
+`surface` can be used as a replacement for `image` as it generates a triangle mesh.
+However it also has a component in z-direction which will affect drawing order.
+You can use `translate!(plot, 0, 0, z_shift)` to work around that.
+As a replacement for `heatmap` you can use `voronoiplot`, which generates cells of arbitrary shape around points given to it. Here you will generally need to set `rlims!(ax, rmax)` yourself.
 
 \begin{examplefigure}{svg = false}
 ```julia
@@ -54,22 +103,26 @@ f = Figure(resolution = (800, 500))
 ax = PolarAxis(f[1, 1], title = "Surface")
 rs = 0:10
 phis = range(0, 2pi, 37)
-cs = [r+cos(4phi) for r in rs, phi in phis]
-p = surface!(ax, 0..10, 0..2pi, cs, shading = false, colormap = :coolwarm)
+cs = [r+cos(4phi) for phi in phis, r in rs]
+p = surface!(ax, 0..2pi, 0..10, cs, shading = false, colormap = :coolwarm)
+ax.gridz[] = 100
 Colorbar(f[2, 1], p, vertical = false, flipaxis = false)
 
 ax = PolarAxis(f[1, 2], title = "Voronoi")
 rs = 1:10
 phis = range(0, 2pi, 37)[1:36]
-cs = [r+cos(4phi) for r in rs, phi in phis]
-p = voronoiplot!(ax, rs, phis, cs, show_generators = false, strokewidth = 0)
-Makie.rlims!(ax, 10.5)
+cs = [r+cos(4phi) for phi in phis, r in rs]
+p = voronoiplot!(ax, phis, rs, cs, show_generators = false, strokewidth = 0)
+rlims!(ax, 0.0, 10.5)
 Colorbar(f[2, 2], p, vertical = false, flipaxis = false)
 
 f
 ```
 \end{examplefigure}
 
+Note that in order to see the grid we need to adjust its depth with `ax.gridz[] = 100` (higher z means lower depth).
+The hard limits for `ax.gridz` are `(-10_000, 10_000)` with `9000` being a soft limit where axis components may order incorrectly.
+
 ## Hiding spines and decorations
 
 For a `PolarAxis` we interpret the outer ring limitting the plotting are as the
@@ -122,24 +175,65 @@ f
 
 ## Interactivity
 
-The `PolarAxis` currently implements zooming by scrolling and allows you to
-reset the view with left control + left mouse button. You can change the key
-combination for resetting the view with the `reset_button` attribute, which
-accepts anything `ispressed` accepts.
+The `PolarAxis` currently implements zooming, translation and resetting.
+Zooming is implemented via scrolling, with `ax.rzoomkey = Keyboard.r` restricting zooming to the radial direction and `ax.thetazoomkey = Keyboard.t` restring to angular zooming.
+You can block zooming in the r-direction by setting `ax.rzoomlock = true` and `ax.thetazoomlock = true` for theta direction.
+Furthermore you can disable zooming from changing just rmin with `ax.fixrmin = true` and adjust its speed with `ax.zoomspeed = 0.1`.
+
+Translations are implemented with mouse drag.
+By default radial translations use `ax.r_translation_button = Mouse.right` and angular translations also use `ax.theta_translation_button = Mouse.right`.
+If `ax.fixrmin = true` translation in the r direction are not allowed.
+If you want to disable one of these interaction you can set corresponding button to `false`.
 
-Note that `PolarAxis` currently does not implement the interaction itnerface
+There is also an interaction for rotating the whole axis using `ax.axis_rotation_button = Keyboard.left_control & Mouse.right` and resetting the axis view uses `ax.reset_button = Keyboard.left_control & Mouse.left`, matching `Axis`.
+You can adjust whether this resets the rotation of the axis with `ax.reset_axis_orientation = false`.
+
+Note that `PolarAxis` currently does not implement the interaction interface
 used by `Axis`.
 
 ## Other Notes
 
 ### Plotting outside a PolarAxis
 
-Currently there is a scatter and poly plot outside the area of the `PolarAxis`
-which clips the content to the relevant area. If you want to draw outside the
-circle limiting the polar axis but still within it's scene area, you will need
+Currently there are two poly plots outside the area of the `PolarAxis`
+which clip the content to the relevant area. If you want to draw outside the
+clip limiting the polar axis but still within it's scene area, you need
 to translate those plots to a z range between `9000` and `10_000` or disable
 clipping via the `clip` attribute.
 
+For reference, the z values used by `PolarAxis` are `po.griddepth[] = 8999` for grid lines, 9000 for the clip polygons, 9001 for spines and 9002 for tick labels.
+
+### Radial Distortion
+
+If you have a plot with a large rmin and rmax over a wide range of angles you will end up with a narrow PolarAxis.
+Consider for example:
+
+\begin{examplefigure}{svg = true}
+```julia
+fig = Figure()
+ax = PolarAxis(fig[1, 1], thetalimits = (0, pi))
+lines!(ax, range(0, pi, length=100), 10 .+ rand(100))
+fig
+```
+\end{examplefigure}
+
+In this case you may want to distort the r-direction to make more of your data visible.
+This can be done by setting `ax.radial_distortion_threshold` to a value between 0 and 1.
+
+\begin{examplefigure}{svg = true}
+```julia
+fig = Figure()
+ax = PolarAxis(fig[1, 1], thetalimits = (0, pi), radial_distortion_threshold = 0.2)
+lines!(ax, range(0, pi, length=100), 10 .+ rand(100))
+fig
+```
+\end{examplefigure}
+
+Internally PolarAxis will check `rmin/rmax` against the set threshold.
+If that ratio exceed the threshold, the polar transform is adjusted to shift all radii by some `r0` such that `(rmin - r0) / rmax - r0) == ax.radial_distortion_threshold`.
+In effect this will hold the inner cutout/clip radius at a fraction of the outer radius.
+Note that at `ax.radial_distortion_threshold >= 1.0` (default) this will never distort your data.
+
 ## Attributes
 
 \attrdocs{PolarAxis}

src/basic_recipes/voronoiplot.jl

@@ -157,7 +157,7 @@ function plot!(p::Voronoiplot{<:Tuple{<:Vector{<:Point{N}}}}) where {N}
     attr[:clip] = map(p, pop!(attr, :clip), p.unbounded_edge_extension_factor,
                               transform_func_obs(p), ps) do bb, ext, tf, ps
         if bb === automatic && tf isa Polar
-            rscaled = maximum(first, ps) * (1 + ext)
+            rscaled = maximum(p -> p[1 + tf.theta_as_x], ps) * (1 + ext)
             return Circle(Point2f(0), rscaled)
         else
             return bb
@@ -168,6 +168,15 @@ function plot!(p::Voronoiplot{<:Tuple{<:Vector{<:Point{N}}}}) where {N}
     return voronoiplot!(p, attr, vorn; transformation=transform)
 end
 
+function data_limits(p::Voronoiplot{<:Tuple{<:Vector{<:Point{N}}}}) where {N}
+    if transform_func(p) isa Polar
+        iter = (to_ndim(Point3f, p, 0f0) for p in p.converted[1][])
+        limits_from_transformed_points(iter)
+    else
+        limits_from_transformed_points(iterate_transformed(p))
+    end
+end
+
 function plot!(p::Voronoiplot{<:Tuple{<:DelTri.VoronoiTessellation}})
     generators_2f = Observable(Point2f[])
     PolyType = typeof(Polygon(Point2f[], [Point2f[]]))