Metadata-Version: 2.4
Name: multicolor
Version: 0.0.4
Summary: A python package for mapping
Author-email: zbhgis <zbhgisrs@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/zbhgis/multicolor
Keywords: multicolor
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cartopy>=0.25.0
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: all
Requires-Dist: multicolor[extra]; extra == "all"
Provides-Extra: extra
Requires-Dist: pandas; extra == "extra"
Dynamic: license-file

# multicolor

[![PyPI version](https://img.shields.io/pypi/v/multicolor.svg)](https://pypi.python.org/pypi/multicolor)
[![License](https://img.shields.io/github/license/zbhgis/multicolor)](https://github.com/zbhgis/multicolor)

**A Python package for colormap management and batch plotting.**

- Free software: MIT License
- Documentation: <https://zbhgis.github.io/multicolor>

## Features

- **色带数据库** — 基于 SQLite 内置 12 条色带，支持按类型、标签、色盲兼容性、关键词筛选
- **色带工厂** — 从数据库一键生成 `matplotlib` Colormap 对象（Sequential / Diverging / Qualitative）
- **自定义色带** — 用户可添加自己的色带，内置色带受保护不可覆盖
- **自动同步** — 升级包时自动同步新版内置色带，同时保留用户自定义内容
- **装饰器批量绘图** — `@batch_cmaps` 一键将同一绘图函数应用到多个色带
- **多子图导出** — 支持 single（独立窗口）和 grid（单图多子图）两种布局

## Installation

### 稳定版

```bash
pip install multicolor
```

### 开发版

```bash
pip install git+https://github.com/zbhgis/multicolor.git
```

### 环境要求

- Python >= 3.10
- 依赖：`cartopy>=0.25.0`, `matplotlib>=3.10.0`, `numpy>=1.24.0`

## Quick Start

### 获取色带

```python
from multicolor import cmap

# 按名称获取
viridis = cmap.get("Viridis")

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

### 筛选与查询

```python
# 按类型
names = cmap.names(cmap_type="sequential")

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

# 只看内置色带（排除用户自定义）
names = cmap.names(is_custom=False)

# 只看用户自定义色带
names = cmap.names(is_custom=True)

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

### 添加自定义色带

```python
cmap.add(
    name="MyCmap",
    colors=["#ff0000", "#00ff00", "#0000ff"],
    cmap_type="sequential",
    tags=["custom"],
    colorblind_safe="none",
    description="my custom colormap",
)
```

### 装饰器批量绘图

```python
from multicolor import cmap, batch_cmaps

# 方式 1：直接指定名称列表
@batch_cmaps(["Viridis", "Plasma", "Inferno"])
def draw(cmap_obj):
    cmap.preview(cmap_obj)

# 方式 2：动态查询筛选
@batch_cmaps(query_func=lambda: cmap.names(cmap_type="diverging"))
def draw_all_diverging(cmap_obj):
    cmap.preview(cmap_obj)

# 方式 3：grid 布局（所有色带画在一张图上）
@batch_cmaps(
    query_func=lambda: cmap.names(colorblind_safe="any", limit=6),
    layout="grid",
    cols=3
)
def draw_grid(cmap_obj, ax=None):
    ax.imshow(data, cmap=cmap_obj)

draw()
draw_all_diverging()
draw_grid()
```

### 结合 Cartopy 绘制地图

```python
import matplotlib.pyplot as plt
import cartopy.crs as ccrs
from multicolor import cmap, batch_cmaps

@batch_cmaps(query_func=lambda: cmap.names(cmap_type="sequential"))
def draw_map(cmap_obj):
    fig = plt.figure()
    ax = fig.add_subplot(1, 1, 1, projection=ccrs.PlateCarree())
    ax.coastlines()
    ax.imshow(data, cmap=cmap_obj, transform=ccrs.PlateCarree())
    plt.savefig(f"map_{cmap_obj.name}.png")
    plt.close()

draw_map()
```

## 内置色带

| ID | Name | Type | Colorblind Safe |
|----|------|------|----------------|
| 1 | RdYlGn | diverging | deutan, protan |
| 2 | Viridis | sequential | deutan, protan, tritan |
| 3 | CoolWarm | diverging | deutan |
| 4 | Terrain | diverging | - |
| 5 | NightLights | sequential | - |
| 6 | LandUse | qualitative | - |
| 7 | Plasma | sequential | deutan |
| 8 | RdBu | diverging | deutan |
| 9 | Inferno | sequential | deutan, protan |
| 10 | Cividis | sequential | deutan, protan, tritan, achromatopsia |
| 11 | Precip | sequential | deutan |
| 12 | Elevation | sequential | - |

## License

MIT License. See [LICENSE](LICENSE) for details.
