PhyloPic: Rendering — API Reference

PaleobiologyDB.TaxonomyMakie overlays PhyloPic silhouette images on existing Makie axes. It is a package extension that activates when both a Makie backend (e.g. CairoMakie) and PhyloPicMakie are loaded.

For taxon-name resolution and image acquisition, see the acquire_phylopic API.

See the PhyloPicMakie guide for installation instructions, worked examples, and a keyword-argument reference.

TaxonomyMakie.PhyloPicPBDB — Module

PaleobiologyDB.PhyloPicPBDB

PBDB-specific PhyloPic integration submodule.

Provides the PBDB → PhyloPic name resolution pipeline and Makie visualization wrappers.

Data API

Function	Description
`acquire_phylopic(taxon_name, prefix; ...)`	Single-taxon metadata lookup → NamedTuple
`acquire_phylopic(df, field, prefix; ...)`	DataFrame enrichment → DataFrame
`augment_phylopic(df, field, prefix; ...)`	In-place DataFrame enrichment
`phylopic_images_dataframe(taxon_name; ...)`	All images for a taxon → DataFrame
`phylopic_node(taxon_name; ...)`	PBDB → PhyloPic node lookup → PhyloPicNode
`phylopic_images(taxon_name; ...)`	PBDB → PhyloPic images → Vector{PhyloPicImage}

Makie API

Function	Description
`augment_phylopic!(ax, xs, ys; taxon, ...)`	Add one glyph per datum
`augment_phylopic(ax, xs, ys; taxon, ...)`	Non-bang alias
`augment_phylopic!(ax, table; x, y, taxon, ...)`	Table-oriented variant
`augment_phylopic_ranges!(ax, xstart, xstop, y; taxon, ...)`	Range-anchored glyphs
`augment_phylopic_ranges(...)`	Non-bang alias
`phylopic_thumbnail_grid!(ax, taxon; ...)`	Gallery in existing axis
`phylopic_thumbnail_grid(taxon; ...)`	Factory: creates Figure + Axis

source

Point placement

TaxonomyMakie.PhyloPicPBDB.augment_phylopic! — Function

augment_phylopic!(
    ax::Makie.Axis,
    x::AbstractVector{<:Real},
    y::AbstractVector{<:Real};
    taxon::Union{AbstractVector, Nothing} = nothing,
    glyph::Union{AbstractMatrix{<:Colorant}, Nothing} = nothing,
    placement::Symbol = :center,
    xoffset::Real = 0.0,
    yoffset::Real = 0.0,
    glyph_size::Real = 0.4,
    aspect::Symbol = :preserve,
    rotation::Real = 0.0,
    mirror::Bool = false,
    image_rendering::Symbol = :thumbnail,
    on_missing::Symbol = :skip,
) -> Nothing

Add one PhyloPic silhouette glyph per datum to an existing Makie axis ax, anchored at positions (x[i], y[i]) in axis data coordinates.

This is the primitive operation. All other augment_phylopic variants reduce to this.

Arguments

x, y: anchor coordinates in axis data space. Must have equal length.

Image source (exactly one required)

taxon: per-datum taxon names (used for glyph lookup via acquire_phylopic). Missing or empty strings are handled according to on_missing.
glyph: a single pre-loaded image matrix (e.g. from FileIO.load), broadcast to every data point. When provided, taxon is ignored.

Placement

placement: anchor position on the glyph relative to the data coordinate. One of :center (default), :left, :right, :top, :bottom, :topleft, :topright, :bottomleft, :bottomright.
xoffset, yoffset: additional offset in data units applied after anchoring.

Sizing

glyph_size: half-height of the rendered glyph in data units (total height = 2 * glyph_size). Default 0.4.
aspect: :preserve (default) maintains the original image aspect ratio; :stretch renders as a square.

Rendering

image_rendering: which PhyloPic image URL to fetch. Default :thumbnail. Ignored when glyph is supplied directly.

`image_rendering`	Format
`:thumbnail` (default)	PNG; square thumbnail, largest available
`:raster`	PNG; full-resolution, largest available
`:og_image`	PNG; Open Graph social-media preview
`:vector`	SVG; black silhouette on transparent — requires SVG-capable `FileIO` plugin
`:source_file`	SVG or raster — format matches the original upload

rotation: clockwise rotation in degrees. Supported values: 0, 90, 180, 270 (and their negatives / modulo equivalents). Default 0.0.
mirror: if true, flip the glyph horizontally before rendering.

Missing-value policy

on_missing: how to handle data points for which no image is available. :skip (default) silently omits the glyph; :error throws; :placeholder draws a small grey rectangle at the glyph position.

Returns

Nothing. The glyphs are added as side-effects to ax.

Examples

using PaleobiologyDB
using PaleobiologyDB.PhyloPicPBDB
using CairoMakie

fig = Figure()
ax  = Axis(fig[1, 1])
lines!(ax, [68.0, 66.0], [1, 1])

augment_phylopic!(
    ax,
    [68.0],
    [1.0];
    taxon          = ["Tyrannosaurus"],
    glyph_size     = 0.4,
    placement      = :left,
    image_rendering = :raster,
)

source

augment_phylopic!(
    ax::Makie.Axis,
    table;
    x,
    y,
    taxon = nothing,
    glyph = nothing,
    kwargs...,
) -> Nothing

Table-oriented variant of augment_phylopic!.

Extracts coordinate and taxon columns from any Tables.jl-compatible source (e.g. a DataFrame) and forwards to the vector API.

Arguments

table: any Tables.jl-compatible object.
x: column selector for x coordinates (Symbol, String, or Integer).
y: column selector for y coordinates.
taxon: column selector for taxon names, or nothing if glyph is used.
glyph: a single pre-loaded image matrix broadcast to all rows (alternative to taxon).
All remaining keyword arguments are forwarded to the vector augment_phylopic!.

Returns

Nothing.

Examples

using PaleobiologyDB
using PaleobiologyDB.PhyloPicPBDB
using CairoMakie, DataFrames

df = DataFrame(
    x     = [68.0, 68.0],
    y     = [1.0, 2.0],
    taxon = ["Tyrannosaurus", "Triceratops"],
)

fig = Figure()
ax  = Axis(fig[1, 1])
augment_phylopic!(ax, df; x = :x, y = :y, taxon = :taxon, glyph_size = 0.4)

source

TaxonomyMakie.PhyloPicPBDB.augment_phylopic — Function

augment_phylopic(df, taxon_field = :accepted_name, fieldname_prefix = "phylopic_"; kwargs...) -> DataFrame

Enrich df with PhyloPic image columns and return the combined DataFrame.

Thin wrapper: calls acquire_phylopic (DataFrame variant) and concatenates the result with a copy of df using hcat.

Examples

enriched = augment_phylopic(df)
enriched_genus = augment_phylopic(df, :genus, "genus_phylopic_")

source

augment_phylopic(
    ax::Makie.Axis,
    x::AbstractVector{<:Real},
    y::AbstractVector{<:Real};
    kwargs...,
) -> Nothing

Non-mutating alias for augment_phylopic!.

Semantically identical: adds a glyph layer to an existing axis. The ! convention is preserved in augment_phylopic!; this alias is provided for naming symmetry only.

See augment_phylopic! for the full keyword-argument documentation.

source

augment_phylopic(
    ax::Makie.Axis,
    table;
    kwargs...,
) -> Nothing

Non-mutating alias for the table-based augment_phylopic!.

See augment_phylopic! for full documentation.

source

Range placement

TaxonomyMakie.PhyloPicPBDB.augment_phylopic_ranges! — Function

augment_phylopic_ranges!(
    ax::Makie.Axis,
    xstart::AbstractVector{<:Real},
    xstop::AbstractVector{<:Real},
    y::AbstractVector{<:Real};
    taxon::Union{AbstractVector, Nothing} = nothing,
    glyph::Union{AbstractMatrix{<:Colorant}, Nothing} = nothing,
    at::Symbol = :start,
    placement::Symbol = :center,
    xoffset::Real = 0.0,
    yoffset::Real = 0.0,
    glyph_size::Real = 0.4,
    aspect::Symbol = :preserve,
    rotation::Real = 0.0,
    mirror::Bool = false,
    on_missing::Symbol = :skip,
) -> Nothing

Add one PhyloPic silhouette per datum to ax, where each glyph is anchored relative to a range (xstart[i], xstop[i]) at vertical position y[i].

This is a convenience wrapper for range-based data (e.g. stratigraphic intervals). It computes anchor x coordinates from the range endpoints and then calls augment_phylopic!.

Arguments

xstart, xstop: range endpoints in axis data units.
y: vertical coordinate for each datum.
at: where along the range to anchor the glyph. One of:
- :start (default) — anchor at xstart[i].
- :stop — anchor at xstop[i].
- :midpoint — anchor at the midpoint (xstart[i] + xstop[i]) / 2.
All remaining keyword arguments are forwarded unchanged to augment_phylopic!.

Returns

Nothing.

Examples

using PaleobiologyDB
using PaleobiologyDB.PhyloPicPBDB
using CairoMakie

taxa      = ["Tyrannosaurus", "Triceratops"]
first_app = [68.0, 68.0]
last_app  = [66.0, 66.0]

fig = Figure()
ax  = Axis(fig[1, 1]; xreversed = true,
           yticks = (1:length(taxa), taxa))

for (i, (fa, la)) in enumerate(zip(first_app, last_app))
    lines!(ax, [fa, la], [i, i]; linewidth = 4, color = :gray30)
end

augment_phylopic_ranges!(
    ax,
    first_app,
    last_app,
    collect(1:length(taxa));
    taxon     = taxa,
    at        = :start,
    glyph_size = 0.4,
    placement = :center,
)

source

augment_phylopic_ranges!(
    ax::Makie.Axis,
    table;
    xstart,
    xstop,
    y,
    taxon = nothing,
    glyph = nothing,
    at::Symbol = :start,
    kwargs...,
) -> Nothing

Table-oriented variant of augment_phylopic_ranges!.

Extracts range and taxon columns from a Tables.jl-compatible source and forwards to the vector range API.

Arguments

table: any Tables.jl-compatible object.
xstart, xstop: column selectors for the range endpoints.
y: column selector for the vertical coordinate.
taxon: column selector for taxon names, or nothing if glyph is used.
glyph: a single pre-loaded image matrix broadcast to all rows.
at: :start (default), :stop, or :midpoint — which end of the range to anchor the glyph.
All remaining keyword arguments are forwarded to the vector augment_phylopic_ranges!.

Returns

Nothing.

Examples

using PaleobiologyDB
using PaleobiologyDB.PhyloPicPBDB
using CairoMakie, DataFrames

df = DataFrame(
    taxon      = ["Tyrannosaurus", "Triceratops"],
    first_app  = [68.0, 68.0],
    last_app   = [66.0, 66.0],
    row        = [1.0, 2.0],
)

fig = Figure()
ax  = Axis(fig[1, 1]; xreversed = true,
           yticks = (1:nrow(df), df.taxon))
for i in 1:nrow(df)
    lines!(ax, [df.first_app[i], df.last_app[i]], [i, i])
end

augment_phylopic_ranges!(
    ax, df;
    xstart = :first_app,
    xstop  = :last_app,
    y      = :row,
    taxon  = :taxon,
    at     = :start,
    glyph_size = 0.4,
)

source

TaxonomyMakie.PhyloPicPBDB.augment_phylopic_ranges — Function

augment_phylopic_ranges(
    ax::Makie.Axis,
    xstart::AbstractVector{<:Real},
    xstop::AbstractVector{<:Real},
    y::AbstractVector{<:Real};
    kwargs...,
) -> Nothing

Non-mutating alias for augment_phylopic_ranges!.

See augment_phylopic_ranges! for full documentation.

source

augment_phylopic_ranges(
    ax::Makie.Axis,
    table;
    kwargs...,
) -> Nothing

Non-mutating alias for the table-based augment_phylopic_ranges!.

See augment_phylopic_ranges! for full documentation.

source

Thumbnail grids

TaxonomyMakie.PhyloPicPBDB.phylopic_thumbnail_grid! — Function

phylopic_thumbnail_grid!(
    ax::Makie.Axis,
    taxon::AbstractVector{<:AbstractString};
    ncols::Union{Integer, Nothing} = nothing,
    nrows::Union{Integer, Nothing} = nothing,
    cell_width::Real = PhyloPicMakie.DEFAULT_THUMBNAIL_GRID_CELL_WIDTH,
    cell_height::Real = PhyloPicMakie.DEFAULT_THUMBNAIL_GRID_CELL_HEIGHT,
    glyph_fraction::Real = PhyloPicMakie.DEFAULT_THUMBNAIL_GRID_GLYPH_FRACTION,
    label_gap::Real = PhyloPicMakie.DEFAULT_THUMBNAIL_GRID_LABEL_GAP,
    label_fontsize::Real = PhyloPicMakie.DEFAULT_THUMBNAIL_GRID_FONT_SIZE,
    title::Union{AbstractString, Nothing} = nothing,
    title_gap::Real = PhyloPicMakie.DEFAULT_THUMBNAIL_GRID_TITLE_GAP,
    on_missing::Symbol = :skip,
    image_interpolate::Bool = true,
    image_filter::Symbol = :clade,
    image_selector = nothing,
    image_max_pages::Union{Int, Nothing} = nothing,
    image_layout::Symbol = :blocks,
    image_rendering::Symbol = :thumbnail,
    image_label = :BASICFIELDS,
    labeljoin::AbstractString = "\n",
    label_lines::Union{Int, Nothing} = nothing,
) -> Nothing

Render a gallery of PhyloPic silhouettes into the existing Makie Axis ax.

Each taxon in taxon contributes one or more cells to the grid depending on image_filter and image_selector. With image_filter = :primary each taxon produces exactly one cell; with the default image_filter = :clade a taxon may produce multiple cells (one per image in its clade).

Arguments

ax: Target Makie axis.
taxon: PBDB taxon names to resolve via the PBDB → PhyloPic pipeline.

Layout keywords

ncols, nrows: Explicit grid dimensions. Supply either, both, or neither.
cell_width, cell_height: Nominal cell size in axis data units.
glyph_fraction: Fraction of cell_height allocated to the image.
label_gap: Vertical gap between image and text label.
label_fontsize: Font size for cell labels.
label_lines: Override the automatic line-count for multi-line labels.
title: Optional axis title.
title_gap: Additional vertical padding reserved for the title.

Image selection and rendering

image_filter: Which pool of images to fetch per taxon.
- :clade (default) — all images for the node and its descendants.
- :primary — designated primary image; 1 per taxon.
- :node — images tagged directly to this node.
image_selector: How to narrow the fetched pool; see PhyloPicMakie.phylopic_thumbnail_grid! for details.
image_max_pages: Pagination limit for :clade/:node queries.
image_rendering: Which URL to fetch for each selected image. Default :thumbnail.
image_layout: :blocks (default), :rows, or :flat.
image_label: Cell caption format. Default :BASICFIELDS.
labeljoin: Field separator for multi-field label presets. Default "\n".

Missing-image policy

on_missing = :skip (default): skip cells with no downloadable image.
on_missing = :placeholder: draw a placeholder for failed cells.
on_missing = :error: throw when any selected image has no URL.

Returns

Nothing.

source

phylopic_thumbnail_grid!(
    ax::Makie.Axis,
    taxon_name::AbstractString;
    kwargs...,
) -> Nothing

Single-taxon convenience wrapper. Equivalent to phylopic_thumbnail_grid!(ax, [taxon_name]; kwargs...).

See phylopic_thumbnail_grid! for full keyword documentation.

source

phylopic_thumbnail_grid!(
    ax::Makie.Axis,
    table;
    taxon,
    kwargs...,
) -> Nothing

Table-oriented variant of phylopic_thumbnail_grid!.

Extracts the taxon column from any Tables.jl-compatible source (e.g. a DataFrame) and forwards to the vector API.

taxon: column selector for taxon names (Symbol, String, or Integer).
All remaining keyword arguments are forwarded to the vector API.

source

TaxonomyMakie.PhyloPicPBDB.phylopic_thumbnail_grid — Function

phylopic_thumbnail_grid(
    taxon::AbstractVector{<:AbstractString};
    figure_size::Union{Tuple{<:Integer, <:Integer}, Nothing} = nothing,
    axis = NamedTuple(),
    ncols::Union{Integer, Nothing} = nothing,
    nrows::Union{Integer, Nothing} = nothing,
    image_filter::Symbol = :clade,
    image_selector = nothing,
    image_max_pages::Union{Int, Nothing} = nothing,
    image_layout::Symbol = :blocks,
    image_rendering::Symbol = :thumbnail,
    image_label = :BASICFIELDS,
    labeljoin::AbstractString = "\n",
    label_lines::Union{Int, Nothing} = nothing,
    kwargs...,
) -> Makie.Figure

Create a new figure containing a silhouette-grid gallery for taxon.

The initial figure size is estimated from DEFAULT_THUMBNAIL_GRID_MAX_COLUMNS (width) and length(taxon) (height). After all images are placed both dimensions are corrected from the actual axis limits so that cell proportions remain consistent. Pass figure_size to fix both dimensions and bypass the auto-resize.

See phylopic_thumbnail_grid! for full documentation.

Returns the created Makie.Figure.

source

phylopic_thumbnail_grid(
    taxon_name::AbstractString;
    kwargs...,
) -> Makie.Figure

Single-taxon convenience wrapper. Equivalent to phylopic_thumbnail_grid([taxon_name]; kwargs...).

See phylopic_thumbnail_grid for full keyword documentation.

source

phylopic_thumbnail_grid(
    table;
    taxon,
    kwargs...,
) -> Makie.Figure

Table-oriented factory variant. Extracts taxon column and calls the vector factory.

source