trx.cli#

TRX Command Line Interface.

This module provides a unified CLI for all TRX file format operations using Typer.

Attributes#

app

concatenate_tractograms_cmd

convert_dsi_cmd

convert_cmd

generate_cmd

manipulate_dtype_cmd

compare_cmd

validate_cmd

verify_header_cmd

visualize_cmd

info_cmd

Functions#

_check_overwrite(→ None)

Check if file exists and raise error if overwrite is not enabled.

concatenate_tractograms(], out_tractogram, ...)

Concatenate multiple tractograms into one.

convert(], out_tractogram, typer.Argument], reference, ...)

Convert tractograms between formats.

convert_dsi(], in_dsi_fa, typer.Argument], ...)

Convert a DSI-Studio TRK file to TRX or TRK and fix space metadata.

generate(], out_tractogram, typer.Argument], ...)

Generate a TRX file from raw data files.

manipulate_dtype(], out_tractogram, typer.Argument], ...)

Manipulate TRX file internal array data types.

compare(], in_tractogram2, typer.Argument], reference, ...)

Compare two tractograms and report basic differences.

validate(], out_tractogram, typer.Option] = None, ...)

Validate a tractogram and optionally clean invalid/duplicate streamlines.

verify_header(]) → None)

Compare spatial attributes of input files.

visualize(], reference, typer.Argument], ...)

Display tractogram and density map with bounding box.

_format_size(→ str)

Format byte size to human readable string.

info(]) → None)

Display detailed information about a TRX file.

main()

Entry point for the TRX CLI.

_create_standalone_app(command_func, name, help_text)

Create a standalone Typer app for a single command.

Module Contents#

trx.cli.app[source]#
trx.cli._check_overwrite(filepath: pathlib.Path, overwrite: bool) → None[source]#

Check if file exists and raise error if overwrite is not enabled.

Parameters:
filepathPath

Path to the output file.

overwritebool

If True, allow overwriting existing files.

Raises:
typer.Exit

If file exists and overwrite is False.

trx.cli.concatenate_tractograms(in_tractograms: typing_extensions.Annotated[List[pathlib.Path], typer.Argument(help='Input tractogram files. Format: trk, tck, vtk, fib, dpy, trx.')], out_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Output filename for the concatenated tractogram.')], delete_dpv: typing_extensions.Annotated[bool, typer.Option('--delete-dpv', help='Delete data_per_vertex if not all inputs have the same metadata.')] = False, delete_dps: typing_extensions.Annotated[bool, typer.Option('--delete-dps', help='Delete data_per_streamline if not all inputs have the same metadata.')] = False, delete_groups: typing_extensions.Annotated[bool, typer.Option('--delete-groups', help='Delete groups if not all inputs have the same metadata.')] = False, reference: typing_extensions.Annotated[pathlib.Path | None, typer.Option('--reference', '-r', help='Reference anatomy for tck/vtk/fib/dpy files (.nii or .nii.gz).')] = None, force: typing_extensions.Annotated[bool, typer.Option('--force', '-f', help='Force overwriting of output files.')] = False) → None[source]#

Concatenate multiple tractograms into one.

If the data_per_point or data_per_streamline is not the same for all tractograms, the data must be deleted first using the appropriate flags.

Parameters:
in_tractogramslist of Path

Input tractogram files (.trk, .tck, .vtk, .fib, .dpy, .trx).

out_tractogramPath

Output filename for the concatenated tractogram.

delete_dpvbool, optional

Delete data_per_vertex if metadata differ across inputs.

delete_dpsbool, optional

Delete data_per_streamline if metadata differ across inputs.

delete_groupsbool, optional

Delete groups when metadata differ across inputs.

referencePath or None, optional

Reference anatomy for tck/vtk/fib/dpy inputs.

forcebool, optional

Overwrite output if it already exists.

Returns:
None

Writes the concatenated tractogram to out_tractogram.

trx.cli.convert(in_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Input tractogram. Format: trk, tck, vtk, fib, dpy, trx.')], out_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Output tractogram. Format: trk, tck, vtk, fib, dpy, trx.')], reference: typing_extensions.Annotated[pathlib.Path | None, typer.Option('--reference', '-r', help='Reference anatomy for tck/vtk/fib/dpy files (.nii or .nii.gz).')] = None, positions_dtype: typing_extensions.Annotated[str, typer.Option('--positions-dtype', help='Datatype for positions in TRX output.')] = 'float32', offsets_dtype: typing_extensions.Annotated[str, typer.Option('--offsets-dtype', help='Datatype for offsets in TRX output.')] = 'uint64', force: typing_extensions.Annotated[bool, typer.Option('--force', '-f', help='Force overwriting of output files.')] = False) → None[source]#

Convert tractograms between formats.

Supports conversion of .tck, .trk, .fib, .vtk, .trx and .dpy files. TCK files always need a reference NIFTI file for conversion.

Parameters:
in_tractogramPath

Input tractogram file.

out_tractogramPath

Output tractogram path.

referencePath or None, optional

Reference anatomy required for some input formats.

positions_dtypestr, optional

Datatype for positions in TRX output.

offsets_dtypestr, optional

Datatype for offsets in TRX output.

forcebool, optional

Overwrite output if it already exists.

Returns:
None

Writes the converted tractogram to disk.

trx.cli.convert_dsi(in_dsi_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Input tractogram from DSI Studio (.trk).')], in_dsi_fa: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Input FA from DSI Studio (.nii.gz).')], out_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Output tractogram file.')], remove_invalid: typing_extensions.Annotated[bool, typer.Option('--remove-invalid', help='Remove streamlines landing out of the bounding box.')] = False, keep_invalid: typing_extensions.Annotated[bool, typer.Option('--keep-invalid', help='Keep streamlines landing out of the bounding box.')] = False, force: typing_extensions.Annotated[bool, typer.Option('--force', '-f', help='Force overwriting of output files.')] = False) → None[source]#

Convert a DSI-Studio TRK file to TRX or TRK and fix space metadata.

Parameters:
in_dsi_tractogramPath

Input DSI-Studio tractogram (.trk or .trk.gz).

in_dsi_faPath

FA volume used as reference (.nii.gz).

out_tractogramPath

Output tractogram path (.trx or .trk).

remove_invalidbool, optional

Remove streamlines outside the bounding box. Defaults to False.

keep_invalidbool, optional

Keep streamlines outside the bounding box. Defaults to False.

forcebool, optional

Overwrite output if it already exists.

Returns:
None

Writes the converted tractogram to disk.

trx.cli.generate(reference: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Reference anatomy (.nii or .nii.gz).')], out_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Output tractogram. Format: trk, tck, vtk, fib, dpy, trx.')], positions: typing_extensions.Annotated[pathlib.Path | None, typer.Option('--positions', help='Binary file with streamline coordinates (Nx3 .npy).')] = None, offsets: typing_extensions.Annotated[pathlib.Path | None, typer.Option('--offsets', help='Binary file with streamline offsets (.npy).')] = None, positions_csv: typing_extensions.Annotated[pathlib.Path | None, typer.Option('--positions-csv', help='CSV file with streamline coordinates (x1,y1,z1,x2,y2,z2,...).')] = None, space: typing_extensions.Annotated[str, typer.Option('--space', help='Coordinate space. Non-default requires Dipy.')] = 'RASMM', origin: typing_extensions.Annotated[str, typer.Option('--origin', help='Coordinate origin. Non-default requires Dipy.')] = 'NIFTI', positions_dtype: typing_extensions.Annotated[str, typer.Option('--positions-dtype', help='Datatype for positions.')] = 'float32', offsets_dtype: typing_extensions.Annotated[str, typer.Option('--offsets-dtype', help='Datatype for offsets.')] = 'uint64', dpv: typing_extensions.Annotated[List[str] | None, typer.Option('--dpv', help='Data per vertex: FILE,DTYPE (e.g., color.npy,uint8).')] = None, dps: typing_extensions.Annotated[List[str] | None, typer.Option('--dps', help='Data per streamline: FILE,DTYPE (e.g., algo.npy,uint8).')] = None, groups: typing_extensions.Annotated[List[str] | None, typer.Option('--groups', help='Groups: FILE,DTYPE (e.g., AF_L.npy,int32).')] = None, dpg: typing_extensions.Annotated[List[str] | None, typer.Option('--dpg', help='Data per group: GROUP,FILE,DTYPE (e.g., AF_L,mean_fa.npy,float32).')] = None, verify_invalid: typing_extensions.Annotated[bool, typer.Option('--verify-invalid', help='Verify positions are valid (within bounding box). Requires Dipy.')] = False, force: typing_extensions.Annotated[bool, typer.Option('--force', '-f', help='Force overwriting of output files.')] = False) → None[source]#

Generate a TRX file from raw data files.

Create a TRX file from CSV, TXT, or NPY files by specifying positions, offsets, data_per_vertex, data_per_streamlines, groups, and data_per_group.

Parameters:
referencePath

Reference anatomy (.nii or .nii.gz).

out_tractogramPath

Output tractogram (.trk, .tck, .vtk, .fib, .dpy, .trx).

positionsPath or None, optional

Binary file with streamline coordinates (Nx3 .npy).

offsetsPath or None, optional

Binary file with streamline offsets (.npy).

positions_csvPath or None, optional

CSV file with flattened streamline coordinates.

spacestr, optional

Coordinate space. Non-default requires Dipy.

originstr, optional

Coordinate origin. Non-default requires Dipy.

positions_dtypestr, optional

Datatype for positions.

offsets_dtypestr, optional

Datatype for offsets.

dpvlist of str or None, optional

Data per vertex entries as FILE,DTYPE pairs.

dpslist of str or None, optional

Data per streamline entries as FILE,DTYPE pairs.

groupslist of str or None, optional

Group entries as FILE,DTYPE pairs.

dpglist of str or None, optional

Data per group entries as GROUP,FILE,DTYPE triplets.

verify_invalidbool, optional

Verify positions are inside bounding box (requires Dipy).

forcebool, optional

Overwrite output if it already exists.

Returns:
None

Writes the generated tractogram to disk.

trx.cli.manipulate_dtype(in_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Input TRX file.')], out_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Output tractogram file.')], positions_dtype: typing_extensions.Annotated[str | None, typer.Option('--positions-dtype', help='Datatype for positions (float16, float32, float64).')] = None, offsets_dtype: typing_extensions.Annotated[str | None, typer.Option('--offsets-dtype', help='Datatype for offsets (uint32, uint64).')] = None, dpv: typing_extensions.Annotated[List[str] | None, typer.Option('--dpv', help='Data per vertex dtype: NAME,DTYPE (e.g., color_x,uint8).')] = None, dps: typing_extensions.Annotated[List[str] | None, typer.Option('--dps', help='Data per streamline dtype: NAME,DTYPE (e.g., algo,uint8).')] = None, groups: typing_extensions.Annotated[List[str] | None, typer.Option('--groups', help='Groups dtype: NAME,DTYPE (e.g., CC,uint64).')] = None, dpg: typing_extensions.Annotated[List[str] | None, typer.Option('--dpg', help='Data per group dtype: GROUP,NAME,DTYPE (e.g., CC,mean_fa,float64).')] = None, force: typing_extensions.Annotated[bool, typer.Option('--force', '-f', help='Force overwriting of output files.')] = False) → None[source]#

Manipulate TRX file internal array data types.

Change the data types of positions, offsets, data_per_vertex, data_per_streamline, groups, and data_per_group arrays.

Parameters:
in_tractogramPath

Input TRX file.

out_tractogramPath

Output TRX file.

positions_dtypestr or None, optional

Target dtype for positions (float16, float32, float64).

offsets_dtypestr or None, optional

Target dtype for offsets (uint32, uint64).

dpvlist of str or None, optional

Data per vertex dtype overrides as NAME,DTYPE pairs.

dpslist of str or None, optional

Data per streamline dtype overrides as NAME,DTYPE pairs.

groupslist of str or None, optional

Group dtype overrides as NAME,DTYPE pairs.

dpglist of str or None, optional

Data per group dtype overrides as GROUP,NAME,DTYPE triplets.

forcebool, optional

Overwrite output if it already exists.

Returns:
None

Writes the dtype-converted TRX file.

trx.cli.compare(in_tractogram1: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='First tractogram file.')], in_tractogram2: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Second tractogram file.')], reference: typing_extensions.Annotated[pathlib.Path | None, typer.Option('--reference', '-r', help='Reference anatomy for tck/vtk/fib/dpy files (.nii or .nii.gz).')] = None) → None[source]#

Compare two tractograms and report basic differences.

Parameters:
in_tractogram1Path

First tractogram file.

in_tractogram2Path

Second tractogram file.

referencePath or None, optional

Reference anatomy for formats requiring it.

Returns:
None

Prints comparison summary to stdout.

trx.cli.validate(in_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Input tractogram. Format: trk, tck, vtk, fib, dpy, trx.')], out_tractogram: typing_extensions.Annotated[pathlib.Path | None, typer.Option('--out', '-o', help='Output tractogram after removing invalid streamlines.')] = None, remove_identical: typing_extensions.Annotated[bool, typer.Option('--remove-identical', help='Remove identical streamlines from the set.')] = False, precision: typing_extensions.Annotated[int, typer.Option('--precision', '-p', help='Number of decimals when hashing streamline points.')] = 1, reference: typing_extensions.Annotated[pathlib.Path | None, typer.Option('--reference', '-r', help='Reference anatomy for tck/vtk/fib/dpy files (.nii or .nii.gz).')] = None, force: typing_extensions.Annotated[bool, typer.Option('--force', '-f', help='Force overwriting of output files.')] = False) → None[source]#

Validate a tractogram and optionally clean invalid/duplicate streamlines.

Parameters:
in_tractogramPath

Input tractogram (.trk, .tck, .vtk, .fib, .dpy, .trx).

out_tractogramPath or None, optional

Optional output tractogram with invalid streamlines removed.

remove_identicalbool, optional

Remove duplicate streamlines based on hashing precision.

precisionint, optional

Number of decimals when hashing streamline points.

referencePath or None, optional

Reference anatomy for formats requiring it.

forcebool, optional

Overwrite output if it already exists.

Returns:
None

Prints validation summary and optionally writes cleaned output.

trx.cli.verify_header(in_files: typing_extensions.Annotated[List[pathlib.Path], typer.Argument(help='Files to compare (trk, trx, and nii).')]) → None[source]#

Compare spatial attributes of input files.

Parameters:
in_fileslist of Path

Files to compare (.trk, .trx, .nii, .nii.gz).

Returns:
None

Prints compatibility results to stdout.

trx.cli.visualize(in_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Input tractogram. Format: trk, tck, vtk, fib, dpy, trx.')], reference: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Reference anatomy (.nii or .nii.gz).')], remove_invalid: typing_extensions.Annotated[bool, typer.Option('--remove-invalid', help='Remove invalid streamlines to avoid density_map crash.')] = False) → None[source]#

Display tractogram and density map with bounding box.

Parameters:
in_tractogramPath

Input tractogram (.trk, .tck, .vtk, .fib, .dpy, .trx).

referencePath

Reference anatomy (.nii or .nii.gz).

remove_invalidbool, optional

Remove invalid streamlines to avoid density map crashes.

Returns:
None

Opens visualization windows when fury is available.

trx.cli._format_size(size_bytes: int) → str[source]#

Format byte size to human readable string.

Parameters:
size_bytesint

Size in bytes.

Returns:
str

Human readable size string (e.g., “1.5 MB”).

trx.cli.info(in_tractogram: typing_extensions.Annotated[pathlib.Path, typer.Argument(help='Input TRX file.')]) → None[source]#

Display detailed information about a TRX file.

Shows file size, compression status, header metadata (affine, dimensions, voxel sizes), streamline/vertex counts, data keys (dpv, dps, dpg), groups, and archive contents listing similar to unzip -l.

Parameters:
in_tractogramPath

Input TRX file (.trx extension required).

Returns:
None

Prints TRX file information to stdout.

Examples

$ trx info tractogram.trx $ trx_info tractogram.trx

trx.cli.main()[source]#

Entry point for the TRX CLI.

trx.cli._create_standalone_app(command_func, name: str, help_text: str)[source]#

Create a standalone Typer app for a single command.

Parameters:
command_funccallable

The command function to wrap.

namestr

Name of the command.

help_textstr

Help text for the command.

Returns:
callable

Entry point function.

trx.cli.concatenate_tractograms_cmd[source]#
trx.cli.convert_dsi_cmd[source]#
trx.cli.convert_cmd[source]#
trx.cli.generate_cmd[source]#
trx.cli.manipulate_dtype_cmd[source]#
trx.cli.compare_cmd[source]#
trx.cli.validate_cmd[source]#
trx.cli.verify_header_cmd[source]#
trx.cli.visualize_cmd[source]#
trx.cli.info_cmd[source]#