Add format parameter to write.fs.surface, update vignette and docs

CHANGES

@@ -5,7 +5,11 @@ freesurferformats Changes
 Version 0.1.9
 -------------
 - Add support for reading brain surface meshes in VTK ASCII file format
-- Add support for reading morph data from text files with one value per line
+- Add support for writing brain surface meshes in VTK ASCII file format
+- Add 'format' parameter to write.fs.surface, the function can now derive the format from the filename like similar functions
+- Add support for reading morph data from text files with one numeric value per line (.txt format)
+- Minor improvements to the vignette
+
 
 Version 0.1.8
 -------------

NAMESPACE

@@ -15,7 +15,6 @@ export(download_optional_data)
 export(fs.get.morph.file.ext.for.format)
 export(fs.get.morph.file.format.from.filename)
 export(fs.patch)
-export(fs.volume.from.oro.nifti)
 export(get_optional_data_filepath)
 export(is.fs.annot)
 export(is.fs.label)

R/mgh2nii.R

@@ -24,7 +24,7 @@
 #'    fsvolume = fs.volume.from.oro.nifti(nii_img);
 #' }
 #'
-#'@export
+#' @keywords internal
 fs.volume.from.oro.nifti <- function(nifti_img) {
 
   if (requireNamespace("oro.nifti", quietly = TRUE)) {
@@ -110,6 +110,7 @@ fs.volume.from.oro.nifti <- function(nifti_img) {
 
     ico7_num_vertices = 163842L; # Vertex count of ICO 7 meshes, like fsaverage. If the dimensions match this, the file is assumed to
     #                              contain morphometry data stored with the FreeSurfer hack.
+    # It is very unlikely though that oro.nifti would accept such data, so this will most likely never happen.
     is_ico7 = (ncols * nifti_img@dim_[3] * nifti_img@dim_[4] == ico7_num_vertices);
 
     ico7_state_string = ifelse(is_ico7, "looks like", "does NOT look like");

R/read_fs_surface.R

@@ -122,7 +122,7 @@ read.fs.surface.vtk <- function(filepath) {
 #' @export
 read.fs.surface <- function(filepath, format='auto') {
 
-  if(!(format %in% c('auto', 'bin', 'asc'))) {
+  if(!(format %in% c('auto', 'bin', 'asc', 'vtk'))) {
     stop("Format must be one of c('auto', 'bin', 'asc').");
   }
 

R/write_fs_surface.R

@@ -9,6 +9,8 @@
 #'
 #' @param faces n x 3 matrix of integers. Each row defined the 3 vertex indices that make up the face. WARNING: Vertex indices should be given in R-style, i.e., the index of the first vertex is 1. However, they will be written in FreeSurfer style, i.e., all indices will have 1 substracted, so that the index of the first vertex will be zero.
 #'
+#' @param format character string, the format to use. One of 'bin' for FreeSurfer binary surface format, 'asc' for FreeSurfer ASCII format, 'vtk' for VTK ASCII legacy format, or 'auto' to derive the format from the file extension given in parameter 'filepath'. With 'auto', a path ending in '.asc' is interpreted as 'asc', a path ending in '.vtk' as vtk, and everything else as 'bin'.
+#'
 #' @return string the format that was written. One of "tris" or "quads". Currently only triangular meshes are supported, so always 'tris'.
 #'
 #' @family mesh functions
@@ -25,10 +27,23 @@
 #' }
 #'
 #' @export
-write.fs.surface <- function(filepath, vertex_coords, faces) {
-  TRIS_MAGIC_FILE_TYPE_NUMBER = 16777214;
-  OLD_QUAD_MAGIC_FILE_TYPE_NUMBER = 16777215;
-  NEW_QUAD_MAGIC_FILE_TYPE_NUMBER = 16777213;
+write.fs.surface <- function(filepath, vertex_coords, faces, format='auto') {
+
+  if(!(format %in% c('auto', 'bin', 'asc', 'vtk'))) {
+    stop("Format must be one of c('auto', 'bin', 'asc', 'vtk').");
+  }
+
+  if(format == 'asc' | (format == 'auto' & filepath.ends.with(filepath, c('.asc')))) {
+    return(write.fs.surface.asc(filepath, vertex_coords, faces));
+  }
+
+  if(format == 'vtk' | (format == 'auto' & filepath.ends.with(filepath, c('.vtk')))) {
+    return(write.fs.surface.vtk(filepath, vertex_coords, faces));
+  }
+
+  TRIS_MAGIC_FILE_TYPE_NUMBER = 16777214L;
+  OLD_QUAD_MAGIC_FILE_TYPE_NUMBER = 16777215L;
+  NEW_QUAD_MAGIC_FILE_TYPE_NUMBER = 16777213L;
 
   num_faces_with_index_zero = sum(faces==0);
   if(num_faces_with_index_zero > 0) {