Update surface_dist docs to make it clear these are all Euclidean dis…

…tances

R/surface_dist.R

@@ -1,5 +1,6 @@
+# Functions for computing Euclidian distance between vertex coordinates.
 
-#' @title Find vertex index closest to given query coordinate.
+#' @title Find vertex index closest to given query coordinate using Euclidean distance.
 #'
 #' @param surface an fs.surface instance or a nx3 numerical matrix representing mesh points.
 #'
@@ -51,42 +52,61 @@ closest.vert.to.point <- function(surface, point_coords) {
 }
 
 
-#' @title Compute Euclidian distance from all mesh vertices to given point.
+#' @title Compute Euclidean distance from all mesh vertices to given point.
 #'
 #' @param surface an fs.surface instance
 #'
 #' @param point_coords double vector of length 3, the xyz coords of a single point.
 #'
 #' @return double vector of distances
 vertexdists.to.point <- function(surface, point_coords) {
+  assert.surface(surface);
   return(apply(surface$vertices, 1, euclidian.dist, point_coords));
 }
 
 
-#' @title Compute Euclidian distance.
+#' @title Compute Euclidean distance.
 #'
 #' @param x1 numerical vector, coords of first point
 #'
 #' @param x2 numerical vector, coords of second point
 #'
-#' @return the Euclidian distance between x1 and x2.
+#' @return the Euclidean distance between x1 and x2.
 #'
 #' @keywords internal
 euclidian.dist <- function(x1, x2) sqrt(sum((x1 - x2) ^ 2))
 
 
-#' @title Compute Euclidian distance between two vertices v1 and v2.
+#' @title Stop unless surf is an fs.surface
+#'
+#' @param surf fs.surface instance or anything else
+#'
+#' @param param_name character string, used in stop message to identify the parameter.
+#'
+#' @return Called for the side effect of stopping if surf is not an fs.surface instance.
+#'
+#' @keywords internal
+assert.surface <- function(surface, param_name="surface") {
+  if(! is.fs.surface(surface)) {
+    stop(sprintf("Parameter '%s' must be an fs.surface instance.", param_name));
+  }
+  return(invisible(NULL));
+}
+
+
+#' @title Compute Euclidean distance between two vertices v1 and v2.
 #'
 #' @param surface an fs.surface instance
 #'
 #' @param v1 positive integer, vertex index of v1
 #'
 #' @param v2 positive integer, vertex index of v2
 #'
-#' @return double, the Euclidian distance between v1 and v2.
+#' @return double, the Euclidean distance between v1 and v2.
 #'
 #' @export
 vertex.euclid.dist <- function(surface, v1, v2) {
+  assert.surface(surface);
   euclidian.dist(surface$vertices[v1, ], surface$vertices[v2, ])
 }