PixelNebula

中文 | English

PixelNebula Logo

🚀 一个强大、高效且可自定义的 Go 语言 SVG 动态头像生成库

✨ 特性 • 📦 安装 • 🚀 快速开始 • 🔧 高级用法 • 💫 动画效果 • ⚡ 缓存系统 • 📊 基准测试 • 💡 示例和演示 • 👥 贡献指南 • 📄 许可证

## 📋 介绍

PixelNebula 是一个 Go 语言编写的高性能 SVG 头像生成库，专注于创建精美、可定制且高度可动态化的矢量头像。使用 PixelNebula，您可以轻松生成各种风格的头像，添加动画效果，并应用各种主题和样式变化。

无论是为应用程序创建用户头像、生成唯一标识图标，还是制作动态可视化效果，PixelNebula 都能满足您的需求。

PixelNebula Demo
示例头像展示
示例代码

## ✨ 特性

多样化风格

动画效果

可自定义

高性能

缓存系统

- 🎨 **多样化风格与主题**: 内置多种风格和主题组合，满足不同设计需求 - 🔄 **丰富动画效果**: 支持旋转、渐变、变换、淡入淡出等多种动画 - 🛠️ **完全可自定义**: 自定义风格、主题、颜色和动画效果 - ⚡ **高性能设计**: 优化的代码结构和缓存机制，确保快速生成 - 💾 **智能缓存系统**: 内置缓存系统，提高重复生成效率 - 📊 **缓存监控**: 支持缓存使用情况监控和分析 - 🔍 **链式调用 API**: 简洁明了的 API 设计，支持流畅的链式调用 - 📱 **响应式设计**: 支持自定义尺寸，适应各种显示环境

## 📦 安装使用 Go 工具链安装包： ```bash go get github.com/landaiqing/go-pixelnebula ```

## 🚀 快速开始 ### 基本用法以下是生成简单 SVG 头像的基本示例：

```go package main import ( "fmt" "os" "github.com/landaiqing/go-pixelnebula" "github.com/landaiqing/go-pixelnebula/style" ) func main() { // 创建一个新的 PixelNebula 实例 pn := pixelnebula.NewPixelNebula() // 设置风格和尺寸 pn.WithStyle(style.GirlStyle) pn.WithSize(231, 231) // 生成 SVG 并保存到文件 svg, err := pn.Generate("unique-id-123", false).ToSVG() if err != nil { fmt.Printf("生成 SVG 失败: %v\n", err) return } // 保存到文件 err = os.WriteFile("my_avatar.svg", []byte(svg), 0644) if err != nil { fmt.Printf("保存文件失败: %v\n", err) return } fmt.Println("头像成功生成: my_avatar.svg") } ```

生成的头像示例

## 🔧 高级用法 ### 自定义主题和风格

点击展开/折叠代码示例

```go // 自定义风格 customStyles := []style.StyleSet{ { // 第一种自定义风格 style.TypeEnv: ``, style.TypeHead: ``, style.TypeClo: ``, style.TypeEyes: ``, style.TypeMouth: ``, style.TypeTop: ``, }, } // 应用自定义风格 pn2.WithCustomizeStyle(customStyles) // 自定义主题 customThemes := []theme.Theme{ { theme.ThemePart{ // 环境部分颜色 "env": []string{"#FF5733", "#C70039"}, // 头部颜色 "head": []string{"#FFC300", "#FF5733"}, // 衣服颜色 "clo": []string{"#2E86C1", "#1A5276"}, // 眼睛颜色 "eyes": []string{"#000000", "#FFFFFF"}, // 嘴巴颜色 "mouth": []string{"#E74C3C"}, // 头顶装饰颜色 "top": []string{"#884EA0", "#7D3C98"}, }, }, } pn.WithCustomizeTheme(customTheme) ```

### 使用 SVGBuilder 链式调用

点击展开/折叠代码示例

```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() ```

## 💫 动画效果 PixelNebula 支持多种动画效果，可以让您的头像栩栩如生：

旋转动画

渐变动画

淡入淡出

路径动画

...

点击查看动画代码示例

```go pn := NewPixelNebula() // 设置风格 pn.WithStyle(style.AfrohairStyle) pn.WithTheme(0) // 1. 旋转动画 - 让环境和头部旋转 pn.WithRotateAnimation("env", 0, 360, 10, -1) // 无限循环旋转环境 // 2. 渐变动画 - 让环境渐变 pn.WithGradientAnimation("env", []string{"#3498db", "#2ecc71", "#f1c40f", "#e74c3c", "#9b59b6"}, 8, -1, true) // 2. 渐变动画 - 让眼睛渐变 pn.WithGradientAnimation("eyes", []string{"#3498db", "#2ecc71", "#f1c40f", "#e74c3c", "#9b59b6"}, 8, -1, true) // 3. 淡入淡出动画 - 让眼睛闪烁 pn.WithFadeAnimation("eyes", "1", "0.3", 2, -1) // 4. 变换动画 - 让嘴巴缩放 //pn.WithTransformAnimation("mouth", "scale", "1 1", "1.2 1.2", 1, -1) // 5. 颜色变换动画 - 让头发颜色变换 pn.WithColorAnimation("top", "fill", "#9b59b6", "#e74c3c", 3, -1) // 5. 颜色变换动画 - 让衣服颜色变换 pn.WithColorAnimation("clo", "fill", "#9b59b6", "#e74c3c", 3, -1) // 6. 弹跳动画 - 让嘴巴弹跳 pn.WithBounceAnimation("mouth", "transform", "0,0", "0,-10", 5, 2.5, -1) // 6. 旋转动画 - 让嘴巴旋转 pn.WithRotateAnimation("mouth", 0, 360, 10, -1) // 无限循环旋转环境 //// 7. 波浪动画 - 让衣服产生波浪效果 //pn.WithWaveAnimation("clo", 5, 0.2, "horizontal", 4, -1) // 8. 闪烁动画 - 让头顶装饰闪烁 //pn.WithBlinkAnimation("head", 0.3, 1.0, 4, 6, -1) // 8. 波浪动画 - 让环境产生波浪效果 //pn.WithWaveAnimation("clo", 5, 2, "horizontal", 4, -1) // 9. 路径动画 - 让眼睛沿着路径移动 //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. 带旋转的路径动画 - 让眼睛在移动的同时旋转 //pn.WithPathAnimationRotate("eyes", "M 0,0 C 5,5 -5,5 0,0", "auto", 4, -1) ```

## ⚡ 缓存系统 PixelNebula 内置智能缓存系统，提高重复生成的效率。

点击查看缓存配置代码示例

```go // 使用默认缓存配置 pn.WithDefaultCache() // 自定义缓存配置 customCacheOptions := cache.CacheOptions{ Enabled: true, DirectorySize: 100, // 最大缓存条目数 Expiration: 1 * time.Hour, // 缓存有效期 //... 其他配置项 } // 创建一个带自定义缓存的PixelNebula实例 pn := pixelnebula.NewPixelNebula().WithCache(customCacheOptions) // 启用缓存监控 pn.WithMonitoring(cache.MonitorOptions{ Enabled: true, SampleInterval: 5 * time.Second, //... 其他配置项 }) // 启用缓存压缩 pn.WithCompression(cache.CompressOptions{ Enabled: true, Level: 6, MinSizeBytes: 100, // 最小压缩大小 (字节) //... 其他配置项 }) ```

## 📊 基准测试我们对 PixelNebula 进行了全面的基准测试，确保在各种场景下都能保持高性能表现。下面是测试结果示例（测试环境：Intel i7-12700K, 32GB RAM）：

操作	每次操作耗时	内存分配	分配次数
基本头像生成	3.5 ms/op	328 KB/op	52 allocs/op
无环境头像	2.8 ms/op	256 KB/op	48 allocs/op
添加旋转动画	4.2 ms/op	384 KB/op	62 allocs/op
使用缓存(命中)	0.3 ms/op	48 KB/op	12 allocs/op
并发生成(10)	5.7 ms/op	392 KB/op	58 allocs/op

### 运行基准测试想要在自己的环境中运行基准测试，请执行： ```bash cd benchmark go test -bench=. -benchmem ``` 更多详细的基准测试信息，请查看 [benchmark/README.md](benchmark/README.md)。

## 💡 示例和演示 ### 📚 示例代码我们准备了一套完整的示例代码，涵盖了 PixelNebula 的所有核心功能，帮助您快速上手使用。

基础用法查看代码	样式和主题查看代码	自定义主题查看代码
动画效果查看代码	链式API 查看代码	缓存系统查看代码
格式转换查看代码	随机头像生成器查看代码	...

📋 示例详细说明

1. **基础用法** [01_basic_usage.go](examples/01_basic_usage.go) - 创建基本的 PixelNebula 头像 - 生成常规头像和无环境头像 - 演示基本配置和错误处理 2. **样式和主题** [02_styles_and_themes.go](examples/02_styles_and_themes.go) - 使用不同样式生成头像 - 应用多种主题组合 - 演示循环使用样式和主题 3. **自定义主题和样式** [03_custom_theme_and_style.go](examples/03_custom_theme_and_style.go) - 创建自定义主题 - 定义自定义样式 - 演示组合主题和样式 4. **动画效果** [04_all_animations.go](examples/04_all_animations.go) - 旋转动画 - 渐变动画 - 淡入淡出效果 - 变换动画 - 颜色变换 - 弹跳效果 - 波浪动画 - 闪烁效果 - 路径动画 5. **SVG构建器链式API** [05_svg_builder_chain.go](examples/05_svg_builder_chain.go) - 基本链式调用 - 带动画的链式调用 - 直接保存到文件 - Base64转换 6. **缓存系统** [06_cache_system.go](examples/06_cache_system.go) - 使用默认缓存 - 自定义缓存配置 - 缓存监控功能 - 压缩缓存示例 7. **格式转换** [07_format_conversion.go](examples/07_format_conversion.go) - Base64编码 - 其他格式暂未找到完美解决方案，欢迎 PR 8. **随机头像生成器** [08_random_avatar_generator.go](examples/08_random_avatar_generator.go) - 随机生成不同风格和主题的头像

### 🎮 运行示例

📋 如何运行示例

1. **运行准备** - 确保已安装 Go 环境（建议 Go 1.16+） - 正确设置 GOPATH 2. **克隆代码库** ```bash git clone github.com/landaiqing/go-pixelnebula.git cd go-pixelnebula ``` 3. **运行单个示例** ```bash go run examples/01_basic_usage.go ``` 4. **运行所有示例** ```bash for file in examples/*_*.go; do echo "🚀 运行: $file" go run $file echo "------------" done ``` 5. **运行基准测试** ```bash cd benchmark go test -bench=. -benchmem ``` **💡 提示：** 查看每个示例的顶部注释，了解功能详情和可自定义的部分。

## 👥 贡献指南欢迎贡献代码、报告问题或提出建议！请遵循以下步骤：

Fork 本仓库 创建分支
git checkout -b feature/amazing-feature 提交更改
git commit -m 'Add some feature' 推送分支
git push origin feature/amazing-feature 开启 PR

## 📄 许可证该项目采用 MIT 许可证 - 详情请查看 [LICENSE](LICENSE) 文件。

用 ❤️ 和 Go 制作