Skip to content

Usage

基础用法

1
2
from multicolor import cmap, batch_cmaps, batch_colors, data_ensure
from multicolor import data_list, is_available, data_remove

获取色带

1
2
3
4
5
# 按名称获取
viridis = cmap.get("Viridis")

# 按 ID 获取
cm = cmap.get_by_id(1)

筛选与查询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# 按类型筛选
for _, name, _ in cmap.list(cmap_type="sequential"):
    print(name)

# 按色盲兼容性筛选
names = cmap.names(colorblind_safe="any")

# 按来源筛选
names = cmap.names(source="matplotlib")

# 只看内置 / 自定义
cmap.list(is_custom=False)  # 内置色带
cmap.list(is_custom=True)   # 用户自定义色带

# 关键词搜索
cmap.list(keyword="temperature")

# 轻量元数据查询（不构建 Colormap 对象）
records = cmap.records(cmap_type="diverging")

添加自定义色带

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
cmap.add(
    name="MyCmap",
    colors=["#ff0000", "#00ff00"],
    cmap_type="sequential",
    tags=["custom"],
    source=["user"],
)

# 删除自定义色带
cmap.remove("MyCmap")

# 导出/导入自定义色带
cmap.export("my_cmaps.json")
cmap.import_data("my_cmaps.json")

色带集合（链式操作）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
from multicolor import cmap

col = cmap.collection(cmap_type="sequential")

# 链式筛选
filtered = col.filter(colorblind_safe="any").filter(tag="common")

# 分组
groups = col.group_by("cmap_type")

# 导出
col.to_html("palette.html")
col.export_images("output/", orientation="horizontal")

装饰器批量绘图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# batch_cmaps: 传递 Colormap 对象
@batch_cmaps(["Viridis", "Plasma"])
def draw(cmap_obj):
    # 自动循环两次
    pass

# batch_colors: 传递原始数据库记录 dict
@batch_colors(["Viridis", "Plasma"])
def process_colors(record):
    # record["colors"] 是 hex 列表
    pass

# 动态查询
@batch_cmaps(query_func=lambda: cmap.names(cmap_type="diverging"))
def draw_all(cmap_obj):
    pass

# grid 布局
@batch_cmaps(["Viridis", "Plasma", "Inferno"], layout="grid", cols=2)
def draw_grid(cmap_obj, ax=None):
    pass

GIS 数据懒下载

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from multicolor import data_list, data_ensure, is_available, data_remove, data_get

# 查看可用数据集
for ds in data_list():
    print(ds["name"], "[cached]" if ds["available"] else "[not downloaded]")

# 自动下载（首次）+ 缓存
path = data_ensure("tavg_10min")

# 检查是否已缓存
is_available("tavg_10min")  # True

# 强制重新下载
data_get("tavg_10min", force=True)

# 删除缓存
data_remove("tavg_10min")

完整示例

更多详细用法见 Examples：