freesurfer-surface

Python Library to Read and Write Surface Files in Freesurfer’s TriangularSurface Format

Freesurfer https://surfer.nmr.mgh.harvard.edu/

Install

pip3 install --user freesurfer-surface

Usage

Read Surface File

from freesurfer_surface import Surface

surface = Surface.read_triangular('bert/surf/lh.pial')

for vertex in surface.vertices[:3]:
    print(vertex)

vertex_0 = surface.vertices[0]
print('coordinates of vertex #0:', (vertex_0.right, vertex_0.anterior, vertex_0.superior))

for triangle_index, triangle in enumerate(surface.triangles[:4]):
    print(f'\ntriangle #{triangle_index}:')
    print('vertex indices:', triangle.vertex_indices)
    print('vertex coordinates:')
    for vertex in surface.select_vertices(triangle.vertex_indices):
        print((vertex.right, vertex.anterior, vertex.superior))

Edit Surface File

from freesurfer_surface import Surface, Vertex, Triangle
surface = Surface.read_triangular('bert/surf/lh.pial'))
vertex_a = surface.add_vertex(Vertex(0.0, 0.0, 0.0))
vertex_b = surface.add_vertex(Vertex(1.0, 1.0, 1.0))
vertex_c = surface.add_vertex(Vertex(2.0, 2.0, 2.0))
surface.triangles.append(Triangle((vertex_a, vertex_b, vertex_c)))
surface.write_triangular('somewhere/else/lh.pial')

List Labels in Annotation File

from freesurfer_surface import Annotation

annotation = Annotation.read('tests/subjects/fabian/label/lh.aparc.annot')
for label in annotation.labels.values():
    print(label.index, label.hex_color_code, label.name)

or

$ freesurfer-annotation-labels tests/subjects/fabian/label/lh.aparc.annot
index  color    name
0      #190519  unknown
1      #196428  bankssts
2      #7d64a0  caudalanteriorcingulate
3      #641900  caudalmiddlefrontal
...
33     #4614aa  temporalpole
34     #9696c8  transversetemporal
35     #ffc020  insula

Find Border of Labelled Region

from freesurfer_surface import Surface
surface = Surface.read_triangular('bert/surf/lh.pial'))
surface.load_annotation_file('bert/label/lh.aparc.annot')
region, = filter(lambda l: l.name == 'precentral',
                 annotation.labels.values())
print(surface.find_label_border_polygonal_chains(region))

Tests

pip3 install --user pipenv
git clone https://github.com/fphammerle/freesurfer-surface.git
cd freesurfer-surface
pipenv run pylint freesurfer_surface
pipenv run pytest --cov=freesurfer_surface