animatar 1.0.1

A blazingly fast, type-safe Rust port of the popular animal-avatar-generator library.

This project generates unique, deterministic SVG animal avatars from a seed string. It is a 1:1 port, ensuring that a given seed produces the exact same avatar as the original JavaScript library.

It can be used as both a Rust library in your own projects and as a standalone command-line tool.

✨ Features

Blazingly Fast: Generate thousands of avatars in a fraction of a second, thanks to Rust's performance.
Type-Safe: Leverage Rust's strong type system for robust and reliable avatar generation.
Dual Usage: Use it as a library (animatar) in your Rust apps, or as a standalone CLI tool (animatar-cli).
Deterministic: Guarantees the same avatar for the same seed string, compatible with the original JS version.
Fully Customizable: Control the size, shape, colors, and more.

🚀 Usage

This project is split into two crates: a library and a command-line tool.

As a Library (`animatar`)

Add the library to your project's Cargo.toml:

[dependencies]
animatar = "1.0.0" # Replace with the latest version

Then, use the avatar function to generate an SVG string:

use animatar::{avatar, AvatarOptions};

fn main() {
    // Use default options
    let svg_default = avatar("my-seed-string", &AvatarOptions::default());

    // Or, customize the options
    let custom_options = AvatarOptions {
        size: 400,
        round: false,
        avatar_colors: &["#c27f5b", "#734933"],
        background_colors: &["#f2d3b8"],
        ..Default::default()
    };
    let svg_custom = avatar("another-seed", &custom_options);

    println!("{}", svg_custom);
    // <svg ...>...</svg>
}

As a Command-Line Tool (`animatar-cli`)

You can install the CLI directly from crates.io or download pre-compiled binaries from the GitHub Releases page.

Installation via Cargo

cargo install animatar-cli

Basic Usage

Provide a seed string as a positional argument. The SVG output is printed to standard output, so you can redirect it to a file.

animatar-cli "my-favorite-seed" > avatar.svg

Advanced Usage

Use flags to customize the output. For example, to create a 500px square avatar with custom colors:

animatar-cli "custom-avatar" \
  --size 500 \
  --no-round \
  --avatar-colors="#ff0000,#00ff00" \
  --background-colors="#000000" \
  > square_avatar.svg

⚙️ Configuration Options

All options are available in both the library (AvatarOptions struct) and the CLI.

Option	Type	CLI Flag	Default	Description
`seed`	`String`	(positional)	(required)	The input string used to generate the avatar.
`size`	`u32`	`--size <SIZE>`	`150`	Avatar size in pixels.
`round`	`bool`	`--no-round`	`true`	Use a round shape. The flag makes it square.
`blackout`	`bool`	`--no-blackout`	`true`	Apply a subtle blackout effect to the right side.
`avatar_colors`	`Vec<&str>`	`--avatar-colors <COLORS>`	`['#d7b89c', ...]`	Comma-separated list of hex colors for the avatar.
`background_colors`	`Vec<&str>`	`--background-colors <COLORS>`	`['#fcf7d1', ...]`	Comma-separated list of hex colors for the background.

🤝 Contributing

Contributions are welcome! This project is set up with a full suite of automated checks to ensure high code quality.

Please read the CONTRIBUTING.md file for guidelines on how to set up your development environment and submit a pull request.

🙏 Acknowledgements

This project is a Rust port of the excellent animal-avatar-generator TypeScript library by Roman Lukashik.

The core logic, SVG shapes, and overall concept are based entirely on the original work. Please be sure to check out and star the original repository!

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.