add as_mat parameter to doapply.transform.mtx function

R/mghheader.R

@@ -669,6 +669,8 @@ surfaceras.to.talairach <- function(sras_coords, talairach, header_cras, first_v
 #'
 #' @param mtx a 4x4 numerical transformation matrix
 #'
+#' @param as_mat logical, whether to force the output coords into a matrix (even if the input was a vector/a single coordinate triple).
+#'
 #' @return the coords after applying the transformation. If coords was nx3, nx3 is returned, otherwise nx4.
 #'
 #' @examples
@@ -677,7 +679,7 @@ surfaceras.to.talairach <- function(sras_coords, talairach, header_cras, first_v
 #'     doapply.transform.mtx(coords_tf, solve(mni152reg()));
 #'
 #' @export
-doapply.transform.mtx <- function(coords, mtx) {
+doapply.transform.mtx <- function(coords, mtx, as_mat = FALSE) {
   if(is.vector(coords)) {
     coords = matrix(coords, nrow = 1L);
   }
@@ -699,13 +701,18 @@ doapply.transform.mtx <- function(coords, mtx) {
   if(was_cartesian) {
     transformed_coords = transformed_coords[,1:3] / transformed_coords[,4]; # convert from homogeneous to cartesian
   }
+  if(is.vector(transformed_coords)) {
+    if(as_mat) {
+      transformed_coords = matrix(transformed_coords, ncol = 3, byrow = TRUE);
+    }
+  }
   return(transformed_coords);
 }
 
 
-#' @title Get fsaverage to MNI 152 transformation matrix.
+#' @title Get fsaverage (MNI305) to MNI152 transformation matrix.
 #'
-#' @note There are better ways to achieve this transformation than using this matrix, see Wu et al., 'Accurate nonlinear mapping between MNI volumetric and FreeSurfer surface coordinate system', Hum Brain Mapp. 2018 Sep; 39(9): 3793–3808. doi: 10.1002/hbm.24213.
+#' @note There are better ways to achieve this transformation than using this matrix, see Wu et al., 'Accurate nonlinear mapping between MNI volumetric and FreeSurfer surface coordinate system', Hum Brain Mapp. 2018 Sep; 39(9): 3793–3808. doi: 10.1002/hbm.24213. The mentioned method is available in R from the 'regfusionr' package (GitHub only atom, not on CRAN).
 #'
 #' @examples
 #'     coords_tf = doapply.transform.mtx(c(1.0, 1.0, 1.0), mni152reg());