PixelNebula

中文 | English

🚀 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.

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:

go get github.com/landaiqing/go-pixelnebula

---

🚀 Quick Start

Basic Usage

Below is a basic example of generating a simple SVG avatar:

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

// Custom style
customStyles := []style.StyleSet{
    {
        // First custom style
        style.TypeEnv:   `<circle cx="50%" cy="50%" r="48%" fill="#FILL0;"></circle>`,
        style.TypeHead:  `<circle cx="50%" cy="50%" r="35%" fill="#FILL0;"></circle>`,
        style.TypeClo:   `<rect x="25%" y="65%" width="50%" height="30%" fill="#FILL0;"></rect>`,
        style.TypeEyes:  `<circle cx="40%" cy="45%" r="5%" fill="#FILL0;"></circle><circle cx="60%" cy="45%" r="5%" fill="#FILL1;"></circle>`,
        style.TypeMouth: `<path d="M 40% 60% Q 50% 70% 60% 60%" stroke="#FILL0;" stroke-width="2" fill="none"></path>`,
        style.TypeTop:   `<path d="M 30% 30% L 50% 10% L 70% 30%" stroke="#FILL0;" stroke-width="4" fill="#FILL1;"></path>`,
    },
}

// 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

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

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

// 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:

cd benchmark
go test -bench=. -benchmem

For more detailed benchmark information, see 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

   • 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

   • 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

   • Create custom themes
   • Define custom styles
   • Demonstrate combining themes and styles

4. Animation Effects 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

   • Basic chainable calls
   • Chainable calls with animation
   • Direct save to file
   • Base64 conversion

6. Cache System 06_cache_system.go

   • Using default cache
   • Custom cache configuration
   • Cache monitoring functionality
   • Compressed cache examples

7. Format Conversion 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

   • 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

   git clone github.com/landaiqing/go-pixelnebula.git
   cd go-pixelnebula
   

3. Run a Single Example

   go run examples/01_basic_usage.go
   

4. Run All Examples

   for file in examples/*_*.go; do
     echo "🚀 Running: $file"
     go run $file
     echo "------------"
   done
   

5. Run Benchmarks

   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 file for details.

---

Made with ❤️ and Go

© 2025 landaiqing