R/read_nisurface.R

In freesurferformats: Read and Write 'FreeSurfer' Neuroimaging File Formats

# Functions to read different neuroimaging surface files formats.
# Uses S3 generics to try several loading methods (file formats) for the same file.


#' @title Read a surface, based on the file path without extension.
#'
#' @description Tries to read all files which can be constructed from the base path and the given extensions.
#'
#' @param filepath_noext character string, the full path to the input surface file without file extension.
#'
#' @param extensions vector of character strings, the file extensions to try.
#'
#' @param ... parameters passed on to \code{\link[freesurferformats]{read_nisurfacefile}}. Allows you to set the `methods`.
#'
#' @return an instance of `fs.surface`, read from the file. See \code{\link[freesurferformats]{read.fs.surface}} for details. If none of the reader methods succeed, an error is raised.
#'
#' @family mesh functions
#'
#' @examples
#' \dontrun{
#'     surface_filepath_noext =
#'      paste(get_optional_data_filepath("subjects_dir/subject1/surf/"),
#'      'lh.white', sep="");
#'     mesh = read_nisurface(surface_filepath_noext);
#'     mesh;
#'  }
#'
#' @export
read_nisurface <- function(filepath_noext, extensions=c('', '.asc', '.gii'), ...) {
  surffile = readable.files(filepath_noext, precedence=extensions);
  return(read_nisurfacefile(surffile, ...));
}


#' @title S3 method to read a neuroimaging surface file.
#'
#' @description Tries to read the file with all implemented surface format reader methods. The file must exist. With the default settings, one can read files in the following surface formats: 1) FreeSurfer binary surface format (e.g., `surf/lh.white`). 2) FreeSurfer ASCII surface format (e.g., `surf/lh.white,asc`). 3) GIFTI surface format, only if package `gifti` is installed. See \code{gifti::read_gifti} for details. Feel free to implement additional methods. Hint:keep in mind that they should return one-based indices.
#'
#' @param filepath character string, the full path to the input surface file.
#'
#' @param methods list of character strings, the formats to try. Each of these must have a function called \code{read_nisurface.<method>}, which must return an `fs.surface` instance on success.
#'
#' @param ... parameters passed on to the individual methods
#'
#' @return an instance of `fs.surface`, read from the file. See \code{\link[freesurferformats]{read.fs.surface}} for details. If none of the reader methods succeed, an error is raised.
#'
#' @family mesh functions
#'
#' @examples
#'     surface_file = system.file("extdata", "lh.tinysurface",
#'                             package = "freesurferformats", mustWork = TRUE);
#'     mesh = read_nisurface(surface_file);
#'     mesh;
#'
#' @export
read_nisurfacefile <- function(filepath, methods=c('fsnative', 'fsascii', 'gifti'), ...) {
  if(!file.exists(filepath)) {
    stop(sprintf("Cannot read neuroimaging surface, file '%s' does not exist.\n", filepath));
  }

  class(filepath) <- c(methods, class(filepath));
  UseMethod('read_nisurfacefile', object = filepath);
}


#' @title Read a FreeSurfer ASCII surface file.
#'
#' @param filepath character string, the full path to the input surface file.
#'
#' @param ... parameters passed to \code{\link[freesurferformats]{read.fs.surface}}.
#'
#' @return an instance of `fs.surface`, read from the file. See \code{\link[freesurferformats]{read.fs.surface}} for details. If none of the reader methods succeed, an error is raised.
#'
#' @export
read_nisurfacefile.fsnative <- function(filepath, ...) {
  # try to read via read.fs.surface
  res <- tryCatch({
    freesurferformats::read.fs.surface(filepath, ...);
  }, error = function(e) {
    NULL;
  });

  # On success, return the surface.
  if(!is.null(res)){
    return(res);
  }

  # Failed, use the next read.ni.surface.* method
  NextMethod('read_nisurfacefile');
}


#' @title Read a FreeSurfer ASCII surface file.
#'
#' @param filepath character string, the full path to the input surface file.
#'
#' @param ... parameters passed to \code{\link[freesurferformats]{read.fs.surface.asc}}.
#'
#' @return an instance of `fs.surface`, read from the file. See \code{\link[freesurferformats]{read.fs.surface}} for details. If none of the reader methods succeed, an error is raised.
#'
#' @export
read_nisurfacefile.fsascii <- function(filepath, ...) {
  res <- tryCatch({
    freesurferformats::read.fs.surface.asc(filepath, ...);
  }, error = function(e) {
    NULL;
  });

  # On success, return the surface.
  if(!is.null(res)){
    return(res);
  }

  # Failed, use the next read.ni.surface.* method
  NextMethod('read_nisurfacefile');
}


#' @title Read a gifti file as a surface.
#'
#' @param filepath character string, the full path to the input surface file.
#'
#' @param ... ignored
#'
#' @return an instance of `fs.surface`, read from the file. See \code{\link[freesurferformats]{read.fs.surface}} for details. If none of the reader methods succeed, an error is raised.
#'
#' @export
read_nisurfacefile.gifti <- function(filepath, ...) {
  if (requireNamespace("gifti", quietly = TRUE)) {
    # Try to read via gifti package
    res <- tryCatch({
      gifti::read_gifti(filepath);
    }, error = function(e) {
      NULL;
    }, warning = function(w) {
      NULL
    });

  } else {   # Won't work without the 'gifti' package
    res = NULL;
  }

  # On success, return the result as a surface.
  if(!is.null(res)){
    if(is.null(res$data$pointset) | is.null(res$data$triangle)) {
      # This is a GIFTI file, but it does not contain a mesh. Note that GIFTI can contain various data types. Maybe the user accidently passed a func GIFTI file.
      NextMethod('read_nisurfacefile');
    } else {
      ret_list = list("vertices"=res$data$pointset, "faces"=matrix(as.integer(res$data$triangle + 1L), ncol=3L), "mesh_face_type" = 'tris');
      class(ret_list) = c("fs.surface", class(ret_list));
      return(ret_list);
    }
  }

  # Failed, use the next read.ni.surface.* method
  NextMethod('read_nisurfacefile');
}

#' @export
read_nisurfacefile.default <- function(filepath, ...) {
  stop(sprintf("Surface file '%s' could not be read with any of the available methods, format invalid or not supported.\n", filepath));
}