API Reference

MakiePatterns

A Julia package for using raster pattern fills with Makie plotting.

Features

• Auto-registration of pattern files from package assets
• Efficient caching of loaded patterns
• Convenient patternpoly! function for choropleth-style maps
• Support for custom downsample factors to control pattern scale

Quick Start

using MakiePatterns, GeoMakie, CairoMakie

# See available patterns
patterns = available_patterns()

# Create a pattern
pat = pattern(:p701)

# Use in a plot
poly!(ax, geometry; color=pat, strokewidth=0.5)

# Or use the convenience function for multiple bins
patternpoly!(ax, geometries, bins;
             patterns=[:p701, :p610, :p710, :p643])

Exports

• register_pattern!: Manually register a pattern
• available_patterns: List all registered patterns
• load_pattern_defaults: Load pattern metadata from TOML
• auto_register_patterns!: Auto-register all patterns from artifact
• make_pattern: Load and downsample a pattern
• pattern: Create a Makie.Pattern from a registered pattern
• patternpoly!: Plot geometries with pattern fills by bin
• clear_pattern_cache!: Clear the pattern cache

register_pattern!(name::Symbol, filename::AbstractString; default_factor::Int=3)

Register a pattern with a given name, filename, and default downsample factor.

Arguments

• name::Symbol: The pattern name (e.g., :p701)
• filename::AbstractString: The pattern filename (e.g., "701.png")
• default_factor::Int=3: Default downsample factor (larger = smaller pattern)

Returns

The pattern name symbol.

Examples

register_pattern!(:p701, "701.png"; default_factor=3)

available_patterns()

Return a sorted vector of all registered pattern names.

Examples

patterns = available_patterns()
# [:p601, :p610, :p643, ...]

auto_register_patterns!(; defaults=load_pattern_defaults(), overwrite=true)

Scan the patterns artifact directory and register all eligible pattern files.

Arguments

• defaults::Dict{String,Int}: Maps filenames to default downsample factors
• overwrite::Bool=true: If true, overwrites existing registrations

Returns

A sorted list of all registered pattern names.

Examples

# Auto-register all patterns with defaults from patterns.toml
auto_register_patterns!()

# Get list of available patterns
patterns = available_patterns()

load_pattern_defaults(; filename="patterns.toml")

Load default downsample factors from a TOML file in the patterns artifact.

TOML Format

default_factor = 3

["701.png"]
factor = 3

["610.png"]
factor = 4

Returns

A Dict{String,Int} mapping filenames to their default factors. The special key "__DEFAULT__" contains the global default factor if specified.

Examples

defaults = load_pattern_defaults()
factor = get(defaults, "701.png", 3)

make_pattern(name::Symbol; factor=nothing, cache=true)

Load and downsample a registered pattern by name.

Arguments

• name::Symbol: The pattern name (must be registered)
• factor::Union{Nothing,Int}=nothing: Downsample factor (larger = smaller pattern). If nothing, uses the registered default factor.
• cache::Bool=true: Whether to cache the loaded pattern

Returns

A downsampled matrix suitable for use with Makie.Pattern.

Details

The downsampling takes every factorth row and column from the loaded image, effectively making the pattern appear smaller when tiled. Larger factors produce smaller patterns.

Examples

# Load pattern with default factor
mat = make_pattern(:p701)

# Load pattern with custom factor
mat = make_pattern(:p701; factor=5)

# Load without caching
mat = make_pattern(:p701; cache=false)

pattern(name::Symbol; factor=nothing, cache=true)

Create a Makie.Pattern from a registered pattern.

Arguments

• name::Symbol: The pattern name (must be registered)
• factor::Union{Nothing,Int}=nothing: Downsample factor (larger = smaller pattern). If nothing, uses the registered default factor.
• cache::Bool=true: Whether to cache the loaded pattern

Returns

A Makie.Pattern object that can be used as a color fill in Makie plots.

Examples

# Create a pattern with default settings
pat = pattern(:p701)

# Use the pattern in a plot
poly!(ax, geometries; color=pat, strokewidth=0.5)

# Create a pattern with custom factor
pat_small = pattern(:p701; factor=10)  # smaller pattern
pat_large = pattern(:p701; factor=2)   # larger pattern

patternpoly!(ax, geoms, bins; patterns, factors=nothing, strokewidth=0.5, cache=true, kwargs...)

Plot geometries with pattern fills based on integer bin codes.

Arguments

• ax: A Makie axis (e.g., Axis, GeoAxis)
• geoms: Vector of geometries (must have same length as bins)
• bins: Vector of integer bin codes (typically 1:k)
• patterns::Vector{Symbol}: Vector of registered pattern names, indexed by bin value
• factors::Union{Nothing,Vector{Int}}=nothing: Optional vector of custom downsample factors per pattern
• strokewidth=0.5: Stroke width for polygon outlines
• cache::Bool=true: Whether to cache loaded patterns
• kwargs...: Additional keyword arguments passed to poly!

Returns

The axis object.

Details

This function simplifies the process of creating choropleth-style maps with pattern fills. Instead of manually calling poly! for each bin, you can specify all patterns at once and the function handles the grouping and plotting.

Examples

using MakiePatterns, GeoMakie, CairoMakie

# Assuming you have a GeoDataFrame `df` with a `geometry` column
# and a `bins` column with values 1:8

f = Figure(size=(3200, 2400))
ga = GeoAxis(f[1, 1]; dest="EPSG:5070")
hidedecorations!(ga)

# Plot with 8 different patterns
patternpoly!(ga, df.geometry, df.bins;
             patterns=[:p701, :p610, :p710, :p643, :p656, :p601, :p707, :p717],
             strokewidth=0.5)

f

# Use custom factors for specific patterns
patternpoly!(ga, df.geometry, df.bins;
             patterns=[:p701, :p610, :p710, :p643],
             factors=[3, 4, 6, 4],
             strokewidth=0.5)

clear_pattern_cache!()

Clear all cached pattern matrices.

Examples

clear_pattern_cache!()