trx-rs

A Rust library for reading, writing, and manipulating TRX brain tractography files, plus format-conversion helpers for common streamline formats.

TRX is a binary file format for storing streamline tractography data using memory-mapped arrays. It supports multiple coordinate precisions (f16, f32, f64), per-vertex data (DPV), per-streamline data (DPS), named groups, and data-per-group (DPG) arrays — all backed by zero-copy memory mapping for efficient access to large datasets.

• Installation
  • As a library dependency
  • Local development
  • Command-line tool
  • Testing
  • Python bindings
• Quick start
  • Load and iterate streamlines
  • Runtime dtype detection
  • Access ancillary data
  • Build and save
  • API reference
• Format conversion
  • Library usage
  • Supported formats
  • CLI conversion
  • TT import behavior
• Applying ANTs transforms to tractograms
  • The “opposite-named h5” rule (cartoon BIDS)
  • Why opposite-named?
  • Library usage
  • CLI usage
  • Affine-only chains
• Operations
  • Subset
  • Merge (concatenate)
  • Set operations on streamlines
  • Duplicate removal
  • Spatial queries
  • Connectivity matrices
  • Metadata operations
• API reference

Features

• Zero-copy memory mapping via memmap2 for efficient access to multi-gigabyte tractography files

• Multiple precision support — f16, f32, and f64 positions with runtime dtype detection

• Full read/write support for both directory-based and ZIP archive (.trx) formats

• Format conversion helpers for .tck, .tck.gz, .vtk, and .tt.gz -> .trx

• Streaming construction — build TRX files incrementally with TrxStream

• Ancillary data access — DPS (per-streamline), DPV (per-vertex), group membership arrays, and DPG metadata

• Set operations — intersection, union, and difference on streamline sets

• Connectivity matrices — compute group-to-group connectivity (count or weighted)

• Subset and merge — extract streamlines by index or concatenate multiple files

Supported data types

Type	Positions	DPS/DPV
f16 (half)	Yes	Yes
f32	Yes	Yes
f64	Yes	Yes
u8, u16, u32, u64	-	Yes
i8, i16, i32, i64	-	Yes

License

BSD 2-Clause.