
# vizpaint

<p align="center">
  <a href="https://pypi.org/project/vizpaint/">
    <img src="https://img.shields.io/pypi/v/vizpaint.svg" alt="PyPI version">
  </a>
  <a href="https://pypi.org/project/vizpaint/">
    <img src="https://img.shields.io/pypi/pyversions/vizpaint.svg" alt="Python Versions">
  </a>
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
  </a>
  <a href="https://pypi.org/project/vizpaint/">
    <img src="https://img.shields.io/pypi/dm/vizpaint" alt="Downloads">
  </a>
  <a href="https://github.com/yourusername/vizpaint">
    <img src="https://img.shields.io/github/stars/yourusername/vizpaint?style=social" alt="GitHub stars">
  </a>
</p>

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

---

## ✨ 核心特性

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

---

## 📦 安装

### 稳定版（推荐）

```bash
pip install vizpaint
```

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

```bash
pip install vizpaint squarify
```

### 开发版（最新）

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

---

## 🚀 快速开始

```python
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. 增强玫瑰图 – 动画演示

```python
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. 桑基图 – 预算分配

```python
import vizpaint

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

### 3. 组合图表 – 多图同屏

```python
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](https://github.com/yourusername/vizpaint/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 许可证**，您可以自由使用、修改、分发，甚至用于商业项目，只需保留原始版权声明。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 👨‍💻 作者

- **zhouxinjun** ([@yourgithub](https://github.com/yourusername))  
  邮箱：369013027@qq.com

---

## 🌟 致谢

- 感谢 [Matplotlib](https://matplotlib.org/) 和 [NumPy](https://numpy.org/) 社区提供的强大基础。
- 玫瑰图灵感来源于 Florence Nightingale 的经典作品。
- 桑基图实现参考了 Matplotlib 官方 Sankey 示例。

---

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

<p align="center">
  <a href="https://github.com/yourusername/vizpaint">
    <img src="https://img.shields.io/github/stars/yourusername/vizpaint?style=for-the-badge&logo=github" alt="GitHub stars">
  </a>
</p>
```

---

