Introduction

TRX-cpp is a C++17 library for reading, writing, and memory-mapping the TRX tractography format. TRX is a ZIP-based container for fiber tract geometry and associated metadata, designed for large-scale diffusion MRI tractography.

Features

Zero-copy memory mapping

Streamline positions, per-vertex data (DPV), and per-streamline data (DPS) are exposed as Eigen::Map views directly over memory-mapped files. Accessing a 10 M-streamline dataset does not require loading the full array into RAM.

Streaming writes

trx::TrxStream appends streamlines incrementally and finalizes to a TRX archive or directory once tracking is complete. Suitable for tractography pipelines where the total count is unknown at the start.

Spatial queries

Build per-streamline axis-aligned bounding boxes (AABBs) and extract spatial subsets in sub-millisecond time per query. Designed for interactive slice-view workflows that need to filter streamlines as the user moves through a volume.

Typed and type-erased APIs

trx::TrxFile is templated on the positions dtype for compile-time type safety. trx::AnyTrxFile reads the dtype from disk and dispatches at runtime — useful when the file format is not known in advance.

ZIP and directory storage

Read and write .trx zip archives and plain on-disk directories with the same API. Directory storage is convenient for in-place access; zip storage is convenient for distribution and transfer.

Optional NIfTI support

Read qform/sform affines from .nii, .hdr, or .nii.gz and embed them in the TRX header for consistent coordinate interpretation downstream.

Where to go next

  • Quick Start — install the library and write a first program

  • Building — full dependency and build options reference

  • Core Concepts — how TRX-cpp represents streamlines and metadata internally

  • API Layers — choosing between AnyTrxFile, TrxFile<DT>, and TrxReader<DT>