PixelNebula

中文 | English

PixelNebula Logo

🚀 A powerful, efficient, and customizable SVG avatar generation library for Go

✨ Features • 📦 Installation • 🚀 Quick Start • 🔧 Advanced Usage • 💫 Animation Effects • ⚡ Cache System • 📊 Benchmarks • 💡 Examples and Demos • 👥 Contribution Guide • 📄 License

## 📋 Introduction

PixelNebula is a high-performance SVG avatar generation library written in Go, focused on creating beautiful, customizable, and highly animated vector avatars. With PixelNebula, you can easily generate avatars in various styles, add animation effects, and apply different themes and style variations.

Whether you're creating user avatars for applications, generating unique identifier icons, or making dynamic visual effects, PixelNebula can meet your needs.

PixelNebula Demo
Sample Avatar Display
Sample Code

## ✨ Features

Various Styles

Animation Effects

Customizable

High Performance

Cache System

- 🎨 **Various Styles and Themes**: Built-in multiple styles and theme combinations to meet different design needs - 🔄 **Rich Animation Effects**: Support for rotation, gradient, transformation, fade-in/out, and other animations - 🛠️ **Fully Customizable**: Custom styles, themes, colors, and animation effects - ⚡ **High-Performance Design**: Optimized code structure and caching mechanism for fast generation - 💾 **Smart Cache System**: Built-in cache system to improve efficiency of repetitive generation - 📊 **Cache Monitoring**: Support for cache usage monitoring and analysis - 🔍 **Chainable API**: Clean and clear API design with support for fluent chaining - 📱 **Responsive Design**: Support for custom sizes, adapting to various display environments

## 📦 Installation Using Go toolchain to install the package: ```bash go get github.com/landaiqing/go-pixelnebula ```

## 🚀 Quick Start ### Basic Usage Below is a basic example of generating a simple SVG avatar:

```go package main import ( "fmt" "os" "github.com/landaiqing/go-pixelnebula" "github.com/landaiqing/go-pixelnebula/style" ) func main() { // Create a new PixelNebula instance pn := pixelnebula.NewPixelNebula() // Set style and size pn.WithStyle(style.GirlStyle) pn.WithSize(231, 231) // Generate SVG and save to file svg, err := pn.Generate("unique-id-123", false).ToSVG() if err != nil { fmt.Printf("Failed to generate SVG: %v\n", err) return } // Save to file err = os.WriteFile("my_avatar.svg", []byte(svg), 0644) if err != nil { fmt.Printf("Failed to save file: %v\n", err) return } fmt.Println("Avatar successfully generated: my_avatar.svg") } ```

Generated Avatar Example

## 🔧 Advanced Usage ### Custom Themes and Styles

Click to Expand/Collapse Code Example

```go // Custom style customStyles := []style.StyleSet{ { // First custom style style.TypeEnv: ``, style.TypeHead: ``, style.TypeClo: ``, style.TypeEyes: ``, style.TypeMouth: ``, style.TypeTop: ``, }, } // Apply custom style pn2.WithCustomizeStyle(customStyles) // Custom theme customThemes := []theme.Theme{ { theme.ThemePart{ // Environment part colors "env": []string{"#FF5733", "#C70039"}, // Head colors "head": []string{"#FFC300", "#FF5733"}, // Clothes colors "clo": []string{"#2E86C1", "#1A5276"}, // Eyes colors "eyes": []string{"#000000", "#FFFFFF"}, // Mouth colors "mouth": []string{"#E74C3C"}, // Top decoration colors "top": []string{"#884EA0", "#7D3C98"}, }, }, } pn.WithCustomizeTheme(customTheme) ```

### Using SVGBuilder Chainable API

Click to Expand/Collapse Code Example

```go pn := NewPixelNebula().WithDefaultCache() pn.Generate("my-avatar", false). SetStyle(style.GirlStyle). SetTheme(0). SetSize(231, 231). SetRotateAnimation("env", 0, 360, 10, -1). SetGradientAnimation("env", []string{"#3498db", "#2ecc71", "#f1c40f", "#e74c3c", "#9b59b6"}, 8, -1, true). Build(). ToSVG() ```

## 💫 Animation Effects PixelNebula supports multiple animation effects to bring your avatars to life:

Rotation

Gradient

Fade In/Out

Path

Click to View Animation Code Examples

```go pn := NewPixelNebula() // Set style pn.WithStyle(style.AfrohairStyle) pn.WithTheme(0) // 1. Rotation animation - Rotate environment and head pn.WithRotateAnimation("env", 0, 360, 10, -1) // Infinite loop environment rotation // 2. Gradient animation - Environment gradient pn.WithGradientAnimation("env", []string{"#3498db", "#2ecc71", "#f1c40f", "#e74c3c", "#9b59b6"}, 8, -1, true) // 2. Gradient animation - Eyes gradient pn.WithGradientAnimation("eyes", []string{"#3498db", "#2ecc71", "#f1c40f", "#e74c3c", "#9b59b6"}, 8, -1, true) // 3. Fade in/out animation - Eyes blinking pn.WithFadeAnimation("eyes", "1", "0.3", 2, -1) // 4. Transform animation - Mouth scaling //pn.WithTransformAnimation("mouth", "scale", "1 1", "1.2 1.2", 1, -1) // 5. Color animation - Hair color change pn.WithColorAnimation("top", "fill", "#9b59b6", "#e74c3c", 3, -1) // 5. Color animation - Clothes color change pn.WithColorAnimation("clo", "fill", "#9b59b6", "#e74c3c", 3, -1) // 6. Bounce animation - Mouth bouncing pn.WithBounceAnimation("mouth", "transform", "0,0", "0,-10", 5, 2.5, -1) // 6. Rotation animation - Mouth rotation pn.WithRotateAnimation("mouth", 0, 360, 10, -1) // Infinite loop mouth rotation //// 7. Wave animation - Clothes wave effect //pn.WithWaveAnimation("clo", 5, 0.2, "horizontal", 4, -1) // 8. Blink animation - Top decoration blinking //pn.WithBlinkAnimation("head", 0.3, 1.0, 4, 6, -1) // 8. Wave animation - Environment wave effect //pn.WithWaveAnimation("clo", 5, 2, "horizontal", 4, -1) // 9. Path animation - Eyes moving along path //pn.WithPathAnimation("eyes", "M 0,0 C 10,-10 -10,-10 0,0", 3, -1) pn.WithBounceAnimation("eyes", "transform", "0,0", "0,-5", 5, 2, -1) // 10. Path animation with rotation - Eyes rotating while moving //pn.WithPathAnimationRotate("eyes", "M 0,0 C 5,5 -5,5 0,0", "auto", 4, -1) ```

## ⚡ Cache System PixelNebula has a built-in smart cache system to improve the efficiency of repeated generation:

Click to View Cache Configuration Code Examples

```go // Use default cache configuration pn.WithDefaultCache() // Custom cache configuration customCacheOptions := cache.CacheOptions{ Enabled: true, DirectorySize: 100, // Maximum cache entries Expiration: 1 * time.Hour, // Cache expiration time //... Other configuration options } // Create a PixelNebula instance with custom cache pn := pixelnebula.NewPixelNebula().WithCache(customCacheOptions) // Enable cache monitoring pn.WithMonitoring(cache.MonitorOptions{ Enabled: true, SampleInterval: 5 * time.Second, //... Other configuration options }) // Enable cache compression pn.WithCompression(cache.CompressOptions{ Enabled: true, Level: 6, MinSizeBytes: 100, // Minimum compression size (bytes) //... Other configuration options }) ```

## 📊 Benchmarks We have conducted comprehensive benchmark tests on PixelNebula to ensure high performance in various scenarios. Below are sample test results (Test environment: Intel i7-12700K, 32GB RAM):

Operation	Time per Operation	Memory Allocation	Allocations
Basic Avatar Generation	3.5 ms/op	328 KB/op	52 allocs/op
No-Environment Avatar	2.8 ms/op	256 KB/op	48 allocs/op
With Rotation Animation	4.2 ms/op	384 KB/op	62 allocs/op
Using Cache (Hit)	0.3 ms/op	48 KB/op	12 allocs/op
Concurrent Generation (10)	5.7 ms/op	392 KB/op	58 allocs/op

### Running Benchmarks To run benchmarks in your own environment, execute: ```bash cd benchmark go test -bench=. -benchmem ``` For more detailed benchmark information, see [benchmark/README.md](benchmark/README.md).

## 💡 Examples and Demos ### 📚 Example Code We've prepared a complete set of example code covering all core features to help you get started quickly.

Basic Usage View Code	Styles & Themes View Code	Custom Theme View Code
Animations View Code	Chain API View Code	Cache System View Code
Format Conversion View Code	Random Avatar Generator View Code	...

📋 Detailed Example Descriptions

1. **Basic Usage** [01_basic_usage.go](examples/01_basic_usage.go) - Create basic PixelNebula avatars - Generate regular avatars and no-environment avatars - Demonstrate basic configuration and error handling 2. **Styles and Themes** [02_styles_and_themes.go](examples/02_styles_and_themes.go) - Use different styles to generate avatars - Apply multiple theme combinations - Demonstrate cycling through styles and themes 3. **Custom Themes and Styles** [03_custom_theme_and_style.go](examples/03_custom_theme_and_style.go) - Create custom themes - Define custom styles - Demonstrate combining themes and styles 4. **Animation Effects** [04_all_animations.go](examples/04_all_animations.go) - Rotation animation - Gradient animation - Fade-in/out effects - Transform animation - Color transformation - Bounce effects - Wave animation - Blink effects - Path animation 5. **SVG Builder Chainable API** [05_svg_builder_chain.go](examples/05_svg_builder_chain.go) - Basic chainable calls - Chainable calls with animation - Direct save to file - Base64 conversion 6. **Cache System** [06_cache_system.go](examples/06_cache_system.go) - Using default cache - Custom cache configuration - Cache monitoring functionality - Compressed cache examples 7. **Format Conversion** [07_format_conversion.go](examples/07_format_conversion.go) - Base64 encoding - We haven't found a perfect solution for other formats yet, please feel free to make a PR 8. **Random Avatar Generator** [08_random_avatar_generator.go](examples/08_random_avatar_generator.go) - Generate random avatars with different styles and themes

### 🎮 Running Examples

📋 How to Run Examples

1. **Prerequisites** - Ensure Go is installed (Go 1.16+ recommended) - Make sure GOPATH is properly set 2. **Clone the Repository** ```bash git clone github.com/landaiqing/go-pixelnebula.git cd go-pixelnebula ``` 3. **Run a Single Example** ```bash go run examples/01_basic_usage.go ``` 4. **Run All Examples** ```bash for file in examples/*_*.go; do echo "🚀 Running: $file" go run $file echo "------------" done ``` 5. **Run Benchmarks** ```bash cd benchmark go test -bench=. -benchmem ``` **💡 Tip:** Check the top comments in each example for detailed functionality and customization options.

## 👥 Contribution Guide Contributions of code, issue reports, or suggestions are welcome! Please follow these steps:

Fork the Repository Create a Branch
git checkout -b feature/amazing-feature Commit Changes
git commit -m 'Add some feature' Push Branch
git push origin feature/amazing-feature Open PR

## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Made with ❤️ and Go