ezu-paint

Rendering primitives + built-in node implementations for the ezu workspace.

This crate sits between the low-level brush engine (hokusai) / 2D rasterizer (tiny-skia) / blur (libblur) and the graph evaluator (ezu-graph).

Three things live here:

1. Paint primitives — functions that take a Canvas and feature data and produce pixels. Reusable on their own.
2. nodes module — NodeFactory implementations for each built-in op, grouped into raster, source, paint, geometry, scalar, util submodules. Each op self-registers via ezu_graph::submit_node!; default_registry() just collects everything via NodeRegistry::from_inventory().
3. host module — host-side glue: ready-made AssetLoader implementations (BrushBankLoader for document-scoped images / brushes, TileLoader for per-tile feature overlays), and conversions from RasterBuf to PNG / straight RGBA.

How a style paints

An ezu style is a typed node DAG, not an ordered layer list. Every operation below is a node, and ports are statically type-checked across seven kinds — Features, Raster, Sprite, Brush, Scalar, Labels, ScalarField (see ezu-graph for what each carries). Ports list the kinds they accept, so polymorphic ops (e.g. blur over Raster/Sprite) pass the input kind straight through, and intermediate buffers are cached and reusable across tiles.

Tile-pyramid inputs go beyond vectors: dem sources feed elevation as a ScalarField, and raster sources feed RGBA imagery (XYZ / TileJSON / PMTiles; satellite photos, pre-rendered basemaps) as a seam-free padded Raster — so any filter chain can post-process a photo basemap (photo-pop.json posterizes 国土地理院 aerial imagery). External inputs — images, brushes, fonts, per-tile MVT/GeoJSON feature layers — enter through one uniform AssetLoader trait (see Host glue); the schemes a style names them with are documented in the ezu-style README.

Example: a watercolor water layer with a brushed road on top of an earth-tone background, composited bottom-to-top with stack.

{
  "name": "demo",
  "pad": 24,
  "sources": {
    "glazing":  { "type": "brush", "src": "file:brushes/watercolor_glazing.myb" },
    "basemap":  { "type": "mvt", "url": "https://papers.reearth.land/protomaps/tilejson.json" }
  },
  "nodes": {
    "bg":      { "op": "solid", "color": "#fbf6e6" },
    "earth":   { "op": "features", "layer": "earth" },
    "earth_p": { "op": "fill-solid", "features": "@earth", "fill": "#e8d9b0" },
    "water":   { "op": "features", "layer": "water" },
    "water_p": { "op": "fill-dabs", "features": "@water",
                 "color": "#5876a0", "opacity": 0.22,
                 "radius-px": 7, "spacing-px": 3 },
    "roads":   { "op": "features", "layer": "roads",
                 "filter-expr": ["==", ["get", "kind_detail"], "motorway"] },
    "brush":   { "op": "brush-file", "src": "@glazing" },
    "roads_p": { "op": "line", "features": "@roads", "brush": "@brush",
                 "color": "#4a3424", "radius-px": 2.6 },
    "out":     { "op": "stack", "layers": ["@bg", "@earth_p", "@water_p", "@roads_p"] }
  },
  "output": "@out"
}

stack composites its layers with plain source-over; reach for blend when you want a specific blend mode, a composite operator, or a clipping mask:

"paper":  { "op": "solid", "color": "#fbf6e6" },
"shaded": { "op": "blend", "base": "@paper", "over": "@ink", "mode": "multiply" }

The full reference watercolor style is in crates/ezu/examples/styles/watercolor.json.

Paint primitives

For fill-dabs the polygon is rasterized to a binary mask, then a regular grid of candidate positions is iterated; no brush trajectory is constructed, which is what keeps fills seamless across tile boundaries.

Stroke curves on line

line exposes four optional stroke curves that vary brush behavior along each polyline, so strokes can simulate taper-in / taper-out and speed dynamics rather than running at constant pressure and rhythm:

Each curve is a piecewise-linear [[t, y], ...] where t is normalized progress along the polyline (t = 0 at the first vertex, t = 1 at the last). t values must be non-decreasing; at least two points are required. Evaluation matches libmypaint's InputMapping::eval (clamps below the first knot, extrapolates from the last segment).

When any of the brush-side curves (radius / opacity / hardness) is set, paint_lines clones the brush per polyline and auto-sets stroke_duration_logarithmic = ln(line_length_px) so the brush's internal stroke input ramps from 0 → 1 over the full polyline length on the rendered canvas. dtime-stroke-curve doesn't need a clone — it scales the per-vertex dtime directly.

Example: ink-style taper (thin → fat → thin, faster in the middle):

"roads_primary": {
  "op": "line", "features": "@roads_primary_f", "brush": "@glazing_brush",
  "color": "#3a2a18",
  "radius-stroke-curve":  [[0.0, -1.5], [0.15, 0.0], [0.85, 0.0], [1.0, -2.0]],
  "opacity-stroke-curve": [[0.0, -0.3], [0.1,  0.0], [0.9,  0.0], [1.0, -0.4]],
  "dtime-stroke-curve":   [[0.0, 3.0],  [0.15, 1.0], [0.85, 1.0], [1.0, 4.0]]
}

Built-in nodes

ezu_paint::nodes::default_registry() returns a NodeRegistry preloaded with:

Raster utility (nodes::raster)

Sources (nodes::source)

Feature paint (nodes::paint)

Geometry ops (nodes::geometry) — turf.js-flavored transforms, mostly Features → Features

Scalars (nodes::scalar) — computed values for any scalar field

Utility (nodes::util)

Each factory implements NodeFactory::schema() so editors picking up the registry-derived JSON Schema get per-op autocomplete. Adding a new op means dropping a file under the right category and ending it with ezu_graph::submit_node!(MyFactory); — no central list to edit. Downstream crates can register custom ops on top of default_registry().

Text labels

The text node renders labels the way MapLibre's symbol layer does, from vector features:

• Shaping — rustybuzz (a pure-Rust HarfBuzz port) shapes each label; placement: point labels each feature point, placement: line / line-center walks each polyline with tangent-rotated glyphs. Layout knobs mirror MapLibre — justify, anchor / anchor-variants (variable anchor), offset-em, max-width-em (wrapping), letter-spacing-em, spacing-px, max-angle-deg, keep-upright.
• Two glyph backends — the font fallback stack names font and/or glyphs sources:
  • a font source supplies outline font bytes (TTF / OTF / TTC), which ezu shapes and rasterises into an SDF itself. Its url is a font file (file:, http(s)://, data:) or an installed-font reference (system:, below).
  • a glyphs source is a MapLibre glyph-PBF endpoint — a {fontstack} / {range} URL template serving pre-rendered 24 px SDF glyphs in 256-codepoint ranges, fetched lazily per range. This is the exact glyph data maplibre-gl-js itself draws, so a translated style can label with zero font files.
• SDF drawing — glyphs are composited from signed-distance fields, so the size, color, and halo (halo-color, halo-width) are all cheap runtime parameters. Every paint property has an optional *-expr sibling (color-expr, size-expr, halo-width-expr, …) evaluated per feature.
• Deterministic collision — collision is on by default and is deterministic across tile boundaries: candidates come from this tile plus its 8 neighbours (host-bound under <source>.<layer>@dx,dy), deduped and placed greedily by symbol-sort-key, so a label straddling a tile edge is placed or dropped identically in both tiles. Set the node's source / layer (the upstream feature source) to enable neighbour gathering; without them collision is centre-tile-only. allow-overlap / ignore-placement / padding-px mirror MapLibre.
• Shared cross-layer placement & icons — label layers can split into text-labels (candidates) feeding one label-placement node, with a text-draw per layer painting its winners: every layer's labels then collide in one index, placed top layer first with ties broken by tile feature order, as MapLibre does. A point symbol's icon places with its text as one unit — icon-size/-anchor/-offset/ -padding, overlap flags, text-optional / icon-optional, and icon-text-fit with nine-slice sprite stretching are all honoured.

ezu translate emits exactly this shape from a MapLibre symbol layer; see the ezu-translate README for the property mapping and the known divergences.

The system: font scheme

A font source can resolve a face from the machine's installed fonts by family name instead of shipping bytes:

"sans": { "type": "font",
          "url": "system:Arial Unicode MS?weight=700&style=italic" }

The family may contain literal spaces or be percent-encoded; weight (100–900, default 400) and style (normal / italic / oblique) are optional query params. A system: reference makes the recipe machine-dependent — the same family resolves to whatever face that machine has installed, so glyph shapes and character coverage can differ across environments, and it is unavailable in the browser/wasm host (supply font bytes there). Reference a font file for a fully portable, reproducible recipe.

{
  "name": "labels",
  "sources": {
    "basemap": { "type": "mvt", "url": "https://papers.reearth.land/protomaps/tilejson.json" },
    "sans":    { "type": "font", "url": "system:Helvetica" }
  },
  "nodes": {
    "bg":        { "op": "solid", "color": "#f7f4ee" },
    "places":    { "op": "features", "source": "basemap", "layer": "places" },
    "place_lbl": { "op": "text", "features": "@places",
                   "source": "basemap", "layer": "places",
                   "font": ["sans"],
                   "text": ["get", "name"],
                   "size": 14,
                   "color": "#333333",
                   "halo-color": "#ffffff", "halo-width": 1.2,
                   "color-expr": ["match", ["get", "kind"], "city", "#111111", "#555555"] },
    "out":       { "op": "stack", "layers": ["@bg", "@place_lbl"] }
  },
  "output": "@out"
}

Brushes

Nothing is bundled into the library — a style references every brush it uses through a src in its sources block, and the host loads it from disk, HTTP, or an inline data: payload. Any MyPaint .myb brush works; brush-solid synthesizes a crisp constant-width one when no file is wanted.

The example styles ship their brushes alongside the style JSON in crates/ezu/examples/styles/brushes/ and reference them by relative file: path (resolved against the style file's directory); those are CC0 brushes by David Revoy from mypaint/mypaint-brushes (attribution in brushes/CREDITS.md).

Canvas

pub struct Canvas { /* … */ }
impl Canvas {
    pub fn new_padded(tile_w: u32, tile_h: u32, pad: u32) -> Self;
    pub fn pixmap(&self) -> &tiny_skia::Pixmap;
    pub fn pixmap_mut(&mut self) -> &mut tiny_skia::Pixmap;
    pub fn into_pixmap(self) -> tiny_skia::Pixmap;          // zero-copy handoff
    // accessors for width / height / tile_width / tile_height / pad
}

The canvas paints into a padded buffer (tile + 2 * pad) so blurs extend cleanly through the tile edge and MVT buffer geometry that overflows [0, extent] lands inside the buffer. Internal node impls construct a Canvas, paint into it, then into_pixmap().take() to hand the pixel Vec<u8> to the graph layer without a memcpy.

Host glue

use ezu_paint::host::{BrushBankLoader, TileLoader, raster_to_png, raster_to_webp, raster_to_rgba8};

let mut assets = BrushBankLoader::new().with_dir("assets/brushes".into());
assets.insert("watercolor_glazing", hokusai::myb::from_str(&myb_json)?);

// Per render, overlay tile-scoped feature layers on top of the base
// loader. `bind_mvt` registers every layer under
// `<source>.<layer-name>` so the style's `features` nodes
// (`source: "basemap", layer: "earth"`) resolve to it.
let mut tile_loader = TileLoader::new(&assets, tile_id);
tile_loader.bind_mvt("basemap", ezu_features::mvt::decode(&bytes)?);

let ev = Evaluator::new(&graph, &cache, &tile_loader);
let raster = ev.render(tile_id, canvas, &params, seed)?;
let png  = raster_to_png(&raster, tile_size, pad)?;       // cropped + PNG
let webp = raster_to_webp(&raster, tile_size, pad)?;      // cropped + lossless WebP
let rgba = raster_to_rgba8(&raster, tile_size, pad);      // cropped, straight RGBA
// `crop_to_png` / `crop_to_webp` / `crop_to_rgba8` take a width and a
// height, for a canvas that is not a square tile (a legend swatch).

BrushBankLoader implements AssetLoader for document-scoped images and brushes (in-memory + disk fallback). TileLoader is a per-render overlay that adds tile-scoped feature bindings on top of any base loader. Both compose freely with custom AssetLoader impls.

Tile binding convention

Anything the style's features / dem node references is expected to be bound by the host once per tile. TileLoader::bind_mvt("<source>", decoded) walks every layer in a decoded MVT and registers each one under <source>.<layer-name>, matching the features node's source + layer fields. DEM bindings use the bare source name to match the dem node's source field. Custom bindings (GeoJSON, in- memory synthesized data, …) go through bind_features(<key>, layer) where <key> is whatever string the style references.

Names that look like asset srcs — those with a scheme: prefix (builtin:, file:, http(s)://) — bypass the per-tile bindings and flow through to the base loader, which is where document-scoped image / brush assets live. Unbound names without a scheme surface as NotFound; the features op treats that as an empty layer so sparse / partial-layer tiles render cleanly.

raster_to_png / raster_to_webp / raster_to_rgba8 all crop the padded buffer down to the central tile region before encoding / demultiplying. WebP uses the pure-Rust image-webp codec (lossless only) — no native deps. A pixmap_to_webp(&tiny_skia::Pixmap) helper covers non-tile-sized outputs (e.g. CLI bbox mosaics).

DEM sources (feature http)

host::dem ports the same sources-driven pattern to raster-DEM tiles. build_dem_sources(doc) walks the style's sources block, building one fetcher (terrarium or mapbox-rgb, PNG or WebP) per declared source; bind_dem_sources(&mut tile_loader, &registry, tile, canvas) fetches the 3×3 neighbourhood (date-line-wrapping in X, edge-clamping in Y), bilinear-resamples it onto the padded canvas, and binds the resulting ScalarField under the bare source name so the style's dem node (source: "<name>") picks it up. Requests beyond the source's max-zoom upsample from the appropriate ancestor tile. Decoded tiles are cached unboundedly per source — well-suited to single-tile and modest-pyramid renders; swap in an LRU bound if working sets ever outgrow memory.

Features

• parallel — pull-through to ezu-graph/parallel (Rayon within-tile evaluation). No effect on the paint primitives themselves; the hot loops inside hokusai are still single-threaded.
• http — enable host::prefetch_doc_assets (walks a parsed Document's assets block, fetches every http(s):// src with reqwest, and stages the decoded brush / image into a BrushBankLoader) and the host::dem module (raster-DEM tile fetcher + 3×3 stitch + overzoom upsampling that feeds the ScalarField port). Off by default so wasm32 keeps its dep graph minimal (the JS host fetches assets directly there).

License

MIT or Apache-2.0, at your option.