# Introduction

TRX-cpp is a C++17 library for reading, writing, and memory-mapping the
[TRX tractography format](https://github.com/tee-ar-ex/trx-spec). 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**

: {class}`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**

: {class}`trx::TrxFile` is templated on the positions dtype for compile-time
  type safety. {class}`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

- {doc}`quick_start` — install the library and write a first program
- {doc}`building` — full dependency and build options reference
- {doc}`concepts` — how TRX-cpp represents streamlines and metadata internally
- {doc}`api_layers` — choosing between `AnyTrxFile`, `TrxFile<DT>`, and
  `TrxReader<DT>`