trx.cli#
TRX Command Line Interface.
This module provides a unified CLI for all TRX file format operations using Typer.
Attributes#
Functions#
|
Check if file exists and raise error if overwrite is not enabled. |
|
Concatenate multiple tractograms into one. |
|
Convert tractograms between formats. |
|
Fix DSI-Studio TRK files for compatibility. |
|
Generate TRX file from raw data files. |
|
Manipulate TRX file internal array data types. |
|
Simple comparison of tractograms by subtracting coordinates. |
|
Validate TRX file and remove invalid streamlines. |
|
Compare spatial attributes of input files. |
|
Display tractogram and density map with bounding box. |
|
Entry point for the TRX CLI. |
|
Create a standalone Typer app for a single command. |
Module Contents#
- 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.
- 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.
- 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]#
Fix DSI-Studio TRK files for compatibility.
This script fixes DSI-Studio TRK files (unknown space/convention) to make them compatible with TrackVis, MI-Brain, and Dipy Horizon.
[bold yellow]WARNING:[/bold yellow] This script is experimental. DSI-Studio evolves quickly and results may vary depending on the data and DSI-Studio version.
- 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 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.
Each –dpv, –dps, –groups option requires FILE,DTYPE format. Each –dpg option requires GROUP,FILE,DTYPE format.
Valid DTYPEs: (u)int8, (u)int16, (u)int32, (u)int64, float16, float32, float64, bool
- 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.
Valid DTYPEs: (u)int8, (u)int16, (u)int32, (u)int64, float16, float32, float64, bool
- 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]#
Simple comparison of tractograms by subtracting coordinates.
Does not account for shuffling of streamlines. Simple A-B operations.
Differences below 1e-3 are expected for affines with large rotation/scaling. Differences below 1e-6 are expected for isotropic data with small rotation.
- 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 TRX file and remove invalid streamlines.
Removes streamlines that are out of the volume bounding box (in voxel space, no negative coordinates or coordinates above volume dimensions).
Also removes streamlines with single or no points. Use –remove-identical to remove duplicate streamlines based on precision.
- 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.
Compares all input files against the first one for compatibility of spatial attributes: affine, dimensions, voxel sizes, and voxel order.
- 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.
Shows the tractogram and its density map (computed from Dipy) in rasmm, voxmm, and vox space with its bounding box.
- 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.