标签Harmony os、ArkTS、ImageKit、RGBA、透明通道透明 PNG 是图片转拼豆图中最容易被误处理的输入。一个常见做法是忽略 alpha只读取 RGB完全透明像素虽然看不见却可能携带黑色通道最后被匹配成深咖啡豆半透明红色边缘则会被当成纯红生成一圈比原图更重的描边。拼豆制图的施工底稿以白色为承载背景因此转换规则必须与最终观看环境一致alpha 很低的像素直接视为空格其余像素先与白色合成再把得到的 RGB 交给 16 色实体调色板匹配。这个顺序不能颠倒否则调色板选择面对的不是用户实际看到的颜色。当前实现把 PixelMap 解码为 70×70、RGBA_8888逐像素读取四通道并以 alpha 16 作为空格门槛。本文完整拆解这条透明像素处理链。本文会解决这些具体问题如何校验 RGBA 缓冲区长度与像素偏移。为什么完全透明像素不能继续参与颜色匹配。alpha 16 的门槛解决什么问题又有哪些边界。如何用整数公式把半透明通道与白色合成。为什么必须“先合成再找最近豆色”。如何准备透明边缘、半透明阴影和纯色样本做回归。透明像素的 RGB 不代表屏幕上看到的颜色PNG 中一个像素可以表示为(R, G, B, A)。当A 0时RGB 通道对最终显示没有贡献但文件仍可能保存任意值。例如(0, 0, 0, 0) 完全透明黑 (255, 0, 0, 0) 完全透明红 (255, 0, 0, 128) 半透明红 (255, 0, 0, 255) 不透明红前两个像素视觉结果相同若忽略 alpha却会分别匹配到深色豆与红色豆。第三个像素叠在白底上看到的是粉红不是纯红。因此转换输入不能只是 RGB 三元组。alpha 决定像素是否为空以及 RGB 要按多大比例与目标背景混合。解码阶段明确请求 RGBA_8888图像服务在创建 PixelMap 时指定目标尺寸和像素格式pixelMapawaitimageSource.createPixelMap({desiredSize:{width:size,height:size},desiredPixelFormat:image.PixelMapFormat.RGBA_8888});desiredSize把缩放前移到解码边界当前size为 70RGBA_8888则让每个通道占一个字节页面算法可以按四字节步长读取。像素格式与读取代码必须成对维护。若未来改成其他格式不能仍然假设offset 3是 alpha。格式声明属于 ImageKit 边界通道解释属于纯算法边界两处需要一起审计。缓冲区大小不要凭经验硬算当前实现从 PixelMap 获取真实字节数constpixelBytespixelMap.getPixelBytesNumber();constbuffernewArrayBuffer(pixelBytes);awaitpixelMap.readPixelsToBuffer(buffer);对理想的 70×70 RGBA 数据预计为70 × 70 × 4 19600 bytes但读取边界仍以getPixelBytesNumber()的返回值为准不要在系统对象外另外猜测分配长度。进入纯函数前可以校验最低需求functionhasEnoughRgbaBytes(buffer:ArrayBuffer,width:number,height:number):boolean{returnbuffer.byteLengthwidth*height*4;}若长度不足应明确失败不要让Uint8Array越界读取后产生一片黑色或透明格子。行列坐标必须映射到唯一四字节偏移缓冲区按行优先排列偏移公式为constbytesPerPixel4;constoffset(row*widthcol)*bytesPerPixel;constredpixels[offset];constgreenpixels[offset1];constbluepixels[offset2];constalphapixels[offset3];这个公式同时依赖 width、row、col。把height误用进索引在非正方形目标上会立即错行即使当前固定 70×70也应保持正确通用写法。可以用四个角做结构校验consttopLeft0;consttopRight(width-1)*4;constbottomLeft((height-1)*width)*4;constbottomRight(width*height-1)*4;最后一个像素会读取到bottomRight 3它必须小于缓冲区长度。alpha 小于 16 时直接生成空格当前循环先读取 alphaconstalphapixels[offset3];if(alpha16){result.push(ImageConvertService.createCell(user-chart,row,col,null));continue;}这一步阻止几乎不可见的像素变成实体豆。createCell(..., null)会写入{id:user-chart-${row}-${col},row,col,colorId:empty,colorCode:,hex:#FFFFFF,isEmpty:true}注意空格虽然用白色作为屏幕背景却不是 H9 纯白豆。真正的空格由isEmpty: true和colorId: empty定义不参与材料统计。alpha 16 是业务门槛不是透明通道的自然分界alpha 的数学范围是 0—255没有“16 以下天然为空”的规定。16 是当前项目为拼豆施工选择的业务门槛低于约 6.3% 的覆盖率时不值得为几乎不可见的残留放一颗实体豆。门槛有明确取舍门槛变化结果风险降低到 1保留更多微弱像素透明边缘产生杂豆保持 16去掉极淡残留极细阴影可能消失提高到 32轮廓更干净半透明细节损失更多调整门槛时应使用同一组透明素材对比豆数、轮廓和空格数量不能只看单个像素示例。它影响的是材料语义不只是视觉滤镜。半透明通道按白色背景做整数合成未被视为空格的像素要把每个通道与白色合成privatestaticblendWithWhite(value:number,alpha:number):number{if(alpha255){returnvalue;}returnMath.round((value*alpha255*(255-alpha))/255);}公式对应out source × alpha white × (1 - alpha)代码使用 0—255 整数表达同一关系。alpha 255直接返回原通道避免不必要计算也明确不透明像素不应改变。合成结果仍限定在 0—255Math.round保证进入颜色距离算法的是整数通道。三个通道必须使用同一个 alpha当前调用顺序为constredImageConvertService.blendWithWhite(pixels[offset],alpha);constgreenImageConvertService.blendWithWhite(pixels[offset1],alpha);constblueImageConvertService.blendWithWhite(pixels[offset2],alpha);以半透明红(255, 0, 0, 128)为例R 255 G ≈ 127 B ≈ 127 结果 ≈ (255, 127, 127)它接近粉红符合红色叠在白纸上的视觉结果。半透明黑(0, 0, 0, 128)则得到约(127,127,127)不会被误当成纯黑。不要只混合亮度或只调整一个通道。颜色距离需要完整 RGB三个通道必须使用相同 alpha 和相同背景值。背景颜色必须与最终施工语义一致为什么选择白色而不是页面主题背景因为当前编号图与导出施工图都把空格视为白色纸面。算法应该匹配最终材料和打印语义而不是用户此刻使用浅色还是深色界面。若未来支持黑色底板或彩色底板应把背景提升为明确参数interfaceRgbColor{red:number;green:number;blue:number;}functionblendChannel(source:number,background:number,alpha:number):number{returnMath.round((source*alphabackground*(255-alpha))/255);}调用者必须同时把同一背景传给预览、材料统计和导出。只改屏幕显示背景却仍按白色合成最终图纸会与预期底板不同。必须先合成再匹配 16 色调色板正确顺序是constredblendWithWhite(sourceRed,alpha);constgreenblendWithWhite(sourceGreen,alpha);constblueblendWithWhite(sourceBlue,alpha);constcolorfindNearestPaletteColor(red,green,blue);错误顺序则是先按原 RGB 找豆色再试图处理透明度// 错误示意constcolorfindNearestPaletteColor(sourceRed,sourceGreen,sourceBlue);实体豆本身没有 alpha。一旦选中某个豆色就必须放一颗不透明材料因此透明度信息只能在选择前折算到背景上。半透明红如果先匹配往往选到更饱和的红色先合成后则可能选择粉红或浅杏更接近白底视觉。空格门槛也必须发生在匹配前否则完全透明像素仍会浪费一次 16 色搜索并错误计入材料。createCellsFromBuffer 只返回普通业务对象完整纯函数不再依赖 PixelMapprivatestaticcreateCellsFromBuffer(buffer:ArrayBuffer,width:number,height:number):BeadCell[]{constpixelsnewUint8Array(buffer);constresult:BeadCell[][];for(letrow0;rowheight;row){for(letcol0;colwidth;col){constoffset(row*widthcol)*4;constalphapixels[offset3];if(alpha16){result.push(createCell(row,col,null));continue;}constcolorfindNearestPaletteColor(blendWithWhite(pixels[offset],alpha),blendWithWhite(pixels[offset1],alpha),blendWithWhite(pixels[offset2],alpha));result.push(createCell(row,col,color));}}returnresult;}系统图像对象只负责产生 ArrayBuffer后续算法只处理字节和BeadCell。这种分层让透明处理可以用人工构造的 1×1、2×2 缓冲区测试不必每次打开相册。同时返回结果不持有 PixelMap资源可以在服务层finally中立即释放。用 2×2 像素块覆盖四种透明状态最小但有效的样本可以包含constrgbanewUint8Array([0,0,0,0,// 完全透明255,0,0,15,// 门槛以下255,0,0,128,// 半透明红255,0,0,255// 不透明红]);预期不是只比较最终 HEX而是验证状态链第 1、2 格为isEmpty true。第 3 格先得到接近(255,127,127)的白底合成色再匹配调色板。第 4 格保持(255,0,0)进入匹配。四格 ID 分别包含正确 row、col。再补充 alpha 16 与 255 两个边界确保比较符号没有写成 16或 255。合成函数要满足端点、范围与单调三个不变量blendWithWhite虽然只有一个公式仍应通过不变量约束而不是只比较几个截图。第一个是端点完全不透明必须返回原通道完全透明若进入合成则应返回 255。expect(blendWithWhite(40,255)).assertEqual(40);expect(blendWithWhite(40,0)).assertEqual(255);实际业务在 alpha 小于 16 时已经提前生成空格因此第二个断言主要用于证明公式本身完整。第二个是范围。白色背景只会把通道向 255 拉近不应产生负数或超过 255for(letalpha0;alpha255;alpha){constvalueblendWithWhite(96,alpha);expect(value96value255).assertTrue();}第三个是单调性。固定源通道小于 255 时alpha 越高原色占比越大输出应逐渐从 255 靠近源值constlowAlphablendWithWhite(96,64);consthighAlphablendWithWhite(96,192);expect(highAlphalowAlpha).assertTrue();这些约束能发现分子写反、漏除以 255、把背景权重写成 alpha 等错误。它们只验证单通道公式RGB 组合、空格门槛与调色板结果仍要由上层样本覆盖。图片级样本要覆盖透明边缘与阴影纯函数样本验证公式真实图片验证缩放与轮廓。建议固定四类 PNG图片关注结果透明背景图标背景不产生黑豆或红豆带柔和阴影的贴纸阴影变浅但不出现硬边半透明红色圆白底后匹配到接近粉色的豆色不透明纯色块与无 alpha 算法结果一致还要比较透明 PNG 与把它预先铺在白底后的普通图片。两者经过 70×70 转换后主体轮廓和主要色号应接近。差异过大通常说明 alpha 处理顺序或解码通道解释有问题。重复转换同一图片还应得到相同 4900 格结果不受页面主题或上一次图片影响。常见透明处理故障按像素链定位现象先看哪里常见根因修复方向透明背景出现一圈黑豆alpha 是否参与判断直接使用隐藏 RGB低 alpha 先变空格半透明红边变成纯红合成与匹配顺序先选豆色再处理 alpha先铺白底再匹配纯白豆被删掉空格条件用 RGB 白色判断空格只用 alpha 与isEmpty图像从某行开始错色offset 公式步长不是 4 或 width 用错按行优先四通道计算末尾像素异常缓冲区长度分配不足或尺寸不一致使用真实字节数并校验透明阴影全部消失alpha 门槛业务门槛过高用固定样本重新评估 16深色模式转换结果变化背景来源使用了页面主题背景固定施工底稿背景连续转换后内存升高PixelMap 生命周期算法返回了系统对象只返回 ArrayBuffer 派生数据排查顺序是通道格式 → 缓冲区长度 → offset → alpha 门槛 → 背景合成 → 调色板匹配。直接调换某个豆色只会掩盖透明处理的根因。小结透明 PNG 转拼豆图的关键是把“像素文件里保存的 RGB”与“用户在白底上看到的颜色”分开。拼豆制图用RGBA_8888读取四通道alpha 小于 16 时生成业务空格其余像素逐通道与白色合成再进入 16 色最近色匹配。这套顺序保证完全透明像素不会变成杂豆半透明边缘不会被错误加深纯白材料也不会与空格混淆。系统对象在外层负责解码ArrayBuffer 进入纯函数最终只返回普通BeadCell[]透明处理因此既可复现也便于独立验证。