\documentclass[article,nojss]{jss}
\DeclareGraphicsExtensions{.pdf,.eps,.png}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Add-on packages and fonts
\usepackage{graphicx}
\usepackage{amsmath}


\newcommand{\noun}[1]{\textsc{#1}}
%% Bold symbol macro for standard LaTeX users
\providecommand{\boldsymbol}[1]{\mbox{\boldmath $#1$}}

%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
\newcommand{\p}{\textbf{\textsf{plot3D }}}
\newcommand{\R}{\proglang{R}}
\title{
  Fifty ways to draw a volcano using package \p.
}
\Plaintitle{Fifty ways to draw a volcano using package plot3D}

\Keywords{
  volcano, 3D plots, 2D plots, \proglang{R}
}

\Plainkeywords{
  volcano, 3D plots, 2D plots, R
}


\author{Karline Soetaert\\
NIOZ-Yerseke\\
The Netherlands
}

\Plainauthor{Karline Soetaert}

\Abstract{
  There must be more than 50 ways to draw the volcano data set from R,
  using R-package plot3D \citep{plot3D}.
}

%% The address of (at least) one author should be given
%% in the following format:
\Address{
  Karline Soetaert\\
  Royal Netherlands Institute of Sea Research (NIOZ)\\
  4401 NT Yerseke, Netherlands\\
  E-mail: \email{karline.soetaert@nioz.nl}\\
  URL: \url{http://http://www.nioz.nl/}\\
}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% R/Sweave specific LaTeX commands.
%% need no \usepackage{Sweave}
%\VignetteIndexEntry{Fifty ways to draw a volcano}
%\VignetteKeywords{2D plots, 3D plots, volcano, plot3D}
%\VignettePackage{plot3D}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Begin of the document
\begin{document}
\SweaveOpts{engine=R,eps=FALSE,resolution = 100}
\SweaveOpts{keep.source=TRUE}

<<preliminaries,echo=FALSE,results=hide>>=
library(plot3D)
options(prompt = " ")
options(continue = "  ")
options(width=75)
@

\maketitle

\section{Intro}
To make this vignette smaller, the size of \code{volcano} is reduced:
<<>>=
# Reduce the resolution
Volcano <- volcano[seq(1, nrow(volcano), by = 3), 
                   seq(1, ncol(volcano), by = 3)]
@
\section{Images and contours}

<<label=imagecontour,include=FALSE>>=
par(mfrow = c(3, 3), mar = c(3, 3, 3, 2))
contour2D(Volcano, lwd = 2, colkey = FALSE)
contour2D(Volcano, lwd = 2)
image2D(Volcano, clab = "m")
image2D(Volcano, shade = 0.4)
image2D(Volcano, facets = FALSE)
image2D(Volcano, contour = TRUE)
image2D(Volcano, rasterImage = TRUE, contour = list(lwd = 2, col = jet.col(11)))
image2D(Volcano, theta = 30, NAcol = "black")
image2D(Volcano, lighting = TRUE, rasterImage = TRUE,
   contour = list(col = "white", labcex = 0.8, lwd = 3, alpha = 0.5))
@

\setkeys{Gin}{width=1.0\textwidth}
\begin{figure}
\begin{center}
<<label=imagecontour,fig=TRUE,echo=FALSE, pdf = FALSE, png = TRUE>>=
<<imagecontour>>
@
\end{center}
\caption{The image2D and contour2D function}
\label{fig:imagecontour}
\end{figure}
\clearpage
\section{persp3D}

<<label=persp,include=FALSE>>=
par(mfrow = c(3, 3), mar = c(2, 2, 2, 2))
persp(Volcano)
persp(Volcano, theta = 40, phi = 40, col = "gold", border = NA, shade = 0.5)
persp3D(z = Volcano, clab = "m")
persp3D(z = Volcano, clab = "m", shade = 0.2)
persp3D(z = Volcano, facets = FALSE)
persp3D(z = Volcano, facets = FALSE, curtain = TRUE)
persp3D(z = Volcano, col = "white", shade = 0.5)
persp3D(z = Volcano, col = ramp.col(c("white", "black")), border = "black")
persp3D(z = Volcano, facets = FALSE, col = "darkblue")
@

\setkeys{Gin}{width=1.0\textwidth}
\begin{figure}
\begin{center}
<<label=persp,fig=TRUE,echo=FALSE, pdf = FALSE, png = TRUE>>=
<<persp>>
@
\end{center}
\caption{The persp3D function}
\label{fig:persp}
\end{figure}

\clearpage
\section{Backgrounds and axes annotations}

<<label=bty,include=FALSE>>=
par(mfrow = c(3, 3), mar = c(1, 1, 1, 1))
persp3D(z = Volcano, col = "lightblue", shade = 0.5)
persp3D(z = Volcano, col = "lightblue", shade = 0.5, box = FALSE)
persp3D(z = Volcano, col = "lightblue", shade = 0.5, ticktype = "detailed")
persp3D(z = Volcano, col = "lightblue", shade = 0.5, bty = "f")
persp3D(z = Volcano, col = "lightblue", shade = 0.5, bty = "b2")
persp3D(z = Volcano, col = "lightblue", shade = 0.5, bty = "g")
persp3D(z = Volcano, col = "lightblue", shade = 0.5, bty = "bl2")
persp3D(z = Volcano, col = "lightblue", shade = 0.5, bty = "u",
      col.panel = "yellow", col.grid = "grey")
persp3D(z = Volcano, col = "lightblue", shade = 0.5,
      ticktype = "detailed", bty = "b2")
@

\setkeys{Gin}{width=1.0\textwidth}
\begin{figure}
\begin{center}
<<label=bty,fig=TRUE,echo=FALSE, pdf = FALSE, png = TRUE>>=
<<bty>>
@
\end{center}
\caption{The box types}
\label{fig:bty}
\end{figure}


\clearpage
\section{View and shading perspectives}

<<label=view,include=FALSE>>=
par(mfrow = c(3, 3), mar = c(1, 1, 1, 1))
x <- 1:nrow(Volcano)
y <- 1:ncol(Volcano)
persp3D(x, y , z = Volcano, col = "lightblue", scale = FALSE,
      shade = 0.5, expand = 0.25)
persp3D(x, y , z = Volcano, col = "lightblue", scale = FALSE,
      shade = 0.5, expand = 0.25, d = 0.1)
persp3D(x, y , z = Volcano, col = "lightblue", scale = FALSE,
      shade = 0.5, expand = 0.25, d = 10)
persp3D(x, y , z = Volcano, col = "lightblue", scale = FALSE,
      shade = 0.5, expand = 0.25, r = 0)
persp3D(x, y , z = Volcano, col = "lightblue", scale = FALSE,
      shade = 0.5, expand = 0.25, r = 10)
persp3D(x, y , z = Volcano, col = "lightblue", scale = FALSE,
      shade = 0.5, expand = 0.25, theta = -10)
persp3D(x, y, z = Volcano, col = "lightblue", scale = FALSE,
      shade = 0.5, expand = 0.25, phi = 10)
persp3D(x, y , z = Volcano, col = "lightblue", scale = FALSE,
      shade = 0.5, expand = 0.25, ltheta = 10)
persp3D(x, y , z = Volcano, col = "lightblue", scale = FALSE,
      shade = 0.5, expand = 0.25, lphi = 90)
@

\setkeys{Gin}{width=1.0\textwidth}
\begin{figure}
\begin{center}
<<label=view,fig=TRUE,echo=FALSE, pdf = FALSE, png = TRUE>>=
<<view>>
@
\end{center}
\caption{The views}
\label{fig:view}
\end{figure}

\clearpage
\section{Ribbons and histograms}

<<label=alt,include=FALSE>>=
par(mfrow = c(2, 2), mar = c(2, 2, 2, 2))
ix <- seq(1, nrow(Volcano), length.out = 20)
iy <- seq(1, ncol(Volcano), length.out = 20)

ribbon3D(z = Volcano[, iy])
ribbon3D(z = Volcano[ix, ], along = "y", 
  curtain = TRUE, space = 0.8, shade = 0.2)
ribbon3D(z = Volcano[ix, iy], along = "xy")
hist3D(z = Volcano[ix,iy], shade = 0.5)
@

\setkeys{Gin}{width=1.0\textwidth}
\begin{figure}
\begin{center}
<<label=alt,fig=TRUE,echo=FALSE, pdf = FALSE, png = TRUE>>=
<<alt>>
@
\end{center}
\caption{ribbons and histograms}
\label{fig:alt}
\end{figure}

\clearpage
\section{Color keys}

<<label=key,include=FALSE>>=
par(mfrow = c(2, 2), mar = c(2, 2, 2, 2))
persp3D(z = Volcano/1000, log = "c", clab = c("km (logscale)"))
persp3D(z = Volcano, clab = "m",
      colkey = list(side = 3, length = 0.5, width = 0.5, cex.axis = 0.8))
persp3D(z = Volcano, clab = c("height", "m"),
      colkey = list(length = 0.5, shift = -0.1))
par(mar = c(4, 4, 2, 2))
image2D(z = Volcano, clab = "height, m",
      colkey = list(dist = -0.20, shift = 0.15,
      side = 3, length = 0.5, width = 0.5,
      cex.clab = 1.2, col.clab = "white", line.clab = 2, 
      col.axis = "white", col.ticks = "white", cex.axis = 0.8))
@

\setkeys{Gin}{width=1.0\textwidth}
\begin{figure}
\begin{center}
<<label=key,fig=TRUE,echo=FALSE, pdf = FALSE, png = TRUE>>=
<<key>>
@
\end{center}
\caption{colorkeys}
\label{fig:key}
\end{figure}

\clearpage
\section{Combined persp3D and image or contour}

<<label=comb,include=FALSE>>=
par(mfrow = c(2, 2), mar = c(2, 2, 2, 2))

ribbon3D(z = Volcano, zlim = c(-100, 200), image = TRUE)
persp3D(z = Volcano, zlim = c(-100, 200), contour = TRUE)
persp3D(z = Volcano, zlim= c(-200, 200), phi = 30,
      contour = list(nlevels = 20, col = "red"),
      image = list(col = grey (seq(0, 1, length.out = 100))))
persp3D(z = Volcano, contour = list(side = c("zmax", "z")), zlim= c(90, 300),
      phi = 30, theta = 20, d = 10, box = FALSE)
@

\setkeys{Gin}{width=1.0\textwidth}
\begin{figure}
\begin{center}
<<label=comb,fig=TRUE,echo=FALSE, pdf = FALSE, png = TRUE>>=
<<comb>>
@
\end{center}
\caption{combined persp3D and image2D}
\label{fig:comb}
\end{figure}

\clearpage
\section{Two more to go}
\subsection{A composite complex one}
<<label=panel,include=FALSE>>=

par(mfrow = c(2, 1), mar = c(2, 2, 2, 2))
## ======================================================================
##  A composite figure
## ======================================================================
 x <- 1:nrow(Volcano)
 y <- 1:ncol(Volcano)
  
# draw the volcano, with contours at bottom 
 persp3D (x, y, z = Volcano, theta = 10, phi = 20, box = FALSE, 
          scale = FALSE, expand = 0.3, contour = TRUE, 
          zlim = c(50, 200), clim = range(volcano), plot = FALSE)

# add a plane (image) at z = 170; jetcolored, transparant: only border
 image3D(x, y, z = 170, add = TRUE, clim = range(volcano),
         colvar = Volcano, colkey = FALSE, facets = NA, plot = FALSE)

# add a contour (image) at z = 170; jetcolored, 
 contour3D(x, y, z = 170, add = TRUE, clim = range(volcano), lwd = 3,
           colvar = Volcano, colkey = FALSE, plot = TRUE)

## ======================================================================
## Drawing on panels
## ======================================================================
x <- 1 : nrow(Volcano)
y <- 1 : ncol(Volcano)

# A function that is called after the axes were drawn
panelfirst <- function(pmat) {
  XY <- trans3D(x = rep(1, ncol(Volcano)), y = y,
                z = Volcano[10,], pmat = pmat)
  scatter2D(XY$x, XY$y, colvar = Volcano[10,],
          type = "l", lwd = 3, add = TRUE, colkey = FALSE)

  XY <- trans3D(x = x, y = rep(ncol(Volcano), nrow(Volcano)),
                z = Volcano[,10], pmat = pmat)
  scatter2D(XY$x, XY$y, colvar = Volcano[,10],
          type = "l", lwd = 3, add = TRUE, colkey = FALSE)
}

pmat <- persp3D(z = Volcano, x = x, y = y, scale = FALSE, theta = 30,
      expand = 0.1, panel.first = panelfirst, colkey = FALSE)

XY <- trans3D(x = rep(10, ncol(Volcano)), y = y, z = Volcano[10,], 
  pmat = pmat)
lines(XY, lwd = 2, lty = 3)

XY <- trans3D(x = x, y = rep(10, nrow(Volcano)), z = Volcano[,10], 
  pmat = pmat)
lines(XY, lwd = 2, lty = 3)
@

\setkeys{Gin}{width=1.0\textwidth}
\begin{figure}
\begin{center}
<<label=panel,fig=TRUE,echo=FALSE, height = 8, width = 6, pdf = FALSE, png = TRUE>>=
<<panel>>
@
\end{center}
\caption{}
\label{fig:complex ones}
\end{figure}

\clearpage
\bibliography{vignettes}

\end{document}
