From 96048b73d6bd54118d361bd15cfbee36e2b82947 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tim=20Sch=C3=A4fer?= <ts+code@rcmd.org>
Date: Thu, 20 May 2021 17:53:42 +0200
Subject: [PATCH] add as_mat parameter to doapply.transform.mtx function

---
 R/mghheader.R                | 13 ++++++++++---
 man/closest.vert.to.point.Rd |  2 +-
 man/doapply.transform.mtx.Rd |  4 +++-
 man/mni152reg.Rd             |  6 +++---
 4 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/R/mghheader.R b/R/mghheader.R
index d3fffd3..a2d50ba 100644
--- a/R/mghheader.R
+++ b/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());
diff --git a/man/closest.vert.to.point.Rd b/man/closest.vert.to.point.Rd
index 60b22b9..4a86242 100644
--- a/man/closest.vert.to.point.Rd
+++ b/man/closest.vert.to.point.Rd
@@ -12,7 +12,7 @@ closest.vert.to.point(surface, point_coords)
 \item{point_coords}{nx3 matrix of query coords. If a vector, will be transformed \code{byrow} to such a matrix.}
 }
 \value{
-named list with entries: 'vertex_id' integer vector, the index of the closest vertex, and 'dist': double vector, the Euclidian distance to that vertex.
+named list with entries: 'vertex_id' integer vector, the index of the closest vertex, and 'dist': double vector, the Euclidean distance to that vertex.
 }
 \description{
 Find vertex index closest to given query coordinate using Euclidean distance.
diff --git a/man/doapply.transform.mtx.Rd b/man/doapply.transform.mtx.Rd
index 5735999..2c6abd2 100644
--- a/man/doapply.transform.mtx.Rd
+++ b/man/doapply.transform.mtx.Rd
@@ -4,12 +4,14 @@
 \alias{doapply.transform.mtx}
 \title{Apply a spatial transformation matrix to the given coordinates.}
 \usage{
-doapply.transform.mtx(coords, mtx)
+doapply.transform.mtx(coords, mtx, as_mat = FALSE)
 }
 \arguments{
 \item{coords}{nx3 (cartesian) or nx4 (homogeneous) numerical matrix, the input coordinates. If nx4, left as is for homogeneous notation, if nx3 (cartesian) a 1 will be appended as the 4th position.}
 
 \item{mtx}{a 4x4 numerical transformation matrix}
+
+\item{as_mat}{logical, whether to force the output coords into a matrix (even if the input was a vector/a single coordinate triple).}
 }
 \value{
 the coords after applying the transformation. If coords was nx3, nx3 is returned, otherwise nx4.
diff --git a/man/mni152reg.Rd b/man/mni152reg.Rd
index 25589f5..cfdcd13 100644
--- a/man/mni152reg.Rd
+++ b/man/mni152reg.Rd
@@ -2,15 +2,15 @@
 % Please edit documentation in R/mghheader.R
 \name{mni152reg}
 \alias{mni152reg}
-\title{Get fsaverage to MNI 152 transformation matrix.}
+\title{Get fsaverage (MNI305) to MNI152 transformation matrix.}
 \usage{
 mni152reg()
 }
 \description{
-Get fsaverage to MNI 152 transformation matrix.
+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.
+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());