vizpaint 0.1.9

A comprehensive Python data visualization library.

vizpaint

vizpaint 是一个强大、易用、功能全面的 Python 数据可视化库。它基于 Matplotlib 构建，集成了从经典 2D 图表到专业级 3D 图形、玫瑰图、桑基图、增强动画等数十种绘图函数。API 设计极简，一行代码即可生成出版级图表，非常适合数据分析、科研绘图、商业报告等场景。

---

✨ 核心特性

• 📊 30+ 种图表类型 – 涵盖常用统计图、专业玫瑰图、桑基图、3D 曲面、雷达图、树状图等。
• 🚀 极简 API – 大部分图表仅需一行核心代码，无需繁琐配置。
• 🎨 深度定制 – 颜色、标签、视角、动画、统计信息……几乎所有元素都可自定义。
• 🌌 原生 3D 支持 – 内置 3D 曲面、3D 散点图，支持交互视角。
• 🌀 增强玫瑰图 – 独家支持生长动画、自动排序、高亮突出，适合动态演示。
• 🔗 流程可视化 – 内置桑基图（Sankey），轻松绘制能源/资金/数据流动。
• 🧩 复合图表 – 分组柱状图、堆叠面积图、散点矩阵、组合图等一应俱全。
• 🛠️ 实用工具 – 一键设置中文字体、保存高清图、批量导出。

---

📦 安装

稳定版（推荐）

pip install vizpaint

可选依赖（树状图需要 squarify）：

pip install vizpaint squarify

开发版（最新）

pip install git+https://github.com/yourusername/vizpaint.git

---

🚀 快速开始

import vizpaint

# 1. 玫瑰图（南丁格尔玫瑰图）
fig, ax, _ = vizpaint.rose_chart(
    values=[15, 22, 18, 25, 12, 30],
    categories=['A', 'B', 'C', 'D', 'E', 'F'],
    title="📊 销售数据玫瑰图"
)

# 2. 增强玫瑰图（带生长动画）
fig2, ax2, wedges, anim = vizpaint.rose_chart_enhanced(
    values=[42, 35, 28, 50, 38, 45, 32],
    animation=True,
    duration=2,
    highlight_top=3,
    explode=True
)

# 3. 3D 曲面图
fig3, ax3, _ = vizpaint.surface_3d(
    title="🌊 3D 正弦曲面",
    cmap='plasma'
)

# 4. 桑基图（能源流动）
fig4, ax4, sankey = vizpaint.create_simple_sankey()

# 显示所有图表
vizpaint.show_all()

---

📚 图表总览

类别	图表函数	说明
基础图表	pie_chart, bar_chart, scatter_plot, curve_statistical_chart	饼图、柱状图、散点图、曲线
统计图表	histogram, box_plot, violin_plot, radar_chart	直方图、箱线图、小提琴图、雷达图
玫瑰图系列	rose_chart, rose_chart_enhanced, wind_rose, stacked_rose_chart	经典玫瑰图、增强版、风向玫瑰图
3D 图表	surface_3d, scatter_3d	3D 曲面、3D 散点图
流程/关系	sankey_diagram, create_simple_sankey, treemap	桑基图、树状图
场/矢量图	quiver_plot, stream_plot	矢量场、流线图
复合图表	grouped_bar, stacked_bar, stacked_area, multiline, pair_plot	分组柱状、堆叠面积、多折线、散点矩阵
高级定制	heatmap, bubble_chart, area_chart, line_plot	热力图、气泡图、面积图、折线图
工具函数	set_style, show_all, clear_all, save_figure, get_version	样式、显示、保存、版本

💡 所有图表函数均支持 fig, ax 返回，方便二次定制。

---

🧪 进阶示例

1. 增强玫瑰图 – 动画演示

import vizpaint

fig, ax, wedges, anim = vizpaint.rose_chart_enhanced(
    values=[55, 48, 32, 44, 61, 39, 27],
    categories=['产品A', '产品B', '产品C', '产品D', '产品E', '产品F', '产品G'],
    title="🔥 市场份额变化",
    animation=True,
    duration=3,
    sort_by_value=True,
    highlight_top=2
)

# 保存为 GIF（需安装 pillow）
# anim.save('rose_animation.gif', writer='pillow')
vizpaint.show_all()

2. 桑基图 – 预算分配

import vizpaint

fig, ax, sankey = vizpaint.create_budget_sankey()
vizpaint.show_all()

3. 组合图表 – 多图同屏

import vizpaint
import numpy as np

fig, axes = vizpaint.create_subplots(2, 2, figsize=(14, 10))

# 子图1：3D曲面
x = np.linspace(-5, 5, 50)
y = np.linspace(-5, 5, 50)
x, y = np.meshgrid(x, y)
z = np.sin(np.sqrt(x**2 + y**2))
axes[0, 0].plot_surface(x, y, z, cmap='viridis')
axes[0, 0].set_title('3D 曲面')

# 子图2：玫瑰图
vizpaint.rose_chart([20, 30, 25, 15], categories=['Q1','Q2','Q3','Q4'], ax=axes[0, 1])

# 子图3：直方图
vizpaint.histogram(bins=20, ax=axes[1, 0])

# 子图4：散点图
vizpaint.scatter_plot(ax=axes[1, 1])

vizpaint.show_all()

---

📖 API 快速参考

函数	描述
rose_chart(values, categories)	经典南丁格尔玫瑰图
rose_chart_enhanced(...)	增强版（动画/高亮/统计）
sankey_diagram(flows, labels)	桑基图
surface_3d()	3D 曲面图（自动生成示例数据）
scatter_3d()	3D 散点图
heatmap(data)	热力图
pair_plot(data)	散点矩阵（需 pandas/seaborn）
treemap(sizes, labels)	树状图（需 squarify）
set_style(style)	设置 matplotlib 样式
save_figure(fig, filename)	保存图表
get_version()	返回当前库版本

📘 完整 API 文档正在建设中，欢迎通过 GitHub Issues 反馈需求。

---

🔧 依赖项

• matplotlib >= 3.3.0
• numpy >= 1.19.0

可选依赖（特定功能需要）：

• squarify – 树状图
• seaborn – 散点矩阵、热力图增强
• pandas – 部分复合图表的数据处理
• scipy – 直方图密度曲线
• pillow – 保存动画 GIF

---

🤝 贡献指南

欢迎任何形式的贡献！无论是新功能、文档改进、Bug 报告还是使用疑问：

1. Fork 本仓库
2. 创建您的特性分支 (git checkout -b feature/amazing)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing)
5. 打开一个 Pull Request

请确保您的代码符合 PEP 8 规范，并为新功能添加相应的单元测试（位于 tests/ 目录）。

---

📄 许可证

本项目采用 MIT 许可证，您可以自由使用、修改、分发，甚至用于商业项目，只需保留原始版权声明。

---

👨‍💻 作者

• zhouxinjun (@yourgithub)
  邮箱：[e-mail]

---

🌟 致谢

• 感谢 Matplotlib 和 NumPy 社区提供的强大基础。
• 玫瑰图灵感来源于 Florence Nightingale 的经典作品。
• 桑基图实现参考了 Matplotlib 官方 Sankey 示例。

---

如果 vizpaint 对你的工作或学习有帮助，欢迎 ⭐️ Star 本项目，让更多人发现它！

```

---