---
title: "Reading GIFTI files in R"
author: "John Muschelli"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Reading GIFTI files in R}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## 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.

```{r, eval = FALSE}
outdir = NULL
library(gifti)
have_gifti_test_data(outdir = outdir)
```

```{r, include = FALSE}
outdir = NULL
library(gifti)
have_gifti_test_data(outdir = outdir)
```

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

```{r, eval = FALSE}
if (!have_gifti_test_data()) {
  download_gifti_data()
}
```

```{r, include = FALSE}
if (!have_gifti_test_data(outdir = outdir)) {
  download_gifti_data(outdir = outdir)
}
```

```{r, eval = FALSE}
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::rgl.open()
    rgl::rgl.triangles(surfs[[1]]$pointset, color = cols)
    rgl::play3d(rgl::spin3d(), duration = 5)
  }
}
```

```{r, include = FALSE}
if (have_gifti_test_data(outdir = outdir)) {
  gii_files = download_gifti_data(outdir = outdir)
  gii_list = readgii(gii_files)
  surf_files = grep("white[.]surf[.]gii", gii_files, value = TRUE)
  surfs = lapply(surf_files, function(r) {
    if (r == surf_files[[1]]) {
      r = readgii(r)
    }
    surf_triangles(r)
    })
  
  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::rgl.open()
    rgl::rgl.triangles(surfs[[1]]$pointset, color = cols)
    rgl::play3d(rgl::spin3d(), duration = 5)
  }
}
```