gifti.py 7.46 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#!/usr/bin/env python
#
# gifti.py - GIFTI file support.
#
# Author: Paul McCarthy  <pauldmccarthy@gmail.com>
#         Michiel Cottar <michiel.cottaar@ndcn.ox.ac.uk>
#
"""This class provides classes and functions for working with GIFTI files.

The GIFTI file format specification can be found at
http://www.nitrc.org/projects/gifti/

Support is currently very basic - only the following classes/functions
are available:

  .. autosummary::
     :nosignatures:

     GiftiSurface
20
21
     loadGiftiSurface
     relatedFiles
22
23
24
"""


25
import            glob
26
27
import os.path as op

28
import numpy   as np
29
30
import nibabel as nib

31
import fsl.utils.path as fslpath
32
from . import            constants
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
from . import            mesh


class GiftiSurface(mesh.TriangleMesh):
    """Class which represents a GIFTI surface image. This is essentially
    just a 3D model made of triangles.

    In addition to the ``vertices`` and ``indices`` provided by the
    :class:`.TriangleMesh` class (from which the ``GiftiSurface`` class
    derives), a ``GiftiSurface`` instance has the following attributes:

    ============== ====================================================
    ``name``       A name, typically the file name sans-suffix.
    ``dataSource`` Full path to the GIFTI file.
    ``surfImg``    Reference to the loaded ``nibabel.gifti.GiftiImage``
    ============== ====================================================
    """


    def __init__(self, infile):
        """Load the given GIFTI file using ``nibabel``, and extracts surface
Paul McCarthy's avatar
Paul McCarthy committed
54
        data using the  :func:`loadGiftiSurface` function.
55

56
        :arg infile: A GIFTI surface file (``*.surf.gii``).
57
58
59

        .. todo:: Allow loading from a ``.topo.gii`` and ``.coord.gii`` file?
                  Maybe.
60
61
        """

62
        surfimg, vertices, indices = loadGiftiSurface(infile)
63
64
65
66
67
68
69
70
71
72
73

        mesh.TriangleMesh.__init__(self, vertices, indices)

        name   = fslpath.removeExt(op.basename(infile), ALLOWED_EXTENSIONS)
        infile = op.abspath(infile)

        self.name       = name
        self.dataSource = infile
        self.surfImg    = surfimg


Paul McCarthy's avatar
Paul McCarthy committed
74
    def loadVertexData(self, dataSource, vertexData=None):
75
76
77
        """Overrides the :meth:`.TriangleMesh.loadVertexData` method.

        Attempts to load data associated with each vertex of this
78
79
        ``GiftiSurface`` from the given ``dataSource``, which may be
        a GIFTI file or a plain text file which contains vertex data.
80
81
        """

Paul McCarthy's avatar
Paul McCarthy committed
82
83
84
85
86
        if vertexData is None:
            if dataSource.endswith('.gii'):
                vertexData = loadGiftiVertexData(dataSource)[1]
            else:
                vertexData = None
87
            
Paul McCarthy's avatar
Paul McCarthy committed
88
        return mesh.TriangleMesh.loadVertexData(self, dataSource, vertexData)
89
90


91
92
93
94
95
96
97
98
99
100
101
ALLOWED_EXTENSIONS = ['.surf.gii', '.gii']
"""List of file extensions that a file containing Gifti surface data
is expected to have.
"""


EXTENSION_DESCRIPTIONS = ['GIFTI surface file', 'GIFTI surface file']
"""A description for each of the :data:`ALLOWED_EXTENSIONS`.
"""


102
def loadGiftiSurface(filename):
103
104
105
106
107
108
109
110
111
112
    """Extracts surface data from the given ``nibabel.gifti.GiftiImage``.

    The image is expected to contain the following``<DataArray>`` elements:

      - one comprising ``NIFTI_INTENT_POINTSET`` data (the surface vertices)
      - one comprising ``NIFTI_INTENT_TRIANGLE`` data (vertex indices
        defining the triangles).

    A ``ValueError`` will be raised if this is not the case.

113
    :arg filename: Name of a GIFTI file containing surface data.
114
115
116

    :returns:     A tuple containing these values:

117
118
                   - The loaded ``nibabel.gifti.GiftiImage`` instance

119
120
121
122
123
124
125
                   - A :math:`N\\times 3` ``numpy`` array containing :math:`N`
                     vertices.
    
                   - A :math:`M\\times 3` ``numpy`` array containing the 
                     vertex indices for :math:`M` triangles.
    """

126
    gimg = nib.load(filename)
127

128
129
130
131
132
133
134
135
136
    pointsetCode = constants.NIFTI_INTENT_POINTSET
    triangleCode = constants.NIFTI_INTENT_TRIANGLE

    pointsets = [d for d in gimg.darrays if d.intent == pointsetCode]
    triangles = [d for d in gimg.darrays if d.intent == triangleCode]

    if len(gimg.darrays) != 2:
        raise ValueError('GIFTI surface files must contain exactly '
                         'one pointset array and one triangle array')
137
    
138
139
140
    if len(pointsets) != 1:
        raise ValueError('GIFTI surface files must contain '
                         'exactly one pointset array')
141
    
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
    if len(triangles) != 1:
        raise ValueError('GIFTI surface files must contain '
                         'exactly one triangle array')

    vertices = pointsets[0].data
    indices  = triangles[0].data

    return gimg, vertices, indices


def loadGiftiVertexData(filename):
    """Loads vertex data from the given GIFTI file.

    It is assumed that the given file does not contain any
    ``NIFTI_INTENT_POINTSET`` or ``NIFTI_INTENT_TRIANGLE`` data arrays, and
    which contains either:
    
      - One ``(M, N)`` data array containing ``N`` data points for ``M``
        vertices

      - One or more ``(M, 1)`` data arrays each containing a single data point
        for ``M`` vertices, and all with the same intent code

    Returns a tuple containing:
166
    
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
      - The loaded ``nibabel.gifti.GiftiImage`` object
    
      - A ``(M, N)`` numpy array containing ``N`` data points for ``M``
        vertices
    """

    gimg = nib.load(filename)

    intents = set([d.intent for d in gimg.darrays])

    if len(intents) != 1:
        raise ValueError('{} contains multiple (or no) intents'
                         ': {}'.format(filename, intents))

    intent = intents.pop()

    if intent in (constants.NIFTI_INTENT_POINTSET,
                  constants.NIFTI_INTENT_TRIANGLE):
        
        raise ValueError('{} contains surface data'.format(filename))

    # Just a single array - return it as-is.
    # n.b. Storing (M, N) data in a single
    # DataArray goes against the GIFTI spec,
    # but hey, it happens.
    if len(gimg.darrays) == 1:
Paul McCarthy's avatar
Paul McCarthy committed
193
        return gimg, gimg.darrays[0].data
194
195
196
197
198
199
200
201

    # Otherwise extract and concatenate
    # multiple 1-dimensional arrays
    vdata = [d.data for d in gimg.darrays]

    if any([len(d.shape) != 1 for d in vdata]):
        raise ValueError('{} contains one or more non-vector '
                         'darrays'.format(filename))
202
    
203
    return gimg, np.vstack(vdata).T
204
205
206
207
208
209
210
211


def relatedFiles(fname):
    """Given a GIFTI file, returns a list of other GIFTI files in the same
    directory which appear to be related with the given one.  Files which
    share the same prefix are assumed to be related to the given file.
    """

Paul McCarthy's avatar
Paul McCarthy committed
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
    # We want to return all files in the same
    # directory which have the following name:

    # 
    # [prefix].*.[type].gii
    #
    #   where
    #     - prefix is the file prefix, and which
    #       may include periods.
    #
    #     - we don't care about the middle
    #
    #     - type is func, shape, label, or time

    # We determine the unique prefix of the
    # given file, and back-up to the most
    # recent period. Then search for other
    # files which have that same (non-unique)
    # prefix.
    prefix  = fslpath.uniquePrefix(fname)
    lastdot = prefix.rfind('.')
    prefix  = prefix[:lastdot]

    if lastdot == -1:
236
        return []
Paul McCarthy's avatar
Paul McCarthy committed
237
238
239
240
241
242
243

    funcs  = list(glob.glob('{}*.func.gii' .format(prefix)))
    shapes = list(glob.glob('{}*.shape.gii'.format(prefix)))
    labels = list(glob.glob('{}*.label.gii'.format(prefix)))
    times  = list(glob.glob('{}*.time.gii' .format(prefix)))

    return funcs + shapes + labels + times