library(rvtk)The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.
library(rvtk)rvtk is an infrastructure package: it does not itself build VTK meshes or render scenes. Instead, it makes the Visualization Toolkit (VTK) available to other R packages that need to link against it from C++. If you are writing an R package with native code that #includes VTK headers and calls VTK classes, rvtk gives you four things:
rvtk::CppFlags() returns the -I (include) paths.rvtk::LdFlags() (and its response-file variant rvtk::LdFlagsFile()) returns the -L/-l arguments.rvtk::use_rvtk() writes all the build-time glue files for you.This vignette explains how VTK is located on each platform, what files a downstream package needs, how the two setup strategies (use_rvtk() versus hand-written files) relate, and how to verify that linking actually worked.
rvtk’s own configure script runs at install time and writes the result to inst/vtk.conf. The strategies differ by platform.
VTK_DIR (path to a VTK build/install tree).brew --prefix vtk) — macOS only.pkg-config (vtk-9.7, vtk-9.6, vtk-9.5, …, vtk-9.1)./usr, /usr/local) — Linux only.configure.win tries, in order:
VTK_DIR.pacman (queries installed packages; never installs automatically)./x86_64-w64-mingw32.static.posix, /ucrt64, /mingw64, …)..a by default, or shared DLLs when VTK_LINK_TYPE=shared is set before installation).Static .a libraries are preferred over shared .dll.a import libraries at the same prefix; if only shared libraries are available, rvtk accepts them and stages the VTK DLLs itself so downstream packages need no extra configuration.
The pre-built fallback is available for the following platform × strategy combinations; a system VTK installation (≥ 9.1.0) found via VTK_DIR, pkg-config, Homebrew, or pacman is always preferred when present.
| Platform | Pre-built fallback | Notes |
|---|---|---|
| macOS arm64 | static .a |
|
| macOS x86_64 | static .a |
|
| Linux x86_64 (glibc) | static .a |
|
| Linux x86_64 (musl / Alpine) | static .a |
headless build: VTK_USE_X=OFF, RenderingOpenGL2=NO |
| Linux aarch64 | static .a |
|
| Windows x64 | static .a (default) or shared DLLs (VTK_LINK_TYPE=shared) |
On Windows the modules VTK_IONetCDF, VTK_IOHDF, and VTK_GeovisCore are disabled because netcdf and libproj are not available in the Rtools45 static.posix sysroot; downstream packages requiring them cannot be built on Windows with rvtk’s pre-built libraries.
The pre-built bundles are built with VTK_BUILD_ALL_MODULES=OFF and the following modules explicitly enabled (VTK resolves and includes all transitive dependencies automatically):
| Module | Purpose |
|---|---|
VTK_IOLegacy |
Legacy VTK file format reader/writer (.vtk) |
VTK_IOXML |
XML-based VTK file formats (.vtp, .vtu, .vts, …) |
VTK_IOCore |
Core I/O infrastructure shared by all I/O modules |
VTK_IOGeometry |
Readers/writers for common geometric formats (.ply, .stl, …) |
VTK_FiltersCore |
Core algorithmic filters (threshold, transform points, …) |
VTK_FiltersGeneral |
General-purpose filters (append, clip, decimate, …) |
VTK_FiltersGeometry |
Filters that modify or convert dataset geometry |
VTK_FiltersModeling |
Filters for geometric modeling and meshing |
VTK_FiltersExtraction |
Filters that extract subsets of data |
VTK_CommonCore |
Core data structures, object model, logging |
VTK_CommonDataModel |
Datasets, cells, point/cell data arrays |
Typical transitive dependencies pulled in automatically include VTK_CommonExecutionModel, VTK_CommonMath, VTK_CommonMisc, VTK_CommonSystem, VTK_CommonTransforms, VTK_IOXMLParser, and vtksys.
Once rvtk is installed, CppFlags(), LdFlags(), LdFlagsFile(), and VtkVersion() read vtk.conf and report whatever VTK was found:
VtkVersion()
#> [1] "9.5.0"
CppFlags()
#> -isystem/opt/homebrew/opt/vtk/include/vtk-9.5The exact flags depend on the detected VTK strategy: system shared libraries on macOS/Linux, .a archives in the pre-built tree, .dll.a import libraries + DLLs on Windows, etc. Your downstream package never has to figure this out itself — it simply calls back into rvtk.
There are two equivalent ways to configure a downstream package. They produce byte-identical files (this equivalence is asserted in rvtk’s own CI on every platform and VTK strategy).
use_rvtk()The recommended one-call approach, in the spirit of usethis:
# from the root of your package (e.g. yourpackage/)
rvtk::use_rvtk()This does the following, in order:
rvtk to the Imports field of DESCRIPTION.src/Makevars (macOS/Linux build rules).src/Makevars.win (Windows build rules).tools/configure.R, a small R helper that resolves the flags at install time.src/vtk_libs.rsp to .gitignore (the response file is generated at install time and must not be committed).R/rvtk_imports.R with a minimal @importFrom rvtk roxygen tag so that R CMD check does not warn about an unused Imports entry.If some of these files already exist, use_rvtk() asks before overwriting in an interactive session and skips them silently otherwise.
Everything use_rvtk() writes can also be written by hand, exactly as documented below (the README’s “Manual setup” section also walks through it). The files are:
DESCRIPTION — declare the dependency:
Imports: rvtk
src/Makevars:
PKG_CPPFLAGS = `"$(R_HOME)/bin/Rscript" ../tools/configure.R --cppflags`
PKG_LIBS = `"$(R_HOME)/bin/Rscript" ../tools/configure.R --libs`src/Makevars.win:
PKG_CPPFLAGS = $(shell "$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" ../tools/configure.R --cppflags)
PKG_LIBS = $(shell "$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" ../tools/configure.R --libs)tools/configure.R:
args <- commandArgs(trailingOnly = TRUE)
flag <- if (length(args)) args[1L] else "--cppflags"
vtk_modules <- c(
"vtkIOLegacy",
"vtkIOXML",
"vtkIOXMLParser",
"vtkIOCore",
"vtkIOGeometry",
"vtkFiltersCore",
"vtkFiltersGeneral",
"vtkFiltersGeometry",
"vtkFiltersModeling",
"vtkFiltersExtraction",
"vtkCommonCore",
"vtkCommonDataModel",
"vtkCommonExecutionModel",
"vtkCommonMath",
"vtkCommonMisc",
"vtkCommonSystem",
"vtkCommonTransforms",
"vtksys"
)
if (flag == "--cppflags") {
rvtk::CppFlags()
} else if (flag == "--libs") {
rvtk::LdFlagsFile(path = "vtk_libs.rsp", modules = vtk_modules)
}.gitignore — add src/vtk_libs.rsp.
R/rvtk_imports.R — import at least one rvtk function so that R CMD check sees the Imports entry as used:
#' @importFrom rvtk CppFlags LdFlagsFile
NULLThere is no shell configure script in the downstream package. Instead, the Makevars files shell out to Rscript at compile time:
"$(R_HOME)/bin/Rscript" ../tools/configure.R --cppflagstools/configure.R is the only file that knows about rvtk’s functions; it prints the flags to standard output, and Make captures them into PKG_CPPFLAGS / PKG_LIBS. This redirection through Rscript is exactly how the flags stay correct no matter where VTK was found — the R session doing the compilation has the same library paths as the rvtk installation being linked against.
On Windows the Make syntax is different ($(shell "$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" …)) because GNU make on Windows needs the $(shell …) form and the R_ARCH_BIN subdirectory.
The --libs path calls LdFlagsFile(), not LdFlags(), because the full set of VTK -l flags can exceed the 8 191-character Windows command-line limit. On Windows the flags are written to src/vtk_libs.rsp and PKG_LIBS receives the short token @vtk_libs.rsp. On macOS and Linux the raw flags are returned directly.
The pre-built bundles shipped with rvtk contain far more than the modules you are likely to use (I/O, filtering, and core modules plus their transitive dependencies). By default use_rvtk() links the following set:
c(
"vtkIOLegacy",
"vtkIOXML",
"vtkIOXMLParser",
"vtkIOCore",
"vtkIOGeometry",
"vtkFiltersCore",
"vtkFiltersGeneral",
"vtkFiltersGeometry",
"vtkFiltersModeling",
"vtkFiltersExtraction",
"vtkCommonCore",
"vtkCommonDataModel",
"vtkCommonExecutionModel",
"vtkCommonMath",
"vtkCommonMisc",
"vtkCommonSystem",
"vtkCommonTransforms",
"vtksys"
)
#> [1] "vtkIOLegacy" "vtkIOXML"
#> [3] "vtkIOXMLParser" "vtkIOCore"
#> [5] "vtkIOGeometry" "vtkFiltersCore"
#> [7] "vtkFiltersGeneral" "vtkFiltersGeometry"
#> [9] "vtkFiltersModeling" "vtkFiltersExtraction"
#> [11] "vtkCommonCore" "vtkCommonDataModel"
#> [13] "vtkCommonExecutionModel" "vtkCommonMath"
#> [15] "vtkCommonMisc" "vtkCommonSystem"
#> [17] "vtkCommonTransforms" "vtksys"Restricting linking to only the modules you need is strongly recommended when you use the pre-built static bundle on macOS. The bundle is built as a collection of static archives, and the linker (with R’s default -undefined dynamic_lookup) resolves symbols lazily at load time rather than at build time. If a kept library contains an object file that references a symbol from a module that is not in your requested set, that object can be dragged in and the missing symbol shows up only when the package is loaded:
symbol not found in flat namespace '__ZN17vtkCellGridReader3NewEv'
For example, the pre-built libraries contain modules (such as I/O readers) that are not part of the default module list; linking too broadly can pull in an object referencing one of them. Because the pre-built libraries are static archives on macOS/Linux, the fixed module list in tools/configure.R is what prevents this. Pass only the modules your code actually uses:
rvtk::use_rvtk(
modules = c(
"vtkIOLegacy",
"vtkCommonCore",
"vtkCommonDataModel"
)
)This also keeps link time down and reduces the size of your compiled code. With a system shared VTK installation, the loader resolves symbols at run time and the full modules = NULL set is fine.
If you set up files manually, edit the vtk_modules vector in tools/configure.R the same way.
The modules argument is also accepted directly by LdFlags() and LdFlagsFile() if you need finer control in your own build scripts:
# flags for just the I/O + core modules
LdFlags(modules = c("vtkIOLegacy", "vtkCommonCore", "vtkCommonDataModel"))
#> -L/opt/homebrew/opt/vtk/lib -lvtkIOLegacy-9.5 -lvtkIOXML-9.5 -lvtkIOXMLParser-9.5 -lvtkIOCore-9.5 -lvtkIOGeometry-9.5 -lvtkFiltersCore-9.5 -lvtkFiltersGeneral-9.5 -lvtkFiltersGeometry-9.5 -lvtkFiltersModeling-9.5 -lvtkFiltersExtraction-9.5 -lvtkCommonCore-9.5 -lvtkCommonDataModel-9.5 -lvtkCommonExecutionModel-9.5 -lvtkCommonMath-9.5 -lvtkCommonMisc-9.5 -lvtkCommonSystem-9.5 -lvtkCommonTransforms-9.5 -lvtksys-9.5A minimal src/code.cpp that exercises the link looks like this:
// src/code.cpp
#include <cpp11.hpp>
#include <vtkNew.h>
#include <vtkPolyData.h>
[[cpp11::register]]
int vtk_poly_data_npoints() {
vtkNew<vtkPolyData> pd;
return static_cast<int>(pd->GetNumberOfPoints());
}Include the headers exactly as the VTK include directory is laid out in the detected installation (e.g. vtk-9.7). -isystem (from CppFlags() on macOS/Linux) makes these includes searchable without turning their content into warnings.
If you use cpp11 (as in rvtk’s own downstream CI), run cpp11::cpp_register() after adding your functions. Note: cpp_register() copies only the function name, return type, and arguments into R/cpp11.R — roxygen tags such as #' @export must live in a separate R file for the wrapper function you export, or the function will not appear in NAMESPACE.
If rvtk is installed with VTK_LINK_TYPE=shared (or a system installation provides only shared libraries), downstream packages link against .dll.a import libraries and load the VTK DLLs at run time from rvtk’s inst/vtk-dlls/ (prepended to PATH by rvtk’s .onLoad hook). Two consequences for package authors:
vtkCommonCore-9.8.dll).For CRAN submissions the static pre-built build is recommended: it is self-contained inside your package binary and has no run-time coupling to rvtk’s DLLs.
Before submitting your package, run a full R CMD check; then load the installed package in a fresh session and call the C++ entry point:
# in a fresh R session, after R CMD INSTALL
library(yourpackage)
yourpackage::vtk_poly_data_npoints() # expect 0: a brand-new vtkPolyData has no pointsIf the package builds but fails to load with an undefined-symbol error, the usual cause is a module being referenced by the code but missing from the modules vector, or a symbol being dragged in from a module outside the requested set (e.g. vtkCellGridReader when vtkIOCellGrid is not listed). Narrow the module list to exactly what the code uses and rebuild.
CppFlags(), LdFlags(), LdFlagsFile(), and VtkVersion().use_rvtk() writes every build-time file for a downstream package; the same files can be written manually, byte-for-byte identically.modules argument to link only what you need — especially with the macOS static bundle.LdFlagsFile() on Windows to avoid the command-line length limit.These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.