README.rst 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114
  1. freesurfer-surface
  2. ==================
  3. .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
  4. :target: https://github.com/psf/black
  5. .. image:: https://travis-ci.org/fphammerle/freesurfer-surface.svg?branch=master
  6. :target: https://travis-ci.org/fphammerle/freesurfer-surface
  7. .. image:: https://coveralls.io/repos/github/fphammerle/freesurfer-surface/badge.svg?branch=master
  8. :target: https://coveralls.io/github/fphammerle/freesurfer-surface?branch=master
  9. .. image:: https://img.shields.io/pypi/v/freesurfer-surface.svg
  10. :target: https://pypi.org/project/freesurfer-surface/#history
  11. .. image:: https://img.shields.io/pypi/pyversions/freesurfer-surface.svg
  12. :target: https://pypi.org/project/freesurfer-surface/
  13. .. image:: https://zenodo.org/badge/185943856.svg
  14. :target: https://zenodo.org/badge/latestdoi/185943856
  15. Python Library to Read and Write Surface Files in Freesurfer’s
  16. TriangularSurface Format
  17. Freesurfer https://surfer.nmr.mgh.harvard.edu/
  18. Install
  19. -------
  20. .. code:: sh
  21. pip3 install --user freesurfer-surface
  22. Usage
  23. -----
  24. Read Surface File
  25. ~~~~~~~~~~~~~~~~~
  26. .. code:: python
  27. from freesurfer_surface import Surface
  28. surface = Surface.read_triangular('bert/surf/lh.pial')
  29. for vertex in surface.vertices[:3]:
  30. print(vertex)
  31. vertex_0 = surface.vertices[0]
  32. print('coordinates of vertex #0:', (vertex_0.right, vertex_0.anterior, vertex_0.superior))
  33. for triangle_index, triangle in enumerate(surface.triangles[:4]):
  34. print(f'\ntriangle #{triangle_index}:')
  35. print('vertex indices:', triangle.vertex_indices)
  36. print('vertex coordinates:')
  37. for vertex in surface.select_vertices(triangle.vertex_indices):
  38. print((vertex.right, vertex.anterior, vertex.superior))
  39. Edit Surface File
  40. ~~~~~~~~~~~~~~~~~
  41. .. code:: python
  42. from freesurfer_surface import Surface, Vertex, Triangle
  43. surface = Surface.read_triangular('bert/surf/lh.pial'))
  44. vertex_a = surface.add_vertex(Vertex(0.0, 0.0, 0.0))
  45. vertex_b = surface.add_vertex(Vertex(1.0, 1.0, 1.0))
  46. vertex_c = surface.add_vertex(Vertex(2.0, 2.0, 2.0))
  47. surface.triangles.append(Triangle((vertex_a, vertex_b, vertex_c)))
  48. surface.write_triangular('somewhere/else/lh.pial')
  49. List Labels in Annotation File
  50. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51. .. code:: python
  52. from freesurfer_surface import Annotation
  53. annotation = Annotation.read('tests/subjects/fabian/label/lh.aparc.annot')
  54. for label in annotation.labels.values():
  55. print(label.index, label.hex_color_code, label.name)
  56. or
  57. .. code:: sh
  58. $ freesurfer-annotation-labels tests/subjects/fabian/label/lh.aparc.annot
  59. index color name
  60. 0 #190519 unknown
  61. 1 #196428 bankssts
  62. 2 #7d64a0 caudalanteriorcingulate
  63. 3 #641900 caudalmiddlefrontal
  64. ...
  65. 33 #4614aa temporalpole
  66. 34 #9696c8 transversetemporal
  67. 35 #ffc020 insula
  68. Find Border of Labelled Region
  69. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  70. .. code:: python
  71. from freesurfer_surface import Surface
  72. surface = Surface.read_triangular('bert/surf/lh.pial'))
  73. surface.load_annotation_file('bert/label/lh.aparc.annot')
  74. region, = filter(lambda l: l.name == 'precentral',
  75. annotation.labels.values())
  76. print(surface.find_label_border_polygonal_chains(region))
  77. Tests
  78. -----
  79. .. code:: sh
  80. pip3 install --user pipenv
  81. git clone https://github.com/fphammerle/freesurfer-surface.git
  82. cd freesurfer-surface
  83. pipenv run pylint freesurfer_surface
  84. pipenv run pytest --cov=freesurfer_surface