BorgVR Guide

Concepts

How BorgVR works

A shared model for datasets, renderers, servers, and collaboration. Once these concepts are familiar, every BorgVR application follows naturally.

Rendered Mandelbulb volume

The basic idea

Volume data is a three-dimensional grid of measurements. BorgVR divides this grid into small blocks called bricks and loads only the bricks and detail levels required for the current image. This makes it possible to explore datasets larger than the available GPU memory.

A voxel may contain one or more measurement channels. BorgVR supports up to four channels with 8 or 16 bits per channel; scalar datasets may additionally use 32-bit values. Voxel spacing stored in the dataset is interpreted in meters, enabling physically meaningful dimensions and measurements.

All native applications and the WebGPU renderer understand the same dataset format. A dataset can be opened locally, streamed from a BorgVR server, or discovered through known sources in a SharePlay session.

ImportantSharePlay primarily transfers the shared state. The volume data itself comes from a local file or from a reachable dataset server.

Rendering modes

Transfer function + light
Maps values to color and opacity and lights visible structures. This provides stronger shape cues but requires additional gradient and lighting work.
Transfer function
Composites color and opacity along each ray without lighting. This mode works well for color-coded or translucent structures.
Isosurface
Shows a surface where the dataset reaches a selected value. The corresponding editor controls that isovalue.

Transfer functions

A transfer function contains separate curves for red, green, blue, and alpha. Alpha determines which values become visible. Transfer functions can be stored with the dataset, loaded from a .tf1d file, or selected from the server catalog.

For multi-channel data, each data channel has its own RGBA transfer function. Select the data channel in the editor before changing its color and opacity curves. Rendering composites the contributions of all active channels.

Lighting

In Transfer Function + Light and Iso, the lighting editor controls light direction and ambient, diffuse, and specular colors. A preview sphere responds immediately. Ambient supplies direction-independent light, diffuse depends on the surface normal, and specular controls highlights. In lit TF mode, the transfer function colors the ambient/diffuse contribution; highlights use the specular color. With all three light colors black, the lit result is black. These settings have no effect in unlit TF.

Sampling, LOD, and bricks

The sampling rate controls the spacing between samples along a ray. Higher values usually improve quality at a performance cost. The level-of-detail system selects coarser or finer bricks. The optional brick visualization is a diagnostic tool and is hidden by default.

Opening and importing data

Progressive loading, a persistent local copy, and the origin cache serve different purposes. Data and Edit States explains these options, the red italic streaming title, offline availability, and reconnection, as well as deleting a dataset and all its edit variants.

  • Local: An existing .data file is read directly from the device.
  • Remote: The app first reads the catalog of a configured BorgVR server and then fetches required bricks on demand.
  • Import: DICOM, NRRD/NHDR, PVM, or QVIS data is converted into the bricked BorgVR format. Import settings only affect newly converted datasets.

The dataset's unique ID connects local copies, server origins, transfer functions, objects, measurements, and saved views. Origins are stored per ID. If one source cannot be reached, BorgVR tries other known sources in most-recently-announced order and can switch origins after a connection failure.

Objects, drawings, and measurements

Active Object chooses a placement asset, such as a sphere or a known .mesh file. Load and the Object Files dropdown instead load a saved .marker collection. With existing objects, loaded objects may be added or replace the collection; measurement files have their own corresponding load workflow. Sphere size and optional direction settings carry over to subsequent spheres.

A length needs at least two points and sums every segment. An area needs three non-collinear anchor points; subsequent points project into their plane and its convex hull determines the area. Anchors are marked distinctly and moving them changes the plane. A spatial volume needs at least four non-coplanar points. The convex hull cannot represent indentations and is not automatic segmentation of the visible volume. Physical accuracy depends on stored voxel spacing and point placement.

All annotations live in dataset coordinates and are depth-composited correctly with the volume. Object rendering and the complete measurement visualization can be hidden independently without deleting data.

Sphere
A named, colored point with an adjustable radius. An optional ray points from the sphere center toward the original camera position.
Stroke
A sequence of spatial points. Strokes can be drawn with touch or mouse and, on Apple Vision Pro, with hands, Logitech Muse, or PlayStation VR2 Sense controllers.
Polygon object
An imported, optionally textured object in BorgVR's mesh format. Object coordinates are interpreted in meters. The same asset can be instantiated repeatedly with independent position, orientation, and scale.
Measurement
A sequence of editable points describes a path length, the convex hull of a planar area, or a convex volume. BorgVR automatically chooses an appropriate physical unit for the result and its label.

Object files use the .marker extension and contain spheres, strokes, and instances of imported objects. Measurements are stored separately as .measurement. Both formats carry the associated dataset ID; BorgVR asks for confirmation before loading them for another dataset.

Object scaleIf an object is more than ten times the dataset extent or smaller than one thousandth of it, BorgVR warns about the unusual scale before opening it.

Saving dataset state

Voxel edits are separate: variants are saved automatically in .data.edits. A .state file is not an edited volume. Use Export Edited Dataset to share permanently changed voxel data. The saving and export guide explains file contents, backups, and the distinction from NRRD and OBJ export.

Save Dataset State stores the current transfer function, objects, measurements, and the remaining visualization state under the dataset name. This includes transform, rendering mode, isovalue, lighting, clipping, and annotation visibility. Restore Dataset State reloads these parts together.

Settings can enable automatic loading and saving independently for transfer functions, objects, measurements, and visualization state.

SharePlay

The ad-hoc server restricts its volume offering to the current host dataset. Shared edits use a separate state without overwriting personal variants. See SharePlay with Local and Remote Data for complete origin, joining, host-change, and error workflows.

A session shares dataset selection, rendering mode, transfer functions for every data channel, isovalue, lighting, clipping, objects, and measurements. iPhone, iPad, and Mac participants use a common screen view by default and may temporarily detach their own view. Vision Pro participants have a spatial view and can see and manipulate the shared and detached screen views in space.

When joining, participants exchange known server origins that are allowed to be shared. A device with a local copy can also advertise an ad-hoc server. If no source is reachable yet, the app waits and retries loading whenever a new source becomes known.

Password-protected sourcesServer settings explicitly control whether an origin, including its password, may be shared through SharePlay. If disabled, that origin is not announced.

BorgVR files

ExtensionContentsUse
.dataMetadata and bricked, optionally LZ4-compressed volume dataRenderers and servers
.data.edits/Companion directory with edit masks, outstanding updates, and variant brick cachesLocal non-destructive volume editing; requires its original file
.tf1dOne-dimensional transfer function and display metadataTransfer-function catalog
.meshPolygon geometry with positions, normals, colors, texture coordinates, and optional embedded texturesReusable object assets
.markerSpheres, directions, spatial strokes, and mesh instances with dataset IDLoad, save, and share objects
.measurementLength, area, and volume measurements with dataset IDLoad, save, and share measurements
.stateTransform, rendering mode, isovalue, lighting, clipping, and visibilityRestore visualization state