1.19.0 [skip ci]

* add the plot_title

* Update bbs/plot_title (#3604)

* add the plot_title

* update plot_title for multiple subplots, fix GR warning

Co-authored-by: Simon Christ <SimonChrist@gmx.de>
Co-authored-by: t-bltg <t-bltg@users.noreply.github.com>

* Update plot_title (#3608)

* add the plot_title

* update plot_title for multiple subplots, fix GR warning

* update plot_title

* consistency with _subplot_defaults

Co-authored-by: Simon Christ <SimonChrist@gmx.de>
Co-authored-by: t-bltg <t-bltg@users.noreply.github.com>

* custom implementation for pgfplotsx backend

* remove `@show`

* remove superfluous plot_titleindex

Co-authored-by: t-bltg <13423344+t-bltg@users.noreply.github.com>
Co-authored-by: t-bltg <t-bltg@users.noreply.github.com>

Project.toml

@@ -1,7 +1,7 @@
 name = "Plots"
 uuid = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 author = ["Tom Breloff (@tbreloff)"]
-version = "1.18.1"
+version = "1.19.0"
 
 [deps]
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"

src/arg_desc.jl

@@ -53,7 +53,8 @@ const _arg_desc = KW(
 :colorbar_entry              => "Bool.  Include this series in the color bar?  Set to `false` to exclude.",
 
 # plot args
-:plot_title                  => "String. Title for the whole plot (not the subplots) (Note: Not currently implemented)",
+:plot_title                  => "String. Title for the whole plot (not the subplots)",
+:plot_titlevspan             => "Number in [0,1]. Vertical span of the whole plot title (fraction of the plot height)",
 :background_color            => "Color Type.  Base color for all backgrounds.",
 :background_color_outside    => "Color Type or `:match` (matches `:background_color`).  Color outside the plot area(s)",
 :foreground_color            => "Color Type.  Base color for all foregrounds.",
@@ -115,7 +116,7 @@ const _arg_desc = KW(
 :colorbar_formatter          => "Function, :scientific, :plain or :auto. A method which converts a number to a string for tick labeling.",
 :legendfont                  => "Font. Font of legend items.",
 :legendtitlefont             => "Font. Font of the legend title.",
-:annotations                 => "(x,y,text) tuple(s).  Can be a single tuple or a list of them.  Text can be String or PlotText (created with `text(args...)`)  Add one-off text annotations at the x,y coordinates.",
+:annotations                 => "(x,y,text) tuple(s).  Can be a single tuple or a list of them.  Text can be String, PlotText (created with `text(args...)`), or a tuple of arguments to `text` (e.g., `(\"Label\", 8, :red, :top)`).  Add one-off text annotations at the x,y coordinates.",
 :annotationfontfamily        => "String or Symbol. Font family of annotations.",
 :annotationfontsize          => "Integer. Font pointsize of annotations.",
 :annotationhalign            => "Symbol. horizontal alignment of annotations, :hcenter, :left, :right or :center.",

src/args.jl

@@ -331,13 +331,15 @@ const _series_defaults = KW(
 
 const _plot_defaults = KW(
     :plot_title                  => "",
+    :plot_titleindex             => 0,
     :plot_titlefontsize          => 16,
-    :plot_title_location         => :center,           # also :left or :right
+    :plot_titlelocation          => :center,           # also :left or :right
     :plot_titlefontfamily        => :match,
     :plot_titlefonthalign        => :hcenter,
     :plot_titlefontvalign        => :vcenter,
     :plot_titlefontrotation      => 0.0,
     :plot_titlefontcolor         => :match,
+    :plot_titlevspan             => 0.05,              # vertical span of the plot title, here 5%
     :background_color            => colorant"white",   # default for all backgrounds,
     :background_color_outside    => :match,            # background outside grid,
     :foreground_color            => :auto,             # default for all foregrounds, and title color,

src/backends.jl

@@ -353,6 +353,7 @@ const _gr_seriestype = [
     :scatter3d,
     :surface,
     :wireframe,
+    :mesh3d,
     :volume,
     :shape,
 ]

src/backends/gr.jl

@@ -524,7 +524,7 @@ function gr_draw_colorbar(cbar::GRColorbar, sp::Subplot, clims, viewport_plotare
         levels = _cbar_unique(contour_levels.(series, Ref(clims)), "levels")
         # GR implicitly uses the maximal z value as the highest level
         if levels[end] < clims[2]
-            @warn("GR: highest contour level less than maximal z value is not supported.")
+            @warn "GR: highest contour level less than maximal z value is not supported."
             # replace levels, rather than assign to levels[end], to ensure type
             # promotion in case levels is an integer array
             levels = [levels[1:end-1]; clims[2]]
@@ -1682,7 +1682,7 @@ function gr_add_series(sp, series)
         end
     elseif st === :contour
         gr_draw_contour(series, x, y, z, clims)
-    elseif st in (:surface, :wireframe)
+    elseif st in (:surface, :wireframe, :mesh3d)
         gr_draw_surface(series, x, y, z, clims)
     elseif st === :volume
         sp[:legend] = :none
@@ -1838,7 +1838,7 @@ function gr_draw_contour(series, x, y, z, clims)
     h = gr_contour_levels(series, clims)
     if series[:fillrange] !== nothing
         if series[:fillcolor] != series[:linecolor] && !is_lc_black
-            @warn("GR: filled contour only supported with black contour lines")
+            @warn "GR: filled contour only supported with black contour lines"
         end
         GR.contourf(x, y, h, z, series[:contour_labels] == true ? 1 : 0)
     else
@@ -1849,7 +1849,8 @@ end
 
 function gr_draw_surface(series, x, y, z, clims)
     e_kwargs = series[:extra_kwargs]
-    if series[:seriestype] === :surface
+    st = series[:seriestype]
+    if st === :surface
         fillalpha = get_fillalpha(series)
         fillcolor = get_fillcolor(series)
         # NOTE: setting nx = 0 or ny = 0 disables GR.gridit interpolation
@@ -1864,9 +1865,42 @@ function gr_draw_surface(series, x, y, z, clims)
         else
             GR.gr3.surface(x, y, z, d_opt)
         end
-    else  # wireframe
+    elseif st === :wireframe
         GR.setfillcolorind(0)
         GR.surface(x, y, z, get(e_kwargs, :display_option, GR.OPTION_FILLED_MESH))
+    elseif st === :mesh3d
+        @warn "GR: mesh3d is experimental (no face colors)"
+        conn = series[:connections]
+        if typeof(conn) <: Tuple{Array, Array, Array}
+            ci, cj, ck = conn
+            if !(length(ci) == length(cj) == length(ck))
+                throw(ArgumentError("Argument connections must consist of equally sized arrays."))
+            end
+        else
+            throw(ArgumentError("Argument connections has to be a tuple of three arrays."))
+        end
+        X = zeros(eltype(x), 4length(ci))
+        Y = zeros(eltype(y), 4length(cj))
+        Z = zeros(eltype(z), 4length(ck))
+        @inbounds for I ∈ 1:length(ci)
+            i = ci[I] + 1  # connections are 0-based
+            j = cj[I] + 1
+            k = ck[I] + 1
+            m = 4(I - 1) + 1; n = m + 1; o = m + 2; p = m + 3
+            X[m] = X[p] = x[i]
+            Y[m] = Y[p] = y[i]
+            Z[m] = Z[p] = z[i]
+            X[n] = x[j]
+            Y[n] = y[j]
+            Z[n] = z[j]
+            X[o] = x[k]
+            Y[o] = y[k]
+            Z[o] = z[k]
+        end
+        gr_set_line(get_linewidth(series), get_linestyle(series), get_linecolor(series), series)
+        GR.polyline3d(X, Y, Z)
+    else
+        throw(ArgumentError("Not handled !"))    
     end
 end
 

src/backends/pgfplotsx.jl

@@ -118,11 +118,22 @@ function (pgfx_plot::PGFPlotsXPlot)(plt::Plot{PGFPlotsXBackend})
         end
 
         for sp in plt.subplots
-            bb1 = sp.plotarea
             bb2 = bbox(sp)
+            dx, dy = bb2.x0
+            sp_width = width(bb2)
+            sp_height = height(bb2)
+            if sp[:subplot_index] == plt[:plot_titleindex]
+                x = dx + sp_width / 2 - 10mm # FIXME: get rid of magic constant
+                y = dy + sp_height / 2
+                pgfx_add_annotation!(the_plot, x, y, PlotText(plt[:plot_title], plottitlefont(plt)), pgfx_thickness_scaling(plt);
+                    cs = "",
+                    options = PGFPlotsX.Options("anchor" => "center")
+                )
+                continue
+            end
+
             sp_width = width(bb2)
             sp_height = height(bb2)
-            dx, dy = bb2.x0
             lpad = leftpad(sp) + sp[:left_margin]
             rpad = rightpad(sp) + sp[:right_margin]
             tpad = toppad(sp) + sp[:top_margin]
@@ -131,7 +142,6 @@ function (pgfx_plot::PGFPlotsXPlot)(plt::Plot{PGFPlotsXBackend})
             dy += tpad
             axis_height = sp_height - (tpad + bpad)
             axis_width = sp_width - (rpad + lpad)
-
             title_cstr = plot_color(sp[:titlefontcolor])
             title_a = alpha(title_cstr)
             title_loc = sp[:titlelocation]
@@ -889,7 +899,7 @@ function pgfx_framestyle(style::Symbol)
         return style
     else
         default_style = get((semi = :box,), style, :axes)
-        @warn( "Framestyle :$style is not (yet) supported by the PGFPlotsX backend. :$default_style was cosen instead.",)
+        @warn "Framestyle :$style is not (yet) supported by the PGFPlotsX backend. :$default_style was chosen instead."
         default_style
     end
 end
@@ -999,24 +1009,27 @@ function pgfx_marker(plotattributes, i = 1)
     )
 end
 
-function pgfx_add_annotation!(o, x, y, val, thickness_scaling = 1)
+function pgfx_add_annotation!(o, x, y, val, thickness_scaling = 1; cs = "axis cs:", options = PGFPlotsX.Options())
     # Construct the style string.
     cstr = val.font.color
     a = alpha(cstr)
     push!(
         o,
-        [
+        join([
             "\\node",
-            PGFPlotsX.Options(
-                get((center = "", left = "right", right = "left"), val.font.halign, "") =>
-                    nothing,
-                "color" => cstr,
-                "draw opacity" => convert(Float16, a),
-                "rotate" => val.font.rotation,
-                "font" => pgfx_font(val.font.pointsize, thickness_scaling),
-            ),
-            " at (axis cs:$x, $y) {$(val.str)};",
-        ],
+            sprint(PGFPlotsX.print_tex, merge(
+                PGFPlotsX.Options(
+                    get((hcenter = "", left = "right", right = "left"), val.font.halign, "") =>
+                        nothing,
+                    "color" => cstr,
+                    "draw opacity" => convert(Float16, a),
+                    "rotate" => val.font.rotation,
+                    "font" => pgfx_font(val.font.pointsize, thickness_scaling),
+                ),
+                options
+            )),
+            string(" at (", cs, x, ",", y, ") {", val.str, "};"),
+        ]),
     )
 end
 

src/examples.jl

@@ -370,10 +370,19 @@ const _examples = PlotExample[
         "Annotations",
         """
         The `annotations` keyword is used for text annotations in data-coordinates.  Pass in a
-        tuple (x,y,text) or a vector of annotations.  `annotate!(ann)` is shorthand for `plot!(;
-        annotation=ann)`.  Series annotations are used for annotating individual data points.
-        They require only the annotation... x/y values are computed.  A `PlotText` object can be
-        build with the method `text(string, attr...)`, which wraps font and color attributes.
+        tuple `(x, y, text)`, or a vector of annotations, each of which is a tuple of `x`, `y`
+        and `text`.
+        `text` may be a simple `String`, or a `PlotText` object, which can be
+        built with the method `text(string, attrs...)`.
+        This wraps font and color attributes and allows you to set text styling.
+        `text` may also be a tuple `(string, attrs...)` of arguments which are passed
+        to `Plots.text`.
+
+        `annotate!(ann)` is shorthand for `plot!(; annotation=ann)`.
+
+        Series annotations are used for annotating individual data points.
+        They require only the annotation; x/y values are computed.  Series annotations
+        require either plain `String`s or `PlotText` objects.
         """,
         [
             :(
@@ -385,11 +394,11 @@ const _examples = PlotExample[
                         leg = false,
                     )
                     annotate!([
-                        (5, y[5], Plots.text("this is #5", 16, :red, :center)),
+                        (5, y[5], ("this is #5", 16, :red, :center)),
                         (
                             10,
                             y[10],
-                            Plots.text("this is #10", :right, 20, "courier"),
+                            ("this is #10", :right, 20, "courier"),
                         ),
                     ])
                     scatter!(
@@ -998,33 +1007,37 @@ const _examples = PlotExample[
         end]
     ),
     PlotExample( # 47
-	"Mesh3d",
-	"""
-	Allows to plot arbitrary 3d meshes. If only x,y,z are given the mesh is generated automatically.
-	You can also specify the connections using the connections keyword.
-    The connections are specified using a tuple of vectors. Each vector contains the 0-based indices of one point of a triangle,
-	such that elements at the same position of these vectors form a triangle.
-	""",
-	[
-		:(
-		  begin
-			# specify the vertices
-			x=[0, 1, 2, 0]
-			y=[0, 0, 1, 2]
-			z=[0, 2, 0, 1]
+        "Mesh3d",
+        """
+        Allows to plot arbitrary 3d meshes. If only x,y,z are given the mesh is generated automatically.
+        You can also specify the connections using the connections keyword.
+        The connections are specified using a tuple of vectors. Each vector contains the 0-based indices of one point of a triangle,
+        such that elements at the same position of these vectors form a triangle.
+        """,
+        [
+            :(
+                begin
+                    # specify the vertices
+                    x=[0, 1, 2, 0]
+                    y=[0, 0, 1, 2]
+                    z=[0, 2, 0, 1]
 
-			# specify the triangles
-			# every column is one triangle,
-			# where the values denote the indices of the vertices of the triangle
-			i=[0, 0, 0, 1]
-			j=[1, 2, 3, 2]
-			k=[2, 3, 1, 3]
+                    # specify the triangles
+                    # every column is one triangle,
+                    # where the values denote the indices of the vertices of the triangle
+                    i=[0, 0, 0, 1]
+                    j=[1, 2, 3, 2]
+                    k=[2, 3, 1, 3]
 
-			# the four triangles gives above give a tetrahedron
-			mesh3d(x,y,z;connections=(i,j,k))
-		  end
-		),
-	],
+                    # the four triangles gives above give a tetrahedron
+                    mesh3d(
+                        x, y, z; connections=(i, j, k),
+                        title="triangles", xlabel="x", ylabel="y", zlabel="z",
+                        legend=:none, margin=2Plots.mm
+                    )
+                end
+            ),
+        ],
     ),
     PlotExample( # 48
         "Vectors of markershapes and segments",
@@ -1214,7 +1227,7 @@ const _examples = PlotExample[
 # Some constants for PlotDocs and PlotReferenceImages
 _animation_examples = [2, 31]
 _backend_skips = Dict(
-    :gr => [25, 30, 47],
+    :gr => [25, 30],
     :pyplot => [2, 25, 30, 31, 47, 49, 55],
     :plotlyjs => [2, 21, 24, 25, 30, 31, 49, 51, 55],
     :plotly => [2, 21, 24, 25, 30, 31, 49, 50, 51, 55],
@@ -1228,6 +1241,8 @@ _backend_skips = Dict(
         49, # polar heatmap
         51, # image with custom axes
     ],
+    :inspectdr => [4, 6, 10, 22, 24, 28, 30, 38, 43, 45, 47, 48, 49, 50, 51, 55],
+    :unicodeplots => [6, 10, 22, 24, 28, 38, 43, 45, 47, 49, 50, 51, 55],
 )
 
 

src/pipeline.jl

@@ -262,6 +262,7 @@ function _subplot_setup(plt::Plot, plotattributes::AKW, kw_list::Vector{KW})
         sp_attrs[sp] = attr
     end
 
+    _add_plot_title!(plt)
     # override subplot/axis args.  `sp_attrs` take precendence
     for (idx, sp) in enumerate(plt.subplots)
         attr = if !haskey(plotattributes, :subplot) || plotattributes[:subplot] == idx
@@ -274,12 +275,35 @@ function _subplot_setup(plt::Plot, plotattributes::AKW, kw_list::Vector{KW})
 
     # do we need to link any axes together?
     link_axes!(plt.layout, plt[:link])
+    return nothing
 end
 
 function series_idx(kw_list::AVec{KW}, kw::AKW)
     Int(kw[:series_plotindex]) - Int(kw_list[1][:series_plotindex]) + 1
 end
 
+function _add_plot_title!(plt)
+    plot_title = plt[:plot_title]
+    if plot_title != ""
+        the_layout = plt.layout
+        vspan = plt[:plot_titlevspan]
+        plt.layout = grid(2, 1, heights=(vspan, 1 - vspan))
+        plt.layout.grid[1, 1] = subplot = Subplot(plt.backend, parent=plt.layout[1, 1])
+        plt.layout.grid[2, 1] = the_layout
+        subplot.plt = plt
+        # propagate arguments plt[:plot_titleXXX] --> subplot[:titleXXX]
+        for sym ∈ filter(x -> startswith(string(x), "plot_title"), keys(_plot_defaults))
+            subplot[Symbol(string(sym)[length("plot_") + 1:end])] = plt[sym]
+        end
+        plt[:force_minpad] = nothing, 0px, nothing, 0px
+        subplot[:subplot_index] = last(plt.subplots)[:subplot_index] + 1
+        plt[:plot_titleindex] = subplot[:subplot_index]
+        subplot[:framestyle] = :none
+        subplot[:margin] = 0px
+        push!(plt.subplots, subplot)
+    end
+    return nothing
+end
 
 ## Series recipes
 

src/plot.jl

@@ -160,6 +160,7 @@ function plot!(plt1::Plot, plt2::Plot, plts_tail::Plot...; kw...)
             cmdidx += 1
         end
     end
+    _add_plot_title!(plt)
 
     # first apply any args for the subplots
     for (idx,sp) in enumerate(plt.subplots)
@@ -225,6 +226,16 @@ function prepare_output(plt::Plot)
         _update_min_padding!(sp)
     end
 
+    # spedific to :plot_title see _add_plot_title!
+    force_minpad = get(plt, :force_minpad, ())
+    if !isempty(force_minpad)
+        for i ∈ eachindex(plt.layout.grid)
+            plt.layout.grid[i].minpad = Tuple(
+                i === nothing ? j : i for (i, j) ∈ zip(force_minpad, plt.layout.grid[i].minpad)
+            )
+        end
+    end
+
     # now another pass down, to update the bounding boxes
     update_child_bboxes!(plt.layout)
 

src/shorthands.jl

@@ -453,12 +453,14 @@ Add annotations to an existing plot.
 # Arguments
 
 - `anns`: An `AbstractVector` of tuples of the form `(x,y,text)`. The `text` object
-          can be a `String` or `PlotText`.
+          can be a `String`, `PlotText` PlotText (created with `text(args...)`),
+          or a tuple of arguments to `text` (e.g., `("Label", 8, :red, :top)`).
 
 # Example
 ```julia-repl
 julia> plot(1:10)
 julia> annotate!([(7,3,"(7,3)"),(3,7,text("hey", 14, :left, :top, :green))])
+julia> annotate!([(4, 4, ("More text", 8, 45.0, :bottom, :red))])
 ```
 """
 annotate!(anns...; kw...)             = plot!(; annotation = anns, kw...)