diff --git a/README.md b/README.md index f86676a..335011e 100644 --- a/README.md +++ b/README.md @@ -41,28 +41,28 @@ save(trx, "output.trk") ### Command-Line Interface -TRX-Python provides a unified CLI (`tff`) for common operations: +TRX-Python provides a unified CLI (`trx`) for common operations: ```bash # Show all available commands -tff --help +trx --help # Convert between formats -tff convert input.trk output.trx +trx convert input.trk output.trx # Concatenate tractograms -tff concatenate tract1.trx tract2.trx merged.trx +trx concatenate tract1.trx tract2.trx merged.trx # Validate a TRX file -tff validate data.trx +trx validate data.trx ``` Individual commands are also available for backward compatibility: ```bash -tff_convert_tractogram input.trk output.trx -tff_concatenate_tractograms tract1.trx tract2.trx merged.trx -tff_validate_trx data.trx +trx_convert_tractogram input.trk output.trx +trx_concatenate_tractograms tract1.trx tract2.trx merged.trx +trx_validate data.trx ``` ## Development diff --git a/docs/source/scripts.rst b/docs/source/scripts.rst index 17829fa..337b125 100644 --- a/docs/source/scripts.rst +++ b/docs/source/scripts.rst @@ -3,38 +3,38 @@ Command-line Interface ====================== -The TRX toolkit provides a unified command-line interface ``tff`` as well as individual standalone commands for backward compatibility. All commands become available on your ``PATH`` after installing ``trx-python``. +The TRX toolkit provides a unified command-line interface ``trx`` as well as individual standalone commands for backward compatibility. All commands become available on your ``PATH`` after installing ``trx-python``. Each command supports ``--help`` for full options. -Unified CLI: ``tff`` +Unified CLI: ``trx`` -------------------- -The recommended way to use TRX commands is through the unified ``tff`` CLI: +The recommended way to use TRX commands is through the unified ``trx`` CLI: .. code-block:: bash - tff --help # Show all available commands - tff --help # Show help for a specific command + trx --help # Show all available commands + trx --help # Show help for a specific command Available subcommands: -- ``tff concatenate`` - Concatenate multiple tractograms -- ``tff convert`` - Convert between tractography formats -- ``tff convert-dsi`` - Fix DSI-Studio TRK files -- ``tff generate`` - Generate TRX from raw data files -- ``tff manipulate-dtype`` - Change array data types -- ``tff compare`` - Simple tractogram comparison -- ``tff validate`` - Validate and clean TRX files -- ``tff verify-header`` - Check header compatibility -- ``tff visualize`` - Visualize tractogram overlap +- ``trx concatenate`` - Concatenate multiple tractograms +- ``trx convert`` - Convert between tractography formats +- ``trx convert-dsi`` - Fix DSI-Studio TRK files +- ``trx generate`` - Generate TRX from raw data files +- ``trx manipulate-dtype`` - Change array data types +- ``trx compare`` - Simple tractogram comparison +- ``trx validate`` - Validate and clean TRX files +- ``trx verify-header`` - Check header compatibility +- ``trx visualize`` - Visualize tractogram overlap Standalone Commands ------------------- For backward compatibility, standalone commands are also available: -tff_concatenate_tractograms +trx_concatenate_tractograms ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Concatenate multiple tractograms into a single output. @@ -44,24 +44,24 @@ Concatenate multiple tractograms into a single output. .. code-block:: bash # Using unified CLI - tff concatenate in1.trk in2.trk merged.trx + trx concatenate in1.trk in2.trk merged.trx # Using standalone command - tff_concatenate_tractograms in1.trk in2.trk merged.trx + trx_concatenate_tractograms in1.trk in2.trk merged.trx -tff_convert_dsi_studio +trx_convert_dsi_studio ~~~~~~~~~~~~~~~~~~~~~~ Convert a DSI Studio ``.trk`` with accompanying ``.nii.gz`` reference into a cleaned ``.trk`` or TRX. .. code-block:: bash # Using unified CLI - tff convert-dsi input.trk reference.nii.gz cleaned.trk + trx convert-dsi input.trk reference.nii.gz cleaned.trk # Using standalone command - tff_convert_dsi_studio input.trk reference.nii.gz cleaned.trk + trx_convert_dsi_studio input.trk reference.nii.gz cleaned.trk -tff_convert_tractogram +trx_convert_tractogram ~~~~~~~~~~~~~~~~~~~~~~ General-purpose converter between ``trk``, ``tck``, ``vtk``, ``fib``, ``dpy``, and ``trx``. @@ -70,13 +70,13 @@ General-purpose converter between ``trk``, ``tck``, ``vtk``, ``fib``, ``dpy``, a .. code-block:: bash # Using unified CLI - tff convert input.trk output.trx --positions-dtype float32 --offsets-dtype uint64 + trx convert input.trk output.trx --positions-dtype float32 --offsets-dtype uint64 # Using standalone command - tff_convert_tractogram input.trk output.trx --positions-dtype float32 --offsets-dtype uint64 + trx_convert_tractogram input.trk output.trx --positions-dtype float32 --offsets-dtype uint64 -tff_generate_trx_from_scratch -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +trx_generate_from_scratch +~~~~~~~~~~~~~~~~~~~~~~~~~ Build a TRX file from raw NumPy arrays or CSV streamline coordinates. - Flags: ``--positions``, ``--offsets``, ``--positions-dtype``, ``--offsets-dtype``, spatial options (``--space``, ``--origin``), and metadata loaders for dpv/dps/groups/dpg. @@ -84,12 +84,12 @@ Build a TRX file from raw NumPy arrays or CSV streamline coordinates. .. code-block:: bash # Using unified CLI - tff generate fa.nii.gz output.trx --positions positions.npy --offsets offsets.npy + trx generate fa.nii.gz output.trx --positions positions.npy --offsets offsets.npy # Using standalone command - tff_generate_trx_from_scratch fa.nii.gz output.trx --positions positions.npy --offsets offsets.npy + trx_generate_from_scratch fa.nii.gz output.trx --positions positions.npy --offsets offsets.npy -tff_manipulate_datatype +trx_manipulate_datatype ~~~~~~~~~~~~~~~~~~~~~~~ Rewrite TRX datasets with new dtypes for positions/offsets/dpv/dps/dpg/groups. @@ -98,61 +98,61 @@ Rewrite TRX datasets with new dtypes for positions/offsets/dpv/dps/dpg/groups. .. code-block:: bash # Using unified CLI - tff manipulate-dtype input.trx output.trx --positions-dtype float16 --dpv color,uint8 + trx manipulate-dtype input.trx output.trx --positions-dtype float16 --dpv color,uint8 # Using standalone command - tff_manipulate_datatype input.trx output.trx --positions-dtype float16 --dpv color,uint8 + trx_manipulate_datatype input.trx output.trx --positions-dtype float16 --dpv color,uint8 -tff_simple_compare +trx_simple_compare ~~~~~~~~~~~~~~~~~~ Compare two tractograms for quick difference checks. .. code-block:: bash # Using unified CLI - tff compare first.trk second.trk + trx compare first.trk second.trk # Using standalone command - tff_simple_compare first.trk second.trk + trx_simple_compare first.trk second.trk -tff_validate_trx -~~~~~~~~~~~~~~~~ +trx_validate +~~~~~~~~~~~~ Validate a TRX file for consistency and remove invalid streamlines. .. code-block:: bash # Using unified CLI - tff validate data.trx --out cleaned.trx + trx validate data.trx --out cleaned.trx # Using standalone command - tff_validate_trx data.trx --out cleaned.trx + trx_validate data.trx --out cleaned.trx -tff_verify_header_compatibility +trx_verify_header_compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Check whether tractogram headers are compatible for operations such as concatenation. .. code-block:: bash # Using unified CLI - tff verify-header file1.trk file2.trk + trx verify-header file1.trk file2.trk # Using standalone command - tff_verify_header_compatibility file1.trk file2.trk + trx_verify_header_compatibility file1.trk file2.trk -tff_visualize_overlap +trx_visualize_overlap ~~~~~~~~~~~~~~~~~~~~~ Visualize streamline overlap between tractograms (requires visualization dependencies). .. code-block:: bash # Using unified CLI - tff visualize tractogram.trk reference.nii.gz + trx visualize tractogram.trk reference.nii.gz # Using standalone command - tff_visualize_overlap tractogram.trk reference.nii.gz + trx_visualize_overlap tractogram.trk reference.nii.gz Notes ----- - Test datasets for examples can be fetched with ``python -m trx.fetcher`` helpers: ``fetch_data(get_testing_files_dict())`` downloads to ``$TRX_HOME`` (default ``~/.tee_ar_ex``). - All commands print detailed usage with ``--help``. -- The unified ``tff`` CLI uses `Typer `_ for beautiful terminal output with colors and rich formatting. +- The unified ``trx`` CLI uses `Typer `_ for beautiful terminal output with colors and rich formatting. diff --git a/pyproject.toml b/pyproject.toml index 10cb2cb..dad07e5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -70,16 +70,16 @@ Documentation = "https://tee-ar-ex.github.io/trx-python/" Repository = "https://github.com/tee-ar-ex/trx-python" [project.scripts] -tff = "trx.cli:main" -tff_concatenate_tractograms = "trx.cli:concatenate_tractograms_cmd" -tff_convert_dsi_studio = "trx.cli:convert_dsi_cmd" -tff_convert_tractogram = "trx.cli:convert_cmd" -tff_generate_trx_from_scratch = "trx.cli:generate_cmd" -tff_manipulate_datatype = "trx.cli:manipulate_dtype_cmd" -tff_simple_compare = "trx.cli:compare_cmd" -tff_validate_trx = "trx.cli:validate_cmd" -tff_verify_header_compatibility = "trx.cli:verify_header_cmd" -tff_visualize_overlap = "trx.cli:visualize_cmd" +trx = "trx.cli:main" +trx_concatenate_tractograms = "trx.cli:concatenate_tractograms_cmd" +trx_convert_dsi_studio = "trx.cli:convert_dsi_cmd" +trx_convert_tractogram = "trx.cli:convert_cmd" +trx_generate_from_scratch = "trx.cli:generate_cmd" +trx_manipulate_datatype = "trx.cli:manipulate_dtype_cmd" +trx_simple_compare = "trx.cli:compare_cmd" +trx_validate = "trx.cli:validate_cmd" +trx_verify_header_compatibility = "trx.cli:verify_header_cmd" +trx_visualize_overlap = "trx.cli:visualize_cmd" [tool.setuptools] packages = ["trx"] diff --git a/trx/cli.py b/trx/cli.py index cae5ed0..69f6429 100644 --- a/trx/cli.py +++ b/trx/cli.py @@ -26,7 +26,7 @@ ) app = typer.Typer( - name="tff", + name="trx", help="TRX File Format Tools - CLI for brain tractography data manipulation.", add_completion=False, rich_markup_mode="rich", @@ -758,55 +758,55 @@ def _create_standalone_app(command_func, name: str, help_text: str): concatenate_tractograms_cmd = _create_standalone_app( concatenate_tractograms, - "tff_concatenate_tractograms", + "trx_concatenate_tractograms", "Concatenate multiple tractograms into one.", ) convert_dsi_cmd = _create_standalone_app( convert_dsi, - "tff_convert_dsi_studio", + "trx_convert_dsi_studio", "Fix DSI-Studio TRK files for compatibility.", ) convert_cmd = _create_standalone_app( convert, - "tff_convert_tractogram", + "trx_convert_tractogram", "Convert tractograms between formats.", ) generate_cmd = _create_standalone_app( generate, - "tff_generate_trx_from_scratch", + "trx_generate_from_scratch", "Generate TRX file from raw data files.", ) manipulate_dtype_cmd = _create_standalone_app( manipulate_dtype, - "tff_manipulate_datatype", + "trx_manipulate_datatype", "Manipulate TRX file internal array data types.", ) compare_cmd = _create_standalone_app( compare, - "tff_simple_compare", + "trx_simple_compare", "Simple comparison of tractograms by subtracting coordinates.", ) validate_cmd = _create_standalone_app( validate, - "tff_validate_trx", + "trx_validate", "Validate TRX file and remove invalid streamlines.", ) verify_header_cmd = _create_standalone_app( verify_header, - "tff_verify_header_compatibility", + "trx_verify_header_compatibility", "Compare spatial attributes of input files.", ) visualize_cmd = _create_standalone_app( visualize, - "tff_visualize_overlap", + "trx_visualize_overlap", "Display tractogram and density map with bounding box.", ) diff --git a/trx/tests/test_cli.py b/trx/tests/test_cli.py index 5860a26..201ff03 100644 --- a/trx/tests/test_cli.py +++ b/trx/tests/test_cli.py @@ -30,89 +30,89 @@ fetch_data(get_testing_files_dict(), keys=["DSI.zip", "trx_from_scratch.zip"]) -# Tests for standalone CLI commands (tff_* commands) +# Tests for standalone CLI commands (trx_* commands) class TestStandaloneCommands: """Tests for standalone CLI commands.""" def test_help_option_convert_dsi(self, script_runner): - ret = script_runner.run(["tff_convert_dsi_studio", "--help"]) + ret = script_runner.run(["trx_convert_dsi_studio", "--help"]) assert ret.success def test_help_option_convert(self, script_runner): - ret = script_runner.run(["tff_convert_tractogram", "--help"]) + ret = script_runner.run(["trx_convert_tractogram", "--help"]) assert ret.success - def test_help_option_generate_trx_from_scratch(self, script_runner): - ret = script_runner.run(["tff_generate_trx_from_scratch", "--help"]) + def test_help_option_generate_from_scratch(self, script_runner): + ret = script_runner.run(["trx_generate_from_scratch", "--help"]) assert ret.success def test_help_option_concatenate(self, script_runner): - ret = script_runner.run(["tff_concatenate_tractograms", "--help"]) + ret = script_runner.run(["trx_concatenate_tractograms", "--help"]) assert ret.success def test_help_option_manipulate(self, script_runner): - ret = script_runner.run(["tff_manipulate_datatype", "--help"]) + ret = script_runner.run(["trx_manipulate_datatype", "--help"]) assert ret.success def test_help_option_compare(self, script_runner): - ret = script_runner.run(["tff_simple_compare", "--help"]) + ret = script_runner.run(["trx_simple_compare", "--help"]) assert ret.success def test_help_option_validate(self, script_runner): - ret = script_runner.run(["tff_validate_trx", "--help"]) + ret = script_runner.run(["trx_validate", "--help"]) assert ret.success def test_help_option_verify_header(self, script_runner): - ret = script_runner.run(["tff_verify_header_compatibility", "--help"]) + ret = script_runner.run(["trx_verify_header_compatibility", "--help"]) assert ret.success def test_help_option_visualize(self, script_runner): - ret = script_runner.run(["tff_visualize_overlap", "--help"]) + ret = script_runner.run(["trx_visualize_overlap", "--help"]) assert ret.success -# Tests for unified tff CLI +# Tests for unified trx CLI class TestUnifiedCLI: - """Tests for the unified tff CLI.""" + """Tests for the unified trx CLI.""" - def test_tff_help(self, script_runner): - ret = script_runner.run(["tff", "--help"]) + def test_trx_help(self, script_runner): + ret = script_runner.run(["trx", "--help"]) assert ret.success - def test_tff_concatenate_help(self, script_runner): - ret = script_runner.run(["tff", "concatenate", "--help"]) + def test_trx_concatenate_help(self, script_runner): + ret = script_runner.run(["trx", "concatenate", "--help"]) assert ret.success - def test_tff_convert_help(self, script_runner): - ret = script_runner.run(["tff", "convert", "--help"]) + def test_trx_convert_help(self, script_runner): + ret = script_runner.run(["trx", "convert", "--help"]) assert ret.success - def test_tff_convert_dsi_help(self, script_runner): - ret = script_runner.run(["tff", "convert-dsi", "--help"]) + def test_trx_convert_dsi_help(self, script_runner): + ret = script_runner.run(["trx", "convert-dsi", "--help"]) assert ret.success - def test_tff_generate_help(self, script_runner): - ret = script_runner.run(["tff", "generate", "--help"]) + def test_trx_generate_help(self, script_runner): + ret = script_runner.run(["trx", "generate", "--help"]) assert ret.success - def test_tff_manipulate_dtype_help(self, script_runner): - ret = script_runner.run(["tff", "manipulate-dtype", "--help"]) + def test_trx_manipulate_dtype_help(self, script_runner): + ret = script_runner.run(["trx", "manipulate-dtype", "--help"]) assert ret.success - def test_tff_compare_help(self, script_runner): - ret = script_runner.run(["tff", "compare", "--help"]) + def test_trx_compare_help(self, script_runner): + ret = script_runner.run(["trx", "compare", "--help"]) assert ret.success - def test_tff_validate_help(self, script_runner): - ret = script_runner.run(["tff", "validate", "--help"]) + def test_trx_validate_help(self, script_runner): + ret = script_runner.run(["trx", "validate", "--help"]) assert ret.success - def test_tff_verify_header_help(self, script_runner): - ret = script_runner.run(["tff", "verify-header", "--help"]) + def test_trx_verify_header_help(self, script_runner): + ret = script_runner.run(["trx", "verify-header", "--help"]) assert ret.success - def test_tff_visualize_help(self, script_runner): - ret = script_runner.run(["tff", "visualize", "--help"]) + def test_trx_visualize_help(self, script_runner): + ret = script_runner.run(["trx", "visualize", "--help"]) assert ret.success