# Kivy 颜色对比度与前景色自动选择工具文档

```markdown
# Kivy 前景色自适应选择函数技术文档

## 概述

该模块提供两个核心函数，用于在 Kivy 框架中根据背景颜色（`bgcolor`）智能选择合适的前景色（如文本颜色），以确保良好的可读性和视觉对比度。其原理基于人眼对不同颜色的感知灰度值，使用心理学标准公式计算灰度，并据此判断应使用深色或浅色前景。

## 编码说明

```python
# -*- coding=utf-8 -*-
```

源码采用 UTF-8 编码，支持中文注释和文档。

---

## 核心原理

### 灰度感知公式

人眼对不同颜色的敏感度不同，因此即使 RGB 值相同，感知亮度也不同。本模块使用标准灰度转换公式：

$$
\text{灰度} = R \times 0.299 + G \times 0.587 + B \times 0.114
$$

其中：
- $ R $：红色分量（0 ~ 1）
- $ G $：绿色分量（0 ~ 1）
- $ B $：蓝色分量（0 ~ 1）

> ✅ **说明**：此权重来源于 ITU-R BT.601 标准，广泛应用于图像处理领域。

根据计算出的灰度值：
- 若灰度 > `0.5`，表示背景较亮，应使用**暗色前景**；
- 若灰度 ≤ `0.5`，表示背景较暗，应使用**亮色前景**。

---

## 函数接口

### `color_gray_rate(color)`

计算给定颜色的感知灰度值。

#### 参数
| 参数名 | 类型 | 描述 |
|--------|------|------|
| `color` | list[float] | 颜色列表 `[R, G, B, A]` 或 `[R, G, B]`，各分量范围为 0~1 |

> ⚠️ 注意：Alpha 通道（透明度）不参与灰度计算。

#### 返回值
- `float`：计算得到的灰度值（0 ~ 1 范围内）

#### 示例
```python
color_gray_rate([1.0, 0.0, 0.0])  # 红色 -> 返回约 0.299
color_gray_rate([0.0, 1.0, 0.0])  # 绿色 -> 返回约 0.587
color_gray_rate([0.0, 0.0, 1.0])  # 蓝色 -> 返回约 0.114
```

---

### `get_fgcolor_from_bgcolor(bgcolor, colors=None)`

根据背景色自动选择最佳前景色。

#### 参数
| 参数名 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| `bgcolor` | list[float] | —— | 背景颜色，格式为 `[R, G, B, A]` |
| `colors` | list[list[float]] 或 None | `None` | 可选的两个前景候选颜色；若为 `None`，则使用内置默认颜色 |

#### 内置默认颜色
- 深色前景：`[0.11, 0.11, 0.11, 1]`（接近黑色）
- 浅色前景：`[0.89, 0.89, 0.89, 1]`（接近白色）

#### 返回值
- `list[float]`：推荐使用的前景颜色（四元组 `[R, G, B, A]`）

#### 工作逻辑

1. 计算背景色的灰度值 `graylevel`
2. 如果未传入 `colors`：
   - 若 `graylevel > 0.5`，返回深色前景
   - 否则返回浅色前景
3. 如果传入了 `colors = [color1, color2]`：
   - 分别计算两个候选颜色的灰度值 `r1`, `r2`
   - 选择与背景灰度差异更大的那个颜色（即对比度更高）
   - 即：比较 `|graylevel - r1|` 与 `|graylevel - r2|`

> ✅ **优势**：支持自定义配色方案，适用于品牌色、主题色等场景。

#### 示例

```python
# 使用默认颜色
get_fgcolor_from_bgcolor([1.0, 1.0, 1.0])     # 白色背景 → 返回 [0.11,0.11,0.11,1]
get_fgcolor_from_bgcolor([0.0, 0.0, 0.0])     # 黑色背景 → 返回 [0.89,0.89,0.89,1]

# 自定义前景颜色
custom_colors = [
    [0.2, 0.6, 0.8, 1],  # 蓝绿色
    [1.0, 0.9, 0.1, 1]   # 明黄色
]
get_fgcolor_from_bgcolor([0.1, 0.1, 0.6], custom_colors)
```

---

## 应用场景

- 动态 UI 主题系统（如深色/浅色模式自动切换文字颜色）
- 标签、按钮、卡片组件的文字颜色适配
- 数据可视化中动态调整标签颜色
- 提升无障碍访问性（Accessibility）

---

## 注意事项

1. 所有颜色值需归一化到 `0~1` 范围（Kivy 要求），不可使用 `0~255` 的整数。
2. 推荐前景色的 Alpha 通常设为 `1`（完全不透明）。
3. 在极端中间色调（灰度 ≈ 0.5）时建议人工微调或增加容差判断。

---

## 版权与许可

© 2025 开源工具函数  
可用于 Kivy 项目中的颜色对比优化，欢迎自由使用与扩展。
```

> 💡 **提示**：可将此文档保存为 `README.md` 或集成至 Sphinx 文档系统中。