# @fideus-labs/fiff 中文文档

规范地址：https://npmcn.com/package/%40fideus-labs/fiff/

版本：0\.8\.2
npm 元数据更新时间：2026-10-08T17:31:45.426Z
中文译文更新时间：2026-11-14T17:15:03.832Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fideus-labs/fiff
原文对照：https://npmcn.com/package/%40fideus-labs/fiff/?lang=original
项目主页：https://github.com/fideus-labs/fiff#readme
源码仓库：https://github.com/fideus-labs/fiff

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

- 包体积（解压后）：269 kB，59 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@fideus-labs/ngff-zarr ^0\.38\.0，@fideus-labs/worker-pool ^2\.1\.0
- 首次发布：2026-02-14T19:45:39.964Z
- 最新版本发布：2026-10-08T17:31:45.071Z
- 近 30 天下载量：7225（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

使用 NGFF OME- Zarr 数据模型将 TIFF 文件作为 sarrita.js Zarr 存储

## 安装

```sh
npm install @fideus-labs/fiff
```

也可以使用：`pnpm add @fideus-labs/fiff`、`yarn add @fideus-labs/fiff`、`bun add @fideus-labs/fiff`

## README

**(法语)**

[![CI](https://github.com/fideus-labs/fiff/actions/workflows/ci.yml/badge.svg)](https://github.com/fideus-labs/fiff/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@fideus-labs/fiff)](https://www.npmjs.com/package/@fideus-labs/fiff) [![license](https://img.shields.io/npm/l/@fideus-labs/fiff)](https://github.com/fideus-labs/fiff/blob/main/LICENSE.txt)

读写 [OME-TIFF( 欧美论坛)](https://docs.openmicroscopy.org/ome-model/latest/ome-tiff/) 通过 a 文件 [萨里塔.js](https://github.com/manzt/zarrita.js) 跟踪Zarr商店 [OME-Zarr v0.5 (英语)](https://ngff.openmicroscopy.org/0.5/) 数据模型.

## \* 特性

### 阅读

-   🚀 **懒惰的 HTTP 范围请求** -- 数据按要求通过 giotiff.js (英语) `readRasters()`,不需要完整文件下载
-   📐 **OME-XML 支持** - 分析 OME-XML 元数据,用于维度、通道、, 物理单位和所有6个尺寸顺序
-   🔍 **金字塔检测** -- 自动发现多分辨率级别 通过子IFDs(现代),平面IFDs(遗留),或COG概览
-   🧩 **边平面零铺设** -- 边界块自动添加到 正确 Zarr 消耗的全部瓦片大小
-   🔗 **zarrita.js 兼容性** -- 执行 `AsyncReadable` 接口; 直接使用与 `zarr.open()` 从扎里塔.js
-   📋 **OME- Zarr v0.5 输出** -- 生成 Zarr v3 元数据 `ome.multiscales` 财务报告和审定财务报表 `ome.omero` 属性

### 写入

-   📝 **OME-TIFF 生成** -- 转换ngff- sarr `Multiscales` 对象为 有效的 OME- TIFF 有嵌入式 OME- XML 元数据的文件
-   🔻 **完全金字塔支持** -- 多解析级为 SubIFDs, 匹配现代 OME-TIFF 金字塔公约
-   🗜️ **断层压缩** - Async zlib/通过土生土长 `CompressionStream` (非阻断) 与同步的后退
-   🧵 **工人集合支助** - 可选 `@fideus-labs/worker-pool` 融合 向Web Workers卸载压缩并解压,全部释放 主线程
-   🧱 **倾斜输出** -- 大图像自动写入为 256x256 块 (可配置), OME-TIFF 高效随机访问推荐格式
-   ⚡ **平行平面读取** -- 飞机用有限度的货币阅读 (可配置)用于从 aync 数据源快速写入
-   💾 **BigTIFF 支助** -- 文件超过时自动使用64位平移格式 4GB,手动覆盖通过 `format` 选项
-   📐 **5D支助** - 处理所有尺寸命令(XYZCT、XYZTC等)和 任意组合 T、 C、 Z、 Y、 X轴
-   🔌 **自定义平面阅读器** -- 可插件 `getPlane` 调用替换 内部 `zarr.get()`,使工人集体解压或零拷贝读取 从未压缩的 zarr 阵列中

## \* 安装

```bash
npm install @fideus-labs/fiff
```

对于写入支持, 同时安装可选的对等依赖 :

```bash
npm install @fideus-labs/ngff-zarr
```

工人池支持(向网络工人卸载压缩/解压):

```bash
npm install @fideus-labs/worker-pool
```

## 使用量

### 读取: 打开 OME- TIFF 作为 Zar 商店

#### 从远程 URL

```typescript
import { TiffStore } from "@fideus-labs/fiff";
import * as zarr from "zarrita";

const store = await TiffStore.fromUrl("https://example.com/image.ome.tif");
const group = await zarr.open(store as unknown as zarr.Readable, { kind: "group" });

// Open the full-resolution array (level 0)
const arr = await zarr.open(group.resolve("0"), { kind: "array" });
const chunk = await zarr.get(arr);

console.log(chunk.shape); // e.g. [1, 3, 1, 512, 512]
console.log(chunk.data);  // Float32Array, Uint16Array, etc.
```

#### 从矩阵缓冲器

```typescript
const response = await fetch("https://example.com/image.tif");
const buffer = await response.arrayBuffer();
const store = await TiffStore.fromArrayBuffer(buffer);
```

#### 从文件 / Blob 中

```typescript
const file = document.querySelector("input[type=file]").files[0];
const store = await TiffStore.fromBlob(file);
```

#### 从现有的 GeoTIFF 实例

```typescript
import { fromUrl } from "geotiff";

const tiff = await fromUrl("https://example.com/image.tif");
const store = await TiffStore.fromGeoTIFF(tiff);
```

#### 访问存储元数据

```typescript
const store = await TiffStore.fromUrl("https://example.com/image.ome.tif");

store.levels;         // number of resolution levels
store.dataType;       // "uint16", "float32", etc.
store.dimensionNames; // ["t", "c", "z", "y", "x"]
store.getShape(0);    // full-res shape, e.g. [1, 3, 1, 2048, 2048]
store.getShape(1);    // level 1 shape, e.g. [1, 3, 1, 1024, 1024]
store.ome;            // parsed OME-XML image metadata (if present)
store.pyramidInfo;    // pyramid structure details
```

### 读取: 从 TiffStore 装入多级

`TiffStore` 执行 zarrita `Readable` 界面,所以可以通过 直接到gff -zarr's的 `fromNgffZarr` 获取 `Multiscales` 对象 :

```typescript
import { TiffStore } from "@fideus-labs/fiff";
import { fromNgffZarr } from "@fideus-labs/ngff-zarr";

const store = await TiffStore.fromUrl("https://example.com/image.ome.tif");
const multiscales = await fromNgffZarr(store, { version: "0.5" });

const image = multiscales.images[0];
console.log(image.dims);        // e.g. ["t", "c", "z", "y", "x"]
console.log(image.data.shape);  // e.g. [1, 3, 1, 512, 512]
console.log(image.data.dtype);  // e.g. "uint16"
console.log(image.scale);       // e.g. { t: 1, c: 1, z: 1, y: 0.5, x: 0.5 }

console.log(multiscales.metadata.axes);     // axis definitions
console.log(multiscales.metadata.datasets); // dataset paths and transforms
```

### 写入: 将 ngff- zarr 多级转换为 OME- TIFF

`toOmeTiff()` 需要一个纳克-扎尔 `Multiscales` 对象返回完整 作为 OME-TIFF 文件 `ArrayBuffer`。 。 。 .

#### 基本写法

```typescript
import { toOmeTiff } from "@fideus-labs/fiff";
import {
  createNgffImage,
  createAxis,
  createDataset,
  createMetadata,
  createMultiscales,
} from "@fideus-labs/ngff-zarr";
import * as zarr from "zarrita";

// 1. Create an ngff-zarr image
const image = await createNgffImage(
  [],              // no parent images
  [512, 512],      // shape: [y, x]
  "uint16",        // data type
  ["y", "x"],      // dimension names
  { y: 0.5, x: 0.5 },    // pixel spacing (micrometers)
  { y: 0.0, x: 0.0 },    // origin offsets
  "my-image",
);

// 2. Populate pixel data
const data = new Uint16Array(512 * 512);
for (let i = 0; i < data.length; i++) data[i] = i % 65536;
await zarr.set(image.data, null, {
  data,
  shape: [512, 512],
  stride: [512, 1],
});

// 3. Build the Multiscales object
const axes = [
  createAxis("y", "space", "micrometer"),
  createAxis("x", "space", "micrometer"),
];
const datasets = [createDataset("0", [0.5, 0.5], [0.0, 0.0])];
const metadata = createMetadata(axes, datasets, "my-image");
const multiscales = createMultiscales([image], metadata);

// 4. Write to OME-TIFF
const buffer = await toOmeTiff(multiscales);

// Save to disk (Node.js / Bun)
await Bun.write("output.ome.tif", buffer);
```

#### 写入选项

```typescript
const buffer = await toOmeTiff(multiscales, {
  compression: "deflate",  // "deflate" (default) or "none"
  compressionLevel: 6,     // 1-9, default 6 (only for deflate)
  dimensionOrder: "XYZCT", // IFD layout order, default "XYZCT"
  imageName: "my-image",   // name in OME-XML metadata
  creator: "my-app",       // creator string in OME-XML
  tileSize: 256,           // tile size in px (0 = strip-based), default 256
  concurrency: 4,          // parallel plane reads, default 4
  format: "auto",          // "auto" | "classic" | "bigtiff", default "auto"
  getPlane: zarrGet,       // custom plane reader (e.g. ngff-zarr's zarrGet)
});
```

### 工人池:向网络工人卸载压缩

通过一个 `@fideus-labs/worker-pool` 例如,降压压缩(写作) 并使用该标准在网络工人上运行解压(读取) `CompressionStream` 编号 : `DecompressionStream` APIs — 完全释放主 线程.

#### 用工人池写作

```typescript
import { toOmeTiff } from "@fideus-labs/fiff";
import WorkerPool from "@fideus-labs/worker-pool";

const pool = new WorkerPool(navigator.hardwareConcurrency ?? 4);

const buffer = await toOmeTiff(multiscales, {
  pool,              // tiles are compressed on workers
  compression: "deflate",
});

pool.terminateWorkers();
```

#### 用工人游泳池阅读

```typescript
import { TiffStore } from "@fideus-labs/fiff";
import WorkerPool from "@fideus-labs/worker-pool";

const pool = new WorkerPool(4);

// Registers a worker-backed deflate decoder with geotiff.js.
// This is a global registration — it affects all geotiff instances.
const store = await TiffStore.fromUrl(
  "https://example.com/image.ome.tif",
  { pool },
);

// All subsequent chunk reads decompress on workers
const group = await zarr.open(store as unknown as zarr.Readable, { kind: "group" });
const arr = await zarr.open(group.resolve("0"), { kind: "array" });
const chunk = await zarr.get(arr);

pool.terminateWorkers();
```

#### 低级别: 带游泳池的构建Tiff

```typescript
import { buildTiff, type WritableIfd } from "@fideus-labs/fiff";
import WorkerPool from "@fideus-labs/worker-pool";

const pool = new WorkerPool(4);
const ifds: WritableIfd[] = [/* ... */];

const buffer = await buildTiff(ifds, {
  compression: "deflate",
  pool,
});

pool.terminateWorkers();
```

### 自定义平面阅读器( O)`getPlane`(中文(简体) )

默认 `toOmeTiff()` 读取每个带有内置的平面( C, Z, T) `zarr.get()`。您可以通过 `getPlane` 选项。 这对于:

-   **卸载去压** - 纳克扎尔的 `zarrGet` 运行 blosc 解压在工人池取而代之的是主线.
-   **完全跳过解压** - 当记忆中的撒勒阵列是 创建于 `bytesOnlyCodecs()` (没有压缩),读作是微不足道的 零起落点.

```typescript
import { toOmeTiff } from "@fideus-labs/fiff"
import { bytesOnlyCodecs, toMultiscales, zarrGet } from "@fideus-labs/ngff-zarr"

// Create multiscales with no compression (OME-TIFF will re-compress with deflate)
const multiscales = await toMultiscales(ngffImage, {
  method: Methods.ITKWASM_GAUSSIAN,
  codecs: bytesOnlyCodecs(),
})

// Write OME-TIFF using zarrGet to read planes (worker-pool-aware)
const buffer = await toOmeTiff(multiscales, {
  compression: "deflate",
  getPlane: zarrGet,
})
```

这个 `GetPlane` 回调类型镜像 `zarr.get()`数字 :

```typescript
type GetPlane = (
  data: zarr.Array<zarr.DataType, zarr.Readable>,
  selection: (number | null)[],
) => Promise<{ data: unknown }>
```

#### 如何运作

-   工人使用情况 `CompressionStream("deflate")` 编号 : `DecompressionStream("deflate")` - 工人内部没有附属物或其他附属物
-   工人脚本在运行时作为 blob URL 内置( 没有单独的文件服务)
-   主线和工人之间转移( 零拷贝) 串联
-   当压缩级别不是默认的 (6),或者没有提供池, fiff倒回已存在的主行路径( CompressStream - > fflate)
-   游泳池的有界货币 代替无界货币 `Promise.all` 超过平板

#### 多分辨率金字塔

当 `Multiscales` 对象包含多个图像(分辨率水平), 所有子分辨率级别都写为 SubIFD:

```typescript
const fullRes = await createNgffImage([], [1024, 1024], "uint16", ["y", "x"], ...);
const halfRes = await createNgffImage([], [512, 512], "uint16", ["y", "x"], ...);
// ... populate both images with zarr.set() ...

const datasets = [
  createDataset("0", [0.5, 0.5], [0.0, 0.0]),
  createDataset("1", [1.0, 1.0], [0.0, 0.0]),
];
const metadata = createMetadata(axes, datasets, "pyramid");
const multiscales = createMultiscales([fullRes, halfRes], metadata);

const buffer = await toOmeTiff(multiscales);
// Result: OME-TIFF with full-res IFDs + half-res SubIFDs
```

#### 圆行: 写回读

```typescript
import { toOmeTiff, TiffStore } from "@fideus-labs/fiff";
import * as zarr from "zarrita";

const buffer = await toOmeTiff(multiscales);
const store = await TiffStore.fromArrayBuffer(buffer);
const group = await zarr.open(store as unknown as zarr.Readable, { kind: "group" });
const arr = await zarr.open(group.resolve("0"), { kind: "array" });
const result = await zarr.get(arr);
// result.data contains the original pixel values
```

## 读取 API

### 工厂方法

| 方法 | 说明 |
| --- | --- |
| `TiffStore.fromUrl(url, opts?)` | 从远程 URL( HTTP 范围请求) 打开 |
| `TiffStore.fromArrayBuffer(buf)` | 从内嵌式阵列打开 |
| `TiffStore.fromBlob(blob)` | 从 Blob 或文件打开 |
| `TiffStore.fromGeoTIFF(tiff)` | 从已打开的 GeoTIFF 实例打开 |

### 选项

所有工厂的方法都接受选择 `TiffStoreOptions` 对象 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `offsets` | `number[]` | `undefined` | 预算的IFD字节抵销O(1)访问 |
| `headers` | `Record<string, string>` | `undefined` | 远程 TIFF 请求的额外 HTTP 头 |
| `pool` | `DeflatePool` | `undefined` | 卸载解压缩的工人池(全球地理平面解码器覆盖) |
| `workerUrl` | `string` | `undefined` | 自定义工人脚本 URL( 仅当 `pool` (已提供) |

### 公众访问器

| 访问器 | 类型 | 说明 |
| --- | --- | --- |
| `store.levels` | `number` | 决议数量 |
| `store.dataType` | `ZarrDataType` | Zarr 数据类型字符串 |
| `store.ome` | `OmeImage[]` | 已解析的 OME- XML 图像( 如果存在) |
| `store.pyramidInfo` | `PyramidInfo` | 金字塔结构细节 |
| `store.dimensionNames` | `string[]` | 尺寸名称( 例如 ). `["t", "c", "z", "y", "x"]`(中文(简体) ) |
| `store.getShape(l)` | `number[]` | 分辨率形状 `l` |
| `store.getChunkShape(l)` | `number[]` | 解析级的块形状 `l` |

## 写 API

### `toOmeTiff(multiscales, options?)`

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `multiscales` | `Multiscales` | ngff- sarr 带有有像素数据的多比例对象 |
| `options` | `WriteOptions` | 可选作者配置 |

**回返情况:** `Promise<ArrayBuffer>` - 一个完整的 OME-TIFF 文件.

### 写入选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `compression` | `"none" | "deflate"` | `"deflate"` | 像素数据压缩 |
| `compressionLevel` | `number` | `6` | 一级至九级(较高=较小) |
| `dimensionOrder` | `string` | `"XYZCT"` | IFD 平面布局顺序 |
| `imageName` | `string` | `"image"` | 在 OME- XML 中的图像名称 |
| `creator` | `string` | `"fiff"` | OME- XML 创建字符串 |
| `tileSize` | `number` | `256` | 平板大小(0 = 有条形,必须是 x16) |
| `concurrency` | `number` | `4` | 最大平行平面读取 |
| `format` | `"auto" | "classic" | "bigtiff"` | `"auto"` | TIFF格式(自动检测 BigTIFF > 4 GB) |
| `pool` | `DeflatePool` | `undefined` | 卸载给 Web 工人压缩的工人池 |
| `workerUrl` | `string` | `undefined` | 自定义工人脚本 URL( 仅当 `pool` (已提供) |
| `getPlane` | `GetPlane` | `undefined` | 自定义平面阅读器替换内部 `zarr.get()` 呼叫(见下文) |

## 发展

### · 先决条件

-   [阿宝](https://bun.sh/) 页:1

### QQ 设置

```bash
git clone https://github.com/fideus-labs/fiff.git
cd fiff
bun install
```

### 项目结构

```
src/
  index.ts           # Public API exports
  tiff-store.ts      # TiffStore class (AsyncReadable implementation)
  metadata.ts        # Zarr v3 / OME-Zarr 0.5 metadata synthesis
  ome-xml.ts         # OME-XML parser (dimensions, channels, DimensionOrder)
  ifd-indexer.ts     # IFD-to-pyramid-level mapping (SubIFD/legacy/COG)
  chunk-reader.ts    # Pixel data reading via geotiff.js readRasters
  dtypes.ts          # TIFF ↔ Zarr data_type mapping
  utils.ts           # Key parsing, pixel window computation, encoding
  write.ts           # High-level toOmeTiff() writer
  tiff-writer.ts     # Low-level TIFF binary builder (IFDs, SubIFDs, deflate)
  ome-xml-writer.ts  # OME-XML generation from Multiscales metadata
  deflate-worker.ts  # Inline Web Worker source for compress/decompress
  worker-utils.ts    # Worker pool task factories and blob URL helper
  worker-decoder.ts  # Worker-backed geotiff deflate decoder
test/
  fixtures.ts        # Test TIFF generation helpers
  *.test.ts          # 201 tests across 11 files
```

### QQ 命令

| 命令 | 说明 |
| --- | --- |
| `bun run build` | 构建到 `dist/` (ESM+声明) |
| `bun test` | 运行所有测试 |
| `bun run typecheck` | 类型检查完整工程 |

## 捐款

欢迎捐款! 请看 [捐款额](https://npmcn.com/package/%40fideus-labs/fiff/CONTRIBUTING.md) 页:1 设置指令,代码样式指南,以及拉动请求工作流程.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40fideus-labs/fiff/LICENSE.txt) - 版权(c) Fideus Labs有限责任公司

## 常见问题

### @fideus-labs/fiff 是什么？

使用 NGFF OME- Zarr 数据模型将 TIFF 文件作为 sarrita\.js Zarr 存储

### 如何安装 @fideus-labs/fiff？

在项目目录运行 npm install @fideus-labs/fiff，或使用 pnpm add / yarn add / bun add。

### @fideus-labs/fiff 支持 TypeScript 吗？

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

### @fideus-labs/fiff 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fideus-labs/fiff 可以商用吗？

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

### @fideus-labs/fiff 的下载量有多少？

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

### @fideus-labs/fiff 还在维护吗？

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