R/rotate3d.R

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

# I guess there are some standard R functions for these.

#' @title Rotate a 2D matrix in 90 degree steps.
#'
#' @param slice a 2D matrix
#'
#' @param degrees integer, must be a (positive or negative) multiple of 90
#'
#' @return 2D matrix, the rotated matrix
#'
#' @export
rotate2D <- function(slice, degrees=90) {
  if(length(dim(slice)) != 2L) {
    if(is.vector(slice)) {
      return(slice); # return vector as is
    } else {
      stop("Slice must be a 2D matrix.");
    }
  }
  degrees = as.integer(degrees %% 360L);
  if(!degrees %in% as.integer(c(0, 90, 180, 270))) {
    stop("Parameter 'degrees' must be a multiple of 90 (it can be negative).");
  }
  if(degrees == 0L) {
    return(slice);
  } else if(degrees == 270) {
    return(rotate90(slice, times=1L, clockwise=FALSE));
  } else if(degrees == 180) {
    return(rotate90(slice, times=2L));
  } else {  # 90
    return(rotate90(slice));
  }
}


#' @title Rotate 2D matrix clockwise in 90 degree steps.
#'
#' @param mtx a 2D matrix
#'
#' @param times integer, how often to rotate in 90 degree steps. Example: pass `3L` to rotate `270` degrees.
#'
#' @param clockwise logical, whether to rotate clockwise.
#'
#' @keywords internal
rotate90 <- function(mtx, times=1L, clockwise=TRUE) {
  for(i in seq_len(times)) {
    if(clockwise) {
      mtx = t(apply(mtx, 2, rev));
    } else {
      mtx = apply(t(mtx), 2, rev);
    }
  }
  return(mtx);
}


#' @title Rotate a 3D array in 90 degree steps.
#'
#' @description Rotate a 3D array in 90 degree steps along an axis. This leads to an array with different dimensions.
#'
#' @param volume a 3D image volume
#'
#' @param axis positive integer in range 1L..3L or an axis name, the axis to use.
#'
#' @param degrees integer, must be a (positive or negative) multiple of 90L.
#'
#' @return a 3D image volume, rotated around the axis. The dimensions may or may not be different from the input image, depending on the rotation angle.
#'
#' @family volume math
#'
#' @export
rotate3D <- function(volume, axis=1L, degrees=90L) {
  if(length(dim(volume)) != 3) {
    stop(sprintf("Volume must have exactly 3 dimensions but has %d.\n", length(dim(volume))));
  }
  if(! is.numeric(axis)) {
    stop("Parameter 'axis' must be numeric.");
  }
  axis = as.integer(axis);
  if(axis < 1L | axis > 3L) {
    stop(sprintf("Axis must be integer with value 1, 2 or 3 but is %d.\n", axis));
  }
  dim1 = dim(volume)[1];
  dim2 = dim(volume)[2];
  dim3 = dim(volume)[3];
  num_voxels = dim1 * dim2 * dim3;

  degrees = as.integer(degrees);

  if(abs(degrees) %in% c(90L, 270L)) {
    if(axis == 1L) {
      new_dim = c(dim1, dim3, dim2);
    } else if (axis == 2L) {
      new_dim = c(dim3, dim2, dim1);
    } else {
      new_dim = c(dim2, dim1, dim3);
    }
  } else {
    new_dim = dim(volume);
  }

  rotbrain = array(rep(0L, num_voxels), new_dim);

  if(axis == 1L) {
    for(ax1_idx in seq_len(dim1)) {
      rotbrain[ax1_idx,,] = rotate2D(volume[ax1_idx,,], degrees = degrees);
    }
  } else if (axis == 2L) {
    for(ax2_idx in seq_len(dim2)) {
      rotbrain[,ax2_idx,] = rotate2D(volume[,ax2_idx,], degrees = degrees);
    }
  } else {
    for(ax3_idx in seq_len(dim3)) {
      rotbrain[,,ax3_idx] = rotate2D(volume[,,ax3_idx], degrees = degrees);
    }
  }
  return(rotbrain);
}


#' @title Flip a 3D array along an axis.
#'
#' @description Flip the slice of an 3D array horizontally or vertically along an axis. This leads to an output array with identical dimensions.
#'
#' @param volume a 3D image volume
#'
#' @param axis positive integer in range 1L..3L or an axis name, the axis to use.
#'
#' @param how character string, one of 'horizontally' / 'h' or 'vertically' / 'v'. How to flip the 2D slices. Note that flipping *horizontally* means that the image will be mirrored along the central *vertical* axis.
#'
#' @return a 3D image volume, flipped around the axis. The dimensions are identical to the dimensions of the input image.
#'
#' @family volume math
#'
#' @export
flip3D <- function(volume, axis=1L, how='horizontally') {
  if(length(dim(volume)) != 3) {
    stop(sprintf("Volume must have exactly 3 dimensions but has %d.\n", length(dim(volume))));
  }
  axis = as.integer(axis);
  if(axis < 1L | axis > 3L) {
    stop(sprintf("Axis must be integer with value 1, 2 or 3 but is %d.\n", axis));
  }
  dim1 = dim(volume)[1];
  dim2 = dim(volume)[2];
  dim3 = dim(volume)[3];
  num_voxels = dim1 * dim2 * dim3;

  flipped_brain = array(rep(0L, num_voxels), dim(volume));

  if(axis == 1L) {
    for(ax1_idx in seq_len(dim1)) {
      flipped_brain[ax1_idx,,] = flip2D(volume[ax1_idx,,], how = how);
    }
  } else if (axis == 2L) {
    for(ax2_idx in seq_len(dim2)) {
      flipped_brain[,ax2_idx,] = flip2D(volume[,ax2_idx,], how = how);
    }
  } else {
    for(ax3_idx in seq_len(dim3)) {
      flipped_brain[,,ax3_idx] = flip2D(volume[,,ax3_idx], how = how);
    }
  }
  return(flipped_brain);
}


#' @title Flip a 2D matrix.
#'
#' @param slice a 2D matrix
#'
#' @param how character string, one of 'vertically' / 'v' or 'horizontally' / 'h'. Note that flipping *horizontally* means that the image will be mirrored along the central *vertical* axis. If `NULL` is passed, the passed value is returned unaltered.
#'
#' @return 2D matrix, the flipped matrix.
#'
#' @export
flip2D <- function(slice, how='horizontally') {
  if(is.null(how)) {
    return(slice);
  }

  if(how == 'vertically' | how == 'v') {
    axis = 2L;
  } else if(how == 'horizontally' | how == 'h') {
    axis = 1L;
  } else {
    stop("How must be one of 'vertically' or 'horizontally' (or NULL for noop).");
  }

  if(length(dim(slice)) != 2L) {
    if(is.vector(slice)) {
      return(slice); # return vector as is
    } else {
      stop("Slice must be a 2D matrix.");
    }
  }
  if(axis == 1L) {
    return(slice[nrow(slice):1,]);
  } else {
    return(slice[, ncol(slice):1]);
  }
}