R/devices.R

In deandevl/Rvisual3dPlot: Plot 3d Functions for R

#' Create a new 3d device window.
#'
#'
#' Function creates a new window with options for background color, size, camera angles, field of view angle,
#' and zoom.
#'
#'
#' @import rgl
#'
#' @param bgrd_color The String background color of the window. Default is "white".
#' @param width The integer width of the window in pixels. The default is 640.
#' @param height The integer height of the window in pixels. The default is 640.
#' @param vp_theta The rotation of the camera. The default is 0.
#' @param vp_phi The rotation of the camera. The default is 15.
#' @param vp_fov The field of view angle. The default is 60.
#' @param vp_zoom The degree of zoom for the camera. The default is 1.
#'
#' @return The newly created integer id for the device window.
#'
#' @export
#'
device_new <- function(bgrd_color="white", width=640, height=640, vp_theta=0, vp_phi=15, vp_fov=60, vp_zoom=1){
  rgl::rgl.open()
  rgl::rgl.bg(color = bgrd_color)
  rgl::par3d(windowRect = 50 + c(0, 0, width, height))
  rgl::rgl.viewpoint(theta = vp_theta, phi = vp_phi, fov = vp_fov, zoom = vp_zoom)
  rgl::rgl.cur()
}

#' Clear an object associated with the window.
#'
#' Function clears specific types of objects from the device window including "shapes", "bboxdeco", "lights", "background".
#'
#'
#' @param clear_types A character vector that specifies the types of
#' objects to clear. Accepted values for the vector include: "shapes", "bboxdeco", "lights", "background".
#' The default is all 4 types are specified.
#'
#' @export
#'
device_clear <- function(clear_types = c("shapes", "bboxdeco", "lights", "background")){
  if(rgl.cur() != 0L & is.vector(clear_types)){
    rgl::rgl.clear(type = clear_types)
  }
}

#' Close the device window.
#'
#' Function closes the current device window.  See 'device_current()' function for setting the current window.
#'
#' @export
#'
device_close <- function(){
  if(rgl::rgl.cur() != 0L){
    rgl::rgl.close()
  }
}

#' Get a list of all device window ids.
#'
#'
#' Function returns a list of all created windows with their respective device id's.
#'
#'
#' @return Returns a list of all the integer ids of the created windows.
#'
#' @export
#'
device_list <- function(){
  rgl::rgl.dev.list()
}

#' Set or return the integer id of the current window.
#'
#'
#' Function is used to set a specific window as 'current' or return the id of the 'current' window.
#' In setting the id, the value is checked for existence among the list of window id's.
#'
#'
#' @param id If defined then sets the current device window to 'id'.
#'
#' @return If id is undefined, returns the current device id among one or more device windows.
#'
#' @export
#'
device_current <- function(id){
  if(!missing(id)){
    if(id %in% rgl::rgl.dev.list()) {
      rgl::rgl.set(id)
    }
  }else {
    rgl::rgl.cur()
  }
}