图像处理【免费下载链接】blurhashA very compact representation of a placeholder for an image.项目地址https://gitcode.com/gh_mirrors/bl/blurhash点击查看免费下载本文是 TypeScript/README.md 的深度展开版。围绕blurhash这个 npm 包逐条讲解decode、encode、isBlurhashValid三个 API 的签名、参数与完整可运行示例并向下钻取到 TypeScript/src 的源码实现base83 编解码、sRGB/线性空间转换、DCT 系数计算同时结合 Algorithm.md 说明 BlurHash 字符串的结构与解码数学原理。读完本文你将能够在浏览器中独立完成图片 → BlurHash 字符串 → Canvas 占位图的完整链路并理解每个参数punch、componentX、componentY等背后的真实影响。一、这是什么一个压缩到极致的图片占位符算法BlurHash 是 Wolt 提出的一种非常紧凑的图片占位符表示方式——它把一个图像压缩成短短 2030 个字符的短字符串前端拿到字符串后可以立即解码出一张模糊的占位图在真实图片加载完成前展示从而避免大面积灰块或布局跳动。TypeScript/README.md 给出的定位是JavaScript encoder and decoder for the Wolt BlurHash algorithm而本仓库正是该算法的官方 TypeScript 实现包名blurhash当前版本 2.0.5核心代码全部位于 TypeScript/srcdecode.ts字符串 → 像素含校验逻辑encode.ts像素 → 字符串base83.ts83 进制字符集编解码utils.tssRGB 与线性 RGB 互转、带符号幂函数error.tsValidationError异常类型index.ts统一导出入口算法层面Algorithm.md 的 Summary 讲得很清楚BlurHash 对图像数据做一次简单的DCT离散余弦变换只保留前几个频率分量再用base 83 编码字符集对 JSON、HTML 和 shell 均安全把这些分量拼成字符串其中 DC 分量图像平均颜色以 sRGB 值无损存储AC 分量则有损量化。二、安装与工程环境2.1 安装npm install --save blurhash安装后即可按需导入注意仓库实现为 ES Module CommonJS 双格式打包现代打包器与 Node 均可用import { decode, encode, isBlurhashValid } from blurhash;如果项目使用 ReactREADME 还提示可以配合 react-blurhashWolt 官方 React 封装直接以组件方式使用本文则聚焦原生 API。2.2 构建与演示脚本当前仓库 TypeScript 子项目提供以下 npm scripts见 TypeScript/package.json命令作用npm run build使用tsup打包出 CJS / ESM / 类型声明三份产物到dist/配置见 tsup.config.tsnpm starttsup --watch监听模式开发npm run demo启动webpack-dev-server运行交互式 demonpm run prettier/prettier-fix代码格式化交互式 demo 的源码在 TypeScript/src/demo.ts页面模板在 TypeScript/demo/index.html左侧选择本地图片、设置 X/Y 方向分量数默认 4×3范围 19中间输出生成的 BlurHash 字符串右侧实时解码渲染到 32×32 的 canvas 上——这是验证本库行为最直观的方式也可作为编码/解码逻辑的参考实现。三、decode把 BlurHash 字符串解码为像素3.1 API 签名decode(blurhash: string, width: number, height: number, punch?: number) Uint8ClampedArray参数说明参数类型说明blurhashstring要解码的 BlurHash 字符串width/heightnumber输出像素的宽高解码尺寸越大渲染越慢占位图通常用 32×32 或图片实际尺寸punchnumber可选解码时放大 AC 分量的倍数默认值取1值越大对比度越强见 3.3 节源码佐证返回Uint8ClampedArray长度严格等于width * height * 4按 RGBA 顺序每像素 4 字节排列alpha 恒为 255。3.2 完整示例README 原例 说明README 给出的标准用法是解码 → 写入ImageData→ 贴到 canvasimport { decode } from blurhash; const pixels decode(LEHV6nWB2yk8pyo0adR*.7kCMdnj, 32, 32); const canvas document.createElement(canvas); const ctx canvas.getContext(2d); const imageData ctx.createImageData(width, height); imageData.data.set(pixels); ctx.putImageData(imageData, 0, 0); document.body.append(canvas);注意上面width/height变量需与decode调用保持一致示例中均为 32。createImageData创建时宽高必须与pixels对应否则set会抛错。实际项目中的落地方式可以直接参考仓库 demo 的渲染逻辑TypeScript/src/demo.tsconst pixels decode(blurhash, 32, 32); const imageData new ImageData(pixels, 32, 32); ctx.putImageData(imageData, 0, 0);3.3 源码佐证punch 与校验逻辑从 decode.ts 看实现入口先校验validateBlurhash会检查字符串非空且长度 ≥ 6并从第一个字符解析出分量数再核对长度是否为4 2 * numX * numY不匹配直接抛ValidationErrordecode.ts。punch 生效点punch punch | 1未传时取 1随后在解码每个 AC 分量时乘上maximumValue * punchdecode.ts——即 punch 是解码端的对比度增强开关乘以 AC 系数而非 DC 系数因此不会改变整体平均色。像素重建对每个输出像素按 DCT 公式对numX × numY个分量做余弦加权求和再将线性 RGB 转回 sRGBdecode.ts。四、encode把像素编码为 BlurHash 字符串4.1 API 签名encode(pixels: Uint8ClampedArray, width: number, height: number, componentX: number, componentY: number) string参数说明参数类型说明pixelsUint8ClampedArrayRGBA 像素数据长度必须严格等于width * height * 4width/heightnumber像素宽高componentXnumberX 方向保留的 DCT 分量数19componentYnumberY 方向保留的 DCT 分量数19分量数即压缩率旋钮分量越多编码字符串越长、还原细节越多通常 4×3 或 4×4 已足够表现大面积色块渐变。仓库 demo 默认 4×3README 示例用 4×4。分量超出 19 或像素长度不匹配时encode会直接抛出ValidationErrorencode.ts。4.2 完整示例README 原例从图片 URL 到 BlurHashimport { encode } from blurhash; const loadImage async src new Promise((resolve, reject) { const img new Image(); img.onload () resolve(img); img.onerror (...args) reject(args); img.src src; }); const getImageData image { const canvas document.createElement(canvas); canvas.width image.width; canvas.height image.height; const context canvas.getContext(2d); context.drawImage(image, 0, 0); return context.getImageData(0, 0, image.width, image.height); }; const encodeImageToBlurhash async imageUrl { const image await loadImage(imageUrl); const imageData getImageData(image); return encode(imageData.data, imageData.width, imageData.height, 4, 4); };性能提示encode对每个分量都要遍历全部像素做余弦加权求和见 4.3复杂度约O(width × height × componentX × componentY)。因此实际项目通常先缩略图如 100px 以内再编码否则大图会明显卡顿。4.3 源码佐证DCT 系数如何算出encode.ts 的实现脉络系数投影multiplyBasisFunction对每个像素先做sRGBToLinear转换再乘上归一化余弦基函数cos(x*i*π/width) * cos(y*j*π/height)累加最后除以width * heightencode.ts——与 Algorithm.md 中DCT 保留前几阶分量的描述完全对应。DC 分量encodeDC把线性 RGB 转回 sRGB 后打包成 24 位整数R 最高位对应 BlurHash 字符串的第 3 段 4 个字符encode.ts。AC 分量量化encodeAC用带符号平方根signPow(x, 0.5)把系数压缩到 -11 再映射到 018 的整数格点三个通道合并为R*19² G*19 B范围 06859每个 AC 分量占 2 个字符encode.ts。最大值缩放所有 AC 分量统一除以实际最大值并量化到 082写为字符串第 2 段实际值恢复为(quantised 1) / 166encode.ts。拼装sizeFlag componentX - 1 (componentY - 1) * 9作为第 1 段随后依次编码最大值、DC、各 AC 分量encode.ts。五、isBlurhashValid解码前的安全校验5.1 API 签名isBlurhashValid(blurhash: string) { result: boolean; errorReason?: string }5.2 示例README 原例import { isBlurhashValid } from blurhash; const validRes isBlurhashValid(LEHV6nWB2yk8pyo0adR*.7kCMdnj); // { result: true } const invalidRes isBlurhashValid(???); // { result: false, errorReason: The blurhash string must be at least 6 characters }典型用途解码来自后端/数据库的字符串前先校验避免非法字符串导致decode抛ValidationError打断渲染流程也可以直接用它作为表单输入的实时反馈。5.3 源码佐证校验了什么isBlurhashValid 内部只是对validateBlurhash做了 try/catch 包装其校验规则decode.ts字符串非空且长度 ≥ 6首字符经decode83解析出numY floor(sizeFlag / 9) 1、numX sizeFlag % 9 1长度必须等于4 2 * numX * numY否则报blurhash length mismatch: ...。注意校验只做结构与长度检查并不会验证字符集合法性之外更深的语义例如某段字符不在 83 字符集内时decode83会得到-1由此引发的行为在 base83.ts 中未做防御。六、BlurHash 字符串结构速查配合 Algorithm.md以官方算法文档 Algorithm.md 中的示例来说明解码时每段字符的职责Example: LlMF%n00%#MwS|WCWEM{R*bbWBbH Legend: 12333344....................段长度内容11 字符分量数标志值(nx-1) (ny-1)*921 字符AC 最大值的量化值实际为(max1)/16634 字符DC 平均颜色24 位 sRGBR 在最高位4每段 2 字符 ×nx*ny-1个AC 分量按 X 递增再 Y 递增排序每段为R*19²G*19BAC 分量的解码语义与 decode.ts 的decodeAC完全一致三个通道各在 018 之间9 代表零08 为负值-((9-X)/9)²1018 为正值((X-9)/9)²最后乘上第 2 段给出的最大值再乘 punch。七、总结至此你可以完整掌握这条链路编码encode(pixels, w, h, componentX, componentY)把图像像素压缩为 2030 字符的 BlurHash 字符串分量数决定精度与长度校验isBlurhashValid(str)在渲染前确认字符串结构合法解码decode(str, w, h, punch?)立即得到 RGBA 像素画上 canvas 即为占位图punch可调节占位图对比度。对应源码均可继续深挖TypeScript/src/index.ts导出入口、TypeScript/src/decode.ts解码、TypeScript/src/encode.ts编码、TypeScript/src/base83.ts83 进制、TypeScript/src/utils.ts色彩空间转换算法总览见 Algorithm.md。赞分享图像处理【免费下载链接】blurhashA very compact representation of a placeholder for an image.项目地址https://gitcode.com/gh_mirrors/bl/blurhash点击查看免费下载相关推荐jose 库 base64url.decode 完全指南Base64URL 解码原理、严格校验与源码级剖析jose 库 base64url.decode 完全指南Base64URL 解码原理、严格校验与源码级剖析 导读 jose.base64url.decode网络安全认证鉴权后端BlurHash TypeScript实现深度剖析BlurHash TypeScript实现深度剖析 本文深入分析了BlurHash TypeScript实现的架构设计、模块划分、base83编码解码器实现细节图像处理Valibot 模块化类型安全校验库实战指南Schema 定义、数据解析与源码原理Valibot 模块化类型安全校验库实战指南Schema 定义、数据解析与源码原理 Valibot 是一个零依赖、可运行于任意 JavaScript 环境的模后端前端上一篇3分钟解锁QQ音乐加密文件qmcdump无损转换工具完全指南下一篇6大网盘直链提取告别限速的智能下载方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考