@fideus-labs/fiff

(法语)

读写 OME-TIFF( 欧美论坛) 通过 a 文件 萨里塔.js 跟踪Zarr商店 OME-Zarr v0.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 阵列中

* 安装

npm install @fideus-labs/fiff

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

npm install @fideus-labs/ngff-zarr

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

npm install @fideus-labs/worker-pool

使用量

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

从远程 URL

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.

从矩阵缓冲器

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

从文件 / Blob 中

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

从现有的 GeoTIFF 实例

import { fromUrl } from "geotiff";

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

访问存储元数据

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 对象 :

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。 。 。 .

基本写法

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);

写入选项

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 — 完全释放主 线程.

用工人池写作

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();

用工人游泳池阅读

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

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() (没有压缩),读作是微不足道的 零起落点.

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()数字 :

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:

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

圆行: 写回读

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

工厂方法

选项

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

公众访问器

写 API

toOmeTiff(multiscales, options?)

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

写入选项

发展

· 先决条件

• 阿宝 页:1

QQ 设置

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 命令

捐款

欢迎捐款! 请看 捐款额 页:1 设置指令,代码样式指南,以及拉动请求工作流程.

许可证

麻省理工学院 - 版权(c) Fideus Labs有限责任公司