Reading GIFTI files in R

John Muschelli

2026-02-05

GIFTI Files

GIFTI files have surface data that can be rendered in R. Overall, they contain data that is stored in standard XML formats. We provide some utilities that rely on the XML parsing of the xml2 package, mainly the readgii function. The read_gifti and readGIfTI functions are duplicates of the readgii function, but were made for ease of use for programmers who are used to the readNIfTI function from the oro.nifti package.

Getting the Data

We provide some test data with the package, but must be downloaded using download_gifti_data. We also provide a test function that allows a user to check if the data is downloaded, which is useful for examples or vignettes, such as this one.

outdir = NULL
library(gifti)
have_gifti_test_data(outdir = outdir)

If this is false, we can combine these to ensure the data is downloaded:

if (!have_gifti_test_data()) {
  download_gifti_data()
}
if (have_gifti_test_data(outdir = outdir)) {
  gii_files = download_gifti_data(outdir = outdir)
  gii_list = lapply(gii_files, readgii)
  surf_files = grep("white[.]surf[.]gii", gii_files, value = TRUE)
  surfs = lapply(surf_files, surf_triangles)
  
  col_file = grep("white[.]shape[.]gii", gii_files, value = TRUE)
  cdata = readgii(col_file)
  cdata = cdata$data$shape
  mypal = grDevices::colorRampPalette(colors = c("blue", "black", "red"))
  n = 4
  breaks = quantile(cdata)
  ints = cut(cdata, include.lowest = TRUE, breaks = breaks)
  ints = as.integer(ints)
  stopifnot(!any(is.na(ints)))
  cols = mypal(n)[ints]
  cols = cols[surfs[[1]]$triangle]
  
  if (requireNamespace("rgl", quietly = TRUE)) {
    rgl::open3d()
    rgl::triangles3d(surfs[[1]]$pointset, color = cols)
    rgl::play3d(rgl::spin3d(), duration = 5)
  }
}