Command-Line Tools

Four command-line tools are provided in the examples/ directory. They are build when CMake is run with example building enabled.

trx_info — Inspect a tractogram

Prints a concise summary of a TRX file: streamline and vertex counts, coordinate dtype and system, voxel-to-RAS affine, and all DPS, DPV, and group fields with their sizes.

trx_info --input tractogram.trx

Example output:

TRX info: hcp_1M.trx

Streamlines: 1000000
Vertices:    67241234
Coord dtype: float32
Coord space: LPS
Dims:        [145, 174, 145]

VoxelToRAS:
    [  1.250000   0.000000   0.000000 -90.000000]
    [  0.000000   1.250000   0.000000 -126.000000]
    [  0.000000   0.000000   1.250000 -72.000000]
    [  0.000000   0.000000   0.000000   1.000000]

DPS fields (1):
  - sift2_weights: values=1000000 (1 col)
DPV fields (0):
Groups (0):

trx_add_groups — Atlas-based parcellation

Wraps TrxParcellationLabeler to assign streamlines to named TRX groups from one or more NIfTI segmentation atlases. Each atlas is specified as a comma-separated triple <nifti>,<label_txt>,<prefix>.

trx_add_groups \
  --input subj.trx \
  --in-place \
  --atlas-spec native_seg.nii.gz,native_seg.txt,Glasser \
  --dilation-radius 1

Use --in-place to append groups to the existing file rather than writing a new one. Multiple --atlas-spec arguments parcellate against several atlases in a single pass.

--dilation-radius N expands each parcel by N voxels before intersection testing, which increases overlap with streamlines that terminate slightly outside parcel boundaries due to registration imprecision.

trx_group_tdi — Track Density Image

Maps streamlines from selected groups onto a reference NIfTI grid, producing a voxel-count or weighted-count image.

trx_group_tdi \
  --input parcellated.trx \
  --reference T1w_1mm.nii.gz \
  --output cst_tdi.nii.gz \
  --group CST_left \
  --stat sum

Group selection predicates support set-algebra queries:

• --groups-all-of A B — streamlines belonging to all listed groups

• --groups-any-of A B — streamlines belonging to any listed group

• --groups-none-of A B — streamlines belonging to none of the listed groups

--weight-field <dps_name> produces a weighted TDI using per-streamline scalar values (e.g. SIFT2 weights for quantitative connectivity).

trx_extract_subset — Extract streamlines

Extracts streamlines by index list or named group membership and writes a compact TRX file. Useful as a bridge between interactive AABB queries and downstream batch processing.

trx_extract_subset \
  --input parcellated.trx \
  --output subset.trx \
  --group CST_left