Advanced Visualization

library(vistool)
library(plotly)
library(purrr)
set.seed(1)

This vignette covers advanced visualization options, overlays, manual layers, and animations. It complements the core vignettes and focuses on fine control and composition.

Surface Visualization Options

You can customize the appearance using the theme system:

viz = as_visualizer(obj("TF_franke"), type = "surface")
viz$plot(theme = list(palette = "grayscale"))

The add_contours() method allows you to add custom contour lines to the surface:

llower = viz$objective$limits_lower
lupper = viz$objective$limits_upper
ssize = (lupper - llower) / 10

viz$add_contours(contours = list(
  y = list(show = TRUE, start = llower[2], end = lupper[2], size = ssize[2], color = "red")
))$plot(theme = list(palette = "grayscale"))

Setting the layout and scene

You can customize layout and scene directly in the plot() method:

viz = as_visualizer(obj("TF_franke"), type = "surface")
viz$plot(layout = list(
  title = list(text = "Custom Title", font = list(size = 20)),
  showlegend = TRUE
))

viz$plot(scene = list(camera = list(eye = list(x = 1.5, y = 1.5, z = 1.5))))

View presets via `set_scene()`

For repeated exploration, you can set camera presets using the helper method set_scene() and then render.

viz = as_visualizer(obj("TF_branin"), type = "surface")
# classic three-quarter view
viz$set_scene(x = 1.3, y = 1.2, z = 1.0)
viz$plot()

# top-down shallow angle
viz$set_scene(x = 0.7, y = 0.7, z = 2.0)
viz$plot()

Overlays: Taylor and Hessian

obj = obj("TF_banana")
# Use surface visualizer for Taylor/Hessian overlays
viz = as_visualizer(obj, type = "surface")

# Point of expansion (choose a point of interest)
x0 = c(0.85, 0.47)

# First-order Taylor plane with compact extent and visible grid contours
viz$add_taylor(
  x0,
  degree = 1,
  npoints_per_dim = 11,
  x1margin = 0.3,
  x2margin = 0.3,
  contours = list(
    x = list(show = TRUE, start = 0, end = 1, size = 0.03, color = "black"),
    y = list(show = TRUE, start = 0, end = 1, size = 0.03, color = "black")
  )
)

# Add Hessian eigen-directions anchored at x0
viz$add_hessian(x0, x1length = 0.25, x2length = 0.25)
viz$plot()

# Second-order Taylor surface (narrow z-limits for clarity)
viz2 = as_visualizer(obj, type = "surface")
viz2$add_taylor(
  x0,
  degree = 2,
  npoints_per_dim = 21,
  x1margin = 0.35,
  x2margin = 0.35,
  zlim = range(viz2$zmat, na.rm = TRUE)
)
viz2$add_hessian(x0, x1length = 0.25, x2length = 0.25)
viz2$plot()

Manual layers

You can extend the returned plot objects directly:

ggplot2: modify the ggplot result with standard layers and themes

viz2d = as_visualizer(obj("TF_franke"))
p = viz2d$plot(show_title = FALSE)
p + ggplot2::labs(title = "Franke Function") + ggplot2::theme_minimal()

plotly: add traces or update layout/scene

viz3d = as_visualizer(obj("TF_branin"), type = "surface")
p = viz3d$plot()
plotly::add_markers(p, x = c(0.5), y = c(0.5), z = c(0.0), name = "mark")

obj = obj("TF_banana")
viz = as_visualizer(obj, type = "surface")
viz$set_theme(vistool_theme(alpha = 0.5))
p = viz$plot()

# Create some synthetic points to overlay as 3D markers
nsim = 100
grid = data.frame(x = runif(nsim), y = runif(nsim))
grid$z = apply(grid, 1, viz$objective$eval) + rnorm(nsim, sd = 0.05)

# Add manual plotly layer on top of vistool’s plotly object
p %>% add_trace(
  data = grid, x = ~x, y = ~y, z = ~z, mode = "markers",
  type = "scatter3d",
  marker = list(symbol = "diamond", size = 3, color = "#2c7fb8", opacity = 0.7),
  name = "samples"
)

Animations

You can animate surface views and optimization traces. The code below creates frames and saves them as images; combine them into GIFs with ImageMagick. This may require kaleido for saving static images from plotly (see Getting Started). Heavy chunks are kept non-evaluated here.

obj = obj("TF_GoldsteinPriceLog")
oo = OptimizerGD$new(obj, x_start = c(0.22, 0.77), lr = 0.01)
oo$optimize(steps = 30)

viz = as_visualizer(obj, type = "surface")
viz$add_optimization_trace(oo)

dir.create("animation", showWarnings = FALSE)
viz$animate(
  dir = "animation",
  nframes = 20,
  view_start = list(x = 1.2, y = 1.2, z = 1.1),
  view_end   = list(x = 1.8, y = 1.4, z = 1.3),
  fext = "png",
  width = 600, height = 500
)

# Then assemble with ImageMagick, e.g.:
# convert -delay 15 -loop 0 animation/*.png optim.gif