{"id":13774444,"url":"https://github.com/flother/spreet","last_synced_at":"2025-12-24T17:35:14.251Z","repository":{"id":38823368,"uuid":"465756978","full_name":"flother/spreet","owner":"flother","description":"Create a spritesheet from a set of SVG images","archived":false,"fork":false,"pushed_at":"2025-04-13T17:17:54.000Z","size":311,"stargazers_count":125,"open_issues_count":6,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-07T13:02:48.967Z","etag":null,"topics":["cartography","cli","mapbox-gl-js","maplibre","maplibre-gl-js","rust-lang"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flother.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-03-03T14:38:12.000Z","updated_at":"2025-05-01T08:39:35.000Z","dependencies_parsed_at":"2023-10-01T23:32:29.617Z","dependency_job_id":"c80e8f66-c4d6-42f0-b19f-246d88211a2c","html_url":"https://github.com/flother/spreet","commit_stats":{"total_commits":120,"total_committers":4,"mean_commits":30.0,"dds":0.09999999999999998,"last_synced_commit":"d177246e251ea80aff22ebc92e340fc298c314ed"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flother%2Fspreet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flother%2Fspreet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flother%2Fspreet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flother%2Fspreet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flother","download_url":"https://codeload.github.com/flother/spreet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509477,"owners_count":22082891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cartography","cli","mapbox-gl-js","maplibre","maplibre-gl-js","rust-lang"],"created_at":"2024-08-03T17:01:26.802Z","updated_at":"2025-12-24T17:35:14.245Z","avatar_url":"https://github.com/flother.png","language":"Rust","funding_links":[],"categories":["Map Styling"],"sub_categories":["Sprite Generation"],"readme":"# Spreet: create spritesheets from SVGs\n\nSpreet is a command-line tool that creates a [spritesheet](https://en.wikipedia.org/wiki/Spritesheet) (aka texture atlas) from a directory of SVG images. You'll need this when you create [MapLibre](https://maplibre.org/) or [Mapbox](https://docs.mapbox.com/) vector web maps, where cartographic stylesheets require that [icons be loaded from a spritesheet](https://maplibre.org/maplibre-gl-js-docs/style-spec/sprite/).\n\nCompared to other tools for creating spritesheets from SVGs, Spreet:\n\n- outputs smaller spritesheets (both fewer pixels and fewer bytes)\n- is a self-contained ~2.2 MB binary\n- is faster\n\n_Spreet_ (also _spreit_, _spret_, _sprit_) is the [Scots](https://en.wikipedia.org/wiki/Scots_language) word for a sprite, the fairy-like creature from Western folklore.\n\n[![CI status](https://github.com/flother/spreet/actions/workflows/ci.yml/badge.svg)](https://github.com/flother/spreet/actions/workflows/ci.yml)\n[![Latest release](https://img.shields.io/github/v/release/flother/spreet)](https://github.com/flother/spreet/releases)\n\n## Table of contents\n\n- [Installation](#installation)\n- [Tutorial](#tutorial)\n- [Command-line usage](#command-line-usage)\n- [Using Spreet as a Rust library](#using-spreet-as-a-rust-library)\n- [Benchmarks](#benchmarks)\n\n## Installation\n\nYou can install Spreet using Homebrew, `cargo install`, by downloading pre-built binaries, or by building from source.\n\n### Homebrew\n\nIf you use [Homebrew](https://brew.sh/) on MacOS or Linux you can install Spreet from the command-line:\n\n```\nbrew install flother/taps/spreet\n```\n\n(You can review [the code run by the formula](https://github.com/flother/homebrew-taps/blob/master/spreet.rb) before you install.)\n\n### Installing from crates.io (`cargo install`)\n\nRust's `cargo install` command lets you install a binary crate locally. You can install the latest published version of Spreet with:\n\n```\ncargo install spreet\n```\n\n### Download pre-built binaries\n\nPre-built binaries are provided for MacOS, Linux, and Windows. The MacOS and Linux binaries are built for both Intel and ARM CPUs. Visit the [releases](https://github.com/flother/spreet/releases) page to download the latest version of Spreet.\n\n### Using via Docker\n\nIf you have [Docker](https://www.docker.com/) installed, you can run Spreet without installing it locally. The Docker image is available from the GitHub Container Registry:\n\n```term\ndocker run \\\n    -v $(pwd)/icons:/app/icons \\\n    -v $(pwd):/app/output \\\n    ghcr.io/flother/spreet \\\n    icons \\\n    output/my_style\n```\n\nThis command mounts your local `icons` directory to `/app/icons` inside the container, and your current local directory to `/app/output` for writing the generated files. Replace `$(pwd)/icons` with your actual input directory, and `my_style` with your desired output filename. The spritesheet and index file will be created in your current directory.\n\n### Build from source\n\nYou'll need a recent version of the Rust toolchain (try [Rustup](https://rustup.rs/) if you don't have it already). With that, you can check out this repository:\n\n    git clone https://github.com/flother/spreet\n    cd spreet\n\nAnd then build a release:\n\n    cargo build --release\n\nOnce finished, the built binary will be available as `./target/release/spreet`.\n\n## Tutorial\n\nWhen you're making your own style for a vector map, you'll have icons that you want to appear on top of the map. Symbols for roads or icons for hospitals and schools — that sort of thing. You'll have a directory of SVGs (like the [`icons` directory in the osm-bright-gl-style](https://github.com/openmaptiles/osm-bright-gl-style/tree/8af4769692d0f9219d0936711609d580b34bf365/icons)) and you'll want to convert them into a single raster image (like the [spritesheet from osm-bright-gl-style](https://github.com/openmaptiles/osm-bright-gl-style/blob/03a529f9040cfdfd3a30fb6760fc96d0ae41cf39/sprite%402x.png)).\n\nLet's say you have a directory of SVGs named `icons` and you want to create a spritesheet named `my_style.png`. Run Spreet like this:\n\n    spreet icons my_style\n\nSpreet will also create an [index file](https://docs.mapbox.com/mapbox-gl-js/style-spec/sprite/#index-file) named `my_style.json` that contains a description of the dimensions and location of each image contained in the spritesheet.\n\nIf you want to create a \"retina\" version of the spritesheet named `my_style@2x.png`, use the `--retina` option:\n\n    spreet --retina icons my_style@2x\n\nYou might have multiple copies of the same icon — for example, you might use the same \"open book\" icon for both libraries (`library.svg`) and bookshops (`bookshop.svg`). If you pass the `--unique` option, Spreet will include only the icon once in the spritesheet, but reference it twice from the index file. This helps reduce the size of your spritesheet.\n\n    spreet --retina --unique icons my_style@2x\n\nBy default the JSON index file is pretty-printed, but you can minify it with the `--minify-index-file` option:\n\n    spreet --retina --unique --minify-index-file icons my_style@2x\n\nWhen you create a spritesheet for your production environment, use `--unique --minify-index-file` for best results.\n\n## Command-line usage\n\n```\n$ spreet --help\nCreate a spritesheet from a set of SVG images\n\nUsage: spreet [OPTIONS] \u003cINPUT\u003e \u003cOUTPUT\u003e\n\nArguments:\n  \u003cINPUT\u003e   A directory of SVGs to include in the spritesheet\n  \u003cOUTPUT\u003e  Name of the file in which to save the spritesheet\n\nOptions:\n  -r, --ratio \u003cRATIO\u003e      Set the output pixel ratio [default: 1]\n      --retina             Set the pixel ratio to 2 (equivalent to `--ratio=2`)\n      --unique             Store only unique images in the spritesheet, and map them to multiple names\n      --recursive          Include images in sub-directories\n      --spacing \u003cSPACING\u003e  Add pixel spacing between sprites [default: 0]\n  -m, --minify-index-file  Remove whitespace from the JSON index file\n      --sdf                Output a spritesheet using a signed distance field for each sprite\n  -h, --help               Print help\n  -V, --version            Print version\n```\n\n## Using Spreet as a Rust library\n\nThe main purpose of Spreet is to be command-line tool, but you can also use it as a library in your own Rust code. To add Spreet as a dependency, include this in your `Cargo.toml`:\n\n```toml\nspreet = { version = \"0.11.0\", default-features = false }\n```\n\nTo learn how to build your spritesheets programmatically, see the [Spreet crate docs on docs.rs](https://docs.rs/spreet) and have a [look at the spritesheet tests](https://github.com/flother/spreet/blob/master/tests/sprite.rs).\n\n## Benchmarks\n\nTo compare the output from [spritezero](https://github.com/mapbox/spritezero-cli) and Spreet, benchmarks are run against SVG sprite sets from four diverse map styles: [osm-bright-gl-style](https://github.com/openmaptiles/osm-bright-gl-style), [openstreetmap-americana](https://github.com/ZeLonewolf/openstreetmap-americana), [mapbox-gl-styles (basic)](https://github.com/mapbox/mapbox-gl-styles), and [mapbox-gl-whaam-style](https://github.com/mapbox/mapbox-gl-whaam-style). Unique, retina spritesheets are output (`--unique --retina`), and Spreet also uses `--minify-index-file` (spritezero doesn't have that option).\n\n### Spritesheet size (total pixels)\n\n| Map style                | Spritezero pixels | Spreet pixels | Change |\n| :----------------------- | ----------------: | ------------: | -----: |\n| osm-bright-gl-style      |           208,810 |       130,048 |   -38% |\n| openstreetmap-americana  |           577,548 |       389,640 |   -33% |\n| mapbox-gl-styles (basic) |           271,488 |       258,064 |    -5% |\n| mapbox-gl-whaam-style    |            90,944 |        59,136 |   -35% |\n\n### Spritesheet file size (bytes)\n\n| Map style                | Spritezero file size | Spreet file size | Change |\n| :----------------------- | -------------------: | ---------------: | -----: |\n| osm-bright-gl-style      |               43,860 |           24,588 |   -44% |\n| openstreetmap-americana  |              140,401 |           78,617 |   -44% |\n| mapbox-gl-styles (basic) |               76,383 |           30,771 |   -60% |\n| mapbox-gl-whaam-style    |               17,342 |            5,037 |   -71% |\n\n### Index file size (bytes)\n\n| Map style                | Spritezero file size | Spreet file size | Change |\n| :----------------------- | -------------------: | ---------------: | -----: |\n| osm-bright-gl-style      |               10,695 |            6,957 |   -35% |\n| openstreetmap-americana  |               20,142 |           13,574 |   -33% |\n| mapbox-gl-styles (basic) |               17,013 |           11,101 |   -35% |\n| mapbox-gl-whaam-style    |                  553 |              372 |   -33% |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflother%2Fspreet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflother%2Fspreet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflother%2Fspreet/lists"}