""" Read and write trackvis files (old interface)

See :mod:`nibabel.streamlines` for the new interface.

We will deprecate this, the old interface, in some future release.

"""

              "in v4.0; please use the 'nibabel.streamlines' interface.",

              DeprecationWarning,

              stacklevel=2)

# Definition of trackvis header structure.

# See http://www.trackvis.org/docs/?subsect=fileformat

# See https://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html

    ('id_string', 'S6'),

    ('dim', 'h', 3),

    ('voxel_size', 'f4', 3),

    ('origin', 'f4', 3),

    ('n_scalars', 'h'),

    ('scalar_name', 'S20', 10),

    ('n_properties', 'h'),

    ('property_name', 'S20', 10),

    ('reserved', 'S508'),

    ('voxel_order', 'S4'),

    ('pad2', 'S4'),

    ('image_orientation_patient', 'f4', 6),

    ('pad1', 'S2'),

    ('invert_x', 'S1'),

    ('invert_y', 'S1'),

    ('invert_z', 'S1'),

    ('swap_xy', 'S1'),

    ('swap_yz', 'S1'),

    ('swap_zx', 'S1'),

    ('n_count', 'i4'),

    ('version', 'i4'),

    ('hdr_size', 'i4'),

]

# Version 2 adds a 4x4 matrix giving the affine transformation going

# from voxel coordinates in the referenced 3D voxel matrix, to xyz

# coordinates (axes L->R, P->A, I->S).  IF (0 based) value [3, 3] from

# this matrix is 0, this means the matrix is not recorded.

    ('id_string', 'S6'),

    ('dim', 'h', 3),

    ('voxel_size', 'f4', 3),

    ('origin', 'f4', 3),

    ('n_scalars', 'h'),

    ('scalar_name', 'S20', 10),

    ('n_properties', 'h'),

    ('property_name', 'S20', 10),

    ('vox_to_ras', 'f4', (4, 4)),  # new field for version 2

    ('reserved', 'S444'),

    ('voxel_order', 'S4'),

    ('pad2', 'S4'),

    ('image_orientation_patient', 'f4', 6),

    ('pad1', 'S2'),

    ('invert_x', 'S1'),

    ('invert_y', 'S1'),

    ('invert_z', 'S1'),

    ('swap_xy', 'S1'),

    ('swap_yz', 'S1'),

    ('swap_zx', 'S1'),

    ('n_count', 'i4'),

    ('version', 'i4'),

    ('hdr_size', 'i4'),

]

# Full header numpy dtypes

# affine to go from DICOM LPS to MNI RAS space

    """ Error in trackvis header

    """

    """ Error in trackvis data

    """

                        'nibabel.streamlines.load, instead.',

                        since='2.5.0', until='4.0.0')

    """ Read trackvis file from `fileobj`, return `streamlines`, `header`

    Parameters

    ----------

    fileobj : string or file-like object

       If string, a filename; otherwise an open file-like object

       pointing to trackvis file (and ready to read from the beginning

       of the trackvis header data)

    as_generator : bool, optional

       Whether to return tracks as sequence (False, default) or as a generator

       (True).

    points_space : {None, 'voxel', 'rasmm'}, optional

        The coordinates in which you want the points in the *output*

        streamlines expressed.  If None, then return the points exactly as they

        are stored in the trackvis file. The points will probably be in

        trackvis voxmm space - see Notes for ``write`` function.  If 'voxel',

        we convert the points to voxel space simply by dividing by the recorded

        voxel size.  If 'rasmm' we'll convert the points to RAS mm space (real

        space). For 'rasmm' we check if the affine is set and matches the voxel

        sizes and voxel order.

    strict : {True, False}, optional

        If True, raise error on read for badly-formed file.  If False, let pass

        files with last track having too few points.

    Returns

    -------

    streamlines : sequence or generator

       Returns sequence if `as_generator` is False, generator if True.  Value

       is sequence or generator of 3 element sequences with elements:

       #. points : ndarray shape (N,3)

          where N is the number of points

       #. scalars : None or ndarray shape (N, M)

          where M is the number of scalars per point

       #. properties : None or ndarray shape (P,)

          where P is the number of properties

    hdr : structured array

       structured array with trackvis header fields

    Notes

    -----

    The endianness of the input data can be deduced from the endianness

    of the returned `hdr` or `streamlines`

    Points are in trackvis *voxel mm*.  Each track has N points, each with 3

    coordinates, ``x, y, z``, where ``x`` is the floating point voxel

    coordinate along the first image axis, multiplied by the voxel size for

    that axis.

    """

    # try defaulting to version 2 format

                     dtype=header_2_dtype,

                     buffer=hdr_str)

                          '5 characters of id_string')

    else:

    # Check version and adapt structure accordingly

                         dtype=header_1_dtype,

                         buffer=hdr_str)

    # Do points_space checks

    # prepare transforms for later use

        # For case where there are no scalars or no properties

        # stream_count == 0 signals read to end of file

            # Check if we got as many bytes as we expect for these points

                # Short of bytes, should we raise an error or continue?

                                        f'{n_streams}, found {actual_n_pts}')

            # Cast bytes to points array

                             buffer=pts_str)

            # Add properties

        # Always close file if we opened it

        # Raise error if we didn't get as many streams as claimed

                f'Expecting {stream_count} streamlines, found only {n_streams}')

                        'nibabel.streamlines.save, instead.',

                        since='2.5.0', until='4.0.0')

          points_space=None):

    """ Write header and `streamlines` to trackvis file `fileobj`

    The parameters from the streamlines override conflicting parameters

    in the `hdr_mapping` information.  In particular, the number of

    streamlines, the number of scalars, and the number of properties are

    written according to `streamlines` rather than `hdr_mapping`.

    Parameters

    ----------

    fileobj : filename or file-like

       If filename, open file as 'wb', otherwise `fileobj` should be an

       open file-like object, with a ``write`` method.

    streamlines : iterable

       iterable returning 3 element sequences with elements:

       #. points : ndarray shape (N,3)

          where N is the number of points

       #. scalars : None or ndarray shape (N, M)

          where M is the number of scalars per point

       #. properties : None or ndarray shape (P,)

          where P is the number of properties

       If `streamlines` has a ``len`` (for example, it is a list or a tuple),

       then we can write the number of streamlines into the header.  Otherwise

       we write 0 for the number of streamlines (a valid trackvis header) and

       write streamlines into the file until the iterable is exhausted.

       M - the number of scalars - has to be the same for each streamline in

       `streamlines`.  Similarly for P. See `points_space` and Notes for more

       detail on the coordinate system for ``points`` above.

    hdr_mapping : None, ndarray or mapping, optional

       Information for filling header fields.  Can be something

       dict-like (implementing ``items``) or a structured numpy array

    endianness : {None, '<', '>'}, optional

       Endianness of file to be written.  '<' is little-endian, '>' is

       big-endian.  None (the default) is to use the endianness of the

       `streamlines` data.

    points_space : {None, 'voxel', 'rasmm'}, optional

        The coordinates in which the points in the input streamlines are

        expressed.  If None, then assume the points are as you want them

        (probably trackvis voxmm space - see Notes).  If 'voxel', the points

        are in voxel space, and we will transform them to trackvis voxmm space.

        If 'rasmm' the points are in RAS mm space (real space).  We transform

        them to trackvis voxmm space.  If 'voxel' or 'rasmm' we insist that the

        voxel sizes and ordering are set to non-default values.  If 'rasmm' we

        also check if the affine is set and matches the voxel sizes

    Returns

    -------

    None

    Examples

    --------

    >>> from io import BytesIO

    >>> file_obj = BytesIO()

    >>> pts0 = np.random.uniform(size=(10,3))

    >>> pts1 = np.random.uniform(size=(10,3))

    >>> streamlines = ([(pts0, None, None), (pts1, None, None)])

    >>> write(file_obj, streamlines)

    >>> _ = file_obj.seek(0)  # returns 0

    >>> streams, hdr = read(file_obj)

    >>> len(streams)

    2

    If there are too many streamlines to fit in memory, you can pass an

    iterable thing instead of a list

    >>> file_obj = BytesIO()

    >>> def gen():

    ...     yield (pts0, None, None)

    ...     yield (pts0, None, None)

    >>> write(file_obj, gen())

    >>> _ = file_obj.seek(0)

    >>> streams, hdr = read(file_obj)

    >>> len(streams)

    2

    Notes

    -----

    Trackvis (the application) expects the ``points`` in the streamlines be in

    what we call *trackvis voxmm* coordinates.  If we have a point (x, y, z) in

    voxmm coordinates, and ``voxel_size`` has the voxel sizes for each of the 3

    dimensions, then x, y, z refer to mm in voxel space. Thus if i, j, k is a

    point in voxel coordinates, then ``x = i * voxel_size[0]; y = j *

    voxel_size[1]; z = k * voxel_size[2]``.   The spatial direction of x, y and

    z are defined with the "voxel_order" field.  For example, if the original

    image had RAS voxel ordering then "voxel_order" would be "RAS".  RAS here

    refers to the spatial direction of the voxel axes: "R" means that moving

    along first voxel axis moves from left to right in space, "A" -> second

    axis goes from posterior to anterior, "S" -> inferior to superior.  If

    "voxel_order" is empty we assume "LPS".

    This information comes from some helpful replies on the trackvis forum

    about `interpreting point coordiantes

    <http://trackvis.org/blog/forum/diffusion-toolkit-usage/interpretation-of-track-point-coordinates>`_

    """

        # write header without streams

    # fill in a new header from mapping-like

    # Try and get number of streams from streamlines.  If this is an iterable,

    # we don't have a len, so we write 0 for length.  The 0 is a valid trackvis

    # value with meaning - keep reading until you run out of data.

    # Get number of scalars and properties

    # calculate number of scalars

    else:

    # calculate number of properties

    else:

    # do points_space checks

    # prepare transforms for later use

    # write header

    # track preliminaries

    # Add back the read first streamline to the sequence

        # This call ensures that the data are 32-bit floats, and that

        # the endianness is OK.

        else:

        else:

    """ Check header `hdr` for consistency with transform `points_space`

    Parameters

    ----------

    hdr : ndarray

        trackvis header as structured ndarray

    points_space : {None, 'voxmm', 'voxel', 'rasmm'

        nature of transform that we will (elsewhere) apply to streamlines

        paired with `hdr`.  None or 'voxmm' means pass through with no futher

        checks.  'voxel' checks for all ``hdr['voxel_sizes'] being <= zero

        (error) or any being zero (warning).  'rasmm' checks for presence of

        non-zeros affine in ``hdr['vox_to_ras']``, and that the affine therein

        corresponds to ``hdr['voxel_order']`` and ''hdr['voxel_sizes']`` - and

        raises an error otherwise.

    Returns

    -------

    None

    Notes

    -----

    """

                              'valid for voxel - voxmm conversion')

                              '"voxel_sizes" all 0')

                              'affine with which to convert points; '

                              'this is present for headers >= version 2')

                              'rasmm points and voxmm')

                              f'from voxel_size field value {zooms}')

                              f'but header voxel_order is {voxel_order}')

    else:

    """ Fill `hdr` from mapping `mapping`, with given endianness """

        # passed a valid mapping as header?  Copy and return

        # otherwise make a new empty header.   If no version specified,

        # go for default (2)

        else:

    # check header values

                          '5 characaters of id_string')

                        'nibabel.streamlines.TrkFile.create_empty_header, instead.',

                        since='2.5.0', until='4.0.0')

    """ Empty trackvis header

    Parameters

    ----------

    endianness : {'<','>'}, optional

       Endianness of empty header to return. Default is native endian.

    version : int, optional

       Header version.  1 or 2.  Default is 2

    Returns

    -------

    hdr : structured array

       structured array containing empty trackvis header

    Examples

    --------

    >>> hdr = empty_header()

    >>> print(hdr['version'])

    2

    >>> hdr['id_string'].item() == b'TRACK'

    True

    >>> endian_codes[hdr['version'].dtype.byteorder] == native_code

    True

    >>> hdr = empty_header(swapped_code)

    >>> endian_codes[hdr['version'].dtype.byteorder] == swapped_code

    True

    >>> hdr = empty_header(version=1)

    >>> print(hdr['version'])

    1

    Notes

    -----

    The trackvis header can store enough information to give an affine

    mapping between voxel and world space.  Often this information is

    missing.  We make no attempt to fill it with sensible defaults on

    the basis that, if the information is missing, it is better to be

    explicit.

    """

    else:

                        'nibabel.streamlines.trk.get_affine_trackvis_to_rasmm, instead.',

                        since='2.5.0', until='4.0.0')

    """ Return voxel to mm affine from trackvis header

    Affine is mapping from voxel space to Nifti (RAS) output coordinate

    system convention; x: Left -> Right, y: Posterior -> Anterior, z:

    Inferior -> Superior.

    Parameters

    ----------

    trk_hdr : mapping

       Mapping with trackvis header keys ``version``. If ``version == 2``, we

       also expect ``vox_to_ras``.

    atleast_v2 : None or bool

        If None, currently defaults to False.  This will change to True in

        future versions.  If True, require that there is a valid 'vox_to_ras'

        affine, raise HeaderError otherwise.  If False, look for valid

        'vox_to_ras' affine, but fall back to best guess from version 1 fields

        otherwise.

    Returns

    -------

    aff : (4,4) array

       affine giving mapping from voxel coordinates (affine applied on

       the left to points on the right) to millimeter coordinates in the

       RAS coordinate system

    Notes

    -----

    Our initial idea was to try and work round the deficiencies of the version

    1 format by using the DICOM orientation fields to store the affine.  This

    proved difficult in practice because trackvis (the application) doesn't

    allow negative voxel sizes (needed for recording axis flips) and sets the

    origin field to 0. In future, we'll raise an error rather than try and

    estimate the affine from version 1 fields

    """

                              'not valid')

    # Now we are in the dark world of the DICOM fields.  We might have made

    # this one ourselves, in which case the origin might be set, and it might

    # have negative voxel sizes

    # The IOP field has only two of the three columns we need

    # R might be a rotation matrix (and so completed by the cross product of

    # the first two columns), or it might be an orthogonal matrix with negative

    # determinant. We try pure rotation first

    # Next we check against the 'voxel_order' field if present and not empty.

    # If the voxel_order conflicts with the affine by one flip, this may have

    # been a negative determinant affine saved with positive voxel sizes

        # If first pass doesn't match, try flipping the (estimated) third

        # column

                              f'voxel_order of {exp_order}')

                        'nibabel.streamlines.TrkFile.affine_to_rasmm property, instead.',

                        since='2.5.0', until='4.0.0')

    """ Set affine `affine` into trackvis header `trk_hdr`

    Affine is mapping from voxel space to Nifti RAS) output coordinate

    system convention; x: Left -> Right, y: Posterior -> Anterior, z:

    Inferior -> Superior.  Sets affine if possible, and voxel sizes, and voxel

    axis ordering.

    Parameters

    ----------

    affine : (4,4) array-like

       Affine voxel to mm transformation

    trk_hdr : mapping

       Mapping implementing __setitem__

    pos_vos : None or bool

        If None, currently defaults to False - this will change in future

        versions of nibabel.  If False, allow negative voxel sizes in header to

        record axis flips.  Negative voxels cause problems for trackvis (the

        application).  If True, enforce positive voxel sizes.

    set_order : None or bool

        If None, currently defaults to False - this will change in future

        versions of nibabel.  If False, do not set ``voxel_order`` field in

        `trk_hdr`.  If True, calculcate ``voxel_order`` from `affine` and set

        into `trk_hdr`.

    Returns

    -------

    None

    Notes

    -----

    version 2 of the trackvis header has a dedicated field for the nifti RAS

    affine. In theory trackvis 1 has enough information to store an affine,

    with the fields 'origin', 'voxel_size' and 'image_orientation_patient'.

    Unfortunately, to be able to store any affine, we'd need to be able to set

    negative voxel sizes, to encode axis flips. This is because

    'image_orientation_patient' is only two columns of the 3x3 rotation matrix,

    and we need to know the number of flips to reconstruct the third column

    reliably.  It turns out that negative flips upset trackvis (the

    application).  The application also ignores the origin field, and may not

    use the 'image_orientation_patient' field.

    """

    # Now on dodgy ground with DICOM fields in header

    # RAS to DPCS output

    # Get zooms

    # If you said we could, adjust zooms to make RS correspond (below) to a

    # true rotation matrix.  We need to set the sign of one of the zooms to

    # deal with this.  Trackvis (the application) doesn't like negative zooms

    # at all, so you might want to disallow this with the pos_vox option.

    # retrieve rotation matrix from RS with polar decomposition.

    # Discard shears because we cannot store them.

    # it's an orthogonal matrix

    # set into header

    """ Error from TrackvisFile class

    """

    """ Convenience class to encapsulate trackvis file information

    Parameters

    ----------

    streamlines : sequence

       sequence of streamlines.  This object does not accept generic iterables

       as input because these can be consumed and make the object unusable.

       Please use the function interface to work with generators / iterables

    mapping : None or mapping

       Mapping defining header attributes

    endianness : {None, '<', '>'}

       Set here explicit endianness if required.  Endianness otherwise inferred

       from `streamlines`

    filename : None or str, optional

       filename

    points_space : {None, 'voxel', 'rasmm'}, optional

        Space in which streamline points are expressed in memory.  Default

        (None) means streamlines contain points in trackvis *voxmm* space

        (voxel positions * voxel sizes).  'voxel' means points are in voxel

        space (and need to be multiplied by voxel size for saving in file).

        'rasmm' mean the points are expressed in mm space according to the

        affine.  See ``read`` and ``write`` function docstrings for more