README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

RGL - 3D visualization device system for R using OpenGL
=======================================================

```{r include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README"
)

suppressPackageStartupMessages(library(rgl))

options(rgl.useNULL = TRUE)

if (!requireNamespace("rmarkdown", quietly = TRUE)) {
  warning(call. = FALSE, "These vignettes assume rmarkdown.  This was not found.")
  knitr::knit_exit()
}
setupKnitr(autoprint = TRUE)
```

```{r polyhedra, fig.height=1.5, echo = FALSE}
hcl.colors <- rgl:::hcl.colors  # might be cm.colors on old R
col <- hcl.colors(5)
mfrow3d(1,5)
shade3d(icosahedron3d(), col = col[1])
next3d()
shade3d(dodecahedron3d(), col = col[2])
next3d()
shade3d(octahedron3d(), col = col[3])
next3d()
shade3d(cube3d(), col = col[4])
next3d()
shade3d(tetrahedron3d(), col = col[5])
```

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/rgl)](https://CRAN.R-project.org/package=rgl)
[![R-CMD-check](https://github.com/dmurdoch/rgl/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/dmurdoch/rgl/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

INTRODUCTION
------------
The RGL package is a visualization device system for R, using 
OpenGL or WebGL as the rendering backend. An OpenGL rgl device 
at its core is a real-time 3D engine written in C++. It provides an 
interactive viewpoint navigation facility (mouse + wheel support)
and an R programming interface.  WebGL, on the other hand, is
rendered in a web browser; rgl produces the input file, and the 
browser shows the images.

WEBSITE
-------

A `pkgdown` website is here:

 https://dmurdoch.github.io/rgl/
 
The unreleased development version website is here:

 https://dmurdoch.github.io/rgl/dev/
 
See [this vignette](https://dmurdoch.github.io/rgl/dev/articles/pkgdown.html)
for details on producing your own `pkgdown` website that
includes `rgl` graphics.

The currently active development site is here:

 https://github.com/dmurdoch/rgl

INSTALLATION
------------

Most users will want to install the latest CRAN release.
For Windows, macOS and some Linux platforms, installation can 
be easy, as CRAN distributes binary versions:

```
# Install latest release from CRAN
install.packages("rgl")
```

To install the latest development version from Github, 
you'll need to do a source install.  Those aren't easy!
Try

```
# Install development version from Github
remotes::install_github("dmurdoch/rgl")
```

If that fails, read the instructions below.

Currently installs are tested on older R versions 
back to R 3.5.x, but this version of `rgl` may work
back as far as R 3.3.0.


LICENSE
-------
The software is released under the GNU Public License. 
See [COPYING](./COPYING) for details.


FEATURES
--------
- portable R package using OpenGL (if available) on macOS, Win32 and X11
- can produce 3D graphics in web pages using WebGL
- R programming interface 
- interactive viewpoint navigation
- automatic data focus
- geometry primitives: 
  points, lines, triangles, quads, texts, point sprites
- high-level geometry:
  surface, spheres
- up to 8 light sources
- alpha-blending (transparency)
- side-dependent fill-mode rendering (dots, wired and filled)
- texture-mapping with mipmapping and environment mapping support
- environmental effects:
  fogging, background sphere
- bounding box with axis ticks marks
- undo operation:
  shapes and light-sources are managed on type stacks,
  where the top-most objects can be popped, or any item specified by
  an identifier can be removed


PLATFORMS
---------
macOS
Windows 7/10
Unix-derivatives


BUILD TOOLS
-----------
R recommended tools (gcc toolchain)
On Windows, Rtools40 (or earlier versions for pre-R-4.0.0)

REQUIREMENTS
------------
**For OpenGL display:**

Windowing System (unix/x11 or Windows)  
OpenGL Library  
OpenGL Utility Library (GLU)  

**For WebGL display:**

A browser with WebGL enabled.  See https://get.webgl.org.

Installing OpenGL support
-----------------------

**Debian and variants including Ubuntu:**

    aptitude install libgl1-mesa-dev libglu1-mesa-dev

**Fedora:**

    yum install mesa-libGL-devel mesa-libGLU-devel libpng-devel

**macOS:**  

Install XQuartz.  
`rgl` should work with XQuartz 2.7.11 or newer, but it will probably
need rebuilding if the XQuartz version changes. XQuartz normally needs
re-installation whenever the macOS version changes.

**Windows:**  

Windows normally includes OpenGL support, but to get the appropriate
include files etc., you will need the appropriate version of
[Rtools](https://cran.r-project.org/bin/windows/Rtools/) matched to your
R version.

Options
-------

The **libpng** library version 1.2.9 or newer is needed for pixmap import/export support.

The **freetype** library is needed for resizable 
anti-aliased fonts.  


BUILDING/INSTALLING
-------------------

Binary builds of `rgl` are available for some platforms on CRAN.

For source builds, install the prerequisites as described
above, download
the tarball and at the command line run

    R CMD INSTALL rgl_`r packageVersion("rgl")`.tar.gz

(with the appropriate version of the tarball).  The build
uses an `autoconf` configure script; to see the options, 
expand the tarball and run `./configure --help`.

Alternatively,
in R run

    install.packages("rgl")

to install from CRAN, or

    remotes::install_github("dmurdoch/rgl")
    
to install the development version from Github.

### BUILDING ON MACOS

To build on MacOS using one of the ARM64 chips (currently M1, M2 or
M3), follow the instructions on https://mac.r-project.org/tools/
to install the tools and libraries into `/opt/R/arm64`.  It is
important that `/opt/R/arm64/bin` appear in your
PATH before `/usr/local/bin` if the latter directory has been used
for x86_64 installs.  If you don't do this, or have some other 
error in setting things up, you'll get a warning during 
`rgl` installation saying that some configure test failed, and `rgl`
will be installed without OpenGL support.

Some versions of RStudio (including 2024.04.2+764) have a bug that 
modifies your PATH on startup and again after every package
installation, putting `/usr/local/bin` at the head of the PATH.
If you are building `rgl` in such a system you need to remove
files from `/usr/local/bin` if there's a file with the same name in 
`/opt/R/arm64/bin`.  Hopefully this bug will be fixed soon!

### BUILDING WITHOUT OPENGL
  
As of version 0.104.1, it is possible to build the package without
OpenGL support on Unix-alikes (including macOS) with the configure option
    --disable-opengl 
For example,
  
    R CMD INSTALL --configure-args="--disable-opengl" rgl_`r packageVersion("rgl")`.tar.gz 
  
  On Windows, OpenGL support cannot currently be disabled.
  
  
DOCUMENTATION and DEMOS: 
------------------------

```
library(rgl)
browseVignettes("rgl")
demo(rgl)
```

CREDITS
-------
Daniel Adler <dadler@uni-goettingen.de>  
Duncan Murdoch <murdoch@stats.uwo.ca>  
Oleg Nenadic <onenadi@uni-goettingen.de>  
Simon Urbanek <simon.urbanek@math.uni-augsburg.de>  
Ming Chen <mchen34@uwo.ca>  
Albrecht Gebhardt <albrecht.gebhardt@uni-klu.ac.at>  
Ben Bolker <bolker@zoo.ufl.edu>  
Gabor Csardi <csardi@rmki.kfki.hu>  
Adam Strzelecki <ono@java.pl>  
Alexander Senger <senger@physik.hu-berlin.de>  
The R Core Team for some code from R.  
Dirk Eddelbuettel <edd@debian.org>  
The authors of Shiny for their private RNG code.  
The authors of `knitr` for their graphics inclusion code.
Jeroen Ooms for `Rtools40` and `FreeType` help.  
Yohann Demont for Shiny code, suggestions, and testing.  
Joshua Ulrich for a lot of help with the Github migration.
Xavier Fernandez i Marin for help debugging the build.  
George Helffrich for draping code.  
Ivan Krylov for window_group code in X11.  
Michael Sumner for as.mesh3d.default enhancement.  
Tomas Kalibera for `winutf8` and other help.  
David Hugh-Jones for documentation improvements.  
Trevor Davis for a `snapshot3d` patch.
Mike Stein for pointer-handling code.
Jonathon Love for the `uname` patch.