BorgVR Guide

Shared workflows

Data and edit states

What BorgVR loads from a server, what stays on your device, and how personal edits and shared SharePlay work fit together.

BorgVR volume dataset

Open locally or load from a server

The dataset ID identifies content independently of its filename or server. A local file and a server copy with the same ID represent the same dataset. If a matching local file is available, BorgVR uses it instead of downloading the volume again.

  1. Under External Data Sources, add a hostname or IP address, the native BorgVR port, and a password if needed. The native dataset port is not the WebGPU or MCP port.
  2. Open the dataset selector and choose an entry. When opening a remote entry normally, BorgVR tries the server shown for that entry first, then known alternate origins if that attempt fails.
  3. BorgVR remembers successfully read server catalogs by dataset ID. Reading a catalog again updates that mapping: newly offered datasets are added, and datasets no longer offered by that server are removed from its entries.

Progressive loading and keeping a local copy are different options

Progressive loading enabled
The renderer opens a remote dataset before every brick has arrived. Required detail levels load while you work, so the initial image may be coarser.
Progressive loading disabled
When opening normally from the dataset selector, BorgVR first downloads a complete local file and then opens the renderer. A paused download can be resumed later.
Keep a local copy
During progressive loading, received bricks are also saved persistently. Once complete, they form a normal local .data file. Without this option, a streaming session remains server-dependent; an image already on screen is not a complete offline dataset.
SharePlay exceptionA remote dataset announced through SharePlay opens progressively, including ad-hoc device connections. The setting for downloading everything before opening applies to the normal Open dialog, not this join workflow.

Status in the render window

On macOS and iOS, the dataset name is dark red and italic while its actual data source still depends on the server. After complete local caching, it uses regular type and the normal text color, black in light appearance. Dark appearance uses a lighter red. Fully local files start with a regular title; without a local copy, a streaming title remains red and italic. This status is local to your device, not a download indicator for other SharePlay participants.

Dataset information shows physical dimensions, voxel count, components, bricks, detail levels, and known alternate origins. A key indicates password protection; a private indicator identifies origins that are not shared through SharePlay.

Disconnections and the origin cache

After a disconnection, the data source attempts reconnection and may use known alternate servers for the same dataset ID. Bricks already available locally remain usable; missing bricks still need a reachable origin. A firewall, an unavailable server, or denied local-network access can prevent recovery.

Clear Dataset Origin Cache in Settings removes remembered origin mappings. It does not delete volume files, edit states, or annotations and is not the same as clearing the browser brick cache.

Register and fuse volumes

Choose Volume Fusion in the import wizard. Select the source type independently for the reference volume and the volume to register: volume file, DICOM series, or Zarr folder. Supported volume files include NRRD/NHDR and native BorgVR .data files. Formats may be mixed; different grid sizes, voxel spacing, and crops are allowed.

Both sources are first decoded into temporary RAW volumes. A shared rigid NMI registration estimates rotation and translation. The reference grid and its values are retained in the first channel; the second channel is sampled onto that grid using the interpolation filter selected in Import settings. Samples outside its bounds are zero. If enabled, 8-bit quantization is then applied to both channels. Source files are not modified.

Fusion currently requires two single-channel integer volumes with matching 8-, 16-, or 32-bit precision. Multichannel, RGB/RGBA, and floating-point inputs are not part of this fusion workflow. The resulting matrix is recorded in the log and in the new dataset's provenance.

Provenance

Dataset information (i) shows the stored provenance history. DICOM import preserves available study, series, acquisition, content creation, instance creation, and processing history. Matching events are combined across slices, averaging their known timestamps and recording the slice count. Distinct processing steps are retained. Date-only values are stored at UTC midnight and marked date only: YYYY-MM-DD. For times without a time zone, the original local value remains in the text and the entry uses the import timestamp.

Fusion retains both source histories with their channel assignments. A new fusion entry records the filter and registration matrix, which maps reference voxel indices to registered-volume voxel indices. Subsequent 8-bit quantization records the original range of every channel. Saving an edited volume as a new .data file retains its history and appends an entry documenting the materialized edit state. NRRD export writes the history directly into the header as # BorgVR provenance: comments and appends the export step and LoD.

Work non-destructively with edit states

Edit Volume does not modify the original .data file. An edit state records which voxels are erased and also keeps prepared edited bricks and outstanding updates. Multiple states of one dataset are independent variants, not successive undo steps.

  1. If saved states exist, choose Original or a named state when opening normally. The last personal choice is preselected. Original hides saved edits without deleting them.
  2. BorgVR finishes outstanding brick updates in the chosen state before opening. A progress dialog appears when needed; there is no separate foreground/background choice.
  3. Select Edit mode and open the Brush tool with its matching button. Changing modes alone does not open the tool window. On Vision Pro, Muse and each PSVR controller can edit independently of the hand mode.

Brushes and preview

The spherical brush has an adjustable radius. Erase sets the selected data channels inside it to zero; all channels are selected by default. Restore recovers their original voxel values there, including where erased strokes overlap. There is no stroke-by-stroke undo. The transfer function determines whether zero is transparent; if zero maps to visible color or opacity, an erased region may remain visible.

The preview sphere shows position and affected region before applying a brush. Project onto Volume uses the visible surface; without projection, editing occurs at the tool position or an adjustable depth plane. Mouse, touch, hand, Muse, and PSVR controls are described in their platform guides.

Brush operations are recorded locally automatically while you work. A red dot on the Edit button indicates pending brick calculation or persistence. It is not a network or SharePlay error indicator. Outstanding work is retained for the next opening.

Select and manage states

For multichannel volumes, expand Edit Channels in the Brush tool and choose All Channels or individual channels. At least one channel stays selected. The selection applies to erase and restore, including Muse and PSVR; other channels remain unchanged. Opening a dataset resets the selection to all channels. Single-channel volumes do not show this extra control. During SharePlay, each participant chooses their own brush channels; every operation carries its selection. Discard All Edits resets every channel regardless of that selection.

ActionEffect
Select OriginalDisplays the unchanged volume without removing other states.
New state (+)Starts an independent empty variant.
DuplicateCopies current edits into another independently editable variant.
RenameAssigns a meaningful name to the selected saved state.
Delete state (trash)Removes exactly that variant after confirmation. Other variants and the original file remain intact.
Discard All Edits / ResetResets only the active state to original values, not every saved variant. During SharePlay, it resets the shared state for all participants.

Outside SharePlay, use the Brush tool to switch states. During a running session, that selector is hidden and state switching through GSC or MCP is blocked as well. When the host opens a new dataset, its opening selector may still delete unused local variants that are no longer in use. Clients cannot manage states there; states in use and running exports remain protected.

What is saved where?

PartContents and storage
.dataOriginal volume, metadata, and detail levels. Brush operations do not change this file.
.data.edits/Companion directory containing edit variants of this local dataset. Created for actual edits; merely opening a volume or an unedited session does not require a saved edit state.
.tf1d, .marker, .measurement, .stateTransfer functions, objects, measurements, and visualization state. These files are independent of voxel edits.

For built-in datasets, edit storage lives in private application storage because app resources are not writable. For remote datasets, it is next to the intended local dataset in the device's data directory. Editing is local to the device and does not write changes back to the original dataset server.

Save and restore dataset state

The render window's Save button stores visualization state, existing objects and measurements, and the transfer functions of all data channels except in Iso mode in the default search directories. Existing files require overwrite confirmation. Load restores the available parts. Settings provide separate automatic load/save options for transfer functions, objects, measurements, and visualization state.

A single-channel volume still uses one .tf1d file. Multichannel volumes save one file per channel, such as volume.channel-1.tf1d and volume.channel-2.tf1d. Automatic loading and saving use the same mapping. The TF currently selected in the editor does not affect Save or Restore Dataset State. Saving a single preset in the TF editor still applies only to the selected channel.

View state is not voxel editingSave Dataset State does not create a complete edited volume file. Voxel edits are saved automatically in edit variants; the .state file describes visualization. Use export to share a permanently modified volume.

Export a permanently edited dataset

  1. Select the desired edit state and choose Export Edited Dataset in the Brush tool. Enter a name and description.
  2. BorgVR captures a consistent state, completes outstanding bricks and detail levels, and displays progress. Compressed originals remain compressed; unchanged bricks are copied without decompression and recompression.
  3. Then choose where to save the new .data file. It receives a new dataset ID and includes the edits permanently without depending on the old edit files. The source and its variants remain intact.

During export, local editing and state changes are blocked for every input path. Cancellation removes incomplete export files, not recorded edits. Dataset export and macOS isosurface export are blocked in SharePlay. Starting SharePlay during export cancels it before installing the shared state.

To back up personal variants, close the dataset first, then copy the original .data file together with its complete .data.edits directory. The edit directory alone is not a standalone volume. GSC and MCP use the same editing and export rules; their references describe the commands.

Origins and edit states in SharePlay

  1. The host chooses the dataset and its desired personal starting state. Participants first check protocol versions; an incompatible installation receives an update message.
  2. The host announces the dataset ID and shareable origins. Each device first searches locally, then among announced and other already known origins. Fresh announcements take precedence over older cached origins.
  3. Volume bricks transfer directly from a reachable BorgVR server, not through SharePlay messages. A client with a complete local copy can also serve the current host dataset, including when its local download finishes during the session.
  4. The host's complete edit mask initializes a separate shared state. Personal client variants are not overwritten. While Synchronizing Edit State is displayed, editing is not ready yet; this step is not the brick download indicator.

Brush operations and erase/restore cursors are shared. Detaching the screen view on macOS or iOS affects only the view and model transform, not edits, rendering settings, or annotations. Leaving restores the device's previous personal choice. A shared state with actual edits remains as a separate SharePlay variant; an unedited session does not create an additional saved state.

Ad-hoc servers and password sharing

The temporary ad-hoc server offers only the host dataset chosen for the session, not the entire local volume directory. Closing or changing the host dataset ends that offering and rebuilds it for the next dataset when needed. This differs from an explicitly enabled background server, which publishes its configured catalog.

A stored origin consists of address, port, and password. Its sharing option controls whether a configured origin and password may be passed through SharePlay. Native apps store passwords locally in the Keychain. Knowing an origin does not guarantee that its server is online or reachable through a firewall.

Waiting, closing, and host changes

While no origin is reachable, a client waits and shows the server currently being tried. BorgVR cycles through known origins with their timeouts and retries; new announcements can enable further attempts. Local-network permission should be granted, and the serving client must remain reachable and active.

Closing the host's dataset closes it on clients as well, which then wait for the next selection. Closing a client's dataset asks for confirmation before leaving the session. If the host leaves the session itself, remaining participants may take over, leave SharePlay, or ignore the prompt. Once someone takes over, the prompt disappears on the other devices; simultaneous takeover requests are resolved.

On macOS, establishing the FaceTime call may still require Join in the green SharePlay system menu. BorgVR displays a centered instruction in this situation. Follow that system step instead of starting a second session.

Closing, resetting, and deleting are different

Close dataset
Stops rendering and its associated jobs. The file and saved edit states remain. In SharePlay, the host/client rules above apply.
Select Original
Displays unedited content. Existing variants can be selected again later.
Delete or reset a state
Affects only that variant or the active shared state, not every other variant.
Delete a local dataset from the selector
After confirmation, removes the .data file and its entire .data.edits directory with every variant. Outstanding edit jobs finish shutting down before removal; a dataset still open is protected. Server originals on other devices and separate .tf1d, .marker, .measurement, and .state files are not deleted.
Back up before deletingDelete Dataset is not merely clearing the origin cache. Export or back up variants you need first. The Restore brush can recover voxels within an existing dataset, not deleted files.

Status messages and troubleshooting

The system's local-network permission covers both loading from another device and serving your own data. It does not mean you just enabled a server. If access was denied, check BorgVR's network permission in system settings. A SharePlay control connection alone does not replace this permission or direct reachability of the data source.

Red italic title
The dataset still needs server data. Check Keep a Local Copy, free storage, and connectivity. The title alone is not an error.
Red dot on the Edit tool
Brick updates or persistence are pending. Outstanding updates finish before the next opening. Export prepares them itself; waiting beforehand is not required.
Waiting for Data Source
Check address and native port, password, local-network permission, firewall, and whether the provider is still active. A correct IP alone does not prove that the service is reachable or can open the file.
Synchronizing Edit State
The shared edit state has not finished installing. This message alone does not explain a dataset download failure; also capture origin probing and snapshot transfer in the log.
Disabled trash button or state selector
A state in use, export, preparation, or SharePlay role may block the action. The host can delete unused states while opening once no dataset uses them. State management remains blocked in the active shared dataset.
Lighting controls have no visible effect
Unlit TF ignores lighting parameters. Switch to TF with Lighting or Iso. Also check that the transfer function makes the intended value range visible.

Enable the Log button in Settings when needed and select Info or a more verbose log level. For network issues, include Checking, Could not query, and Loading SharePlay dataset lines with address and port; for edit issues, also include snapshot/brick errors. Record platforms, host and client roles, and the exact sequence of steps. Do not put passwords or access tokens in a report. GUI log history is bounded, so copy relevant messages promptly.

Update reminders

The optional App Store check does not require a custom update server. Show in App Store opens the store, Remind Me Later postpones the reminder, Ignore This Update skips the reported version, and Never Remind Me disables automatic reminders. Choices are saved. Settings can disable checking or re-enable it after Never Remind Me. A SharePlay compatibility message is separate: it means the participating protocol versions do not match.