vizpaint 0.2.0
A comprehensive Python data visualization library.
Requires Python: >=3.7


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


---



**vizpaint** is a **powerful, user-friendly, and comprehensive** Python data visualization library. Built upon Matplotlib, it integrates **dozens of plotting functions** ranging from classic 2D charts to professional-grade 3D graphics, rose charts, sankey charts, enhanced animations, and more. With its minimalist API design, publishing-quality charts can be generated with just one line of code, making it ideal for data analysis, scientific plotting, business reporting, and other scenarios.

---

## ✨ Core Features

- 📊 **30+ chart types** – including commonly used statistical charts, professional rose charts, sankey charts, 3D surfaces, radar charts, treemaps, and more.
- 🚀 **Minimalist API** – Most charts require only one line of core code, eliminating the need for cumbersome configuration.
- 🎨 **Deep customization** – Colors, labels, perspectives, animations, statistical information... almost all elements can be customized.
- 🌌 **Native 3D Support** – Built-in 3D surface and 3D scatter plots, supporting interactive perspectives.
- 🌀 **Enhanced Rose Diagram** – Exclusive support for **growth animation**, automatic sorting, and highlighting, suitable for dynamic presentations.
- 🔗 **Process visualization** – Built-in Sankey diagram, easily drawing energy/fund/data flows.
- 🧩 **Composite Charts** – A comprehensive range of grouped bar charts, stacked area charts, scatter matrices, combination charts, and more.
- 🛠️ **Practical Tools** – One-click setting of Chinese fonts, saving of high-definition images, and batch export.

---

## 📦 Installation

### Stable version (recommended)

```bash
pip install vizpaint
```

**Optional dependencies** (tree diagram requires `squarify`):

```bash
pip install vizpaint squarify
```

### Development version (latest)

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

---

## 🚀 Quick Start

```python
import vizpaint

# 1.  Rose diagram (Nightingale rose diagram)
fig, ax, _ = vizpaint.rose_chart(
    values=[15, 22, 18, 25, 12, 30],
    categories=['A', 'B', 'C', 'D', 'E', 'F'],
    title="📊 Sales Data Rose Chart"
)

# 2.  Enhanced rose diagram (with growth animation)
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 surface chart
fig3, ax3, _ = vizpaint.surface_3d(
    title="🌊 3D sine surface",
    cmap='plasma'
)

# 4.  Sankey diagram (energy flow)
fig4, ax4, sankey = vizpaint.create_simple_sankey()

# Display all charts
vizpaint.show_all()
```

---

## 📚 Chart Overview

| Category           | Chart Function                                                                 | Description                 |
|----------------|--------------------------------------------------------------------------|------------------------------|
| **Basic Charts**   | `pie_chart`, `bar_chart`, `scatter_plot`, `curve_statistical_chart`     | Pie chart, bar chart, scatter plot, curve   |
| **Statistical Chart**   | `histogram`, `box_plot`, `violin_plot`, `radar_chart`                  | Histogram, Box Plot, Violin Plot, Radar Chart |
| **Rose Chart Series** | `rose_chart`, `rose_chart_enhanced`, `wind_rose`, `stacked_rose_chart` | Classic Rose Chart, Enhanced Version, Wind Rose |
| **3D Charts** | `surface_3d`, `scatter_3d`                                              | 3D Surface, 3D Scatter Plot |
| **Process/Relationship** | `sankey_diagram`, `create_simple_sankey`, `treemap` | Sankey diagram, treemap |
| **Field/Vector Plot** | `quiver_plot`, `stream_plot`                                           | Vector Field, Streamline Plot |
| **Composite Charts**   | `grouped_bar`, `stacked_bar`, `stacked_area`, `multiline`, `pair_plot` | Grouped Bar, Stacked Area, Multi-line, Scatter Matrix |
| **Advanced Customization**   | `heatmap`, `bubble_chart`, `area_chart`, `line_plot`                   | Heatmap, Bubble Chart, Area Chart, Line Plot |
| **Utility Functions**   | `set_style`, `show_all`, `clear_all`, `save_figure`, `get_version`     | Styling, Display, Saving, Version       |

💡 All chart functions support returning `fig, ax`, facilitating secondary customization.

---
## 🧪 Advanced Example

### 1.  Enhanced Rose Diagram - Animated Demonstration

```python
import vizpaint

fig, ax, wedges, anim = vizpaint.rose_chart_enhanced(
values=[55, 48, 32, 44, 61, 39, 27],
categories=['Product A', 'Product B', 'Product C', 'Product D', 'Product E', 'Product F', 'Product G'],
title="🔥 Market Share Changes",
animation=True,
duration=3,
sort_by_value=True,
highlight_top=2
)

# Save as GIF (requires pillow to be installed)
# anim.save('rose_animation.gif', writer='pillow')
vizpaint.show_all()
```

### 2.  Sanji Diagram - Budget Allocation

```python
import vizpaint

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

### 3.  Combined chart – multiple charts on one screen

```python
import vizpaint
import numpy as np

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

# Sub-figure 1: 3D Surface
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 Surface')

# Sub-figure 2: Rose Diagram
vizpaint.rose_chart([20, 30, 25, 15], categories=['Q1','Q2','Q3','Q4'], ax=axes[0, 1])

# Sub-figure 3: Histogram
vizpaint.histogram(bins=20, ax=axes[1, 0])

# Sub-figure 4: Scatter Plot
vizpaint.scatter_plot(ax=axes[1, 1])

vizpaint.show_all()
```

---

## 📖 API Quick Reference

| Function | Description |
|-------------------------------|--------------------------------|
| `rose_chart(values, categories)` | Classic Nightingale Rose Chart |
| `rose_chart_enhanced(...)` | Enhanced version (animation/highlighting/statistics) |
| `sankey_diagram(flows, labels)` | Sankey diagram |
| `surface_3d()` | 3D surface plot (automatically generates sample data) |
| `scatter_3d()` | 3D scatter plot |
| `heatmap(data)` | Heatmap |
| `pair_plot(data)` | Scatterplot matrix (requires pandas/seaborn) |
| `treemap(sizes, labels)` | Tree map (requires squarify) |
| `set_style(style)` | Set matplotlib style |
| `save_figure(fig, filename)` | Save the chart |
| `get_version()` | Returns the current library version |

📘 The complete API documentation is currently under construction. We welcome feedback on your requirements through [GitHub Issues](https://github.com/yourusername/vizpaint/issues).

---

## 🔧 Dependencies

- `matplotlib >= 3.3.0`
- `numpy >= 1.19.0`

**Optional dependencies** (required for specific functions):
- `squarify` – treemap
- `seaborn` – scatter matrix, heatmap enhancement
- `pandas` – Data processing for some composite charts
- `scipy` – Histogram density curve
- `pillow` – Save animated GIFs

---

## 🤝 Contribution Guidelines

Contributions of any kind are welcome! Whether it's new features, documentation improvements, bug reports, or usage inquiries:

1. **Fork** this repository
2. Create your feature branch (`git checkout -b feature/amazing`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a **Pull Request**

Please ensure that your code adheres to the PEP 8 guidelines and add corresponding unit tests for new features (located in the `tests/` directory).

---

## 📄 License

This project is licensed under the **MIT License**, allowing you to freely use, modify, distribute, and even use it in commercial projects, as long as the original copyright notice is retained.

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

---

## 👨‍💻 Author

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

---

## 🌟 Acknowledgements

- Thank you to the [Matplotlib](https://matplotlib.org/) and [NumPy](https://numpy.org/) communities for providing a robust foundation.
- The inspiration for the rose diagram comes from the classic work of Florence Nightingale.
- The implementation of the Sankey diagram refers to the official Sankey example provided by Matplotlib.

---

If vizpaint is helpful to your work or study, please ⭐️ Star this project and let more people discover it! **
<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>