为什么需要 perfectcolorbar？

在使用 Matplotlib 时，创建一个颜色条通常需要多个步骤，并且要处理很多细节：

1. 创建 Figure 和 Axes 对象。
2. 在 Axes 上绘图（如 imshow, contourf）。
3. 创建颜色条对象 cbar = fig.colorbar(...)
4. 手动调整：
   • 设置 cbar.ax.tick_params 来调整刻度标签的字体大小、颜色、方向。
   • 设置 cbar.set_label 来设置标签，并手动调整其位置、大小和颜色。
   • 调整颜色条的长度和宽度（fraction, pad）。
   • 处理刻度标签的格式化（Formatter）。
   • 调整颜色条在图中的位置（location）。

这些操作代码冗长,且每次都要重复写。perfectcolorbar 将这些繁琐的步骤封装起来，让你用几行代码就能实现。

安装 perfectcolorbar

你需要安装这个库,它依赖于 matplotlib 和 numpy。

pip install perfectcolorbar

核心概念：Colorbar 类

perfectcolorbar 的核心是 Colorbar 类，你不需要手动创建 Figure 和 Axes，而是将 Colorbar 视为你的主要对象，然后在其上进行配置。

基本使用流程：

1. 创建绘图：像平常一样用 Matplotlib 创建你的图像。
2. 实例化 Colorbar：将你的 Axes 对象传递给 Colorbar。
3. 链式调用配置方法：使用类似 cbar.method().method() 的方式来配置颜色条的各个方面。
4. 调用 .show()：调用 .show() 方法来渲染和显示颜色条。

详细教程与代码示例

让我们通过一系列例子来学习 perfectcolorbar 的强大功能。

示例 1：基础用法（对比 Matplotlib 原生方式）

假设我们有一个简单的 2D 数据图。

传统 Matplotlib 方式：

import matplotlib.pyplot as plt
import numpy as np
# 1. 创建数据和绘图
data = np.random.rand(10, 10)
fig, ax = plt.subplots()
img = ax.imshow(data, cmap='viridis')
# 2. 创建颜色条并手动调整
cbar = fig.colorbar(img, ax=ax, fraction=0.046, pad=0.04)
cbar.ax.tick_params(labelsize=12)  # 调整刻度字体大小
cbar.set_label('Value', size=14, weight='bold') # 设置标签
"Matplotlib Native Way")
plt.show()

使用 perfectcolorbar 方式：

import matplotlib.pyplot as plt
import numpy as np
from perfectcolorbar import Colorbar # 导入 Colorbar
# 1. 创建数据和绘图
data = np.random.rand(10, 10)
fig, ax = plt.subplots()
img = ax.imshow(data, cmap='viridis')
# 2. 使用 perfectcolorbar 创建和配置颜色条
# 只需一行代码完成所有配置！
Colorbar(ax, img).label('Value').tick_params(labelsize=12).show()
"Perfect Colorbar Way")
plt.show()

观察：perfectcolorbar 的代码更简洁，意图更清晰。.label() 和 .tick_params() 是链式调用的方法。

示例 2：常用配置方法详解

Colorbar 类提供了大量方法来精细控制颜色条的外观，我们逐一来看。

设置标签

# 基本标签
Colorbar(ax, img).label('Temperature (°C)').show()
# 更详细的标签控制
Colorbar(ax, img).label(
    'Temperature (°C)',
    size=16,          # 字体大小
    weight='bold',    # 字体粗细
    color='darkred',  # 字体颜色
    pad=10            # 标签与颜色条的距离
).show()

调整刻度

Colorbar(ax, img).label('Value').tick_params(
    labelsize=14,      # 刻度标签大小
    width=1.5,         # 刻度线宽度
    length=6,          # 刻度线长度
    colors='blue',     # 刻度标签和线的颜色
    direction='inout'  # 刻度线方向 ('in', 'out', 'inout')
).show()

设置刻度标签格式

from matplotlib.ticker import FormatStrFormatter
# 使用 Matplotlib 的 Formatter
Colorbar(ax, img).label('Value').tick_params(
    labelsize=12
).formatter(FormatStrFormatter('%.2f')).show() # 保留两位小数
# 也可以直接传入格式化字符串（便捷方法）
Colorbar(ax, img).label('Value').tick_params(
    labelsize=12
).format_string('%.1f').show() # 保留一位小数

调整颜色条的位置和尺寸

Colorbar(ax, img).label('Value').tick_params(labelsize=12).location(
    'right'  # 位置: 'right', 'left', 'top', 'bottom'
).fraction(0.045)      # 占用 Axes 宽度的比例
.pad(0.05)             # 与 Axes 的间距
.orientation('vertical') # 方向: 'vertical', 'horizontal'
.show()

添加网格线

Colorbar(ax, img).label('Value').tick_params(labelsize=12).grid(
    which='major', # 'major', 'minor', or 'both'
    axis='y',      # 'x' or 'y' (对于水平颜色条是 'x')
    color='gray',
    linestyle='--',
    linewidth=0.5
).show()

示例 3：进阶用法 - 复杂布局

perfectcolorbar 在处理复杂子图布局时尤其强大。

场景：一个 2x2 的子图网格，我们只想在右侧为第一列和第三列添加一个共享的颜色条。

传统 Matplotlib 方式非常繁琐。

perfectcolorbar 方式：

import matplotlib.pyplot as plt
import numpy as np
from perfectcolorbar import Colorbar
# 创建 2x2 的子图
fig, axs = plt.subplots(2, 2, figsize=(10, 8))
fig.subplots_adjust(hspace=0.3, wspace=0.3)
# 为每个子图生成数据并绘图
for i, ax in enumerate(axs.flat):
    data = np.random.rand(10, 10)
    im = ax.imshow(data, cmap='plasma')
    ax.set_title(f'Subplot {i+1}')
# 获取第一列的 Axes 对象 (axs[0, 0] 和 axs[1, 0])
# 注意：fig.colorbar 需要一个父 Axes，我们选择第一个子图
# perfectcolorbar 可以更精确地控制
cbar_ax = fig.add_axes([0.92, 0.15, 0.02, 0.7]) # 手动创建一个 Axes 给颜色条
# 创建颜色条，并指定它应该关联到哪些图像
# 我们可以将多个图像对象传递给 Colorbar
images = [axs[0, 0].images[0], axs[1, 0].images[0]]
Colorbar(
    cbar_ax,         # 将颜色条放到我们新创建的 Axes 上
    images,          # 传递一个图像对象列表
    ticks=[0, 0.5, 1.0] # 自定义刻度位置
).label('Shared Value').tick_params(labelsize=12).show()
plt.suptitle('Advanced Layout with Shared Colorbar', fontsize=16)
plt.show()

注意：对于更复杂的共享颜色条场景，Colorbar 的构造方式可能需要结合 fig.add_axes 来手动指定颜色条的位置，这比 Matplotlib 原生方式还是要简单得多。

示例 4：水平颜色条

创建水平颜色条同样简单。

import matplotlib.pyplot as plt
import numpy as np
from perfectcolorbar import Colorbar
fig, ax = plt.subplots(figsize=(8, 2))
# 绘制一个水平的数据图
data = np.random.rand(1, 100)
img = ax.imshow(data, aspect='auto', cmap='magma', extent=[0, 100, 0, 1])
# 创建水平颜色条
Colorbar(ax, img).label('Time Series').location('bottom').orientation('horizontal').show()
"Horizontal Colorbar")
plt.show()

总结与最佳实践

1. 声明式思维：perfectcolorbar 鼓励声明式编程，你只需描述你想要的颜色条是什么样的，而不是一步步去实现它。
2. 链式调用：充分利用链式调用的便利性，将多个配置连接在一起，代码既简洁又流畅。
3. 快速原型：在数据探索和可视化原型设计阶段，perfectcolorbar 可以极大地提高效率，让你专注于数据和洞察，而不是调整样式。
4. 与传统方法结合：perfectcolorbar 并不是要取代 Matplotlib，而是在其之上提供一个更便捷的封装，如果遇到 perfectcolorbar 无法实现的极端定制需求，你仍然可以回到 Matplotlib 的原生 API 进行调整。

perfectcolorbar 是一个非常实用的工具，尤其适合那些经常需要生成高质量、风格统一图表的数据科学家和研究人员，希望这个教程能帮助你快速上手！