Getting started with cgvR

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
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[@]metanet.ch.

cgvR renders 3D graphs with a Vulkan backend. This vignette walks through the main APIs on small built-in examples: opening a viewer, uploading a graph, laying it out, controlling the camera, highlighting a path, and recording a short video.

1. A first graph

Start with a tiny graph: 8 nodes on the corners of a cube, edges along the cube’s edges. Positions are explicit, no layout needed.

nodes <- 1:8
edges <- cbind(
  c(1,2,3,4, 5,6,7,8, 1,2,3,4),
  c(2,3,4,1, 6,7,8,5, 5,6,7,8)
)

# corner coordinates of a unit cube, scaled
pos <- matrix(c(
  -1,-1,-1,   1,-1,-1,   1, 1,-1,  -1, 1,-1,
  -1,-1, 1,   1,-1, 1,   1, 1, 1,  -1, 1, 1
), ncol = 3, byrow = TRUE) * 5

v <- cgv_viewer(800, 600, "cube")
cgv_background(v, "black")
cgv_set_graph(v, nodes, edges,
              positions   = pos,
              node_values = as.double(seq_len(8)),
              node_sizes  = rep(20, 8))
cgv_camera(v, position = c(15, 12, 18), target = c(0, 0, 0))
cgv_run(v)

node_values is mapped through a colormap (viridis by default — see cmap in ?cgv_set_graph for plasma / inferno / magma).

2. Force-directed layout

For graphs without natural coordinates use cgv_layout_fr (pure-R Fruchterman-Reingold) or cgv_layout_fr_bh (Barnes-Hut, O(n log n) in C — prefer it for thousands of nodes).

set.seed(1)
n <- 60L
# random tree + a few extra edges
ef <- 1L; et <- integer(0)
for (i in 2:n) { ef <- c(ef, sample.int(i - 1, 1)); et <- c(et, i) }
ef <- c(ef, sample.int(n, 20)); et <- c(et, sample.int(n, 20))
edges <- cbind(ef[seq_len(min(length(ef), length(et)))],
               et[seq_len(min(length(ef), length(et)))])

pos <- cgv_layout_fr(n, edges, n_iter = 200L, seed = 42L)
str(pos)

v <- cgv_viewer(1000, 700, "FR layout")
cgv_set_graph(v, seq_len(n), edges,
              positions   = pos,
              node_values = as.double(seq_len(n)),
              node_sizes  = rep(10, n))
cgv_camera(v, position = c(20, 16, 24), target = c(0, 0, 0))
cgv_run(v)

Same call, larger graph, faster algorithm:

pos <- cgv_layout_fr_bh(5000L, edges_big, n_iter = 200L, seed = 1L)

3. Highlighting a path

cgv_highlight_path overlays a path on top of the existing graph. Pass any sequence of node ids; consecutive ids get a thick coloured edge between them.

v <- cgv_viewer(1000, 700, "path demo")
cgv_set_graph(v, seq_len(n), edges, positions = pos,
              node_values = as.double(seq_len(n)),
              node_sizes  = rep(8, n))

cgv_highlight_path(v, c(1, 5, 17, 42), color = "#FF2200",
                   node_scale = 2.0, edge_width = 4.0)

# remove the highlight again:
# cgv_clear_path(v)

cgv_run(v)

4. Camera control

Three modes are available — fly (WASD + mouse), orbit, arcball. Switch at runtime with cgv_camera_mode. Two helpers animate the camera:

cgv_fly_to(v, node_id, duration) — fly to a single node.
cgv_fly_path(v, node_ids, duration) — animate along a Catmull-Rom spline through several waypoints.

v <- cgv_viewer(1000, 700, "camera demo")
cgv_set_graph(v, seq_len(n), edges, positions = pos,
              node_sizes = rep(8, n))

cgv_camera_mode(v, "orbit")
cgv_fly_path(v, c(1, 17, 42, 5, 1), duration = 6.0)
cgv_run(v)

5. Recording a video

cgv_record_start / cgv_record_stop pipe frames to ffmpeg (must be on PATH). In offscreen mode you control the number of frames explicitly via cgv_run(v, n_frames = ...), which is convenient for scripted rendering.

v <- cgv_viewer(1280, 720, "record demo", offscreen = TRUE)
cgv_set_graph(v, seq_len(n), edges, positions = pos,
              node_sizes = rep(8, n))
cgv_camera(v, position = c(20, 16, 24), target = c(0, 0, 0))

cgv_record_start(v, "demo.mp4", fps = 30)
cgv_run(v, n_frames = 90L)        # 3 seconds at 30 fps
cgv_record_stop(v)

6. Headless mode

offscreen = TRUE skips the GLFW window. Useful for tests, CI, and anywhere a display is unavailable.

v <- cgv_viewer(640, 480, offscreen = TRUE)
cgv_set_graph(v, nodes, edges, positions = pos)
cgv_run(v, n_frames = 1L)
cgv_close(v)

Where to next

The inst/examples/ directory ships ready-to-run scripts:

demo_small_graph.R — random 100-node graph with FR layout.
demo_cycles_bh.R — TopSpin cycles with Barnes-Hut FR.
demo_tictactoe.R — Tic-Tac-Toe state graph; node colour = move number.
demo_record.R, demo_cycles_bh_record.R — video recording end-to-end.

Run them with Rscript inst/examples/<file>.R from the package root.

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.