vizpaint 0.2.1.1

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 本项目，让更多人发现它！

---

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)

pip install vizpaint

Optional dependencies (tree diagram requires squarify):

pip install vizpaint squarify

Development version (latest)

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

---

🚀 Quick Start

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

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

import vizpaint

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

3. Combined chart – multiple charts on one screen

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.

---

🔧 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.

---

👨‍💻 Author

• zhouxinjun (@yourgithub) Email: [e-mail]

---

🌟 Acknowledgements

• Thank you to the Matplotlib and NumPy 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! **