NF: trx --debug to help with environment mismatch

Author: skoudoro

README.md

@@ -147,6 +147,10 @@ export TRX_TMPDIR=use_working_dir
 
 Temporary folders are automatically cleaned, but if the code crashes unexpectedly, ensure folders are deleted manually.
 
+## Troubleshooting
+
+If the `trx` command is not working as expected, run `trx --debug` to print diagnostic information about the Python interpreter, package location, and whether all required and optional dependencies are installed.
+
 ## Documentation
 
 Full documentation is available at https://tee-ar-ex.github.io/trx-python/

docs/source/scripts.rst

@@ -19,6 +19,7 @@ The recommended way to use TRX commands is through the unified ``trx`` CLI:
 
 Available subcommands:
 
+- ``trx info`` - Display detailed TRX file information
 - ``trx concatenate`` - Concatenate multiple tractograms
 - ``trx convert`` - Convert between tractography formats
 - ``trx convert-dsi`` - Fix DSI-Studio TRK files
@@ -34,6 +35,20 @@ Standalone Commands
 
 For backward compatibility, standalone commands are also available:
 
+trx_info
+~~~~~~~~
+Display detailed information about a TRX file, including file size, compression status, header metadata (affine, dimensions, voxel sizes), streamline/vertex counts, data keys (dpv, dps, dpg), groups, and archive contents.
+
+- Only ``.trx`` files are supported.
+
+.. code-block:: bash
+
+    # Using unified CLI
+    trx info tractogram.trx
+
+    # Using standalone command
+    trx_info tractogram.trx
+
 trx_concatenate_tractograms
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Concatenate multiple tractograms into a single output.
@@ -151,6 +166,35 @@ Visualize streamline overlap between tractograms (requires visualization depende
     # Using standalone command
     trx_visualize_overlap tractogram.trk reference.nii.gz
 
+Troubleshooting
+---------------
+
+If the ``trx`` command is not working as expected, run ``trx --debug`` to print
+diagnostic information about the Python interpreter, package location, and
+whether all required and optional dependencies are installed:
+
+.. code-block:: bash
+
+    trx --debug
+
+    # Example output:
+    # Environment diagnostics:
+    #   Python executable : /Users/you/myenv/bin/python
+    #   sys.prefix        : /Users/you/myenv
+    #   trx-python version: 0.3.1
+    #   trx package       : /Users/you/myenv/lib/python3.11/site-packages/trx
+    #
+    # Required dependencies:
+    #   deepdiff     found
+    #   nibabel      found
+    #   numpy        found
+    #   typer        found
+    #
+    # Optional dependencies:
+    #   dipy         found
+    #   fury         not found
+    #   vtk          not found
+
 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``).

trx/cli.py

@@ -6,11 +6,10 @@
 """
 
 from pathlib import Path
-from typing import List, Optional
+from typing import Annotated, List, Optional
 
 import numpy as np
 import typer
-from typing_extensions import Annotated
 
 from trx.io import load, save
 from trx.trx_file_memmap import TrxFile, concatenate, load as load_trx
@@ -25,11 +24,99 @@
     verify_header_compatibility,
 )
 
+
+def _debug_callback(value: bool) -> None:
+    """Print environment and dependency diagnostics, then exit.
+
+    Parameters
+    ----------
+    value : bool
+        Whether the ``--debug`` flag was passed.
+    """
+    if not value:
+        return
+
+    import importlib.metadata
+    import importlib.util
+    import sys
+
+    from trx import __version__
+
+    typer.echo("Environment diagnostics:")
+    typer.echo(f"  Python executable : {sys.executable}")
+    typer.echo(f"  sys.prefix        : {sys.prefix}")
+    typer.echo(f"  trx-python version: {__version__}")
+
+    trx_spec = importlib.util.find_spec("trx")
+    trx_location = (
+        trx_spec.submodule_search_locations[0]
+        if trx_spec and trx_spec.submodule_search_locations
+        else "unknown"
+    )
+    typer.echo(f"  trx package       : {trx_location}")
+
+    # Read required dependencies from package metadata
+    required_deps = []
+    try:
+        import re
+
+        for req in importlib.metadata.requires("trx-python") or []:
+            # Skip optional / extra deps (they contain "; extra ==")
+            if "extra ==" in req:
+                continue
+            # Extract the package name (strip version specifiers like >=, <=, ~=)
+            dep_name = re.split(r"[>=<!~;\s]", req)[0]
+            required_deps.append(dep_name)
+    except importlib.metadata.PackageNotFoundError:
+        required_deps = ["deepdiff", "nibabel", "numpy", "typer"]
+
+    optional_deps = ["dipy", "fury", "vtk"]
+
+    typer.echo("\nRequired dependencies:")
+    for dep in required_deps:
+        spec = importlib.util.find_spec(dep)
+        if spec is None:
+            typer.echo(f"  {dep:12s} NOT FOUND")
+        else:
+            typer.echo(f"  {dep:12s} found")
+
+    typer.echo("\nOptional dependencies:")
+    for dep in optional_deps:
+        spec = importlib.util.find_spec(dep)
+        if spec is None:
+            typer.echo(f"  {dep:12s} not found")
+        else:
+            typer.echo(f"  {dep:12s} found")
+
+    raise typer.Exit()
+
+
+def _main_callback(
+    _debug: Annotated[
+        bool,
+        typer.Option(
+            "--debug",
+            help="Print environment and dependency diagnostics.",
+            callback=_debug_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """TRX File Format Tools - CLI for brain tractography data manipulation.
+
+    Parameters
+    ----------
+    _debug : bool, optional
+        If True, print environment and dependency diagnostics and exit.
+    """
+
+
 app = typer.Typer(
     name="trx",
     help="TRX File Format Tools - CLI for brain tractography data manipulation.",
     add_completion=False,
     rich_markup_mode="rich",
+    callback=_main_callback,
 )