Pixel Avatars

A simple, customizable pixel avatar generator for Node.js applications.

Features

• Generate symmetrical pixel avatars with customizable parameters
• Deterministic generation with seed support
• Flexible sizing and resolution options
• Works both as a CLI tool and a programmatic API
• Built with TypeScript for type safety

Installation

# Using npm
npm install pixel-avatars

# Using yarn
yarn add pixel-avatars

# Using pnpm
pnpm add pixel-avatars

Usage

CLI

# Generate a basic avatar
npx pixel-avatars --filename=avatar.png

# Customize your avatar
npx pixel-avatars --colors=5 --width=512 --height=512 --pwidth=12 --pheight=12 --seed="your-custom-seed" --filename=custom-avatar.png

API

import { generateImage } from "pixel-avatars";

// Generate a basic avatar
const image = await generateImage({
  filename: "avatar.png"
});

// Generate a customized avatar
const customImage = await generateImage({
  colors: 5, // Number of colors to use
  width: 512, // Output image width in pixels
  height: 512, // Output image height in pixels
  pwidth: 12, // Pattern width (higher = more complex)
  pheight: 12, // Pattern height (higher = more complex)
  seed: "username", // Deterministic seed value
  filename: "custom-avatar.png" // Optional output filename
});

// Use with Sharp for further processing
await customImage.blur(5).toFile("blurred-avatar.png");

API Reference

generateImage(params)

Generates a pixel avatar and returns a Sharp instance.

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | colors | number | 2 | Number of colors to use in the avatar | | width | number | 256 | Width of the output image in pixels | | height | number | 256 | Height of the output image in pixels | | pwidth | number | 16 | Pattern width in cells | | pheight | number | 16 | Pattern height in cells | | seed | string | Random | Seed for deterministic generation | | filename | string | null | Output filename (if provided) |

Returns

Promise<sharp.Sharp> - A Sharp instance containing the generated image

Development

# Clone the repository
git clone https://github.com/meitrix8208/pixel-avatars.git
cd pixel-avatars

# Install dependencies
pnpm install

# Run tests
pnpm dev

# Build the package
pnpm build

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Credits

Inspired by various pixel art generators and avatar creation tools.