rsplotlib 0.1.5__tar.gz → 0.1.5.post1__tar.gz

rsplotlib-0.1.5.post1/PKG-INFO

@@ -0,0 +1,777 @@
+Metadata-Version: 2.4
+Name: rsplotlib
+Version: 0.1.5.post1
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Scientific/Engineering :: Visualization
+License-File: LICENSE
+Summary: A high-performance matplotlib-compatible plotting library powered by Rust
+Keywords: plotting,matplotlib,visualization,rust,scientific
+Author: YJ-Niu
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# rsplotlib
+
+> 一个由 Rust 强力驱动的高性能 Python 绘图库，提供 Matplotlib 兼容 API
+
+[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)
+[![Rust](https://img.shields.io/badge/Rust-2021-orange)](https://www.rust-lang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyO3](https://img.shields.io/badge/PyO3-0.29-2c2d72)](https://pyo3.rs/)
+[![plotters](https://img.shields.io/badge/plotters-0.3-7d5cff)](https://github.com/plotters-rs/plotters)
+
+---
+
+## 目录
+
+- [项目简介](#项目简介)
+- [核心特性](#核心特性)
+- [安装指南](#安装指南)
+- [快速入门](#快速入门)
+- [功能清单](#功能清单)
+- [API 参考](#api-参考)
+- [性能优势](#性能优势)
+- [项目结构](#项目结构)
+- [开发与贡献](#开发与贡献)
+- [许可证](#许可证)
+
+---
+
+## 项目简介
+
+**rsplotlib** 是一个跨语言的 Python 绘图库，核心渲染引擎完全使用 Rust 编写，通过 PyO3 提供与 Matplotlib 兼容的 Python API。项目的目标是在保持与现有 Matplotlib 代码最大兼容性的同时，利用 Rust 的内存安全和零成本抽象带来显著的性能提升。
+
+### 设计理念
+
+- **API 优先**：提供与 Matplotlib 高度一致的接口，降低迁移成本
+- **性能为王**：将性能关键路径（渲染、批量操作）下沉到 Rust 层
+- **零额外依赖**：不依赖原生 Matplotlib 的安装，仅需 Python 解释器即可运行
+- **跨平台一致**：在 macOS、Linux、Windows 上提供相同的渲染质量
+
+---
+
+## 核心特性
+
+### 丰富的图表类型
+
+- **基础图表**：折线图、散点图、柱状图、水平柱状图
+- **统计图表**：直方图、箱线图、饼图、误差棒图、茎叶图、阶梯图
+- **高级图表**：堆叠面积图、热力图/图像显示、填充区域图
+
+### 辅助元素
+
+- **参考线**：水平参考线 (`axhline`)、垂直参考线 (`axvline`)
+- **区间高亮**：水平区间填充 (`axhspan`)、垂直区间填充 (`axvspan`)
+- **任意斜率参考线**：`axline` — 通过两点绘制贯穿全图的任意角度参考线
+- **批量线**：`hlines` / `vlines` — Rust 层批量实现，避免 Python 级 for 循环
+- **文本标注**：`text`、`title`、带箭头的 `annotate`（支持 `arrowprops`）
+
+### 坐标与布局
+
+- 多子图支持：`subplots()`、`subplot()`、网格布局
+- 双坐标轴：`twinx()` / `twiny()`
+- 对数坐标：`semilogx()`、`semilogy()`、`loglog()`
+- 网格显示、图例、坐标轴范围、刻度自定义
+
+### 输出与分辨率
+
+- **PNG**：位图输出，支持 DPI 控制
+- **SVG**：矢量图输出，可无损缩放
+- **自定义 DPI**：`savefig(filename, dpi=300)` 支持任意分辨率输出
+- **像素尺寸 DPI**：PNG 元数据中写入 DPI 信息，方便出版使用
+
+### 散点图增强
+
+- **每点独立颜色**：`ax.scatter(x, y, c=['red', 'blue', 'green'])`
+- **每点独立大小**：`ax.scatter(x, y, s=[10, 20, 30, 40])`
+- **颜色+大小同时独立**：Rust 层实现，零 Python 循环开销
+
+### 样式管理
+
+- **`plt.style` 模块**：兼容 Matplotlib 的样式接口
+- **`plt.style.use()`**：应用预设样式
+- **`plt.style.available`**：查询可用样式
+- **`plt.rcParams`**：全局参数配置（字体族、字号等）
+
+### 字体与国际化
+
+- **跨平台字体解析**：自动查找系统可用字体
+- **CJK 支持**：内置中文、日文、韩文字体自动检测
+- **自定义字体注册**：`register_sans_serif_font(path)` 注册任意字体文件
+
+---
+
+## 安装指南
+
+### 前置依赖
+
+| 依赖    | 版本要求 | 说明                   |
+| ------- | -------- | ---------------------- |
+| Python  | 3.8+     | CPython 实现           |
+| Rust    | 1.70+    | 从源码构建时需要       |
+| maturin | 1.13+    | Rust-Python 包构建工具 |
+
+### 方法一：使用 maturin 从源码构建（推荐开发者）
+
+```bash
+# 1. 克隆项目
+git clone https://github.com/YJ-Niu/rsplotlib.git
+cd rsplotlib
+
+# 2. 构建并安装（自动编译 Rust 并安装到当前 Python 环境）
+pip install maturin
+maturin develop --release
+```
+
+### 方法二：构建 wheel 包
+
+```bash
+# 使用项目提供的构建脚本
+./build_wheel.sh
+
+# 安装生成的 wheel
+pip install target/wheels/rsplotlib-*.whl
+```
+
+### 方法三：仅编译 Rust 扩展（调试用）
+
+```bash
+# 编译 Rust cdylib
+cargo build --release
+
+# 将编译产物复制为正确的 Python 扩展模块名称
+# macOS:
+cp target/release/librsplotlib.dylib python/rsplotlib/rsplotlib.cpython-39-darwin.so
+
+# Linux:
+# cp target/release/librsplotlib.so python/rsplotlib/rsplotlib.cpython-39-x86_64-linux-gnu.so
+
+# 从源码目录使用
+export PYTHONPATH="$PWD/python:$PYTHONPATH"
+```
+
+### 验证安装
+
+```python
+>>> import rsplotlib.pyplot as plt
+>>> fig, ax = plt.subplots()
+>>> ax.plot([1, 2, 3], [1, 4, 9])
+>>> fig.savefig('test.png')
+# ✅ 生成 test.png 即安装成功
+```
+
+---
+
+## 快速入门
+
+### 基础使用：折线图
+
+```python
+from rsplotlib import pyplot as plt
+from rsplotlib.pylab import mpl
+
+# 可选：配置中文字体
+mpl.rcParams['font.sans-serif'] = ['PingFang SC', 'Microsoft YaHei', 'Arial']
+
+# 创建 Figure 和 Axes
+fig, ax = plt.subplots(figsize=(8, 6))
+
+# 绘制数据
+x = [0, 1, 2, 3, 4, 5]
+y1 = [1, 2, 4, 8, 16, 32]
+y2 = [32, 16, 8, 4, 2, 1]
+
+ax.plot(x, y1, label='指数增长', lw=2.0)
+ax.plot(x, y2, label='指数衰减', lw=2.0, linestyle='--')
+
+# 装饰图表
+ax.set_title('基础折线图示例')
+ax.set_xlabel('时间')
+ax.set_ylabel('数值')
+ax.legend()
+ax.grid(True)
+
+# 保存为高分辨率 PNG
+fig.savefig('line_plot.png', dpi=300)
+```
+
+### 散点图：每点独立颜色和大小
+
+```python
+import random
+from rsplotlib import pyplot as plt
+
+# 生成随机数据
+random.seed(42)
+n = 50
+x = [random.gauss(0, 1) for _ in range(n)]
+y = [random.gauss(0, 1) for _ in range(n)]
+
+# 每点独立颜色和大小（Rust 层处理，Python 层零循环）
+colors = ['red' if xi > 0 else 'blue' for xi in x]
+sizes = [max(10, abs(xi * yi * 50)) for xi, yi in zip(x, y)]
+
+fig, ax = plt.subplots()
+ax.scatter(x, y, c=colors, s=sizes, alpha=0.7)
+ax.set_title('散点图：颜色/大小独立')
+fig.savefig('scatter.png')
+```
+
+### 区间高亮与参考线
+
+```python
+from rsplotlib import pyplot as plt
+
+fig, ax = plt.subplots()
+x = list(range(-5, 6))
+y = [xi**2 for xi in x]
+
+# 绘制数据
+ax.plot(x, y, 'b-', lw=2, label='y = x²')
+
+# 垂直区间高亮
+ax.axvspan(-1, 1, color='yellow', alpha=0.3, label='最小值区域')
+
+# 水平区间高亮
+ax.axhspan(0, 5, color='lightgreen', alpha=0.2)
+
+# 水平/垂直参考线
+ax.axhline(y=0, color='gray', linestyle=':', linewidth=1)
+ax.axvline(x=0, color='gray', linestyle=':', linewidth=1)
+
+# 任意斜率参考线（贯穿整张图）
+ax.axline((0, 0), (1, 1), color='red', linestyle='--', linewidth=1.5)
+
+ax.legend()
+fig.savefig('reference_lines.png')
+```
+
+### 箭头标注
+
+```python
+from rsplotlib import pyplot as plt
+
+fig, ax = plt.subplots()
+
+# 绘制曲线
+x = list(range(-10, 11))
+y = [xi**3 - 3*xi for xi in x]
+ax.plot(x, y, 'b-', lw=2)
+
+# 添加箭头标注
+ax.annotate('局部极大值', xy=(-1, 2), xytext=(-8, 500),
+            fontsize=11, color='red',
+            arrowprops={'arrowstyle': '->', 'arrowsize': 1.0})
+
+ax.annotate('局部极小值', xy=(1, -2), xytext=(3, -500),
+            fontsize=11, color='blue',
+            arrowprops={'arrowstyle': '->', 'arrowsize': 1.0})
+
+ax.annotate('原点', xy=(0, 0), xytext=(5, 200),
+            fontsize=11, color='darkgreen')
+
+ax.set_title('ax.annotate：带箭头的文本标注')
+fig.savefig('annotations.png')
+```
+
+### 批量水平线/垂直线（Rust 层实现）
+
+```python
+from rsplotlib import pyplot as plt
+
+fig, ax = plt.subplots()
+ax.plot([0, 10], [0, 10], 'k-', lw=1)
+
+# 批量绘制水平线（Rust 层循环，Python 零开销）
+ax.hlines([2, 4, 6, 8], color='steelblue', linestyle='--', linewidth=1)
+
+# 批量绘制垂直线
+ax.vlines([2, 4, 6, 8], color='darkorange', linestyle=':', linewidth=1)
+
+ax.set_title('hlines / vlines：批量参考线（Rust 层实现）')
+fig.savefig('hlines_vlines.png')
+```
+
+### 多子图
+
+```python
+from rsplotlib import pyplot as plt
+
+# 2x2 网格
+fig, axes = plt.subplots(2, 2)
+
+# axes 是一个扁平列表
+axes[0].plot([1, 2, 3], [1, 4, 9])
+axes[0].set_title('子图 1')
+
+axes[1].bar(['A', 'B', 'C'], [3, 7, 2])
+axes[1].set_title('子图 2')
+
+axes[2].scatter([1,2,3,4], [4,3,2,1], c=['red','green','blue','orange'])
+axes[2].set_title('子图 3')
+
+axes[3].hist([0.5, 1.2, 1.8, 2.1, 2.5, 3.0, 3.2, 3.8, 4.1, 4.5], bins=5)
+axes[3].set_title('子图 4')
+
+fig.savefig('subplots.png', dpi=200)
+```
+
+### 模块级接口（无需显式创建 Axes）
+
+```python
+from rsplotlib import pyplot as plt
+
+# 直接使用 plt.* 接口
+plt.figure()
+plt.plot([1, 2, 3], [1, 2, 3], 'r-')
+plt.axhline(y=2, color='gray', linestyle='--')
+plt.axvspan(1, 2, color='yellow', alpha=0.3)
+plt.title('模块级接口')
+plt.savefig('module_level.png')
+```
+
+---
+
+## 功能清单
+
+### 绘图函数
+
+| 函数             | 说明                        | 模块级接口 | Axes 接口 |
+| ---------------- | --------------------------- | ---------- | --------- |
+| `plot()`         | 折线图                      | ✅         | ✅        |
+| `scatter()`      | 散点图（支持颜色/大小数组） | ✅         | ✅        |
+| `bar()`          | 柱状图                      | ✅         | ✅        |
+| `barh()`         | 水平柱状图                  | ✅         | ✅        |
+| `hist()`         | 直方图                      | ✅         | ✅        |
+| `pie()`          | 饼图                        | ✅         | ✅        |
+| `boxplot()`      | 箱线图                      | ✅         | ✅        |
+| `fill_between()` | 曲线间填充                  | ✅         | ✅        |
+| `errorbar()`     | 误差棒图                    | ✅         | ✅        |
+| `stem()`         | 茎叶图                      | ✅         | ✅        |
+| `step()`         | 阶梯图                      | ✅         | ✅        |
+| `imshow()`       | 图像/热力图                 | ✅         | ✅        |
+| `stackplot()`    | 堆叠面积图                  | ✅         | ✅        |
+| `semilogx()`     | x 轴对数坐标折线图          | ✅         | ✅        |
+| `semilogy()`     | y 轴对数坐标折线图          | ✅         | ✅        |
+| `loglog()`       | 双对数坐标折线图            | ✅         | ✅        |
+
+### 辅助元素
+
+| 函数         | 说明                 | 模块级接口 | Axes 接口 |
+| ------------ | -------------------- | ---------- | --------- |
+| `axhline()`  | 水平参考线           | ✅         | ✅        |
+| `axvline()`  | 垂直参考线           | ✅         | ✅        |
+| `axhspan()`  | 水平区间填充         | ✅         | ✅        |
+| `axvspan()`  | 垂直区间填充         | ✅         | ✅        |
+| `axline()`   | 任意斜率参考线       | ✅         | ✅        |
+| `hlines()`   | 批量水平线 (Rust 层) | ✅         | ✅        |
+| `vlines()`   | 批量垂直线 (Rust 层) | ✅         | ✅        |
+| `text()`     | 文本标注             | ✅         | ✅        |
+| `annotate()` | 带箭头文本标注       | ✅         | ✅        |
+
+### 图表配置
+
+| 函数                                   | 说明                             |
+| -------------------------------------- | -------------------------------- |
+| `title()` / `ax.set_title()`           | 设置图表标题                     |
+| `xlabel()` / `ax.set_xlabel()`         | 设置 X 轴标签                    |
+| `ylabel()` / `ax.set_ylabel()`         | 设置 Y 轴标签                    |
+| `grid()`                               | 显示/隐藏网格                    |
+| `legend()`                             | 显示图例                         |
+| `xlim()` / `ylim()`                    | 设置坐标轴范围                   |
+| `xticks()` / `yticks()`                | 设置刻度位置和标签               |
+| `xscale()` / `yscale()`                | 设置坐标缩放（`linear` / `log`） |
+| `margins()`                            | 设置自动缩放边距                 |
+| `box()`                                | 设置坐标轴边框显示               |
+| `minorticks_on()` / `minorticks_off()` | 次要刻度显示控制                 |
+
+### 子图与布局
+
+| 函数                           | 说明             |
+| ------------------------------ | ---------------- |
+| `subplots(nrows, ncols)`       | 创建子图网格     |
+| `subplot(nrows, ncols, index)` | 创建单个子图     |
+| `twinx()` / `twiny()`          | 创建双坐标轴     |
+| `tight_layout()`               | 自动调整布局     |
+| `fig.set_size(w, h)`           | 设置图形像素尺寸 |
+
+### 图形控制
+
+| 函数                          | 说明                       |
+| ----------------------------- | -------------------------- |
+| `figure()`                    | 创建新 Figure 对象         |
+| `savefig(filename, dpi=None)` | 保存到文件，支持自定义 DPI |
+| `show()`                      | 显示图形（保存到默认位置） |
+| `gca()`                       | 获取当前 Axes              |
+| `gcf()`                       | 获取当前 Figure            |
+| `cla()`                       | 清空当前 Axes              |
+| `clf()`                       | 清空当前 Figure            |
+| `close()`                     | 关闭当前 Figure            |
+
+---
+
+## API 参考
+
+### Figure.savefig
+
+保存图形到文件。
+
+```python
+fig.savefig(filename, dpi=None)
+```
+
+**参数：**
+
+- `filename` (str): 输出文件路径。支持 `.png` 和 `.svg` 扩展名
+- `dpi` (float, 可选): 分辨率（每英寸点数）。默认使用 Figure 创建时的 DPI
+
+**示例：**
+
+```python
+fig.savefig('plot.png')              # 默认 DPI
+fig.savefig('plot_hd.png', dpi=150)  # 屏幕分辨率
+fig.savefig('plot_print.png', dpi=300)  # 印刷分辨率
+fig.savefig('plot.svg')              # 矢量图
+```
+
+### Axes.scatter — 增强版
+
+散点图，支持每点独立颜色/大小。
+
+```python
+ax.scatter(x, y, s=20.0, c=None, marker='o', label=None, alpha=1.0, **kwargs)
+```
+
+**参数：**
+
+- `x`, `y` (list/array): 点坐标数据
+- `s` (float 或 list/array): 单个浮点值用于所有点，或数组表示每点大小
+- `c` (str 或 list[str]): 单个颜色字符串，或颜色字符串数组
+- `marker` (str): 标记形状，支持 `'o'`, `'s'`, `'^'`, `'v'`, `'D'`, `'*'`, `'+'`, `'x'`, `'<'`, `'>'`
+- `label` (str): 图例标签
+- `alpha` (float): 透明度 (0.0-1.0)
+- `**kwargs`: 额外参数，支持 `color`（作为 `c` 的别名）
+
+**示例：**
+
+```python
+# 单色散点
+ax.scatter(x, y, c='red', s=50)
+
+# 每点独立颜色
+ax.scatter(x, y, c=['red', 'green', 'blue', ...], s=50)
+
+# 每点独立大小
+ax.scatter(x, y, s=[10, 20, 30, ...], c='blue')
+
+# 颜色+大小同时独立（Rust 层批量处理）
+ax.scatter(x, y, c=colors, s=sizes, marker='D', alpha=0.8)
+```
+
+### Axes.axhspan / axvspan
+
+区间高亮填充。
+
+```python
+ax.axhspan(ymin, ymax, color=None, alpha=0.3)
+ax.axvspan(xmin, xmax, color=None, alpha=0.3)
+```
+
+**参数：**
+
+- `ymin`, `ymax` (float): 水平区间的 y 轴上下界（数据坐标）
+- `xmin`, `xmax` (float): 垂直区间的 x 轴左右界（数据坐标）
+- `color` (str): 填充颜色，默认浅蓝灰色
+- `alpha` (float): 透明度，默认 0.3
+
+### Axes.axline
+
+通过两点绘制贯穿全图的任意斜率参考线。
+
+```python
+ax.axline(xy1, xy2, color=None, linestyle=None, linewidth=None)
+```
+
+**参数：**
+
+- `xy1` (tuple): 起点坐标 `(x1, y1)`
+- `xy2` (tuple): 终点坐标 `(x2, y2)`
+- `color` (str): 线颜色
+- `linestyle` (str): 线型，`'-'` (实线), `'--'` (虚线), `':'` (点线), `'-.'` (点划线)
+- `linewidth` (float): 线宽
+
+### Axes.annotate
+
+添加带箭头的文本标注。
+
+```python
+ax.annotate(text, xy, xytext=None, fontsize=12.0, color='black',
+            arrowprops=None, arrowstyle=None, arrowsize=1.0)
+```
+
+**参数：**
+
+- `text` (str): 标注文本
+- `xy` (tuple): 被标注点坐标 `(x, y)`
+- `xytext` (tuple, 可选): 文本放置位置。若提供，自动从该位置绘制箭头到 `xy`
+- `fontsize` (float): 字体大小，默认 12.0
+- `color` (str): 文本和箭头颜色，默认 `'black'`
+- `arrowprops` (dict, 可选): 箭头属性字典，支持：
+  - `arrowstyle`: 箭头样式（如 `'->'`, `'-|>'`）
+  - `arrowsize`: 箭头相对大小
+- `arrowstyle` (str, 可选): 独立于 `arrowprops` 的箭头样式
+- `arrowsize` (float, 可选): 独立于 `arrowprops` 的箭头大小
+
+### hlines / vlines（Rust 层批量实现）
+
+绘制多条水平线或垂直线。所有内部循环在 Rust 层完成，避免 Python 级循环开销。
+
+```python
+ax.hlines(y, color=None, linestyle=None, linewidth=None)
+ax.vlines(x, color=None, linestyle=None, linewidth=None)
+```
+
+**参数：**
+
+- `y` / `x` (list/array): 位置列表
+
+---
+
+## 性能优势
+
+rsplotlib 在架构设计上通过"分层下沉"策略实现性能优化：
+
+### 架构分层
+
+```
+┌──────────────────────────────────────────────┐
+│  Python 层 (API 兼容层)                      │
+│  · pyplot.py   (Matplotlib 兼容接口)         │
+│  · api.py      (参数规范化 / 别名映射)       │
+│  · _patch_*    (方法补丁 / 动态分发)         │
+├──────────────────────────────────────────────┤
+│  Rust 层 (高性能核心)                        │
+│  · lib.rs      (模块注册 / 字体系统)         │
+│  · figure.rs   (Figure 对象 / 渲染调度)      │
+│  · axes.rs     (Axes 对象 / 数据解析)        │
+│  · elements.rs (绘图元素数据结构)            │
+│  · axes_render_elements.rs (plotters 渲染)   │
+│  · pyfuncs.rs  (模块级函数暴露)              │
+└──────────────────────────────────────────────┘
+```
+
+### 性能关键路径下沉到 Rust
+
+| 功能                        | 传统实现                            | rsplotlib 实现                  |
+| --------------------------- | ----------------------------------- | ------------------------------- |
+| `scatter(c=colors)`         | Python 层遍历每个点                 | Rust 层 `ScatterMulti` 统一渲染 |
+| `scatter(s=sizes)`          | Python 层遍历每个点                 | Rust 层统一大小数组处理         |
+| `hlines([y1, y2, y3, ...])` | Python `for` 循环多次调用 `axhline` | Rust 层单次调用批量处理         |
+| `vlines([x1, x2, x3, ...])` | Python `for` 循环多次调用 `axvline` | Rust 层单次调用批量处理         |
+| `savefig(dpi=300)`          | 无 DPI 支持 / Python 层缩放         | Rust 层直接写入 PNG DPI 元数据  |
+
+### 为什么选择 Rust + Python 混合架构
+
+1. **开发效率**：Python 层快速迭代 API 设计、参数校验
+2. **执行性能**：Rust 层处理渲染、循环、内存密集型计算
+3. **内存安全**：Rust 编译期保证无数据竞争
+4. **零额外依赖**：无原生 Matplotlib 安装要求
+
+---
+
+## 项目结构
+
+```
+rsplotlib/
+├── python/                          # Python 包装层
+│   └── rsplotlib/
+│       ├── __init__.py              # 包入口与导出
+│       ├── api.py                   # 模块级 API 函数定义
+│       ├── pyplot.py                # Matplotlib 兼容 pyplot 接口
+│       │                            # (含中文 docstring, IDE 悬停提示)
+│       ├── pylab.py                 # pylab 风格接口，提供 mpl.rcParams
+│       ├── style.py                 # plt.style 样式管理
+│       ├── _rcparams.py             # rcParams 配置管理
+│       ├── _font_resolver.py        # 系统字体路径解析
+│       ├── _figure_defaults.py      # Figure 默认配置
+│       ├── gridspec.py              # 网格布局管理
+│       └── ticker.py                # 刻度定位器 (AutoLocator, MaxNLocator)
+│
+├── src/                             # Rust 核心实现
+│   ├── lib.rs                       # 库入口，Python 模块注册
+│   ├── figure.rs                    # Figure 类 (savefig, DPI 管理)
+│   ├── axes.rs                      # Axes 类 (所有绘图方法)
+│   ├── axes_render_elements.rs      # 元素渲染引擎 (基于 plotters)
+│   ├── axes_bounds.rs               # 坐标边界计算
+│   ├── axes_title.rs                # 标题渲染
+│   ├── axes_legend.rs               # 图例渲染
+│   ├── axes_grid.rs                 # 网格线渲染
+│   ├── axes_mesh.rs                 # 坐标轴刻度
+│   ├── axis.rs                      # Axis 数据结构
+│   ├── elements.rs                  # 绘图元素枚举 (Line/Scatter/Bar/...)
+│   ├── pyfuncs.rs                   # 暴露给 Python 的模块级函数
+│   ├── colors.rs                    # 颜色解析 (命名色, RGB, HSL)
+│   ├── colormap.rs                  # 颜色映射
+│   ├── marker.rs                    # 标记形状渲染
+│   └── text_utils.rs                # 文本工具函数
+│
+├── Cargo.toml                       # Rust 依赖 (PyO3, plotters, png)
+├── pyproject.toml                   # Python 包配置 (maturin)
+├── build_wheel.sh                   # wheel 包构建脚本
+├── README.md                        # 英文说明
+└── README_zh.md                     # 中文说明（本文档）
+```
+
+---
+
+## 开发与贡献
+
+### 本地开发环境
+
+```bash
+# 1. 安装 Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# 2. 安装 maturin
+pip install maturin
+
+# 3. 开发模式构建（自动编译 Rust 并安装到当前 Python 环境）
+maturin develop --release
+
+# 4. 运行交互式测试
+python3 -c "
+from rsplotlib import pyplot as plt
+fig, ax = plt.subplots()
+ax.plot([1,2,3], [1,4,9])
+fig.savefig('/tmp/test.png')
+print('OK')
+"
+```
+
+### 开发工作流
+
+1. **理解需求**：分析需要实现的 Matplotlib 功能
+2. **Rust 层实现**：在 `src/` 中添加核心逻辑
+   - 新增绘图元素：修改 `elements.rs`
+   - 添加绘图方法：修改 `axes.rs`
+   - 添加渲染逻辑：修改 `axes_render_elements.rs`
+   - 暴露模块级函数：修改 `pyfuncs.rs`
+   - 注册：修改 `lib.rs`
+3. **Python 层包装**：在 `python/rsplotlib/` 中添加 API
+   - 添加中文 docstring（供 IDE 悬停显示）
+   - 处理参数别名（如 `lw` → `linewidth`）
+   - 将数组参数路由到 Rust 层批量方法
+4. **编译测试**：`maturin develop --release`
+5. **验证结果**：生成图像进行目视检查
+
+### 为 Python 层添加文档（IDE 悬停）
+
+Python 包装层的函数都包含详细的中文 docstring，当用户在 IDE（VS Code、PyCharm 等）中悬停在函数上时，会自动显示中文说明和参数列表。
+
+```python
+def axhspan(ymin, ymax, **kwargs):
+    """绘制水平方向的区间填充。
+
+    用法:
+        plt.axhspan(0, 1, color='yellow', alpha=0.3)
+
+    Args:
+        ymin: y 轴下限
+        ymax: y 轴上限
+        color: 填充颜色 (默认蓝灰色)
+        alpha: 透明度 (0.0-1.0, 默认 0.3)
+    """
+    ...
+```
+
+### 贡献指南
+
+欢迎提交 PR！请在提交时包含：
+
+- 清晰的功能说明或问题修复描述
+- 适用时包含生成的示例图像
+- 确保同时更新 `README.md` 和 `README_zh.md`
+
+### 已知限制
+
+- 当前版本不支持 3D 绘图
+- 不支持动画/交互式图表
+- `contour` / `violinplot` / `hexbin` 为占位实现
+
+---
+
+## 字体配置
+
+rsplotlib 支持通过 `mpl.rcParams` 自定义字体，同时支持直接注册字体文件。
+
+### 自动检测的系统字体
+
+| 平台        | 常用字体                                                                   |
+| ----------- | -------------------------------------------------------------------------- |
+| **macOS**   | Arial, Helvetica, PingFang SC, STHeiti, Hiragino Sans GB, Arial Unicode MS |
+| **Linux**   | DejaVu Sans, Liberation Sans, Noto Sans CJK SC, WenQuanYi Micro Hei        |
+| **Windows** | Microsoft YaHei, SimHei, SimSun, Arial                                     |
+
+### 自定义字体配置
+
+```python
+from rsplotlib.pylab import mpl
+from rsplotlib import pyplot as plt
+
+# 设置 sans-serif 字体族（优先顺序）
+mpl.rcParams['font.sans-serif'] = ['PingFang SC', 'Microsoft YaHei', 'DejaVu Sans']
+
+# 设置默认字体大小
+mpl.rcParams['font.size'] = 12
+```
+
+### 直接注册字体文件
+
+```python
+from rsplotlib import rsplotlib as _rs
+
+# 从任意 .ttf/.otf/.ttc 文件注册为 sans-serif 字体
+_rs.register_sans_serif_font('/path/to/your/custom-font.ttf')
+```
+
+---
+
+## 许可证
+
+MIT License — 详见 [LICENSE](LICENSE) 文件。
+
+---
+
+## 致谢
+
+- [**PyO3**](https://github.com/PyO3/pyo3) — Rust ↔ Python 绑定库，版本 0.29
+- [**plotters**](https://github.com/plotters-rs/plotters) — Rust 绘图库，提供底层渲染能力
+- [**Matplotlib**](https://matplotlib.org/) — Python 绘图生态标准，提供 API 设计参考
+- [**maturin**](https://github.com/PyO3/maturin) — Rust Python 包构建与发布工具
+
+---
+
+## 相关链接
+
+- **GitHub**: https://github.com/YJ-Niu/rsplotlib
+- **PyPI**: (待发布)
+- **文档**: (待完善)
+
+---
+
+_最后更新：2026-06-17 · 版本 v0.1.5_
+