20 KiB
20 KiB
PixelNebula
PixelNebula 中文 | English
🚀 一个强大、高效且可自定义的 Go 语言 SVG 动态头像生成库
✨ 特性 • 📦 安装 • 🚀 快速开始 • 🔧 高级用法 • 💫 动画效果 • ⚡ 缓存系统 • 📊 基准测试 • 💡 示例和演示 • 👥 贡献指南 • 📄 许可证
📋 介绍
|
PixelNebula 是一个 Go 语言编写的高性能 SVG 头像生成库，专注于创建精美、可定制且高度可动态化的矢量头像。使用 PixelNebula，您可以轻松生成各种风格的头像，添加动画效果，并应用各种主题和样式变化。 无论是为应用程序创建用户头像、生成唯一标识图标，还是制作动态可视化效果，PixelNebula 都能满足您的需求。 |
✨ 特性
 多样化风格 |
 动画效果 |
 可自定义 |
 高性能 |
 缓存系统 |
- 🎨 多样化风格与主题: 内置多种风格和主题组合，满足不同设计需求
- 🔄 丰富动画效果: 支持旋转、渐变、变换、淡入淡出等多种动画
- 🛠️ 完全可自定义: 自定义风格、主题、颜色和动画效果
- ⚡ 高性能设计: 优化的代码结构和缓存机制，确保快速生成
- 💾 智能缓存系统: 内置缓存系统，提高重复生成效率
- 📊 缓存监控: 支持缓存使用情况监控和分析
- 🔍 链式调用 API: 简洁明了的 API 设计，支持流畅的链式调用
- 📱 响应式设计: 支持自定义尺寸，适应各种显示环境
📦 安装
使用 Go 工具链安装包：
go get github.com/landaiqing/go-pixelnebula
🚀 快速开始
基本用法
以下是生成简单 SVG 头像的基本示例：
|
🔧 高级用法
自定义主题和风格
点击展开/折叠代码示例
// 自定义风格
customStyles := []style.StyleSet{
{
// 第一种自定义风格
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>`,
},
}
// 应用自定义风格
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 链式调用
点击展开/折叠代码示例
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 支持多种动画效果，可以让您的头像栩栩如生：
点击查看动画代码示例
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 内置智能缓存系统，提高重复生成的效率。
点击查看缓存配置代码示例
// 使用默认缓存配置
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 |
运行基准测试
想要在自己的环境中运行基准测试，请执行：
cd benchmark
go test -bench=. -benchmem
更多详细的基准测试信息，请查看 benchmark/README.md。
💡 示例和演示
📚 示例代码
我们准备了一套完整的示例代码，涵盖了 PixelNebula 的所有核心功能，帮助您快速上手使用。
📋 示例详细说明
-
基础用法 01_basic_usage.go
- 创建基本的 PixelNebula 头像
- 生成常规头像和无环境头像
- 演示基本配置和错误处理
-
样式和主题 02_styles_and_themes.go
- 使用不同样式生成头像
- 应用多种主题组合
- 演示循环使用样式和主题
-
自定义主题和样式 03_custom_theme_and_style.go
- 创建自定义主题
- 定义自定义样式
- 演示组合主题和样式
-
动画效果 04_all_animations.go
- 旋转动画
- 渐变动画
- 淡入淡出效果
- 变换动画
- 颜色变换
- 弹跳效果
- 波浪动画
- 闪烁效果
- 路径动画
-
SVG构建器链式API 05_svg_builder_chain.go
- 基本链式调用
- 带动画的链式调用
- 直接保存到文件
- Base64转换
-
缓存系统 06_cache_system.go
- 使用默认缓存
- 自定义缓存配置
- 缓存监控功能
- 压缩缓存示例
-
- Base64编码
- 其他格式暂未找到完美解决方案，欢迎 PR
-
随机头像生成器 08_random_avatar_generator.go
- 随机生成不同风格和主题的头像
🎮 运行示例
📋 如何运行示例
-
运行准备
- 确保已安装 Go 环境（建议 Go 1.16+）
- 正确设置 GOPATH
-
克隆代码库
git clone github.com/landaiqing/go-pixelnebula.git cd go-pixelnebula -
运行单个示例
go run examples/01_basic_usage.go -
运行所有示例
for file in examples/*_*.go; do echo "🚀 运行: $file" go run $file echo "------------" done -
运行基准测试
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 文件。
用 ❤️ 和 Go 制作
© 2025 landaiqing