BorgVR Guide

Mac

BorgVR for macOS

The complete desktop workspace for multi-channel volume data, dockable tools, objects, measurements, GSC and MCP automation, and collaboration.

Mandelbulb volume

The interface in pictures

The illustrated UI tour explains the control bar, color-coded modes and reset buttons, transfer functions, lighting, objects, measurements, and volume editing using current macOS screenshots.

BorgVR control bar with a reset above every interaction mode
Rendering mode, interaction mode, and tool windows are separate choices. The UI tour explains how they relate.

Workflow

  1. Open a local BorgVR file, a recent dataset, or a remote-server catalog from the main menu.
  2. Select rendering and interaction modes in the render window. Dragging rotates the model with an arcball; trackpad or mouse gestures translate and scale it.
  3. Open only the tools you need and dock them to the render window or detach them into separate windows.

A recent dataset that is no longer reachable is checked only when opened. BorgVR then reports the error without delaying the start screen with speculative network checks.

Render window and dockable tools

The top control bar contains close, SharePlay, Synchronize View, participants, WebGPU link, dataset information, state load and save, and optional log, performance graph, and docking. Rendering and interaction modes plus color-matched tool buttons appear below.

A dark-red italic dataset name means its data source still depends on the server. After complete local caching, the title returns to regular type and black in light appearance; dark appearance uses appropriately lighter colors. Without a local copy, a remote dataset remains red and italic. The red dot on Edit instead indicates pending brick updates, not network activity.

Rendering controls
May overlay the image, dock to the window, or live in a separate window.
TF/isovalue editor
Follows the rendering mode, provides data-channel selection for multi-channel volumes, and can dock beside the rendering area.
Lighting
Arcball for light direction and color controls for ambient, diffuse, and specular light with a live preview sphere.
Objects window
Active object asset, spheres, strokes, and mesh instances with multiple selection plus loading and saving of .marker files.
Measurements window
Edit length, area, and volume measurements and load or save .measurement files.
Performance
Shows frame rate, timing history, and periods using a reduced sampling rate for diagnostics.

Interaction modes

  • Model: Arcball rotation, translation, and scaling of the volume.
  • Clipping: Manipulation of the clipping plane.
  • Transfer: Direct manipulation of the transfer-function curve in the rendering area.
  • Drawing: Draw spatial strokes; points may optionally project onto the visible surface using depth from the previous raycasting frame.
  • Placement: Place, select, and drag the active sphere or imported polygon object.
  • Measurement: Place and edit points for paths, areas, or volumes.
  • Edit: Erase voxels or restore original values with a spherical brush. The Brush button opens the editor; Shift temporarily switches to the opposite brush.

Objects support multiple selection, shared color, size, and direction changes, and independent visibility. Measurements use physical voxel spacing and automatically choose an appropriate unit for length, area, or volume.

Keyboard shortcuts

Renderer shortcuts work while the rendering view has keyboard focus, so typing in a text field never triggers a rendering action. Number keys 1–7 select interaction modes; Shift+1–3 select TF, TF with lighting, and Iso rendering. App commands using ⌘ do not require focus on the rendering view. Button tooltips also show their shortcuts.

AreaActionShortcut
InteractionModel1
Clipping2
Transfer3
Draw4
Place5
Measure6
Edit volume7
Erase volumeK
Restore original volumeU
Smaller brush[
Larger brush]
Rendering modeTF⇧1
TF + lighting⇧2
Iso⇧3
Rendering viewMove volume in the image plane← → ↑ ↓
ScreenshotS
Extract isosurface as OBJ (Iso mode)X
Reset all rendering parametersR
Toggle brick visualizationB
Synchronize viewV
Show or hide controlsTab
TF/isovalue editorE
LightingL
ObjectsO
MeasurementsM
PerformanceP
LogG
Dataset informationI
WindowsDock or detach rendering controlsD
App commandsOpen dataset⌘O
Import / Export⇧⌘O
Save dataset state⌘S
Restore dataset state⌘R
Dataset information⌘I
Close dataset⇧⌘W
Start recording⌥⌘R
Stop and save recording⌥⌘S
Run script⇧⌘R
Stop script⌘.
Start SharePlay⇧⌘P
Synchronize view⌥⌘V
Copy WebGPU link⌥⌘C

Edit volume

Dataset and isosurface exports are disabled during SharePlay. While an export is running, edits and edit-state changes are blocked for every input source, including scripts and MCP. If SharePlay starts during an export, that export is cancelled before the shared edit state is installed.

If saved edit states exist, BorgVR asks which one to use before opening a dataset normally. Original stays unchanged. The last personal state is preselected; the trash button deletes one state after confirmation. The Brush panel lets you select, create, duplicate, and rename states.

Pending volume updates in the selected edit state are completed automatically before opening. BorgVR shows progress when needed; no additional choice is required. Export and preparation share the same exact bottom-up rebuilding service with Metal acceleration when available and a CPU fallback.

SharePlay uses a separate shared edit state initialized from the host's selected state. Joining receives its complete mask without overwriting personal states. State selection is locked during a session. Erase/restore cursors and brush operations are shared. Leaving restores the previous personal selection; the shared work remains available as a separate SharePlay state.

Edit states are stored beside the .data file in its .data.edits companion folder; only built-in datasets use private app storage. Remote datasets use the local dataset directory. Discard All Edits restores only the active state to the original after confirmation; other saved states are preserved. During SharePlay, this clears the shared state for all participants.

Select the red Edit Volume mode with the 7 key or the mode bar. The Brush button directly below opens and closes its separately dockable editor. Erase (K) sets voxels inside the spherical brush to zero in every channel. Restore (U) restores the original values there, including after overlapping erase strokes. Hold Shift to temporarily use the opposite brush. The original file stays intact.

A small red dot in the top-right corner of the Edit Volume button indicates pending background brick updates. It disappears once calculation and saving have finished.

Export Edited Dataset opens a dialog for the name and description. During calculation it displays progress; Cancel stops the export and removes incomplete export files. Afterwards, choose the save location. The name and description are stored in the new dataset. Export preserves the source compression and copies unchanged bricks without decompressing or recompressing them.

The brush preview follows the pointer even when no mouse button is pressed. Click or drag in the rendering view to edit. With Project onto Volume enabled, the brush follows the visible surface; its projection stays stable during a stroke. Without projection, use a depth plane and move it with the scroll wheel or a two-finger vertical gesture. Adjust the radius with the slider, a zoom gesture, or [ and ].

Edits are recorded locally automatically while you work. Bricks update in the background; reopening finishes outstanding work in the selected state before rendering. SharePlay uses a separate shared state. Zero is rendered through the selected transfer function and is not necessarily transparent.

Export Edited Dataset creates a new, independent .data file with a new dataset ID. Export uses the edit state captured at its start, computes all levels of detail and value ranges, and produces a dataset that requires no edit sidecars.

The Data and Edit States chapter explains Original, new variants, duplication, renaming, resetting, deletion, and SharePlay restrictions. In the opening selector, the host may delete unused variants once they are no longer in use.

Import, local files, and servers

The integrated converter creates BorgVR files from DICOM, NRRD/NHDR, PVM, and QVIS. Export mode reconstructs any stored level of detail as a flat, uncompressed NRRD volume. Object import reads OBJ, STL, PLY, and USD, adds a description and UUID, and writes the compact .mesh format; object export creates OBJ/MTL and, when needed, a texture file.

Single- and multi-channel data can be imported and exported. BorgVR renders up to four channels with 8 or 16 bits per channel; scalar datasets additionally support 32 bits.

Remote servers are configured with hostname, native BorgVR port, and optional password. Normal opening tries the displayed server first, then known alternatives. Progressive loading shows the volume during transfer; without it, the Open dialog first downloads the complete file. Datasets announced through SharePlay, including ad-hoc connections, instead open progressively. Keep a Local Copy is a separate storage option. Saved passwords live in the Keychain.

After confirmation, the dataset selector's trash button deletes a local .data file and every variant in its .data.edits directory. Separate transfer-function, object, measurement, and view files remain. See Closing, Resetting, and Deleting for backup guidance and deletion scope.

Export an isosurface as polygon geometry

Choose Iso mode and the desired isovalue. Extract Isosurface beside the render-mode selector, the corresponding menu command, or X with rendering focus opens the OBJ destination dialog. Extraction includes the current edit state, computes geometry rather than a screenshot, and provides progress and cancellation. It is blocked during SharePlay. Ordinary LoD export to NRRD is available in the Import/Export wizard instead; use Brush export for a new permanently edited .data file.

The Mac can run its own native dataset server and HTTPS WebGPU server. A button in the rendering window copies a dataset-specific browser link once the active dataset is available through that server.

SharePlay

Mac, iPhone, and iPad use a common view state by default. Synchronize View detaches or reattaches the Mac while rendering mode, transfer functions for every channel, isovalue, lighting, clipping, objects, and measurements remain synchronized. Reattaching adopts the current shared view.

The host announces the dataset ID, its ad-hoc address, and known shareable origins. Every participant merges these into its origin cache and may advertise a local copy in turn. This allows a reachable client to provide data when the host is behind a firewall.

If BorgVR shows a centered Join instruction after FaceTime connects, click Join in the green SharePlay system menu instead of starting another session. Ad-hoc servers offer only the current host dataset and are advertised automatically when a local download completes later. See the SharePlay workflow for waiting states, host changes, and shared edits.

Scripting

The macOS app supports GSC scripts for reproducible interaction, rendering parameters, objects, measurements, import, export, and screenshots. Start Recording captures user actions; Stop and Save coalesces consecutive transforms and transfer-function or clipping changes and writes an executable .gsc script. The GSC reference documents the language, examples, and every command.

Reproducible resultsSaved dataset state or recorded scripts recreate publication and presentation views precisely, including objects and measurements.

Dataset state and MCP

Save Dataset State stores transfer functions, objects, measurements, transform, rendering mode, isovalue, lighting, clipping, and visibility under the dataset name. Restore Dataset State reloads these parts together.

The independent MCP server exposes the same application controls to trusted AI agents. Agents can inspect metadata, open and close datasets, change rendering parameters and annotations, wait for completed frames, and retrieve screenshots. Local access uses HTTP without a token; network access uses HTTPS and an access token.

Settings

Simplifying the user interface

Under Settings → User Interface, choose visible rendering and interaction modes. At least one mode of each kind remains enabled; a selector with only one mode disappears. RGB/RGBA rendering is unaffected. Hide the reset row and the panel-button row, or hide individual panel buttons. Diagnostic controls are configured here as well. Preferences stay local and are included in settings export and import. This simplifies the UI rather than restricting SharePlay or automation access. On visionOS, Muse and PSVR retain their independent tool modes.

If SharePlay activates a locally hidden rendering mode, it temporarily appears selected and disabled in the selector, even when only one local mode is allowed. The extra entry disappears when a locally allowed mode becomes active again; preferences remain unchanged. On macOS and iOS, TF/isovalue, object, measurement, and brush panel buttons require their associated interaction modes; the object button remains available for either drawing or placement. Lighting stays independent. On visionOS, panel buttons remain independent of hand modes so Muse and PSVR can still use them.

The sidebar separates General, User Interface, Rendering, Performance, Data Source, Import, Export, External Data Sources, Servers, SharePlay, and MCP. General includes automatic saving and update checks; User Interface controls visibility of interface elements and diagnostic buttons. Rendering controls appearance and sampling; Performance holds LOD, paging, atlas, and hash parameters. Data Source selects the local directory; External Data Sources manages remote connections and download options. Servers controls your own services.

  • Automatic loading and saving of transfer functions, objects, measurements, and visualization state
  • Solid or gradient background
  • Static and dynamic oversampling
  • Randomized sample phase
  • Brick visualization and log button
  • Remote loading and local copies
  • Local, ad-hoc, and WebGPU servers plus independent MCP server
  • App Store update checks