Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install sheetsmithcli

It will make the sheetsmithcli command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall sheetsmithcli uninstalls.

Back to the crate overview.

Readme

this image was created using sheetsmith 👀 (see /example directory)

SheetSmith Rust Workspace

Important

In heavy development, will change alot!

A simple sprite sheet packer written in Rust with different interfaces (CLI & GUI). It takes a directory of images and packs them into a single sprite sheet, along with metadata about the position and size of each sprite.

Important

For the shipwrights/reviewers, if you arent one then you can disregard. Last time I forgot to mention the "examples" directory, so sorry for that. Clone the repository and you have a fodlder with a fiew square sprites to test with. See CLI Examples for guidance, they work with GUI aswell ofc!

CLI Usage

Note

(only if you are using an executable and not crate) If you are on linux, you need to do chmod +x sheetsmithcli before you can run the command and prefix it with ./, if you are on windows, add ".exe" after sheetsmithcli!`

Options:

Usage: sheetsmithcli [OPTIONS]

Options:
  -i, --input-dir <INPUT_DIR>  The input directory containing the images to pack [default: input]
  -o, --output <OUTPUT>        The output file for the packed sprite sheet [default: output.png]
      --no-color               Disable color in prints
  -s, --size <SIZE>            The size of the output sprite sheet [default: 1080x1080]
  -p, --padding <PADDING>      Padding between sprites in pixels [default: 0]
      --alg <ALGORITHM>        Algorithm to use for packing. Options: guillotiere [default: guillotiere]
  -t, --trim-transparent       Trim transparent pixels from the edges of images before packing This can help GREATLY reduce the size of the output sprite sheet and improve packing efficiency
  -a, --auto-size              Automatically find a good sheet size
  -d, --debug                  Debug mode: Print more often to find problematic images
  -h, --help                   Print help
  -V, --version                Print version

Examples:

Note

Add ".exe" after sheetsmithcli if you are on windows!

sheetsmithcli -i example -o logo.png -s 896x256
- This will create the logo at the top of this readme using the sprites in /example. This folder is only there if you cloned the repository that is.
sheetsmithcli -o finished.png -s 2048x2048
- Create a sheet with the size 2048px wide and 2048px in height then fill that sheet with the images in the input directory.
sheetsmithcli -i sprites -o sheet.png -a
- Will automatically find a good sheet size for the images in the sprites directory, currently only recommended if you have square images, will be made better soon.

GUI Usage

Install with cargo install sheetsmithgui, might take a few minutes to build but you always have the sheetsmithcli crate or you can download built binaries from the releases tab! <3

Important

Refer to CLI options for explanations on parameters!

Example Output Sheet

Example Sheet

Notable Dependencies

anyhow [error handling]
egui [ui library]
colored [colorful terminal output]
clap [command-line argument parsing]
guillotiere [packing algorithm]

Flavortown Sidequests

Optimization

I have had two optimzationm techniques in mind when making this:

Efficient algorithms
- This entire project is based off an algorithm that packs the images efficiently, I've also made it possible for you to be able to select with algorithm you want to use.
Optimize asset sizes
- Theres args you can add to your command to optimize the size and layout fo your final image, you can remove transparency on the input images and you can compress the output images if you want that, theres alot to chose from.

Rusty Frontend

egui
- Insanely easy to use UI library that carries the GUI crate.

Todo

Implement other packing algorithms
Implement metadata ouput for unity
~~Fill sheet left -> right, top -> bottom instead of what the hell is currently happening~~
~~Add size optimizer that tries to find the smallest possible max_size for the output sprite sheet~~
~~Add a GUI~~
File compression

Credits

https://kenney.nl for the example sprites 👑