Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dmurdoch/rgl

rgl is a 3D visualization system based on OpenGL. It provides a medium to high level interface for use in R, currently modelled on classic R graphics, with extensions to allow for interaction.
https://github.com/dmurdoch/rgl

graphics opengl r rgl webgl

Last synced: 7 days ago
JSON representation

rgl is a 3D visualization system based on OpenGL. It provides a medium to high level interface for use in R, currently modelled on classic R graphics, with extensions to allow for interaction.

Awesome Lists containing this project

README 

        
---

output: github_document

---



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])

```



[![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)



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   

Duncan Murdoch   

Oleg Nenadic   

Simon Urbanek   

Ming Chen   

Albrecht Gebhardt   

Ben Bolker   

Gabor Csardi   

Adam Strzelecki   

Alexander Senger   

The R Core Team for some code from R.  

Dirk Eddelbuettel   

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.  

Volodymyr Agafonkin and many others for the `earcut`

triangulation code.