spritore 0.2.0

Generate MapLibre sprite sheets from SVG icons in Rust or from the command line
Documentation

spritore

spritore generates the PNG sprite sheet and JSON index used by MapLibre styles. Install its command for directory-based asset builds, or use its Rust API when your application works with SVG strings and generated bytes directly.

The CLI fits static site builds, map-style repositories, and CI jobs. The Rust API fits asset services, desktop tools, and other applications that need sprite generation as part of a larger workflow.

CLI

cargo install spritore
spritore build ./icons -o ./public/sprites

The command reads lowercase .svg files and generates these files by default:

public/sprites/
├── sprite.png
├── sprite.json
├── sprite@2x.png
└── sprite@2x.json

The complete command is:

spritore build <svg-dir> -o <out-dir> [--name sprite] [--ratio 1,2] [--fast] [--skip-invalid]
  • --name <name> changes the output basename.
  • --ratio <ratios> accepts comma-separated integers from 1 to 255.
  • --fast prioritizes generation speed over PNG file size.
  • --skip-invalid reports SVG parse errors and continues with valid icons.

Without --skip-invalid, an invalid SVG stops the command before output files are written. Icon IDs come from filename stems; characters outside a-zA-Z0-9_- become -, and collisions after conversion are errors.

Rust API

Disable default features when an application needs the library API without the command-line executable:

cargo add spritore --no-default-features

Or add it to Cargo.toml:

[dependencies]
spritore = { version = "0.2.0", default-features = false }
use spritore::{BuildOptions, build_sprite_sheet, index_to_json, render_icon};

fn main() -> Result<(), Box<dyn std::error::Error>> {
	let svg = r##"<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16">
		<circle cx="8" cy="8" r="6" fill="#4264fb" />
	</svg>"##;
	let icons = [render_icon("marker", svg, 1)?];
	let sheet = build_sprite_sheet(&icons, 1, BuildOptions::default())?;

	std::fs::write("sprite.png", sheet.png)?;
	std::fs::write("sprite.json", index_to_json(&sheet.index))?;
	Ok(())
}

Use render_icon by itself when you need RGBA pixels for MapLibre's map.addImage. Use BuildOptions { fast: true } for interactive previews; the default mode prioritizes smaller final assets.

Features

  • cli (default) builds the spritore executable.
  • --no-default-features is intended for applications that only use the Rust library API.

SVG limitations

  • External resources such as linked images and web fonts are not loaded.
  • SVG <text> is not supported because fonts are not bundled. Text elements may parse successfully but are not rendered.

License

Licensed under either Apache-2.0 or MIT, at your option.