Package {cgvR}

Title:	Interactive 3D Visualization of Large Cayley Graphs via Vulkan
Version:	0.1.2
Description:	Provides interactive 3D visualization for large-scale Cayley graphs. Specifically designed for analyzing state spaces of the 'TopSpin' puzzle. Leverages the 'Datoviz' library and Vulkan-based GPU rendering for smooth real-time exploration of large graphs and complex state transitions. Implements efficient coordinate mapping for high-dimensional permutation groups, allowing users to visualize the connectivity and structural properties of the puzzle's state space. The rendering engine provides high-performance visuals and interactive camera controls, making it suitable for mathematical analysis of group-theoretic puzzles within the R environment.
Depends:	R (≥ 4.1.0)
Imports:	grDevices, stats
Suggests:	cayleyR, knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
License:	MIT + file LICENSE
Encoding:	UTF-8
SystemRequirements:	C17, C++17, GNU make, pkg-config, libvulkan-dev (Linux) or LunarG 'Vulkan' 'SDK' (Windows, macOS), libglfw3-dev (Linux) or glfw via Homebrew (macOS), ffmpeg (optional, for cgv_record_*). Optional configure flags: --with-vulkan / --without-vulkan, --with-simd for SSE4.1 + PCLMUL fpng.
RoxygenNote:	7.3.3
Config/testthat/edition:	3
URL:	https://github.com/Zabis13/cgvR
BugReports:	https://github.com/Zabis13/cgvR/issues
NeedsCompilation:	yes
Packaged:	2026-05-06 09:08:39 UTC; yuri
Author:	Yuri Baramykov [aut, cre], Cyrille Rossant [ctb, cph] (Author of the Datoviz library)
Maintainer:	Yuri Baramykov <lbsbmsu@mail.ru>
Repository:	CRAN
Date/Publication:	2026-05-11 19:20:07 UTC

cgvR: Interactive 3D Visualization of Large Cayley Graphs via Vulkan

Description

Provides interactive 3D visualization for large-scale Cayley graphs. Specifically designed for analyzing state spaces of the 'TopSpin' puzzle. Leverages the 'Datoviz' library and Vulkan-based GPU rendering for smooth real-time exploration of large graphs and complex state transitions. Implements efficient coordinate mapping for high-dimensional permutation groups, allowing users to visualize the connectivity and structural properties of the puzzle's state space. The rendering engine provides high-performance visuals and interactive camera controls, making it suitable for mathematical analysis of group-theoretic puzzles within the R environment.

Author(s)

Maintainer: Yuri Baramykov lbsbmsu@mail.ru (ORCID)

Other contributors:

• Cyrille Rossant (Author of the Datoviz library) [contributor, copyright holder]

See Also

Useful links:

• https://github.com/Zabis13/cgvR

• Report bugs at https://github.com/Zabis13/cgvR/issues

Set Background Color

Description

Set the panel background to a solid color or a 4-corner gradient.

Usage

cgv_background(viewer, color)

Arguments

Value

No return value, called for side effects: updates the panel's background color on the GPU. Returns NULL invisibly.

Set Camera Position and Direction

Description

Set Camera Position and Direction

Usage

cgv_camera(viewer, position = c(0, 0, 5), target = c(0, 0, 0), up = c(0, 1, 0))

Arguments

Value

No return value, called for side effects: updates the camera's position, look-at target and up vector on the active panel. Returns NULL invisibly.

Switch Camera Mode

Description

Switch Camera Mode

Usage

cgv_camera_mode(viewer, mode = c("fly", "orbit"))

Arguments

Value

No return value, called for side effects: switches the active camera between fly and orbit interaction modes. Returns NULL invisibly.

Clear Path Highlight

Description

Remove path highlight and restore original node colors and sizes.

Usage

cgv_clear_path(viewer)

Arguments

Value

No return value, called for side effects: removes the path highlight overlay and restores original node colors and sizes. Returns NULL invisibly.

Close the Viewer

Description

Close the Viewer

Usage

cgv_close(viewer)

Arguments

Value

No return value, called for side effects: releases the underlying Vulkan application, GPU resources and (in windowed mode) the GLFW window held by viewer. Returns NULL invisibly.

Fly Camera Along a Path

Description

Smoothly animate the camera along a sequence of 3D waypoints using Catmull-Rom spline interpolation.

Usage

cgv_fly_path(viewer, positions, duration = 5, loop = FALSE)

Arguments

Value

No return value, called for side effects: starts a Catmull-Rom spline camera animation through the given waypoints. Returns NULL invisibly.

Fly Camera to a Node

Description

Smoothly animate the camera to center on a given node. Requires that cgv_set_graph was called first (for node positions).

Usage

cgv_fly_to(viewer, node_id, duration = 1)

Arguments

Value

No return value, called for side effects: starts a camera animation toward the chosen node. Returns NULL invisibly.

Highlight a Path

Description

Draw a highlighted path between nodes. Path nodes get a distinct color and enlarged size; path edges are drawn as thick colored segments on top of existing edges.

Usage

cgv_highlight_path(
  viewer,
  path,
  color = "#FF0000",
  node_scale = 2,
  edge_width = 5
)

Arguments

Value

No return value, called for side effects: adds (or replaces) the highlight overlay for the given path. Returns NULL invisibly.

Is this a stub build?

Description

Returns TRUE when cgvR was installed without native rendering support (no Vulkan / GLFW found at install time). In that case all rendering functions raise an error; pure-R helpers like cgv_layout_fr still work.

Usage

cgv_is_stub_build()

Value

Logical scalar.

Fruchterman-Reingold Force-Directed Layout

Description

Computes 3D (or 2D) node positions so that connected nodes settle at approximately equal distance ideal_len, while non-adjacent nodes repel each other. Implements the Fruchterman-Reingold algorithm with linearly-cooling temperature, fully vectorized over nodes and edges.

Usage

cgv_layout_fr(
  n_nodes,
  edges,
  n_iter = 300L,
  ideal_len = NULL,
  dim = 3L,
  seed = NULL,
  init = NULL,
  cool = 0.98,
  normalize = TRUE,
  verbose = FALSE
)

Arguments

Value

Numeric matrix n_nodes x dim of node coordinates.

Examples

edges <- cbind(c(1, 2, 3, 4), c(2, 3, 4, 1))
pos <- cgv_layout_fr(4, edges, n_iter = 200)

Barnes-Hut Fruchterman-Reingold Layout (3D, fast)

Description

Same energy model as cgv_layout_fr but with O(n log n) repulsion approximated through an octree. Suitable for large graphs (10^4+ nodes).

Usage

cgv_layout_fr_bh(
  n_nodes,
  edges,
  n_iter = 200L,
  ideal_len = NULL,
  theta = 1,
  cool = 0.98,
  min_dist = 0.01,
  seed = NULL,
  init = NULL,
  normalize = TRUE
)

Arguments

Value

Numeric matrix n_nodes x 3 of node coordinates.

Start Recording the Viewer to a Video File

Description

Pipes raw RGB frames from the live canvas into ffmpeg, which encodes them on the fly. The recording runs in the background while the user keeps interacting with the viewer (mouse, keyboard).

Usage

cgv_record_start(
  viewer,
  file,
  fps = 30L,
  duration = NA_real_,
  ffmpeg_args = NULL
)

Arguments

Details

Requires ffmpeg on PATH. The container/codec is chosen by the file extension (.mp4 / .mkv / .webm / etc.). Frames are captured at the requested fps; if the rendering loop produces frames faster, extras are dropped.

The recording is automatically stopped when the viewer is closed, cgv_record_stop() is called, or the optional duration elapses.

Value

No return value, called for side effects: stores the recording parameters on the viewer; the ffmpeg pipe is opened lazily on the first rendered frame. Returns NULL invisibly.

Stop the Active Recording

Description

Closes the ffmpeg pipe (which finalises the output file) and frees the recording state on the viewer.

Usage

cgv_record_stop(viewer)

Arguments

Value

Invisibly, an integer vector c(frames, fps) reporting how many frames were written.

Run the Viewer Event Loop

Description

Starts the rendering loop.

Usage

cgv_run(viewer, n_frames = 0L)

Arguments

Value

No return value, called for side effects: drives the render loop. Blocks until the window is closed (interactive mode, n_frames = 0) or until exactly n_frames frames have been rendered (scripted/offscreen mode). Returns NULL invisibly.

Set Graph Data for Rendering

Description

Provide the full graph (or a subgraph) as adjacency data with optional node colors, sizes, and colormap.

Usage

cgv_set_graph(
  viewer,
  nodes,
  edges,
  positions = NULL,
  node_values = NULL,
  node_colors = NULL,
  node_sizes = NULL,
  cmap = 6L
)

Arguments

Value

No return value, called for side effects: uploads the node and edge buffers to the GPU and caches node positions on the viewer for subsequent cgv_fly_to / picking calls. Returns NULL invisibly.

Set Visibility Depth

Description

Controls how many hops from the current focus node are rendered.

Usage

cgv_set_visibility(viewer, depth = 10L)

Arguments

Value

No return value, called for side effects: updates the visibility depth used to filter rendered nodes by BFS distance. Returns NULL invisibly.

Create a 3D Cayley Graph Viewer

Description

Opens a Vulkan-powered 3D window for interactive graph visualization.

Usage

cgv_viewer(width = 1280L, height = 720L, title = "cgvR", offscreen = FALSE)

Arguments

Value

An external pointer to the viewer object (invisibly).