trx.io
======

.. py:module:: trx.io

.. autoapi-nested-parse::

   Unified I/O interface for tractogram file formats.

   ..
       !! processed by numpydoc !!


Attributes
----------

.. autoapisummary::

   trx.io.dipy_available


Functions
---------

.. autoapisummary::

   trx.io.get_trx_tmp_dir
   trx.io.load_sft_with_reference
   trx.io.load
   trx.io.save


Module Contents
---------------

.. py:data:: dipy_available
   :value: True


.. py:function:: get_trx_tmp_dir()

   
   Return a temporary directory honoring the ``TRX_TMPDIR`` setting.

   When the ``TRX_TMPDIR`` environment variable is set to ``"use_working_dir"``
   the current working directory is used. Otherwise, the value of
   ``TRX_TMPDIR`` is used directly. If the variable is not set, the system
   temporary directory is used.




   :Returns:

       tempfile.TemporaryDirectory
           Context-managed temporary directory placed according to the environment
           configuration.











   ..
       !! processed by numpydoc !!

.. py:function:: load_sft_with_reference(filepath, reference=None, bbox_check=True)

   
   Load a tractogram as a StatefulTractogram with an explicit reference.


   :Parameters:

       **filepath** : str
           Path to the tractogram file (.trk, .tck, .fib, .vtk, .dpy).

       **reference** : str or nibabel.Nifti1Image, optional
           Reference image used for formats without embedded affine information.
           Pass ``"same"`` to reuse the header embedded in .trk files.

       **bbox_check** : bool, optional
           If True, validate that streamlines lie within the reference bounding
           box. Defaults to True.



   :Returns:

       StatefulTractogram or None
           Loaded tractogram. Returns ``None`` when ``dipy`` is unavailable.




   :Raises:

       IOError
           If the file format is unsupported or a required reference is missing.







   ..
       !! processed by numpydoc !!

.. py:function:: load(tractogram_filename, reference)

   
   Load a tractogram from disk and return a TRX or StatefulTractogram.


   :Parameters:

       **tractogram_filename** : str
           Path to the input tractogram. TRX directories are supported.

       **reference** : str or nibabel.Nifti1Image
           Reference image used for formats without embedded affine information.



   :Returns:

       TrxFile or StatefulTractogram
           TRX file handle for ``.trx`` inputs, otherwise a StatefulTractogram.











   ..
       !! processed by numpydoc !!

.. py:function:: save(tractogram_obj, tractogram_filename, bbox_valid_check=False)

   
   Save a tractogram object to disk.


   :Parameters:

       **tractogram_obj** : TrxFile or StatefulTractogram
           Tractogram to persist. Non-TRX inputs are converted to StatefulTractogram
           before saving to non-TRX formats.

       **tractogram_filename** : str
           Destination file name. ``.trx`` will be saved using the TRX writer; all
           other extensions are handled by ``dipy.save_tractogram``.

       **bbox_valid_check** : bool, optional
           If True, validate that streamlines lie within the reference bounding
           box when saving non-TRX formats. Defaults to False.



   :Returns:

       None
           The function writes to disk and returns ``None``. Returns ``None``
           immediately when ``dipy`` is unavailable.











   ..
       !! processed by numpydoc !!