# @fideus-labs/ngff-zarr 中文文档

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

版本：0\.42\.0
npm 元数据更新时间：2026-11-13T11:48:30.163Z
中文译文更新时间：2026-11-14T17:13:59.526Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.8 MB，315 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.18\.0 \|\| ^24\.11\.0 \|\| \>=26\.0\.0
- 运行依赖：8 个
- 首次发布：2025-07-16T02:41:22.902Z
- 最新版本发布：2026-11-13T11:48:29.750Z
- 近 30 天下载量：8482（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 57 个）

## 中文简介

TypeScript 用于读取和写入 OME- Zarr 文件的 ngff- zarr 执行

## 安装

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

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

## README

# ngff- sarr 类型脚本

[![npm - Version](https://img.shields.io/npm/v/@fideus-labs/ngff-zarr.svg)](https://www.npmjs.com/package/@fideus-labs/ngff-zarr)

用于读取和写 OME-Zarr 文件的 ngff- sarr 的 TypeScript 执行, 兼容 Node.js 和浏览器.

## 特征

-   📘 **类型脚本第一**: 用 TypeScript 编写, 随声明一起运出
-   📦 **npm 软件包**:为节点J、捆绑机和浏览器建立无害环境管理
-   🔍 **类型安全**: 用 Zod schema 验证的完整类型脚本支持
-   🗂️ **OME- Zarr 支持**:读取 OME-Zarr v0.4, v0.5, 和 v0. 6, 并使用 fizarrita 写入 v0. 5 和 v. 6. 6 ( Zarr v3)
-   🧪 **测试良好**: 与Vitest、Node和Playwright一起运行的综合测试套房
-   🏗️ **镜像 Python API**: TypeScript 类和类型镜像 Python 数据类

## 安装

### 节点.js/npm

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

```typescript
import * as ngffZarr from "@fideus-labs/ngff-zarr";
```

解码器工船作为单独的文档 `dist/workers/` 被产出 与 `new Worker(new URL("../workers/omero_codec_worker.js", import.meta.url), { type: "module" })`, (中文(简体) ), vite 和 Webpack 5 等窗体捆绑器被确认为工人条目 在不配置的情况下,在捆绑的同时发射.

## 快速启动

### 正在读取 OME- Zarr 文件

```typescript
import { OMEZarrReader } from "@fideus-labs/ngff-zarr";

const reader = new OMEZarrReader({ validate: true });
const multiscales = await reader.fromNgffZarr("path/to/image.ome.zarr");

console.log(`Loaded ${multiscales.images.length} scale levels`);
console.log(`Image shape: ${multiscales.images[0].data.shape}`);
```

### 写入 OME- Zarr 文件

```typescript
import {
  createMetadata,
  createMultiscales,
  createNgffImage,
  OMEZarrWriter,
} from "@fideus-labs/ngff-zarr";

// Create a simple 2D image
const image = createNgffImage(
  new ArrayBuffer(256 * 256),
  [256, 256],
  "uint8",
  ["y", "x"],
  { y: 1.0, x: 1.0 },
  { y: 0.0, x: 0.0 },
);

// Create metadata
const axes = [
  { name: "y", type: "space" },
  { name: "x", type: "space" },
];
const datasets = [
  {
    path: "0",
    coordinateTransformations: [
      { type: "scale", scale: [1.0, 1.0] },
      { type: "translation", translation: [0.0, 0.0] },
    ],
  },
];
const metadata = createMetadata(axes, datasets);

// Create multiscales
const multiscales = createMultiscales([image], metadata);

// Write to OME-Zarr
const writer = new OMEZarrWriter();
await writer.toOmeZarr("output.ome.zarr", multiscales);
```

### Schema 验证

```typescript
import { MetadataSchema, validateMetadata } from "@fideus-labs/ngff-zarr";

const metadata = {
  axes: [
    { name: "y", type: "space" },
    { name: "x", type: "space" },
  ],
  datasets: [
    {
      path: "0",
      coordinateTransformations: [
        { type: "scale", scale: [1.0, 1.0] },
        { type: "translation", translation: [0.0, 0.0] },
      ],
    },
  ],
  name: "test_image",
  version: "0.4",
};

// Validate using Zod schema
const validatedMetadata = MetadataSchema.parse(metadata);

// Or use utility function
const validatedMetadata2 = validateMetadata(metadata);
```

## API 参考

### 核心类型

-   `NgffImage`: 与相关元数据相映像
-   `Multiscales`: 图像多级容器
-   `DaskArray`: 工作缸数组元数据表示
-   `Metadata`: OME-Zarr元数据结构

### I/O类

-   `OMEZarrReader`: 使用 fizarrita 读取 OME- Zarr 文件
-   `OMEZarrWriter`: 使用 fizarrita 写入 OME- Zarr 文件

### 验证

-   所有数据结构的 Zod 方案
-   用于验证的功能
-   类型安全解析和验证

### 工厂功能

-   `createNgffImage()`: 创建 Ngff 图像实例
-   `createMetadata()`: 创建元数据结构
-   `createMultiscales()`: 创建多比例容器

## 发展

### 先决条件

-   [节点.js](https://nodejs.org/) 22.18, 24.11, 或较新(`npm` (列入)
-   [皮克西语Name](https://pixi.sh/) (可选;提供节点js和任务别名) (见下文)

工具链是 [维特+](https://viteplus.dev/) (单位:千美元)`vp`),作为dev安装 依赖性:用于测试的活性测试,用于起伏和格式化的Oxlint和Oxfmt, t倒为所建.

### 设置

```bash
cd ts/
npm ci          # or: pixi run install
```

### 图标

```bash
# Run tests
npm test                 # or: pixi run test

# Format code
npm run fmt              # or: pixi run fmt

# Lint code
npm run lint             # or: pixi run lint

# Format + lint + type check in one pass
npm run check            # or: pixi run check

# Build the npm package into dist/
npm run build            # or: pixi run build

# Node tests against the built package
npm run test:node        # or: pixi run test-node

# Browser testing with Playwright
npm run test:browser     # or: pixi run test-browser

# Browser testing with UI
npm run test:browser:ui

# Run all tests (including browser tests)
npm run test:all         # or: pixi run test-all
```

### 浏览器测试

该项目包括使用Playwright进行综合浏览器测试. 这个 浏览器测试验证 npm- transpiled 软件包是否真实正确 浏览器环境.

**特征 :**

-   多浏览器测试(Chrome、Firefox、Safari、Mobile)
-   浏览器上下文中的国家预防机制软件包验证
-   依赖性导入分辨率测试
-   浏览器环境中的Schema 验证

**快速启动 :**

```bash
# Build the package, inline the worker, bundle, and run the browser tests
npm run test:browser

# Run browser tests with interactive UI
npm run test:browser:ui

# Debug browser tests
npm run test:browser:debug
```

**测试文件 :**

-   `/test/browser-npm/` - 浏览器测试文件和配置
-   `/test/browser/server.ts` - 测试服务资产的服务器
-   `/scripts/run_playwright.mjs` - 用于执行Playwright的节点.js包装器

见 [测试/浏览器/README.md](https://npmcn.com/package/%40fideus-labs/ngff-zarr/test/browser/README.md) 用于详细浏览器 测试文档.

### 项目结构

```
ts/
├── src/
│   ├── types/          # TypeScript type definitions
│   ├── schemas/        # Zod validation schemas
│   ├── io/            # Zarr I/O operations
│   ├── utils/         # Utility functions
│   └── mod.ts         # Main module exports
├── test/              # Test files
├── scripts/           # Build scripts
├── package.json       # npm package manifest and scripts
├── vite.config.ts     # Vite+ configuration (test, lint, fmt, pack)
├── tsconfig.json      # TypeScript configuration
├── pixi.toml          # Pixi environment
└── README.md
```

## 与 Python 软件包的关系

此类型脚本包镜像 Python ngff- zarr 包 :

-   **类型**: TypeScript 接口/类对应 Python 数据类
-   **API 密码**: 类似的函数名称和模式
-   **验证**: Zod schemas 提供运行时间验证, 如 Python
-   **一. 业务**: fizarrita 提供 Zarr 操作像 sarr-python

## 捐款

1.  叉子存储器
2.  创建特性分支
3.  做你的改变
4.  添加测试
5.  运行测试套件 : `npm test`
6.  提交拉动请求

## 许可证

麻省理工学院许可证 - 详情见LICENSE文件.

## 常见问题

### @fideus-labs/ngff-zarr 是什么？

TypeScript 用于读取和写入 OME- Zarr 文件的 ngff- zarr 执行

### 如何安装 @fideus-labs/ngff-zarr？

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

### @fideus-labs/ngff-zarr 支持 TypeScript 吗？

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

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

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

### @fideus-labs/ngff-zarr 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.18\.0 \|\| ^24\.11\.0 \|\| \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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