Format conversion

trx-rs supports reading and writing multiple tractogram formats via its library conversion layer.

Library usage

use trx_rs::{convert, read_tractogram, write_tractogram, ConversionOptions, DType};

// Convert between file formats.
convert("input.tck.gz".as_ref(), "output.trx".as_ref(), &ConversionOptions::default())?;

// Read a non-TRX tractogram into the neutral in-memory representation.
let tractogram = read_tractogram("bundles.tt.gz".as_ref(), &ConversionOptions::default())?;

// Write TRX with explicit positions dtype.
let options = ConversionOptions {
    trx_positions_dtype: DType::Float16,
    ..Default::default()
};
write_tractogram("bundles_f16.trx".as_ref(), &tractogram, &options)?;

Supported formats

Format	Read	Write	Notes
TRX	Yes	Yes	Directory and .trx zip archives
TCK / TCK.GZ	Yes	Yes	Gzipped TCK is supported
VTK	Yes	Yes	Legacy PolyData POINTS + LINES subset
TT.GZ	Yes	No	Import only; TT clusters become TRX groups and TT colors become dpg/<group>/color.3.uint8

CLI conversion

The trxrs binary exposes the same conversion functionality:

# Convert gzipped TCK to TRX with float16 positions
trxrs convert bundles.tck.gz bundles.trx --positions-dtype f16

# Rewrite an existing TRX with float32 positions
trxrs manipulate-dtype input.trx output.trx --positions-dtype f32

# Concatenate TRX files and write float16 output
trxrs concatenate shard1.trx shard2.trx --output merged.trx --positions-dtype f16

TT import behavior

• TT streamline points are decoded in voxel space and mapped to TRX positions with trans_to_mni directly

• TT cluster values become TRX groups

• file.tt.gz.txt sidecar labels are used for group names when present

• TT colors become dpg/<group>/color.3.uint8

• TT report and parameter_id are stored in header.extra