animatar 1.0.1

<div align="center">
  <img src="https://github.com/luizvbo/animatar/blob/main/animatar-example.svg" width="250px"/>
</div>

<h1 align="center">Animatar</h1>

<div align="center">
  <!-- Crates.io Badges -->
  <a href="https://crates.io/crates/animatar">
    <img src="https://img.shields.io/crates/v/animatar.svg" alt="Library on crates.io">
  </a>
  <a href="https://crates.io/crates/animatar-cli">
    <img src="https://img.shields.io/crates/v/animatar-cli.svg" alt="CLI on crates.io">
  </a>
  <!-- CI Badge -->
  <a href="https://github.com/luizvbo/animatar/actions/workflows/rust-ci.yml">
    <img src="https://github.com/luizvbo/animatar/actions/workflows/rust-ci.yml/badge.svg" alt="CI Status">
  </a>
</div>

<br>

A blazingly fast, type-safe Rust port of the popular
[animal-avatar-generator](https://github.com/roma-lukashik/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`:

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

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

```rust
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](https://github.com/YOUR_USERNAME/animatar/releases) page.

#### Installation via Cargo

```bash
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.

```bash
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:

```bash
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](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](https://github.com/roma-lukashik/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](LICENSE)
file for details.