text

text(positions; text, kwargs...)
text(x, y; text, kwargs...)
text(x, y, z; text, kwargs...)

Plots one or multiple texts passed via the text keyword. Text uses the PointBased conversion trait.

Attributes

Specific to `Text`

text specifies one piece of text or a vector of texts to show, where the number has to match the number of positions given. Makie supports String which is used for all normal text and LaTeXString which layouts mathematical expressions using MathTeXEngine.jl .
align::Tuple{Union{Symbol, Real}, Union{Symbol, Real}} = (:left, :bottom) sets the alignment of the string w.r.t. position . Uses :left, :center, :right, :top, :bottom, :baseline or fractions.
font::Union{String, Vector{String}} = "TeX Gyre Heros Makie" sets the font for the string or each character.
justification::Union{Real, Symbol} = automatic sets the alignment of text w.r.t its bounding box. Can be :left, :center, :right or a fraction. Will default to the horizontal alignment in align .
rotation::Union{Real, Quaternion} rotates text around the given position.
textsize::Union{Real, Vec2f} sets the size of each character.
markerspace::Symbol = :pixel sets the space in which textsize acts. See Makie.spaces() for possible inputs.
strokewidth::Real = 0 sets the width of the outline around a marker.
strokecolor::Union{Symbol, <:Colorant} = :black sets the color of the outline around a marker.
glowwidth::Real = 0 sets the size of a glow effect around the marker.
glowcolor::Union{Symbol, <:Colorant} = (:black, 0) sets the color of the glow effect.
word_wrap_with::Real = -1 specifies a linewidth limit for text. If a word overflows this limit, a newline is inserted before it. Negative numbers disable word wrapping.

Generic attributes

visible::Bool = true sets whether the plot will be rendered or not.
overdraw::Bool = false sets whether the plot will draw over other plots. This specifically means ignoring depth checks in GL backends.
transparency::Bool = false adjusts how the plot deals with transparency. In GLMakie transparency = true results in using Order Independent Transparency.
fxaa::Bool = false adjusts whether the plot is rendered with fxaa (anti-aliasing). Note that text plots already include a different form of anti-aliasing.
inspectable::Bool = true sets whether this plot should be seen by DataInspector .
depth_shift::Float32 = 0f0 adjusts the depth value of a plot after all other transformations, i.e. in clip space, where 0 <= depth <= 1 . This only applies to GLMakie and WGLMakie and can be used to adjust render order (like a tunable overdraw).
model::Makie.Mat4f sets a model matrix for the plot. This replaces adjustments made with translate! , rotate! and scale! .
color sets the color of the plot. It can be given as a named color Symbol or a Colors.Colorant . Transparency can be included either directly as an alpha value in the Colorant or as an additional float in a tuple (color, alpha) . The color can also be set for each character by passing a Vector of colors.
space::Symbol = :data sets the transformation space for text positions. See Makie.spaces() for possible inputs.

Pixel space text

By default, text is drawn in pixel space ( space = :pixel ). The text anchor is given in data coordinates, but the size of the glyphs is independent of data scaling. The boundingbox of the text will include every data point or every text anchor point. This also means that autolimits! might cut off your text, because the glyphs don't have a meaningful size in data coordinates (the size is independent of zoom level), and you have to take some care to manually place the text or set data limits such that it is fully visible.

You can either plot one string with one position, or a vector of strings with a vector of positions.

using CairoMakie

f = Figure()

Axis(f[1, 1], aspect = DataAspect(), backgroundcolor = :gray50)

scatter!(Point2f(0, 0))
text!(0, 0, text = "center", align = (:center, :center))

circlepoints = [(cos(a), sin(a)) for a in LinRange(0, 2pi, 16)[1:end-1]]
scatter!(circlepoints)
text!(
    circlepoints,
    text = "this is point " .* string.(1:15),
    rotation = LinRange(0, 2pi, 16)[1:end-1],
    align = (:right, :baseline),
    color = cgrad(:Spectral)[LinRange(0, 1, 15)]
)

f

Data space text

For text whose dimensions are meaningful in data space, set markerspace = :data . This means that the boundingbox of the text in data coordinates will include every glyph.

using CairoMakie

f = Figure()
LScene(f[1, 1])

text!(
    [Point3f(0, 0, i/2) for i in 1:7],
    text = fill("Makie", 7),
    rotation = [i / 7 * 1.5pi for i in 1:7],
    color = [cgrad(:viridis)[x] for x in LinRange(0, 1, 7)],
    align = (:left, :baseline),
    textsize = 1,
    markerspace = :data
)

f

Alignment

Text can be aligned with the horizontal alignments :left , :center , :right and the vertical alignments :bottom , :baseline , :center , :top .

using CairoMakie

aligns = [(h, v) for v in [:bottom, :baseline, :center, :top]
                 for h in [:left, :center, :right]]
x = repeat(1:3, 4)
y = repeat(1:4, inner = 3)
scatter(x, y)
text!(x, y, text = string.(aligns), align = aligns)
current_figure()

Justification

By default, justification of multiline text follows alignment. Text that is left aligned is also left justified. You can override this with the justification attribute.

using CairoMakie

scene = Scene(camera = campixel!, resolution = (800, 800))

points = [Point(x, y) .* 200 for x in 1:3 for y in 1:3]
scatter!(scene, points, marker = :circle, markersize = 10px)

symbols = (:left, :center, :right)

for ((justification, halign), point) in zip(Iterators.product(symbols, symbols), points)

    t = text!(scene, 
        point,
        text = "a\nshort\nparagraph",
        color = (:black, 0.5),
        align = (halign, :center),
        justification = justification)

    bb = boundingbox(t)
    wireframe!(scene, bb, color = (:red, 0.2))
end

for (p, al) in zip(points[3:3:end], (:left, :center, :right))
    text!(scene, p .+ (0, 80), text = "align :" * string(al),
        align = (:center, :baseline))
end

for (p, al) in zip(points[7:9], (:left, :center, :right))
    text!(scene, p .+ (80, 0), text = "justification\n:" * string(al),
        align = (:center, :top), rotation = pi/2)
end

scene

Offset

The offset attribute can be used to shift text away from its position. This is especially useful with space = :pixel , for example to place text together with barplots. You can specify the end of the barplots in data coordinates, and then offset the text a little bit to the left.

using CairoMakie

f = Figure()

horsepower = [52, 78, 80, 112, 140]
cars = ["Kia", "Mini", "Honda", "Mercedes", "Ferrari"]

ax = Axis(f[1, 1], xlabel = "horse power")
tightlimits!(ax, Left())
hideydecorations!(ax)

barplot!(horsepower, direction = :x)
text!(Point.(horsepower, 1:5), text = cars, align = (:right, :center),
    offset = (-20, 0), color = :white)

f

MathTeX

Makie can render LaTeX strings from the LaTeXStrings.jl package using MathTeXEngine.jl .

using CairoMakie

lines(0.5..20, x -> sin(x) / sqrt(x), color = :black)
text!(7, 0.38, text = L"\frac{\sin(x)}{\sqrt{x}}", color = :black)
current_figure()

You can also pass L-strings to many objects that use text, for example as labels in the legend.

using CairoMakie

f = Figure()
ax = Axis(f[1, 1])

lines!(0..10, x -> sin(3x) / (cos(x) + 2),
    label = L"\frac{\sin(3x)}{\cos(x) + 2}")
lines!(0..10, x -> sin(x^2) / (cos(sqrt(x)) + 2),
    label = L"\frac{\sin(x^2)}{\cos(\sqrt{x}) + 2}")

Legend(f[1, 2], ax)

f

These docs were autogenerated using Makie: v0.17.13, GLMakie: v0.6.13, CairoMakie: v0.8.13, WGLMakie: v0.6.13

Navigation