Merge branch 'master' into bja/pkgcompfonts

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 ## [Unreleased]
+- CairoMakie: Add argument `pdf_version` to restrict the PDF version when saving a figure as a PDF [#3845](https://github.com/MakieOrg/Makie.jl/pull/3845).
 
 - Improved relocatability with PackageCompiler [#3882](https://github.com/MakieOrg/Makie.jl/pull/3882)
 
@@ -510,7 +511,8 @@ All other changes are collected [in this PR](https://github.com/MakieOrg/Makie.j
 [Unreleased]: https://github.com/MakieOrg/Makie.jl/compare/v0.21.2...HEAD
 [0.21.2]: https://github.com/MakieOrg/Makie.jl/compare/v0.21.0...v0.21.2
 [0.21.1]: https://github.com/MakieOrg/Makie.jl/compare/v0.21.0...v0.21.1
-[0.21.0]: https://github.com/MakieOrg/Makie.jl/compare/v0.20.9...v0.21.0
+[0.21.0]: https://github.com/MakieOrg/Makie.jl/compare/v0.20.10...v0.21.0
+[0.20.10]: https://github.com/MakieOrg/Makie.jl/compare/v0.20.9...v0.20.10
 [0.20.9]: https://github.com/MakieOrg/Makie.jl/compare/v0.20.8...v0.20.9
 [0.20.8]: https://github.com/MakieOrg/Makie.jl/compare/v0.20.7...v0.20.8
 [0.20.7]: https://github.com/MakieOrg/Makie.jl/compare/v0.20.6...v0.20.7
@@ -556,3 +558,4 @@ All other changes are collected [in this PR](https://github.com/MakieOrg/Makie.j
 [0.15.3]: https://github.com/MakieOrg/Makie.jl/compare/v0.15.2...v0.15.3
 [0.15.2]: https://github.com/MakieOrg/Makie.jl/compare/v0.15.1...v0.15.2
 [0.15.1]: https://github.com/MakieOrg/Makie.jl/compare/v0.15.0...v0.15.1
+[0.15.0]: https://github.com/MakieOrg/Makie.jl/compare/v0.14.2...v0.15.0

CairoMakie/src/cairo-extension.jl

@@ -74,3 +74,10 @@ function get_render_type(surface::Cairo.CairoSurface)
     typ == Cairo.CAIRO_SURFACE_TYPE_IMAGE && return IMAGE
     return IMAGE # By default assume that the render type is IMAGE
 end
+
+function restrict_pdf_version!(surface::Cairo.CairoSurface, v::Integer)
+    @assert surface.ptr != C_NULL
+    0 ≤ v ≤ 3 || throw(ArgumentError("version must be 0, 1, 2, or 3 (received $v)"))
+    ccall((:cairo_pdf_surface_restrict_to_version, Cairo.libcairo), Nothing,
+          (Ptr{UInt8}, Int32), surface.ptr, v)
+end

CairoMakie/src/screen.jl

@@ -68,6 +68,15 @@ function surface_from_output_type(type::RenderType, io, w, h)
     end
 end
 
+@enum PDFVersion PDFv14 PDFv15 PDFv16 PDFv17
+function pdfversion(version::AbstractString)
+    version == "1.4" && return PDFv14
+    version == "1.5" && return PDFv15
+    version == "1.6" && return PDFv16
+    version == "1.7" && return PDFv17
+    throw(ArgumentError("PDF version must be one of '1.4', '1.5', '1.6', '1.7' (received '$version')"))
+end
+
 """
 Supported options: `[:best => Cairo.ANTIALIAS_BEST, :good => Cairo.ANTIALIAS_GOOD, :subpixel => Cairo.ANTIALIAS_SUBPIXEL, :none => Cairo.ANTIALIAS_NONE]`
 """
@@ -85,13 +94,22 @@ to_cairo_antialias(aa::Int) = aa
 * `pt_per_unit = 0.75`
 * `antialias::Union{Symbol, Int} = :best`: antialias modus Cairo uses to draw. Applicable options: `[:best => Cairo.ANTIALIAS_BEST, :good => Cairo.ANTIALIAS_GOOD, :subpixel => Cairo.ANTIALIAS_SUBPIXEL, :none => Cairo.ANTIALIAS_NONE]`.
 * `visible::Bool`: if true, a browser/image viewer will open to display rendered output.
+* `pdf_version::String = nothing`: the version of output PDFs. Applicable options are `"1.4"`, `"1.5"`, `"1.6"`, `"1.7"`, or `nothing`, which leaves the PDF version unrestricted.
 """
 struct ScreenConfig
     px_per_unit::Float64
     pt_per_unit::Float64
     antialias::Symbol
     visible::Bool
     start_renderloop::Bool # Only used to satisfy the interface for record using `Screen(...; start_renderloop=false)` for GLMakie
+    pdf_version::Union{Nothing, PDFVersion}
+
+    function ScreenConfig(px_per_unit::Real, pt_per_unit::Real,
+            antialias::Symbol, visible::Bool, start_renderloop::Bool,
+            pdf_version::Union{Nothing, AbstractString})
+        v = isnothing(pdf_version) ? nothing : pdfversion(pdf_version)
+        new(px_per_unit, pt_per_unit, antialias, visible, start_renderloop, v)
+    end
 end
 
 function device_scaling_factor(rendertype, sc::ScreenConfig)
@@ -213,6 +231,11 @@ function apply_config!(screen::Screen, config::ScreenConfig)
     aa = to_cairo_antialias(config.antialias)
     Cairo.set_antialias(context, aa)
     set_miter_limit(context, 2.0)
+
+    if get_render_type(surface) === PDF && !isnothing(config.pdf_version)
+        restrict_pdf_version!(surface, Int(config.pdf_version))
+    end
+
     screen.antialias = aa
     screen.device_scaling_factor = dsf
     screen.config = config
@@ -285,6 +308,11 @@ function Screen(scene::Scene, config::ScreenConfig, surface::Cairo.CairoSurface)
     aa = to_cairo_antialias(config.antialias)
     Cairo.set_antialias(ctx, aa)
     set_miter_limit(ctx, 2.0)
+
+    if get_render_type(surface) === PDF && !isnothing(config.pdf_version)
+        restrict_pdf_version!(surface, Int(config.pdf_version))
+    end
+
     return Screen{get_render_type(surface)}(scene, surface, ctx, dsf, aa, config.visible, config)
 end
 

CairoMakie/test/runtests.jl

@@ -198,3 +198,37 @@ functions = [:volume, :volume!, :uv_mesh]
     missing_images, scores = ReferenceTests.record_comparison(recording_dir)
     ReferenceTests.test_comparison(scores; threshold = 0.05)
 end
+
+@testset "PdfVersion" begin
+    @test CairoMakie.pdfversion("1.4") === CairoMakie.PDFv14
+    @test CairoMakie.pdfversion("1.5") === CairoMakie.PDFv15
+    @test CairoMakie.pdfversion("1.6") === CairoMakie.PDFv16
+    @test CairoMakie.pdfversion("1.7") === CairoMakie.PDFv17
+    @test_throws ArgumentError CairoMakie.pdfversion("foo")
+end
+
+@testset "restrict PDF version" begin
+    magic_number(filename) = open(filename) do f
+        return String(read(f, sizeof("%PDF-X.Y")))
+    end
+
+    filename = "$(tempname()).pdf"
+
+    try
+        save(filename, Figure(), pdf_version=nothing)
+        @test startswith(magic_number(filename), "%PDF-")
+    finally
+        rm(filename)
+    end
+
+    for version in ["1.4", "1.5", "1.6", "1.7"]
+        try
+            save(filename, Figure(), pdf_version=version)
+            @test magic_number(filename) == "%PDF-$version"
+        finally
+            rm(filename)
+        end
+    end
+
+    @test_throws ArgumentError save(filename, Figure(), pdf_version="foo")
+end

MakieCore/src/basic_plots.jl

@@ -269,9 +269,9 @@ Available algorithms are:
     ) begin
     "Sets the volume algorithm that is used."
     algorithm = :mip
-    "Sets the range of values picked up by the IsoValue algorithm."
-    isovalue = 0.5
     "Sets the target value for the IsoValue algorithm."
+    isovalue = 0.5
+    "Sets the range of values picked up by the IsoValue algorithm."
     isorange = 0.05
     "Sets whether the volume data should be sampled with interpolation."
     interpolate = true
@@ -317,13 +317,26 @@ Creates a connected line plot for each element in `(x, y, z)`, `(x, y)` or `posi
     color = @inherit linecolor
     "Sets the width of the line in screen units"
     linewidth = @inherit linewidth
-    "Sets the pattern of the line e.g. `:solid`, `:dot`, `:dashdot`. For custom patterns look at `Linestyle(Number[...])`"
+    """
+    Sets the dash pattern of the line. Options are `:solid` (equivalent to `nothing`), `:dot`, `:dash`, `:dashdot` and `:dashdotdot`.
+    These can also be given in a tuple with a gap style modifier, either `:normal`, `:dense` or `:loose`.
+    For example, `(:dot, :loose)` or `(:dashdot, :dense)`.
+    
+    For custom patterns have a look at [`Makie.Linestyle`](@ref).
+    """
     linestyle = nothing
-    "Sets the type of linecap used, i.e. :butt (flat with no extrusion), :square (flat with 0.5 linewidth extrusion) or :round."
+    """
+    Sets the type of line cap used. Options are `:butt` (flat without extrusion),
+    `:square` (flat with half a linewidth extrusion) or `:round`.
+    """
     linecap = @inherit linecap
-    "Controls whether line joints are rounded (:round) or not (:miter)."
+    """
+    Controls the rendering at corners. Options are `:miter` for sharp corners,
+    `:bevel` for "cut off" corners, and `:round` for rounded corners. If the corner angle
+    is below `miter_limit`, `:miter` is equivalent to `:bevel` to avoid long spikes.
+    """
     joinstyle = @inherit joinstyle
-    "Sets the minimum inner joint angle below which miter joints truncate. See also `Makie.miter_distance_to_angle()`"
+    "Sets the minimum inner join angle below which miter joins truncate. See also `Makie.miter_distance_to_angle`."
     miter_limit = @inherit miter_limit
     "Sets which attributes to cycle when creating multiple plots."
     cycle = [:color]
@@ -345,7 +358,13 @@ Plots a line for each pair of points in `(x, y, z)`, `(x, y)`, or `positions`.
     color = @inherit linecolor
     "Sets the width of the line in pixel units"
     linewidth = @inherit linewidth
-    "Sets the pattern of the line e.g. `:solid`, `:dot`, `:dashdot`. For custom patterns look at `Linestyle(Number[...])`"
+    """
+    Sets the dash pattern of the line. Options are `:solid` (equivalent to `nothing`), `:dot`, `:dash`, `:dashdot` and `:dashdotdot`.
+    These can also be given in a tuple with a gap style modifier, either `:normal`, `:dense` or `:loose`.
+    For example, `(:dot, :loose)` or `(:dashdot, :dense)`.
+    
+    For custom patterns have a look at [`Makie.Linestyle`](@ref).
+    """
     linestyle = nothing
     "Sets the type of linecap used, i.e. :butt (flat with no extrusion), :square (flat with 1 linewidth extrusion) or :round."
     linecap = @inherit linecap
@@ -594,7 +613,13 @@ Plots polygons, which are defined by
     strokecolormap = @inherit colormap
     "Sets the width of the outline."
     strokewidth = @inherit patchstrokewidth
-    "Sets the pattern of the line (e.g. `:solid`, `:dot`, `:dashdot`)"
+    """
+    Sets the dash pattern of the line. Options are `:solid` (equivalent to `nothing`), `:dot`, `:dash`, `:dashdot` and `:dashdotdot`.
+    These can also be given in a tuple with a gap style modifier, either `:normal`, `:dense` or `:loose`.
+    For example, `(:dot, :loose)` or `(:dashdot, :dense)`.
+    
+    For custom patterns have a look at [`Makie.Linestyle`](@ref).
+    """
     linestyle = nothing
     linecap = @inherit linecap
     joinstyle = @inherit joinstyle
@@ -620,6 +645,31 @@ Draws a wireframe, either interpreted as a surface or as a mesh.
     depth_shift = -1f-5
 end
 
+"""
+    arrows(points, directions; kwargs...)
+    arrows(x, y, u, v)
+    arrows(x::AbstractVector, y::AbstractVector, u::AbstractMatrix, v::AbstractMatrix)
+    arrows(x, y, z, u, v, w)
+    arrows(x, y, [z], f::Function)
+
+Plots arrows at the specified points with the specified components.
+`u` and `v` are interpreted as vector components (`u` being the x
+and `v` being the y), and the vectors are plotted with the tails at
+`x`, `y`.
+
+If `x, y, u, v` are `<: AbstractVector`, then each 'row' is plotted
+as a single vector.
+
+If `u, v` are `<: AbstractMatrix`, then `x` and `y` are interpreted as
+specifications for a grid, and `u, v` are plotted as arrows along the
+grid.
+
+`arrows` can also work in three dimensions.
+
+If a `Function` is provided in place of `u, v, [w]`, then it must accept
+a `Point` as input, and return an appropriately dimensioned `Point`, `Vec`,
+or other array-like output.
+"""
 @recipe Arrows (points, directions) begin
     "Sets the color of arrowheads and lines. Can be overridden separately using `linecolor` and `arrowcolor`."
     color = :black

docs/.gitignore

@@ -3,3 +3,5 @@ __site/
 node_modules/
 package-lock.json
 news.md
+src/changelog.md
+build/

docs/Project.toml

@@ -11,8 +11,8 @@ DelaunayTriangulation = "927a84f5-c5f4-47a5-9785-b46e178433df"
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
-Franklin = "713c75ef-9fc9-4b05-94a9-213340da978e"
 GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
 Gumbo = "708ec375-b3d6-5a57-a7ce-8257bf98657a"
@@ -27,6 +27,3 @@ Observables = "510215fc-4207-5dde-b226-833fc4488ee2"
 RPRMakie = "22d9f318-5e34-4b44-b769-6e3734a732a6"
 RadeonProRender = "27029320-176d-4a42-b57d-56729d2ad457"
 WGLMakie = "276b4fcb-3e11-5398-bf8b-a0c2d153d008"
-
-[compat]
-Documenter = "<1"