GIFTI — neuroimaging surfaces (.gii)
The GIFTI XML format for cortical and other surfaces and their per-vertex data, what FreeSurfer, Connectome Workbench, SimNIBS, Brainstorm and MNE exchange (roadmap 2.4.4). Both engines read and write it (formats/gifti.cpp through pugixml, meshioplusplus.gifti), and they write the same bytes.
| Format name | gifti |
| Extensions | .gii (.surf.gii, .func.gii, .label.gii, .shape.gii all end in it) |
| Read / Write | ✓ / ✓ (one triangle surface) |
| Extra dependencies | — (zlib for GZipBase64Binary arrays) |
Reading
import meshioplusplus
mesh = meshioplusplus.read("lh.pial.surf.gii")Every DataArray is decoded: ASCII, Base64Binary and GZipBase64Binary (base64, then a zlib stream), little- or big-endian, row- or column-major, any NIfTI integer or float type. External-file arrays are refused by name.
NIFTI_INTENT_POINTSETis the points; itsCoordinateSystemTransformMatrixisfield_data["gifti:transform"](4x4) and its space namesgifti:data_spaceandgifti:transformed_space(bytes).NIFTI_INTENT_TRIANGLEis the triangle block.- Every other array with one row per vertex is point data named by its
Namemetadata, elsegifti:<intent>_<index>(gifti:labelfor an unnamedNIFTI_INTENT_LABEL). An array of another length is skipped with a warning. - With a
NIFTI_INTENT_LABELarray, eachLabelTableentry is a point region over the vertices carrying its key, tagged with the key.
Writing
meshioplusplus.write("out.surf.gii", mesh)One triangle block (or none): the points as a float32 POINTSET with the transform (identity when the mesh has none), the triangles as an int32 TRIANGLE array, then each point data array as float32 (SHAPE, or NONE with several components) or int32 (NONE; LABEL for the one named gifti:label), every array little-endian Base64Binary, row-major and carrying its name. Point regions with a non-negative tag become the LabelTable. Coordinates and floating-point data are float32, as the format stores them.
Verification
nibabel 5.5 reads what meshio++ writes (points, triangles, named arrays, the label table) and meshio++ reads what nibabel writes in every encoding and byte order (tests/python/test_gifti.py).