AskaEth
2ce394fbfc
先按 alpha 过滤像素、再做块平均（整块全透明则跳过）。原实现先平均再比门槛， 块内 255 与 0 的整数除法得 127 < 128 → 512×512 里 131072 个不透明像素被报 NoOpaquePixels，UI 会告诉用户「背景图几乎全透明」，与事实相反。 - 新增 half_transparent_image_keeps_its_opaque_colour（红） - 新增 mostly_transparent_image_still_samples_the_visible_part - 模块文档加一行「混合透明度」的处置与踩坑说明
233 lines
10 KiB
Rust
233 lines
10 KiB
Rust
//! 已解码的 RGBA 像素 → 一个**种子色**（D38 第一/二级的入口，D40 的 `crates/design` 半边）。
|
||
//!
|
||
//! 这是整个取色链在 `crates/design` 里的**唯一公开入口**：零 IO、零第三方依赖，
|
||
//! 只吃「调用方已经解码好的像素」。解码（PNG/JPEG/WebP…）在 `crates/palette-extract`，
|
||
//! 分层理由见 D40。
|
||
//!
|
||
//! ```no_run
|
||
//! use unlucky_design::color::{Scheme, SchemeFlavor};
|
||
//! use unlucky_design::palette::seed_from_rgba;
|
||
//!
|
||
//! // 一张 2×2 的天蓝图（调用方负责解码）
|
||
//! let pixels: [u8; 16] = [
|
||
//! 0x3C, 0x8D, 0xBC, 0xFF, 0x3C, 0x8D, 0xBC, 0xFF,
|
||
//! 0x3C, 0x8D, 0xBC, 0xFF, 0x3C, 0x8D, 0xBC, 0xFF,
|
||
//! ];
|
||
//! let seed = seed_from_rgba(&pixels, 2, 2).expect("纯色图有确定的种子");
|
||
//! let scheme = seed.scheme(SchemeFlavor::Light, 12.0);
|
||
//! assert!(scheme.contrast(unlucky_design::color::Role::OnPrimary, unlucky_design::color::Role::Primary) >= 4.5);
|
||
//! ```
|
||
//!
|
||
//! ## 五类输入的处置（每类都有单测）
|
||
//!
|
||
//! | 输入 | 处置 | 为什么 |
|
||
//! |---|---|---|
|
||
//! | 过小图（< 4 像素） | [`Failure::TooSmall`] | 1~3 个像素没有「主色」概念，任一个噪点都会变成整套配色 |
|
||
//! | 纯色图（有彩度） | 正常取色 | 单色图只要够鲜艳就是合格的种子（不做特殊化） |
|
||
//! | 灰度/灰白图 | [`Failure::LowChroma`]（**不是**返回青灰色） | D40 实测：零彩度种子的 CAM16 色相恒为 209.49°，硬取色会把灰白壁纸「凭空上色」成青色 `#006874`；极低彩度段色相还是噪声放大器（`#808080` → 209.5°、`#7A7C7E` → 231.2°，摆 22°） |
|
||
//! | 超大图（>65536 像素） | 先按 4^n 块做**块平均**降采样，再量化 | 取色只需要「色彩分布」，不需要分辨率；块平均能保住细纹理的平均色，避免等距抽样在条纹/网格图上走样 |
|
||
//! | 混合透明度（一半不透明一半全透明） | **先按 alpha 过滤、再块平均**（整块全透明则跳过） | 「先平均再比门槛」会把 `255/2 = 127 < 128` 判成全透明，于是 13 万个不透明像素被报成 `NoOpaquePixels`——复审实测踩到的坑 |
|
||
//! | 解码失败 | 不在本 crate：见 `crates/palette-extract` | D40 分层 |
|
||
//!
|
||
//! 阈值 [`MIN_SEED_CHROMA`] = 8 是 **D40 的定案值**（`seed chroma < ~8 视为无信息量`），
|
||
//! 与 [`super::score::CUTOFF_CHROMA`] = 5 分工不同：5 决定「能不能当候选」，8 决定
|
||
//! 「这个候选够不够格当种子」。落在这条缝里（5~8）的图会有一堆候选，最终仍然回落色卡。
|
||
|
||
use super::quantize::{self, Cluster};
|
||
use super::score;
|
||
use crate::color::{Color, Palettes, Scheme, SchemeFlavor};
|
||
|
||
/// 最小像素数：低于它的图没有「主色」可言。
|
||
pub const MIN_PIXELS: u32 = 4;
|
||
/// 参与量化的最大采样点数（块的边长按它反推）。
|
||
pub const MAX_SAMPLES: usize = 65_536;
|
||
/// D40 的种子彩度门槛：低于它视为「这张图没有可用的颜色信息」。
|
||
pub const MIN_SEED_CHROMA: f64 = 8.0;
|
||
/// 「低彩度但可用」的第二道线：落在这条线下的种子会被标成 [`Seed::is_muted`]，
|
||
/// UI 可以提示「从这张图取到的颜色偏灰」。
|
||
pub const MUTED_SEED_CHROMA: f64 = 16.0;
|
||
/// alpha 低于它的像素不参与取色（半透明叠加会让颜色变成「混了背景的假色」）。
|
||
const ALPHA_THRESHOLD: u8 = 128;
|
||
|
||
/// 取色结果：种子色 + 足以让 UI 解释「为什么是这个颜色」的观感数据。
|
||
#[derive(Debug, Clone, Copy, PartialEq)]
|
||
pub struct Seed {
|
||
/// 种子色（图上真实存在的颜色，不是各色平均出来的）。
|
||
pub color: Color,
|
||
/// 种子的 CAM16 色相角（度）。
|
||
pub hue: f64,
|
||
/// 种子的 CAM16 彩度。
|
||
pub chroma: f64,
|
||
/// 该色在其色相族里占全图的像素比例（0..1）。
|
||
pub share: f64,
|
||
}
|
||
|
||
impl Seed {
|
||
/// 种子彩度偏低（可用但发灰）——UI 可提示「这张图颜色较淡」。
|
||
pub fn is_muted(self) -> bool {
|
||
self.chroma < MUTED_SEED_CHROMA
|
||
}
|
||
|
||
/// 用这个种子生成一套完整调色板（中性彩度由调用方给，通常沿用用户当前选中色卡的取值）。
|
||
pub fn palettes(self, neutral_chroma: f64) -> Palettes {
|
||
Palettes::from_seed_with_neutral_chroma(self.color, neutral_chroma)
|
||
}
|
||
|
||
/// 用这个种子生成一套完整方案（49 个角色）。
|
||
pub fn scheme(self, flavor: SchemeFlavor, neutral_chroma: f64) -> Scheme {
|
||
Scheme::from_palettes(&self.palettes(neutral_chroma), flavor)
|
||
}
|
||
}
|
||
|
||
/// 取色失败的原因。**每一种都要能变成一句人话**（Provenance 用它生成提示）。
|
||
#[derive(Debug, Clone, Copy, PartialEq)]
|
||
pub enum Failure {
|
||
/// 像素缓冲长度与 `width × height × 4` 不符（调用方给错了数据）。
|
||
BadDimensions {
|
||
/// 宽。
|
||
width: u32,
|
||
/// 高。
|
||
height: u32,
|
||
/// 期望的字节数（`width × height × 4`）。
|
||
expected: usize,
|
||
/// 实际拿到的字节数。
|
||
actual: usize,
|
||
},
|
||
/// 图太小（< [`MIN_PIXELS`] 像素）。
|
||
TooSmall {
|
||
/// 宽。
|
||
width: u32,
|
||
/// 高。
|
||
height: u32,
|
||
},
|
||
/// 全是透明/半透明像素，没有可用的不透明像素。
|
||
NoOpaquePixels,
|
||
/// 彩度不足：`chroma < MIN_SEED_CHROMA`，硬取色会凭空上色。
|
||
LowChroma {
|
||
/// 最有希望的那个色（提示文案里当「最接近的颜色」）。
|
||
color: Color,
|
||
/// 实测 CAM16 彩度。
|
||
chroma: f64,
|
||
},
|
||
}
|
||
|
||
impl Failure {
|
||
/// 稳定原因码（写日志 / 存设置 / 做提示映射的键，别用 `Debug` 输出）。
|
||
pub const fn code(self) -> &'static str {
|
||
match self {
|
||
Failure::BadDimensions { .. } => "bad-dimensions",
|
||
Failure::TooSmall { .. } => "too-small",
|
||
Failure::NoOpaquePixels => "no-opaque-pixels",
|
||
Failure::LowChroma { .. } => "low-chroma",
|
||
}
|
||
}
|
||
}
|
||
|
||
/// 取色并给出**完整原因**（推荐入口：失败时能生成提示）。
|
||
pub fn analyze_rgba(pixels: &[u8], width: u32, height: u32) -> Result<Seed, Failure> {
|
||
let total = (width as usize).saturating_mul(height as usize);
|
||
if total < MIN_PIXELS as usize {
|
||
return Err(Failure::TooSmall { width, height });
|
||
}
|
||
let expected = total.saturating_mul(4);
|
||
if pixels.len() != expected {
|
||
return Err(Failure::BadDimensions {
|
||
width,
|
||
height,
|
||
expected,
|
||
actual: pixels.len(),
|
||
});
|
||
}
|
||
|
||
// 采样点已经是「只由不透明像素算出的块平均」（见 [`sample_blocks`]），这里不再按 alpha 过滤。
|
||
let samples = sample_blocks(pixels, width as usize, height as usize);
|
||
if samples.is_empty() {
|
||
return Err(Failure::NoOpaquePixels);
|
||
}
|
||
|
||
let clusters = quantize::quantize(&samples);
|
||
let ranked = score::rank(&clusters);
|
||
match ranked.first() {
|
||
Some(best) if best.chroma >= MIN_SEED_CHROMA => Ok(Seed {
|
||
color: best.cluster.color,
|
||
hue: best.hue,
|
||
chroma: best.chroma,
|
||
share: best.excited,
|
||
}),
|
||
// 有候选但都不够鲜艳：带着「最鲜艳的候选」和实测彩度回去，让 UI 能说清原因。
|
||
Some(best) => Err(Failure::LowChroma {
|
||
color: best.cluster.color,
|
||
chroma: best.chroma,
|
||
}),
|
||
// 一个候选都没有（灰度图）：把最鲜艳的簇的彩度报回去（通常是 0~4）。
|
||
None => Err(Failure::LowChroma {
|
||
color: most_populated(&clusters)
|
||
.map(|cluster| cluster.color)
|
||
.unwrap_or(Color::rgb(0x80, 0x80, 0x80)),
|
||
chroma: score::max_chroma(&clusters),
|
||
}),
|
||
}
|
||
}
|
||
|
||
/// D40 的入口形状：`Option<Seed>`（`None` = 这张图没有可用的颜色信息）。
|
||
///
|
||
/// 需要知道「为什么没有」就用 [`analyze_rgba`]。
|
||
pub fn seed_from_rgba(pixels: &[u8], width: u32, height: u32) -> Option<Seed> {
|
||
analyze_rgba(pixels, width, height).ok()
|
||
}
|
||
|
||
fn most_populated(clusters: &[Cluster]) -> Option<&Cluster> {
|
||
clusters.iter().max_by_key(|cluster| cluster.population)
|
||
}
|
||
|
||
/// 块平均降采样：块边长按「不超过 [`MAX_SAMPLES`] 个采样点」反推，小图不降采样（块边长 1）。
|
||
///
|
||
/// **先按 alpha 过滤、再求平均**：块内只累加 `a >= ALPHA_THRESHOLD` 的像素，整块没有有效像素
|
||
/// 就直接跳过（不产出采样点）。
|
||
///
|
||
/// 为什么不能「先平均、再拿平均 alpha 跟门槛比」：块内 alpha 用整数除法截断，
|
||
/// 一半不透明一半透明的块平均下来是 `255/2 = 127 < 128`，于是**整张图被判成「没有不透明像素」**
|
||
/// （复审实测：512×512 里 131072 个完全不透明像素 → `Err(NoOpaquePixels)`）。
|
||
/// 副作用是「半透明像素的颜色」也被排除在外——这是有意的：半透明像素的 RGB 常常是
|
||
/// 未预乘的原始值（有些解码器给的是 0,0,0），混进来会把种子拽向黑色。
|
||
fn sample_blocks(pixels: &[u8], width: usize, height: usize) -> Vec<Color> {
|
||
let mut block = 1usize;
|
||
while width.div_ceil(block) * height.div_ceil(block) > MAX_SAMPLES {
|
||
block += 1;
|
||
}
|
||
|
||
let mut samples = Vec::with_capacity(width.div_ceil(block) * height.div_ceil(block));
|
||
let mut top = 0usize;
|
||
while top < height {
|
||
let bottom = (top + block).min(height);
|
||
let mut left = 0usize;
|
||
while left < width {
|
||
let right = (left + block).min(width);
|
||
let mut sum = [0u64; 3];
|
||
let mut count = 0u64;
|
||
for y in top..bottom {
|
||
for x in left..right {
|
||
let offset = (y * width + x) * 4;
|
||
if pixels[offset + 3] < ALPHA_THRESHOLD {
|
||
continue;
|
||
}
|
||
for channel in 0..3 {
|
||
sum[channel] += u64::from(pixels[offset + channel]);
|
||
}
|
||
count += 1;
|
||
}
|
||
}
|
||
if count > 0 {
|
||
let average = |channel: usize| (sum[channel] / count) as u8;
|
||
samples.push(Color::rgb(average(0), average(1), average(2)));
|
||
}
|
||
left = right;
|
||
}
|
||
top = bottom;
|
||
}
|
||
samples
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests;
|