nd2-rs 0.1.0

Pure Rust library for reading Nikon ND2 microscopy files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

# nd2-rs


Pure Rust library for reading Nikon ND2 microscopy files.

## Overview


`nd2-rs` is a Rust implementation for reading metadata and image data from modern ND2 files (versions 2.0, 2.1, and 3.0) created by Nikon NIS Elements software.

## Features


- Read ND2 file metadata and image pixel data
- Support for modern ND2 formats (v2.0, v2.1, v3.0)
- `sizes()` – dimension sizes (P, T, C, Z, Y, X)
- `loop_indices()` – P/T/C/Z mapping for each frame
- `read_frame(index)` – read raw pixels (u16, C×Y×X) by sequence index
- `read_frame_2d(p, t, c, z)` – read 2D Y×X frame at (P,T,C,Z)
- CLX Lite binary format parser
- Uncompressed and zlib-compressed image data
- Serde serialization support

## Installation


Add this to your `Cargo.toml`:

```toml
[dependencies]
nd2-rs = "0.1.0"
```

Or from git:

```toml
[dependencies]
nd2-rs = { git = "https://github.com/keejkrej/nd2-rs" }
```

## Usage


```rust
use nd2_rs::{Nd2File, Result};

fn main() -> Result<()> {
    let mut nd2 = Nd2File::open("image.nd2")?;

    // Get sizes for iteration (P, T, C, Z, Y, X)
    let sizes = nd2.sizes()?;

    // Read 2D Y×X frame at (p, t, c, z)
    let pixels = nd2.read_frame_2d(0, 0, 0, 0)?;

    Ok(())
}
```

## CLI Usage


The `nd2-rs` command-line tool provides quick access to ND2 file metadata:

```bash
# Display file information

nd2-rs info image.nd2

# Output as JSON

nd2-rs info image.nd2 --json

# List all chunks in the file

nd2-rs chunks image.nd2
```

### Installation


```bash
cargo install --path .
```

Or run directly:

```bash
cargo run -- info path/to/file.nd2
```

## Testing


```bash
cargo test
```

Without `ND2_TEST_FILE`, integration tests skip. To run full integration tests:

```bash
# Linux/macOS

ND2_TEST_FILE=/path/to/file.nd2 cargo test

# Windows

$env:ND2_TEST_FILE="D:\path\to\file.nd2"; cargo test
```

CI runs build, unit tests, and clippy. Integration tests require a local ND2 file.

## Library Usage Examples


Run the metadata reader example:

```bash
cargo run --example read_metadata path/to/your/file.nd2
```

## Metadata Types


The library provides strongly-typed access to:

- **Attributes**: Image dimensions, bit depth, pixel type, compression
- **TextInfo**: Author, description, date, and other text metadata
- **Experiment**: Time-lapse, Z-stack, XY position, and custom loop definitions
- **Channels**: Channel names, colors, wavelengths (coming soon)

## File Format


ND2 files use a chunk-based binary format:

- **Chunk Header**: 16 bytes (magic, name_length, data_length)
- **ChunkMap**: Located at end of file, maps chunk names to (offset, size)
- **Metadata Encoding**: CLX Lite binary TLV format or XML (version dependent)
- **Compression**: Zlib for both metadata and image data

For detailed technical documentation about the file format and how the library works, see [ARCHITECTURE.md](ARCHITECTURE.md).

## Limitations


Not yet implemented:

- Legacy ND2 format (JPEG2000-based, v1.0)
- ROI and binary mask data
- Frame-level metadata
- Channel metadata parsing

## Documentation


- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Detailed technical documentation about ND2 file format and parsing
- **[AGENTS.md](AGENTS.md)** - Development notes for Claude Code agents

## License


MIT OR Apache-2.0

## References


This is a Rust reimplementation inspired by the Python [nd2 library](https://github.com/tlambert03/nd2).