bt-luma

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

特性

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

安装

# npm
npm install bt-luma --save

# yarn
yarn add bt-luma

快速开始

1. 直接输入 RGB 数值

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 通道）：

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）：

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 文件）。