# bt-luma

**Repository Path**: rolldown/bt-luma

## Basic Information

- **Project Name**: bt-luma
- **Description**: 一款轻量、类型安全的 TypeScript 库，用于从 RGB 值计算**亮度（感知明暗程度）**，严格遵循行业标准 BT.601（标清）和 BT.709（高清/超高清）规范。专为图像处理、视频编码、UI 设计及图形应用场景设计，兼顾性能与易用性。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-10
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# bt-luma

一个轻量、高性能的 TypeScript 库，用于根据 **BT.601**（标清）和 **BT.709**（高清/超高清）标准计算 RGB 颜色的亮度值。支持直接输入 RGB 数值、RGB 字符串和十六进制颜色，专注于单颜色亮度计算场景，无冗余检查以保证极致性能。


## 特性
- ✅ 支持 BT.601 和 BT.709 两种行业标准
- ✅ 兼容多种输入格式：RGB 数值、`rgb()` 字符串、十六进制（`#fff`/`#ffffff`）
- ✅ 无冗余校验，专注性能优化（适合高频调用场景）
- ✅ 零依赖，体积极小（~1KB）
- ✅ 完整 TypeScript 类型支持


## 安装
```bash
# npm
npm install bt-luma --save

# yarn
yarn add bt-luma
```


## 快速开始
### 1. 直接输入 RGB 数值
```typescript
import { bt601, bt709 } from 'bt-luma';

// BT.601 标准（标清场景）
const luma601 = bt601(255, 128, 64); // 红=255, 绿=128, 蓝=64
console.log(luma601); // 约 136.0

// BT.709 标准（高清场景）
const luma709 = bt709(255, 128, 64);
console.log(luma709); // 约 128.0
```

### 2. 从 RGB 字符串转换
支持 `rgb()` 和 `rgba()` 格式（自动忽略 alpha 通道）：
```typescript
import { bt601, bt709 } from 'bt-luma';

// 解析 rgb 字符串
const luma1 = bt601.fromString('rgb(255, 128, 64)');
const luma2 = bt709.fromString('rgba(255, 128, 64, 0.5)'); // 忽略 alpha

// 支持 0-1 范围的数值（如图形渲染场景）
const luma3 = bt709.fromString('rgb(1.0, 0.5, 0.25)', { range: '0-1' });
```

### 3. 从十六进制颜色转换
支持 3 位（`#f08`）、6 位（`#ff0088`）及带 alpha 的格式（`#ff0088cc`）：
```typescript
import { bt601, bt709 } from 'bt-luma';

// 6 位十六进制
const luma1 = bt601.fromHex('#ff0088');

// 3 位简写（自动扩展为 6 位：#f08 → #ff0088）
const luma2 = bt709.fromHex('#f08');

// 带 alpha 通道（自动忽略）
const luma3 = bt601.fromHex('#ff0088cc');
```


## API 文档

### 核心函数
#### `bt601(r: number, g: number, b: number, options?: Options): number`
根据 BT.601 标准计算亮度（适用于标清电视、DVD 等场景）。  
- 参数：
  - `r`：红色通道值（0-255 或 0-1，取决于 `range`）
  - `g`：绿色通道值（同上）
  - `b`：蓝色通道值（同上）
  - `options`：可选配置，`{ range?: '0-255' | '0-1' }`（默认 `'0-255'`）
- 返回：亮度值（与输入范围一致）

#### `bt709(r: number, g: number, b: number, options?: Options): number`
根据 BT.709 标准计算亮度（适用于高清电视、4K 显示器、sRGB 色域等场景）。  
- 参数和返回值同 `bt601`


### 字符串转换方法
#### `bt601.fromString(str: string, options?: Options): number`
从 RGB 字符串（如 `rgb(255, 128, 64)`）解析并计算 BT.601 亮度。  
- 参数：
  - `str`：RGB/RGBA 字符串（如 `'rgb(255, 128, 64)'`、`'rgba(255,128,64,0.5)'`）
  - `options`：同核心函数

#### `bt709.fromString(str: string, options?: Options): number`
从 RGB 字符串解析并计算 BT.709 亮度，参数同上。


### 十六进制转换方法
#### `bt601.fromHex(hex: string, options?: Options): number`
从十六进制颜色（如 `#ff0088`）解析并计算 BT.601 亮度。  
- 参数：
  - `hex`：十六进制字符串（支持 `#f08`、`#ff0088`、`#ff0088cc` 等格式，可省略 `#`）
  - `options`：同核心函数（十六进制默认解析为 0-255 范围）

#### `bt709.fromHex(hex: string, options?: Options): number`
从十六进制颜色解析并计算 BT.709 亮度，参数同上。


### 工具函数（可选导出）
#### `parseRgbString(str: string): [number, number, number]`
单独解析 RGB 字符串为 [r, g, b] 数组（用于自定义处理）。

#### `parseHexString(hex: string): [number, number, number]`
单独解析十六进制颜色为 [r, g, b] 数组（用于自定义处理）。


## 支持的颜色格式
| 输入类型       | 示例                          | 说明                                  |
|----------------|-------------------------------|---------------------------------------|
| RGB 数值       | `(255, 128, 64)` 或 `(1.0, 0.5, 0.25)` | 直接输入红、绿、蓝通道值              |
| RGB 字符串     | `'rgb(255, 128, 64)'`         | 标准 CSS 格式，支持空格或无空格       |
| RGBA 字符串    | `'rgba(255, 128, 64, 0.5)'`   | 自动忽略 alpha 通道                   |
| 十六进制（6位）| `'#ff0088'` 或 `'ff0088'`     | 完整格式，支持大小写字母              |
| 十六进制（3位）| `'#f08'` 或 `'f08'`           | 简写格式，自动扩展为 6 位（`f08` → `ff0088`） |
| 带 alpha 的十六进制 | `'#ff0088cc'`  | 自动忽略 alpha 部分（取前 6 位）      |


## 注意事项
1. **无输入校验**：为保证性能，库不验证输入值的有效性（如是否在 0-255 范围内），需用户自行确保输入正确。
2. **范围处理**：
   - 十六进制和大多数 RGB 字符串默认解析为 0-255 范围。
   - 若输入为 0-1 范围的数值（如图形渲染），需通过 `{ range: '0-1' }` 声明。
3. **异常输入**：无效格式（如非数字、错误的十六进制字符）可能返回 `NaN`，需自行处理。


## 标准公式
- **BT.601**：`Y = 0.299 × R + 0.587 × G + 0.114 × B`（适用于标清场景）
- **BT.709**：`Y = 0.2126 × R + 0.7152 × G + 0.0722 × B`（适用于高清/超高清场景）


## 许可证
MIT 许可证（详见 [LICENSE](LICENSE) 文件）。