# @bb-studio/exr 中文文档

规范地址：https://npmcn.com/package/%40bb-studio/exr/

版本：0\.2\.0
npm 元数据更新时间：2026-09-20T04:55:12.284Z
中文译文更新时间：2026-11-07T18:58:15.512Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bb-studio/exr
原文对照：https://npmcn.com/package/%40bb-studio/exr/?lang=original
项目主页：https://github.com/promto-c/exr-lab/tree/main/packages/exr#readme
源码仓库：https://github.com/promto-c/exr-lab

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-03-13T20:22:52.215Z
- 最新版本发布：2026-09-20T04:55:12.127Z
- 近 30 天下载量：4647（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

OpenEXR 扫描线解析器/解码器/编码器以及浏览器和节点的后端中性 RGBA 帮助器

## 安装

```sh
npm install @bb-studio/exr
```

也可以使用：`pnpm add @bb-studio/exr`、`yarn add @bb-studio/exr`、`bun add @bb-studio/exr`

## README

# 翻译:

[![npm version](https://img.shields.io/npm/v/%40bb-studio%2Fexr?logo=npm)](https://www.npmjs.com/package/@bb-studio/exr) [![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Live%20Demo-0?logo=github)](https://promto-c.github.io/exr-lab/) [![GitHub](https://img.shields.io/github/stars/promto-c/exr-lab)](https://github.com/promto-c/exr-lab)

OpenEXR 扫描线 parser/decoder/encoder和后端中立的RGBA帮助器,用于浏览器和节点.js.

## 安装

```bash
npm install @bb-studio/exr
```

## 图像 API

```ts
import { decodeExrRgba, encodeExrRgba, inspectExrImage } from '@bb-studio/exr';

const info = inspectExrImage(buffer);
const image = decodeExrRgba(buffer);
const encodedImage = encodeExrRgba(
  { width: image.width, height: image.height, rgba: image.rgba },
  { precision: 'half', includeAlpha: true },
);
```

`decodeExrRgba` 选择请求的部分,或带有数据窗口的第一部分,扩展被采样的通道,并解决常规的RGB/A名称,包括层后缀和Y/luma倒置. 结果保留了数据/播放窗口,频道描述符,以及部分属性.

`encodeExrRgba` 接受直线 `Float32Array` RGBA像素外加可选的命名通道,打出属性,压缩,以及非零数据/播放窗口. 它返回EXR字节,没有 Blob,渲染器,或平台依赖性.

## 核心 API

```ts
import { parseExr, decodeExrPart, readExr, writeExr } from '@bb-studio/exr';

const buffer = await fetch('/image.exr').then((r) => r.arrayBuffer());
const structure = parseExr(buffer);
const decoded = decodeExrPart(buffer, structure, { partId: structure.parts[0].id });

// Convenience parse+decode in one call
const result = readExr(buffer);

// Encode scanline EXR
const encoded = writeExr({
  parts: [
    {
      compression: 3, // ZIP
      dataWindow: { xMin: 0, yMin: 0, xMax: 1, yMax: 1 },
      channels: [{ name: 'R', pixelType: 2, data: new Float32Array([0, 1, 2, 3]) }],
    },
  ],
});
```

每一部分也可提供类型 `string`, (中文(简体) ), `int`, (中文(简体) ), `float`,或 `chromaticities` 属性 :

```ts
const attributes = {
  ocioColorSpace: { type: 'string', value: 'ACEScg' },
  chromaticities: {
    type: 'chromaticities',
    value: {
      redX: 0.713,
      redY: 0.293,
      greenX: 0.165,
      greenY: 0.83,
      blueX: 0.128,
      blueY: 0.044,
      whiteX: 0.32168,
      whiteY: 0.33767,
    },
  },
} as const;
```

`decodeExrPart` 返回带有采样元数据的有样本的内源信道平面。 仅仅实现 具体物理渠道,通过确切姓名 `channelNames`数字 :

```ts
const depth = decodeExrPart(buffer, structure, {
  partId: structure.parts[0].id,
  channelNames: ['depth.Z'],
});
```

由于 OpenEXR 压缩基于块, 解码器仍然解压缩每个需要的扫描线块, 但是 它只为选定的信道分配和转换样机。 未选中的频道字节被跳过 同时保留其物理行布局。 未知请求名称失败 `CHANNEL_NOT_FOUND`。 。 。 . 工人协助 `decodeExrPartWithWorkers` API接受相同的选择.

## 浏览器工作助手

```ts
import { decodeExrPartWithWorkers, expandDecodedPartChannels } from '@bb-studio/exr/browser';
```

-   `decodeExrPartWithWorkers` 可选预解码 ZIP/DWA 块使用工人.
-   `decodeExrRgbaWithWorkers` 通过工人辅助路径应用相同的 RGBA 语义.
-   `expandDecodedPartChannels` 可从根包中获取,目前仍可在此再出口给现有的浏览器消费者.

## 错误/诊断

-   通过输入失败 `ExrError` 财务报告和审定财务报表 `ExrErrorCode`。 。 。 .
-   通过 `onEvent` 回调( n)`ExrEvent`, (中文(简体) ), `ExrEventCode`) (中文(简体) ).

## 写入支持

-   扫描线单段和多段写作.
-   压缩 : `NO_COMPRESSION`, (中文(简体) ), `RLE_COMPRESSION`, (中文(简体) ), `ZIPS_COMPRESSION`, (中文(简体) ), `ZIP_COMPRESSION`, (中文(简体) ), `PIZ_COMPRESSION`, (中文(简体) ), `PXR24_COMPRESSION`, (中文(简体) ), `B44_COMPRESSION`, (中文(简体) ), `B44A_COMPRESSION`。 。 。 .
-   像素类型 : `UINT`, (中文(简体) ), `HALF`, (中文(简体) ), `FLOAT`。 。 。 .

## 许可证

-   包许可证:麻省理工学院([`LICENSE`](https://npmcn.com/package/%40bb-studio/exr/LICENSE)(中文(简体) )
-   第三方依赖性通知: [`THIRD_PARTY_LICENSES.md`](https://npmcn.com/package/%40bb-studio/exr/THIRD_PARTY_LICENSES.md)

## 常见问题

### @bb-studio/exr 是什么？

OpenEXR 扫描线解析器/解码器/编码器以及浏览器和节点的后端中性 RGBA 帮助器

### 如何安装 @bb-studio/exr？

在项目目录运行 npm install @bb-studio/exr，或使用 pnpm add / yarn add / bun add。

### @bb-studio/exr 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bb-studio/exr 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bb-studio/exr 可以商用吗？

@bb-studio/exr 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bb-studio/exr 的下载量有多少？

根据 npm 官方下载统计，@bb-studio/exr 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,647 次，日均约 155 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bb-studio/exr 还在维护吗？

最新版本 0\.2\.0 发布于 2026/09/20（1 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/03/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。