R/plots.R

In deandevl/Rvisual3dPlot: Plot 3d Functions for R

#' Plot points in a 3d device window
#'
#' Function plots the 3d points in the current device window.  x, y, and z are vectors providing the
#' location of the points.  Options for point color and size along with labelling and axis options are provided.
#'
#' @param win_width,win_height An integer defining the dimensions of the plot window.
#' @param x,y,z A vector of numeric values defining the x, y, z location of each point to be plotted.
#' @param pt_color A character string defining the color of the points.
#' @param pt_size A numeric defining the size of the points in pixels.
#' @param bkg_color A character string defining the window background color.
#' @param draw_axis A logical which if TRUE draws the axes.
#' @param main_lab A character string defining the plot's main title.
#' @param x_lab,y_lab,z_lab A character string defining the axis labels.
#' @param axis_color A character string defining the axis color.
#' @param xlim,ylim,zlim An integer vector defining the min/max of an axis.
#' @param x_ticks,y_ticks,z_ticks An integer defining the number of ticks for an axis.
#' @param html_file A character string that defines the file path to creating an html of the plot.
#'
#' @import rgl
#'
#' @return  The device window id (an integer).
#'
#' @export
#'
plot_points <- function(
  win_width = 1000,
  win_height = 800,
  x, y, z,
  pt_color = "black",
  pt_size = 6.0,
  bkg_color = "white",
  draw_axis = TRUE,
  main_lab = NULL, x_lab = "X", y_lab = "Y", z_lab = "Z",
  axis_color="black",
  xlim = c(0,10),
  ylim = c(0,10),
  zlim = c(0,10),
  x_ticks = 11, y_ticks = 11, z_ticks = 11,
  html_file = NULL){

    if(Rvisual3dPlot::device_current() == 0) {
      device_id <- Rvisual3dPlot::device_new(bgrd_color = bkg_color, width=win_width, height=win_height)
    }

    rgl::rgl.points(x, z, y, color = pt_color, size = pt_size)

    if(draw_axis){
      # add axes
      rgl.lines(xlim, c(0,0), c(0,0), color=axis_color)
      rgl.lines(c(0,0), ylim, c(0,0), color=axis_color)
      rgl.lines(c(0,0), c(0,0), zlim, color=axis_color)

      # add axis ticks
      rgl::axis3d("x--", pos = c(NA,0,0), nticks = x_ticks, col = axis_color)
      rgl::axis3d("y--", pos = c(0,NA,0), nticks = y_ticks, col = axis_color)
      rgl::axis3d("z--", pos = c(0,0,NA), nticks = z_ticks, col = axis_color)

      rgl::title3d(main = main_lab, xlab = x_lab, ylab = z_lab, zlab = y_lab)
    }
    if(!is.null(html_file)) {
      writeWebGL(filename = html_file, width = win_width, height = win_height)
    }

    Rvisual3dPlot::device_current()
  }

#' Plots lines in a 3d device window
#'
#'
#' Function plots a collection of line segments where \code{lines} is a dataframe of 2n x 3 with pairs of
#' start/stop x, y, and z coordinates for n segements. Options are provided for sizing the device window,
#' width/color of the segments, and defining/labelling axis,
#'
#' @param win_width,win_height An integer defining the dimensions of the plot window.
#' @param lines A numeric 2n x 3 dataframe.
#' @param line_color A single character string defining a line's color.
#' @param line_width A numeric defining the width of the line segments.
#' @param bkg_color A character string defining the window background color.
#' @param draw_axis A logical which if TRUE draws the axes.
#' @param main_lab A character string defining the plot's main title.
#' @param x_lab,y_lab,z_lab A character string defining the axis labels.
#' @param axis_color A character string defining the axis color.
#' @param xlim,ylim,zlim An integer vector defining the min/max of an axis.
#' @param x_ticks,y_ticks,z_ticks An integer defining the number of ticks for an axis.
#' @param html_file A character string that defines the file path to creating an html of the plot.
#'
#' @return  The device window id (an integer).
#'
#' @export
#'
plot_lines <- function(
  win_width = 1000,
  win_height = 800,
  lines,
  line_color = "black",
  line_width = 2,
  bkg_color = "white",
  draw_axis = TRUE,
  main_lab = NULL, x_lab = "X", y_lab = "Y", z_lab = "Z",
  axis_color="black",
  xlim = c(0,10),
  ylim = c(0,10),
  zlim = c(0,10),
  x_ticks = 11, y_ticks = 11, z_ticks = 11,
  html_file = NULL){
    if(Rvisual3dPlot::device_current() == 0) {
      device_id <- Rvisual3dPlot::device_new(bgrd_color = bkg_color, width=win_width, height=win_height)
    }

    if(draw_axis){
      # add axes
      rgl.lines(xlim, c(0,0), c(0,0), color=axis_color)
      rgl.lines(c(0,0), ylim, c(0,0), color=axis_color)
      rgl.lines(c(0,0), c(0,0), zlim, color=axis_color)


      # add axis ticks
      rgl::axis3d("x--", pos = c(NA,0,0), nticks = x_ticks, col = axis_color)
      rgl::axis3d("y--", pos = c(0,NA,0), nticks = y_ticks, col = axis_color)
      rgl::axis3d("z--", pos = c(0,0,NA), nticks = z_ticks, col = axis_color)

      rgl::title3d(main = main_lab, xlab = x_lab, ylab = z_lab, zlab = y_lab)
    }

    lines_rev <- lines[,1]
    lines_rev[,2] <- lines[,3]
    lines_rev[,3] <- lines[,2]
    rgl::segments3d(lines_rev, col=line_color)

    if(!is.null(html_file)) {
      writeWebGL(filename = html_file, width = win_width, height = win_height)
    }

    Rvisual3dPlot::device_current()
  }