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.
- 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.
- 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.
- 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.
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.
- 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.
- BorgVR finishes outstanding brick updates in the chosen state before opening. A progress dialog appears when needed; there is no separate foreground/background choice.
- 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.
| Action | Effect |
|---|---|
| Select Original | Displays the unchanged volume without removing other states. |
| New state (+) | Starts an independent empty variant. |
| Duplicate | Copies current edits into another independently editable variant. |
| Rename | Assigns 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 / Reset | Resets 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?
| Part | Contents and storage |
|---|---|
.data | Original 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, .state | Transfer 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.
Export a permanently edited dataset
- Select the desired edit state and choose Export Edited Dataset in the Brush tool. Enter a name and description.
- 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.
- 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.
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.
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.

