feat: LaTeX and Typst text handlers for Makie's text_handler hook

Project.toml

@@ -19,19 +19,21 @@ tectonic_jll = "d7dd28d6-a5e6-559c-9131-7eb760cdacc5"
 
 [weakdeps]
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 
 [extensions]
 MakieTeXCairoMakieExt = "CairoMakie"
+MakieTeXGLMakieExt = "GLMakie"
 
 [compat]
 Cairo = "1.0.5"
-CairoMakie = "0.12.2"
+CairoMakie = "0.12.2, 0.16"
 Colors = "0.9, 0.10, 0.11, 0.12"
 DocStringExtensions = "0.8, 0.9"
 Ghostscript_jll = "9"
 Glib_jll = "2"
 LaTeXStrings = "1"
-Makie = "0.21.2"
+Makie = "0.21.2, 0.25"
 Poppler_jll = "21.9, 22, 23"
 Rsvg = "1"
 julia = "1.9"

ext/MakieTeXCairoMakieExt.jl

@@ -2,7 +2,6 @@ module MakieTeXCairoMakieExt
 
 using CairoMakie, MakieTeX
 using Makie
-using Makie.MakieCore
 using Poppler_jll
 using Cairo
 using Colors
@@ -21,11 +20,39 @@ end
 CairoMakie.cairo_scatter_marker(v::AbstractArray{<: MakieTeX.AbstractDocument}) = CairoMakie.cairo_scatter_marker.(v)
 CairoMakie.cairo_scatter_marker(v::NTuple{N, <: MakieTeX.AbstractDocument}) where N = CairoMakie.cairo_scatter_marker.(v)
 
+# Vector-render a cached PDF (or TEX/Typst, which both wrap a PDF page) as a
+# scatter marker. Mirrors CairoMakie's `Matrix{<:Colorant}` dispatch in its
+# transform stack, but hands the page to Poppler, which renders content
+# directly into the Cairo context — no raster intermediate, no resampling,
+# hairlines stay crisp.
+function CairoMakie.draw_marker(
+        ctx, marker::Union{MakieTeX.CachedPDF, MakieTeX.CachedTEX, MakieTeX.CachedTypst}, pos,
+        strokecolor #= unused =#, strokewidth #= unused =#, mat
+    )
+    w, h = marker.dims
+    document = MakieTeX.update_handle!(marker)
+    page = ccall(
+        (:poppler_document_get_page, Poppler_jll.libpoppler_glib),
+        Ptr{Cvoid}, (Ptr{Cvoid}, Cint), document, marker.doc.page
+    )
+    Cairo.translate(ctx, pos[1], pos[2])
+    CairoMakie.cairo_transform(ctx, mat)
+    Cairo.scale(ctx, 1.0 / w, 1.0 / h)
+    Cairo.translate(ctx, -w / 2, -h / 2)
+    ccall(
+        (:poppler_page_render, Poppler_jll.libpoppler_glib),
+        Cvoid, (Ptr{Cvoid}, Ptr{Cvoid}), page, ctx.ptr
+    )
+    return
+end
+
 # # Teximg
 
 # Override `is_cairomakie_atomic_plot` to allow `TeXImg` to remain a unit,
 # instead of auto-decomposing into its component scatter plot.
-CairoMakie.is_cairomakie_atomic_plot(plot::TeXImg) = true
+# Disabled while bringing MakieTeX up against Makie >= 0.25 — the scatter
+# child plot of the TeXImg recipe handles rendering on its own there.
+# CairoMakie.is_cairomakie_atomic_plot(plot::TeXImg) = true
 
 # # Scatter markers
 

ext/MakieTeXGLMakieExt.jl

@@ -1,10 +1,37 @@
 module MakieTeXGLMakieExt
-#=
-This extension tells GLMakie how to rasterize a cached document, if it is required.
-=#
+
+# Rasterize cached LaTeX/PDF documents into a Matrix{ARGB32} so GLMakie's
+# scatter marker pipeline can upload them as a GPU texture. CairoMakie has
+# its own native vector dispatch (see MakieTeXCairoMakieExt) and does NOT
+# go through this hook, so this extension only affects GL/WGL-style
+# backends and doesn't compromise CairoMakie's vector quality.
+
 using GLMakie, MakieTeX
+using Makie
+
+# Heuristic for rasterization density. `s` is per-marker pixel-size in
+# markerspace (Vec2f); take its longest axis and scale by a factor so that
+# a 30pt fontsize → ~density 4 (good visual fidelity without huge textures).
+_density_for_size(s) = max(2, ceil(Int, maximum(s) / 8))
+
+function Makie.rasterize_marker_for_gpu(doc::MakieTeX.AbstractCachedDocument, scale)
+    s = scale isa AbstractVector ? first(scale) : scale
+    return _rasterize_doc(doc, _density_for_size(s))
+end
+
+function Makie.rasterize_marker_for_gpu(docs::AbstractVector{<:MakieTeX.AbstractCachedDocument}, scale)
+    # Per-marker scale if `scale` is a Vector, otherwise broadcast the
+    # scalar.
+    sizes = scale isa AbstractVector ? scale : fill(scale, length(docs))
+    return [_rasterize_doc(d, _density_for_size(sz)) for (d, sz) in zip(docs, sizes)]
+end
 
-# GLMakie.GLAbstraction.gl_convert(ct::MakieTeX.AbstractCachedDocument) = MakieTeX.rasterize(ct, #=scale=#1)
-# GLMakie.GLAbstraction.gl_convert((ct::MakieTeX.AbstractCachedDocument, scale::Real)) = MakieTeX.rasterize(ct, scale)
+# `MakieTeX.rasterize(::CachedTEX/CachedTypst, _)` currently ignores its
+# `scale` arg; `page2img(…; render_density)` honors it. Route through that
+# uniformly so fontsize controls bitmap resolution.
+function _rasterize_doc(doc::MakieTeX.AbstractCachedDocument, density::Int)
+    return MakieTeX.page2img(doc, doc.doc isa Nothing ? 0 : doc.doc.page;
+        render_density = density)
+end
 
-end
+end

src/MakieTeX.jl

@@ -1,7 +1,6 @@
 module MakieTeX
 
 using Makie
-using Makie.MakieCore
 
 using Colors, LaTeXStrings, Typstry
 using Base64
@@ -41,6 +40,8 @@ include("rendering/typst.jl")
 include("rendering/pdf.jl")
 include("rendering/svg.jl")
 
+include("text_integration.jl")
+
 export Cached
 export TeXDocument, CachedTeX
 export TEXDocument, CachedTEX
@@ -50,6 +51,7 @@ export SVGDocument, CachedSVG
 export dvi2svg, latex2dvi, rsvg2recordsurf, svg2rsvg
 export teximg, teximg!, TeXImg
 export LTeX
+export MakieTeXLaTeX, compile_latex_for_makie
 
 export LaTeXStrings, LaTeXString, latexstring, @L_str
 export Typstry, TypstString, @typst_str

src/text_integration.jl

@@ -0,0 +1,248 @@
+# Integration with Makie's `text` recipe via the `AbstractTextPrimitive` +
+# `latex_handler` extension hooks (added in Makie 0.25). Lets MakieTeX
+# render any `LaTeXString` passed into `text()` (and therefore Axis labels,
+# titles, tick labels via `xtickformat`, etc.) with a real LaTeX engine
+# instead of MathTeXEngine's in-process glyph approximation.
+#
+# Usage:
+#
+#   set_theme!(latex_handler = MakieTeXLaTeX())                       # global default
+#   with_theme(latex_handler = MakieTeXLaTeX(preamble = "…")) do … end # scoped override
+#   text!(scene, L"…"; latex_handler = MakieTeXLaTeX(preamble = "…"))  # per-plot override
+#
+# Each `MakieTeXLaTeX` value carries its own preamble / class options /
+# engine, so different text plots in the same figure can compile against
+# different LaTeX setups (e.g. one Axis using `physics` package macros and
+# another using `siunitx`).
+#
+# Without a handler set, Makie's default MathTeXEngine path is used — good
+# for quick iteration; switch to MakieTeXLaTeX to polish a publication-
+# quality figure without changing plot code (especially useful when the
+# LaTeXStrings come from a third-party plotting function you don't control).
+#
+# See companion PR: https://github.com/MakieOrg/Makie.jl/pull/5632
+
+# Scatter centers its marker on the position, then adds `marker_offset`. To
+# make `position` correspond to the alignment edge of the marker, shift by
+# half the marker size scaled by the alignment fraction. `valign === :baseline`
+# is supported: `baseline_from_bottom` is the descender depth in markerspace.
+function _latex_align_offset(align::Tuple, wh::Makie.Vec2f, baseline_from_bottom::Real = 0.0f0)
+    halign, valign = align
+    fhalign = halign === :left ? 0.0f0 :
+        halign === :center ? 0.5f0 :
+        halign === :right ? 1.0f0 : Float32(halign)
+    ox = (0.5f0 - fhalign) * wh[1]
+    oy = if valign === :baseline
+        0.5f0 * wh[2] - Float32(baseline_from_bottom)
+    else
+        fvalign = valign === :bottom ? 0.0f0 :
+            valign === :center ? 0.5f0 :
+            valign === :top ? 1.0f0 : Float32(valign)
+        (0.5f0 - fvalign) * wh[2]
+    end
+    return Makie.Vec2f(ox, oy)
+end
+
+const _DEFAULT_PREAMBLE = "\\usepackage{amsmath, amsfonts, xcolor}\n\\pagestyle{empty}\n\\nopagecolor"
+const _DEFAULT_CLASSOPTIONS = "preview, tightpage, 12pt"
+
+"""
+    MakieTeXLaTeX(; preamble, classoptions, engine, border_pt,
+                    crop_margin_pt, base_pt)
+
+A `latex_handler` for Makie's `text` recipe that renders `LaTeXString`
+content with a real LaTeX engine (via MakieTeX). Construct one and pass it
+to `set_theme!` / `with_theme` / a plot's `latex_handler` attribute.
+
+# Fields
+
+* `preamble` — LaTeX preamble (everything between `\\documentclass{…}` and
+  `\\begin{document}`). Default loads `amsmath, amsfonts, xcolor` and sets
+  `\\pagestyle{empty}\\nopagecolor` so the page background is transparent.
+* `classoptions` — options to the standalone class (without `border=`, that
+  field is appended automatically from `border_pt`). Default
+  `"preview, tightpage, 12pt"`.
+* `engine` — `nothing` (use `MakieTeX.CURRENT_TEX_ENGINE[]`) or a `Cmd` like
+  `` `lualatex` `` / `` `pdflatex` `` / `` `tectonic` ``.
+* `border_pt` — pt margin built into the standalone page MediaBox; must be
+  larger than `crop_margin_pt` so the safety crop below has room to extend.
+* `crop_margin_pt` — symmetric pt safety pad cropped around the ink, so
+  anti-aliased glyph edges aren't clipped by the page boundary.
+* `base_pt` — LaTeX font size assumed in the document (Makie's `fontsize`
+  is scaled by `fontsize / base_pt`).
+"""
+Base.@kwdef struct MakieTeXLaTeX
+    preamble::String = _DEFAULT_PREAMBLE
+    classoptions::String = _DEFAULT_CLASSOPTIONS
+    engine::Union{Nothing, Cmd} = nothing
+    border_pt::Int = 3
+    crop_margin_pt::Float32 = 2.0f0
+    base_pt::Float32 = 12.0f0
+end
+
+"""
+    compile_latex_for_makie(h::MakieTeXLaTeX, latex_src::AbstractString)
+        -> (cached::CachedPDF, baseline_pt::Float32)
+
+Compile a LaTeX snippet under the configuration `h` to a `CachedPDF` and
+simultaneously extract the descender depth (`\\dp`) of the rendered box —
+needed for `align = (:left, :baseline)`. Single LaTeX run: the content is
+wrapped in `\\sbox` + `\\typeout`, then `\\usebox`'d, so the same compile
+produces both the PDF that gets rendered and a log line we parse back for
+the baseline. The returned `cached` document is cropped with a symmetric
+`h.crop_margin_pt` margin to avoid clipping anti-aliased glyph edges.
+"""
+function compile_latex_for_makie(h::MakieTeXLaTeX, latex_src::AbstractString)
+    src = String(latex_src)
+    body = """
+    \\newsavebox\\makietexbaselinebox%
+    \\sbox\\makietexbaselinebox{$(src)}%
+    \\typeout{MAKIETEX_BASELINE_DEPTH=\\the\\dp\\makietexbaselinebox}%
+    \\usebox\\makietexbaselinebox
+    """
+    # Build the TEXDocument ourselves so we can set `border=Npt` from the
+    # handler config — gives the page MediaBox enough room for our crop
+    # margin (otherwise the crop clamps to MediaBox and the margin
+    # disappears in y).
+    doc = TEXDocument(body, true;
+        requires = "\\RequirePackage{luatex85}",
+        preamble = h.preamble,
+        class = "standalone",
+        classoptions = "$(h.classoptions), border=$(h.border_pt)pt",
+    )
+    engine = h.engine === nothing ? CURRENT_TEX_ENGINE[] : h.engine
+    pdf, baseline_pt = _compile_latex_capture_baseline(String(doc.contents), engine, h.crop_margin_pt)
+    # `CachedTEX(::Vector{UInt8})` is broken upstream (it stashes `nothing`
+    # into a strictly-typed `doc::TEXDocument` field). `CachedPDF` works
+    # fine and is what `page2img` dispatches on anyway.
+    return CachedPDF(PDFDocument(pdf)), baseline_pt
+end
+
+# Like MakieTeX's `crop_pdf`, but reads Ghostscript's `%%HiResBoundingBox`
+# (sub-pt precision) rather than the integer `%%BoundingBox`. With the
+# integer version, glyph edges can be jittered by up to ~1pt within the
+# crop, which propagates into visible baseline misalignment.
+function _hires_pdf_bbox(path::String)
+    out = Pipe(); err = Pipe()
+    success(pipeline(`$(Ghostscript_jll.gs()) -q -dBATCH -dNOPAUSE -sDEVICE=bbox $path`, stdout = out, stderr = err))
+    close(out.in); close(err.in)
+    result = read(err, String)
+    m = match(r"%%HiResBoundingBox: ([-0-9.]+) ([-0-9.]+) ([-0-9.]+) ([-0-9.]+)", result)
+    m === nothing && error("could not extract %%HiResBoundingBox from gs output")
+    return parse.(Float64, (m.captures[1], m.captures[2], m.captures[3], m.captures[4]))
+end
+
+function _hires_crop_pdf(path::String, margin::Real)
+    bb = _hires_pdf_bbox(path)
+    crop_box = (bb[1] - margin, bb[2] - margin, bb[3] + margin, bb[4] + margin)
+    crop_cmd = join(crop_box, " ")
+    out_path = "_hires_cropped.pdf"
+    out = Pipe(); err = Pipe()
+    try
+        redirect_stderr(err) do
+            redirect_stdout(out) do
+                Ghostscript_jll.gs() do gs_exe
+                    run(`$gs_exe -o $out_path -sDEVICE=pdfwrite -c "[/CropBox [$crop_cmd]" -c "/PAGES pdfmark" -f $path`)
+                end
+            end
+        end
+    catch e
+    finally
+        close(out.in); close(err.in)
+    end
+    return read(out_path)
+end
+
+# Mirror of MakieTeX.compile_latex's tempdir-and-latexmk pipeline, but also
+# reads `temp.log` before the directory is torn down and pulls the baseline
+# depth out of it. Returns the cropped PDF as `Vector{UInt8}` plus the depth
+# in pt.
+function _compile_latex_capture_baseline(document::String, engine::Cmd, crop_margin_pt::Real)
+    return mktempdir() do dir
+        cd(dir) do
+            write("temp.tex", document)
+            out = Pipe(); err = Pipe()
+            try
+                cmd = if engine == `tectonic`
+                    `$(tectonic_jll.tectonic()) temp.tex`
+                else
+                    `latexmk -file-line-error --shell-escape -cd -$(engine) -interaction=nonstopmode temp.tex`
+                end
+                run(pipeline(ignorestatus(cmd), stdout = out, stderr = err))
+            finally
+                close(out.in); close(err.in)
+            end
+            log_text = isfile("temp.log") ? read("temp.log", String) : ""
+            m = match(r"MAKIETEX_BASELINE_DEPTH=([-0-9.]+)pt", log_text)
+            baseline_pt = m === nothing ? 0.0f0 : max(0.0f0, parse(Float32, m.captures[1]))
+            pdf = _hires_crop_pdf("temp.pdf", crop_margin_pt)
+            return pdf, baseline_pt
+        end
+    end
+end
+
+# Makie calls the handler as `h(outputs, latex_str, i, N, _inputs...)`. We
+# make `MakieTeXLaTeX` callable with that exact signature.
+function (h::MakieTeXLaTeX)(
+        outputs::NamedTuple, latex_str::LaTeXString,
+        i, N, fontsize, font, align, rotation, justification,
+        lineheight, word_wrap_width, offset, fonts, color, strokecolor, strokewidth
+    )
+
+    fs = Float32(Makie.sv_getindex(fontsize, i))
+    al = Makie.sv_getindex(align, i)
+    rot = convert(Makie.Quaternionf, Makie.sv_getindex(rotation, i))
+    off = Makie.Vec3f(Makie.sv_getindex(offset, i))
+
+    # Single LaTeX compile: yields the rendered PDF + the box-depth in pt for
+    # `align = (..., :baseline)`. The `CachedPDF` is passed straight to scatter
+    # as the marker — CairoMakie's `draw_marker(::CachedPDF, …)` override (in
+    # MakieTeXCairoMakieExt) hands it to `poppler_page_render`, which puts
+    # the PDF's vector content directly into the figure's Cairo surface (no
+    # raster intermediate, so hairlines stay crisp).
+    cached, baseline_pt = compile_latex_for_makie(h, String(latex_str))
+
+    # `dim_pt` includes the safety pad `h.crop_margin_pt` on each side (added
+    # at crop time to keep anti-aliased glyphs from clipping). The natural
+    # ink box is `dim_pt - 2 * crop_margin_pt`. Alignment refers to the ink
+    # box so the safety pad doesn't shift positions.
+    scale = fs / h.base_pt
+    dim_pt = Makie.Vec2f(Float32(cached.dims[1]), Float32(cached.dims[2]))
+    target_size = dim_pt .* scale
+    ink_size = (dim_pt .- 2 * h.crop_margin_pt) .* scale
+    baseline_from_bottom = baseline_pt * scale
+
+    align_off = _latex_align_offset(al, ink_size, baseline_from_bottom)
+    marker_offset = Makie.Vec3f(align_off[1], align_off[2], 0) + off
+
+    # `text_blocks` must have one entry per input string. This block has no
+    # glyphs — only a Scatter spec — so we push an empty range.
+    curr = length(outputs.glyphindices)
+    push!(outputs.text_blocks, (curr + 1):curr)
+    push!(
+        outputs.glyphcollections, Makie.GlyphCollection(
+            UInt64[], Makie.NativeFont[], Makie.Point3f[], Makie.GlyphExtent[],
+            Makie.Vec2f[], Makie.Quaternionf[], Makie.RGBAf[], Makie.RGBAf[], Float32[]
+        )
+    )
+
+    # Emit the LaTeX render as a single Scatter PlotSpec. Positions are in
+    # block-relative markerspace (origin = the text block's anchor point);
+    # the text recipe shifts by the projected block position late, so we
+    # only need to supply a zero point here. `space`/`markerspace` are
+    # patched in by the recipe to match the parent text plot.
+    push!(outputs.text_specs, Makie.PlotSpec(:Scatter, Makie.Point3f[Makie.Point3f(0, 0, 0)];
+        marker = [cached],
+        markersize = [target_size],
+        marker_offset = [marker_offset],
+        rotation = [rot],
+    ))
+    push!(outputs.text_spec_block_indices, i)
+
+    # Block-relative bbox: marker_offset is the center, ink box is target
+    # minus the 2*margin safety pad on each side; rotation is applied.
+    half = 0.5f0 .* Makie.Vec3f(target_size..., 0)
+    bb = Makie.Rect3d(Makie.to_ndim(Makie.Point3d, marker_offset, 0) .- half, Makie.Vec3d(target_size..., 0))
+    push!(outputs.text_spec_bboxes, Makie.rotate_bbox(bb, rot))
+    return
+end