helper functions for scaling

README.md

@@ -1,10 +1,55 @@
 # MakiePublicationTheme
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://kimauth.github.io/MakiePublicationTheme.jl/stable/)
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://kimauth.github.io/MakiePublicationTheme.jl/dev/)
 [![Build Status](https://github.com/kimauth/MakiePublicationTheme.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/kimauth/MakiePublicationTheme.jl/actions/workflows/CI.yml?query=branch%3Amain)
 
 My favourite settings for publication quality [`Makie.jl`](https://docs.makie.org/) plots.
 This theme is for example used in [Auth et. al., 2024](https://doi.org/10.1016/j.euromechsol.2024.105418).
 
+
+The [Makie demofigure for themes](https://docs.makie.org/stable/explanations/theming/predefined_themes) will look as follows:
+```julia
+using MakiePublicationTheme
+using CairoMakie, Random # needed for demofigure
+
+with_theme(publication_theme()) do
+    f = demofigure()
+end
+```
 ![Makie-theme-demofigure for publication theme](/assets/makie_demofigure.png)
+
+# Exporting figures with physical dimensions
+`MakiePublicationTheme.jl` supplies helper functions in order to [match physical figure and
+font sizes](https://docs.makie.org/v0.21/explanations/figure#Matching-figure-and-font-sizes-to-documents)
+when saving figures.
+```julia
+using MakiePublicationTheme
+using CairoMakie, Random
+
+set_theme!(publication_theme())
+update_theme!(fontsize=11) # use fontsize 11 instead of the default fontsize 10 here
+
+size_cm = (12.0, 8.0)
+dpi = 300
+size, px_per_unit = size_pixelgraphic(size_cm, dpi)
+
+# generate figure with correct canvas size
+f = Figure(; size)
+
+# fill the figure with a few things with font sizes
+ax = Axis(f[1,1];
+    xlabel = "xlabel in fontsize 11",
+    ylabel = "ylabel in fontsize 11",
+    title = "My 12cm x 8cm figure",
+    xticks = MultiplesTicks(5, π, "π"),
+    )
+lines!(ax, 0.0:0.1:3π, sin)
+lines!(ax, 0.0:0.1:3π, cos)
+cycle = (color=:color) # cycle over (lineplot) colors instead of inheriting :textcolor
+text!(ax, 3π/4, sin(3π/4); text="sin", align=(:left, :bottom), cycle, fontsize=16)
+text!(ax, 3π/4, cos(3π/4); text="cos", align=(:right, :top), cycle, fontsize=16)
+
+# save figure that will have a resolution of 300dpi at 12cm x 8cm size
+save("my_12x8cm_figure.png", f; px_per_unit)
+```
+![Demofigure for figure + font sizes](/assets/my_12x8cm_figure.png)

src/MakiePublicationTheme.jl

@@ -3,7 +3,9 @@ module MakiePublicationTheme
 using Makie
 
 include("publication_theme.jl")
-
 export publication_theme
 
+include("figure_sizes.jl")
+export size_vectorgraphic, size_pixelgraphic
+
 end

src/figure_sizes.jl

@@ -0,0 +1,73 @@
+"""
+    size_vectorgraphic(size; unit=:cm)
+
+Compute the required figure size and `pt_per_unit` for a given physical size in `:cm` or
+`:inch`. The (physical) font size will be the same as set in the theme, i.e. the default is
+10 pt.
+
+Example:
+```@example
+using MakiePublicationTheme
+using CairoMakie
+
+size_cm = (12.0, 8.0)
+size, pt_per_unit = size_vectorgraphic(size_cm)
+
+f = Figure(; size)
+# lots of plotting here
+save("my_12x8cm_figure.pdf", f; pt_per_unit)
+```
+
+More information about matching figure and font sizes can be found in the
+[Makie documentation](https://docs.makie.org/v0.21/explanations/figure#Matching-figure-and-font-sizes-to-documents). 
+"""
+function size_vectorgraphic(size; unit=:cm)
+    if unit == :cm
+        size_pt = size ./ 2.54 .* 72.0
+    elseif unit == :inch
+        size_pt = size .* 72.0
+    else
+        error("Unknown unit $unit.")
+    end
+    pt_per_unit = 1
+
+    return size_pt, pt_per_unit
+end
+
+"""
+    size_pixelgraphic(size, dpi; unit=:cm)
+
+Compute the required figure size and `px_per_unit` at a resolution of `dpi` dots-per-inch
+and for a given physical size in `:cm` or `:inch`. The (physical) font size will be the same
+as set in the theme, i.e. the default is 10 pt.
+
+Example:
+```@example
+using MakiePublicationTheme
+using CairoMakie
+
+size_cm = (12.0, 8.0)
+dpi = 600
+size, px_per_unit = size_pixelgraphic(size_cm, dpi)
+
+f = Figure(; size)
+# lots of plotting here
+save("my_12x8cm_figure.png", f; px_per_unit)
+```
+
+More information about matching figure and font sizes can be found in the
+[Makie documentation](https://docs.makie.org/v0.21/explanations/figure#Matching-figure-and-font-sizes-to-documents). 
+"""
+function size_pixelgraphic(size, dpi; unit=:cm)
+    if unit == :cm
+        size_inch = size ./ 2.54
+    elseif unit == :inch
+        size_inch = size
+    else
+        error("Unknown unit $unit.")
+    end
+    size_pt = size_inch .* 72.0
+    px_per_unit = first(size_inch) * dpi / first(size_pt)
+
+    return size_pt, px_per_unit
+end

test/figure_size.jl

@@ -0,0 +1,23 @@
+@testset "figure sizes" begin 
+    size_inch = (5, 4)
+    size_cm = size_inch .* 2.54
+    dpi = 600.0
+
+    # vector graphics
+    size_inchbased, pt_per_unit_inchbased = size_vectorgraphic(size_inch; unit=:inch)
+    @test size_inchbased == (360.0, 288.0)
+    @test pt_per_unit_inchbased == 1.0
+
+    size_cmbased, pt_per_unit_cmbased = size_vectorgraphic(size_cm; unit=:cm)
+    @test all(size_cmbased .≈ size_inchbased)
+    @test pt_per_unit_inchbased == 1.0
+
+    # pixel graphics
+    size_inchbased, px_per_unit_inchbased = size_pixelgraphic(size_inch, dpi; unit=:inch)
+    @test size_inchbased == (360.0, 288.0)
+    @test px_per_unit_inchbased == 25/3
+
+    size_cmbased, px_per_unit_cmbased = size_pixelgraphic(size_cm, dpi; unit=:cm)
+    @test all(size_cmbased .≈ size_inchbased)
+    @test px_per_unit_cmbased == 25/3
+end

test/runtests.jl

@@ -3,4 +3,5 @@ using Test
 
 @testset "MakiePublicationTheme.jl" begin
     include("makie_demofigure.jl")
+    include("figure_size.jl")
 end