Finding your way around ivue

Point clouds and annotations

attr(widget, "ivue") records coordinates, integer row.ids, explicit observation.ids (or NULL for unnamed coordinates), mapped colors, highlight, draw IDs, aspect, camera, and the captured scene. Draw IDs describe serialized scene objects, not a device left open for further drawing.

Graph preparation and plotting

Accepted formats are an edge data frame with from, to, weight and an explicit vertices argument (including isolates); a list with edges and vertices; paired adj.list/weight.list lists whose neighbors are integer row indices; dense square adjacency matrices; Matrix sparse adjacency matrices; and igraph objects. A prepared ivue_graph can be reused and is revalidated. Vertex attributes are retained. Table edges retain input order; reciprocal undirected list/matrix edges retain one copy from the lower vertex index. Edge widths and colors follow this prepared edge order.

Matrices use zero for absence; use tables/lists for actual zero-weight edges. Explicit sparse zeros are rejected. Undirected adjacency must be reciprocal with equal weights. Self-loops and parallel edges are rejected, and directed data can be prepared but cannot be rendered in this release.

With supplied X, ivue does not compute a layout or construct an igraph object for table/list/matrix inputs. Built-in layout = "kk" and "fr" require igraph: Kamada-Kawai uses positive distances, whereas Fruchterman-Reingold uses positive strengths. Declare weight.type accordingly; no inversion is performed. "unweighted" permits only unit or missing weights. Missing weights otherwise fail. Finite zero/negative weights can be stored and drawn with supplied coordinates, but not used by these layout adapters. Weights never automatically set visual edge width or color. A custom layout function receives the prepared graph and returns n-by-3 coordinates. ivue provides no general embedding or graph-construction API. See the weighted graph workflow.

Reusable color scales and legends

Continuous scales use the reference range by default; limits fixes it. center requires a supplied diverging palette or color.map and makes automatic limits symmetric about it. For a palette, it places the center at the palette midpoint. A custom color.map instead receives data-unit values unchanged by centering; with explicit limits, center does not alter callback colors. With explicit limits, the center must lie strictly inside them. For constant or all-missing reference inputs, see the scale help.

Out-of-range values are squished to the endpoints by default. oob = "censor" uses na.color; oob = "error" rejects them. Missing values use na.color (default "gray80"). No default winsorization occurs. In mode = "binned", choose uniform or quantile bins, or explicit increasing breaks; the intervals are right-closed, with the lowest endpoint included. The scale help gives the contracts for explicit breaks, winsorization, and legend precision.

Factors retain level order, including unused nonmissing levels. Other group vectors use first-occurrence order. When plots fit a default categorical scale, this is the supplied annotation order before ID alignment, for both point and graph views. Reuse a scale when annotation order or membership changes. Named colors must cover the reference levels; unknown groups error unless unknown = "missing". Missing values are distinct from a literal "NA" category; empty strings are valid groups. Numeric palette indices are resolved when fitting scales. A color.map function runs at mapping time on data-unit values after out-of-range handling. It must return one color per value and be deterministic and pointwise: the same value must have the same color when mapped alone, reordered, or in another batch. Observations, legend ticks, and the ramp are separate calls. function(x) ifelse(x < 0, "blue", "red") obeys that contract; recomputing range(x) or ranks inside each call does not, even without mutable external state. Prefer a palette with fixed limits for ordinary comparisons. Supply color.map or palette, not both.

map.colors() returns a legend with label, color, and count. Continuous ticks have missing counts; binned/category counts describe the mapped input. A missing entry appears when needed. Reuse one scale across related views: separately autoscaled panels can give the same color to different numbers. The shared-view recipe checks this explicitly. Animation accepts a map.colors() result through mapping to retain its legend; caption explains what the fixed colors mean across frames.

Geometric layers

Combine specifications with layers = list(edge.layer, label.layer, ...) in a plotting call. Edges, paths, labels, and meshes use plotting rows (aligned graph rows for graph plots). Label offset has three components in coordinate units. Mesh colors are per face and do not inherit point colors. Meshes retain supplied connectivity and do not repair folds or degenerate geometry.

A surface has its own grid: z[i, j] belongs to (x[i], y[j]), so z has length(x) rows and length(y) columns. Both axes are strictly monotone; coordinates must be finite. Grid cells split into planar triangles. No alignment or rescaling occurs. Surface bounds contribute to the scene, but automatic origin-axis limits use the plotted observations. See the introduction for meshes and reference surfaces.

layer3D.axes() crosses at c(0, 0, 0) by default, with positive arrowheads and no ticks. It is distinct from ordinary bounding-box axes enabled by axes = TRUE; normally use axes = FALSE with this layer. Its 3-by-2 limits set endpoints, not clipping. The camera is unchanged.

Callbacks run once during scene construction on the private rgl device, before serialization, not on later browser events. Their first argument contains X, integer row.ids, observation.ids, colors, highlight, and draw.ids; args supplies named additional arguments. They must not open, close, or switch devices. Captured object IDs are not live devices. Constructing the specification does not run the callback; drawing its plot does. Prefer ordinary layer constructors when they express the intended geometry.

Cameras and aspect ratios

point.size measures screen pixels. point.type = "sphere" instead uses sphere.radius in coordinate units (default one percent of the largest span, with a minimum of 1e-8). Setting radius alone does not select spheres. Spheres carry spatial extent and can overlap; large scenes cost more to draw. aspect = "equal" preserves equal units along all axes. "normalized" stretches axes independently, changing relative distances and proportions.

fov = 0 is orthographic: distance from the camera does not shrink an object. Positive field of view introduces perspective foreshortening. Static plots default to camera.zup(elevation = 20, turn = -135, fov = 0, zoom = 0.8). Away from the poles, positive z initially projects upward. Interactive rotation can tilt it; this is not an enforced rotation constraint. Explicit theta, phi, or userMatrix selects the alternative camera controls described in help("plot3D.plain", package = "ivue"). Browser rotation does not update R-side camera metadata or synchronize another widget. Open View controls for keyboard rotation/zoom and Reset view. Download view settings saves an R recipe containing the current camera, bounds, and aspect. Source it and supply those settings explicitly to another plot:

source("ivue-view.R")
recovered <- plot3D.plain(X, camera = view$camera, limits = view$limits,
                          aspect = view$aspect)

The file contains viewing settings, not coordinates, annotations, or layers. Use matching widget dimensions as well for equal screen scale. The camera is transferable, but a bounds range from one scene may not contain another dataset. limits = rbind(c(-2, 2), c(-2, 2), c(-2, 2)) fixes the x/y/z framing range; all observations must fit. Spheres and layers cannot enlarge it, and geometry outside the range may fall outside the viewport. It is not a clipping box. See the common-bounds recipe.

Recorded-coordinate animation and export

Frame rows keep stable observation identity. If row names are present, every frame must have the same unique, nonempty names in the same order; frames are not automatically reordered. Each row must be entirely finite or entirely missing (NA/NaN), meaning inactive. Partially missing rows and infinity fail. Incident edges are hidden while either endpoint is inactive. An empty frame is allowed, but the whole sequence must contain a finite point. Two columns are embedded at z = 0 with a face-on default camera; three use z-up.

labels means one string per original frame, not vertex labels. frame.index selects increasing original indices and overrides max.frames (default 100 evenly spaced frames, retaining endpoints). Bounds use all original frames, even those omitted. Retained frames have equal playback duration. These may represent algorithm iterations or physical measurements, but the player does not infer elapsed time, interpolate, or align coordinates. Camera rotation changes the view, not the recorded positions. The animation guide distinguishes these operations in detail.

GIF controls are fps (0.1–100), width/height (64–8192 pixels), final.hold (0–600 additional seconds), loop, labels, and overwrite. The parent directory must exist and existing files are protected by default. annotations = TRUE adds the retained mapping legend and caption outside the scene; use larger dimensions for long text. Smaller camera zoom values enlarge both browser and GIF views. GIF delays round to centiseconds; points and edges need not look pixel-identical to WebGL, especially at intersections. Perspective cameras are rejected. selfcontained and libdir belong to htmlwidgets::saveWidget(), not GIF export. Neither export operation automatically captures later browser interaction; download view settings and reconstruct the R widget to reuse it.