TerminalConverterApp
The Swift converter reads DICOM directories, QVIS, NRRD/NHDR, PVM, and IV3Dm files, exports BorgVR datasets, or creates reproducible synthetic volumes. Import and generation write the bricked BorgVR format.
TerminalConverterApp D <input-directory> <output.data> <description> <brick-size> <overlap>
TerminalConverterApp Q <input-file> <output.data> <description> <brick-size> <overlap>
TerminalConverterApp N <input-file> <output.data> <description> <brick-size> <overlap>
TerminalConverterApp P <input-file> <output.data> <description> <brick-size> <overlap>
TerminalConverterApp I <input-file> <output.data> <description> <brick-size> <overlap>
TerminalConverterApp V <input.uvf> <output.data> <description> <brick-size> <overlap>
TerminalConverterApp F <input.vff> <output.data> <description> <brick-size> <overlap>
TerminalConverterApp Z <input.ozx|input.zarr> <output.data> <description> <brick-size> <overlap>
Import and generation optionally accept --source-info <ISO8601-date-time> <source-text>, for example --source-info 2026-11-01T10:30:00Z "Downloaded from https://example.org/scan". Repeat this option for a longer history; entries retain their command-line order. The source is recorded with its date and time. A current English provenance entry converted by TOOL VERSION is always appended.
Import modes D/Q/N/P/I/Z/V accept --size-x <meters> as the total X extent when the source lacks a physical size. --force-size-x <meters> always sets this extent, even when size metadata exists. Both scale all axes uniformly; Y and Z follow from resolution and relative voxel spacings. Use only one of these options. Applied scaling is recorded in provenance.
TerminalConverterApp Z scan.ozx scan.data "Scan" 32 2 --size-x 0.2
TerminalConverterApp N scan.nrrd corrected.data "Corrected scale" 32 2 --force-size-x 0.2
Mode P reads PVM, PVM2, and PVM3, including the DDS v3d and DDS v3e compression wrappers. Without a size option, relative PVM voxel spacing is preserved proportionally and normalized to a longest total extent of one meter.
Mode I reads ImageVis3D Mobile volumes (IV3Dm version 1) as .i3m files or ZIP archives containing exactly one such volume. It imports the 8-bit scalar values, discards stored gradients, and normalizes relative voxel spacing as for PVM. Transfer functions, scenes, and geometry are not imported. Archives containing multiple volumes must be unpacked first.
Mode V reads ImageVis3D UVF files. Only the full-resolution volume (LoD 0) is imported through a temporary RAW file. Coarser levels, histograms, transfer functions, and geometry are not imported. Relative voxel spacings are preserved proportionally with a longest extent of one meter; use --size-x to supply a known physical size.
Mode F reads scalar Sun/GE VFF files with an ASCII header and signed 8-, 16-, or 32-bit data. Samples are shifted losslessly into an unsigned range. Physical sizes from elementsize, spacing and spacingunit are converted to meters. Without physical size metadata the longest extent defaults to one meter; the size options are also available.
Descriptions containing spaces must be quoted. brick-size and overlap are positive integers.
Mode Z reads local Zarr v3 arrays with named axes and OME-Zarr 0.5 images as .zarr directories or .ozx files. It supports uint8/16/32, int8/16/32, float32/64, up to four channels, Zstandard, gzip, and shards. Signed integers are shifted losslessly; each float channel's global finite range is mapped to UInt16. The highest resolution is imported. Physical units are converted to meters; unitless data use a longest extent of one meter. Zarr v2, time series, and other codecs are explicitly rejected.
Importing image sequences
TerminalConverterApp S ./slices ./scan.data "Color scan" 32 2 0.2 0.2 0.35
Mode S reads a folder of images as slices sorted by filename. Use zero-padded numeric names. All images must have identical dimensions after applying their orientation. The last three values specify the whole volume's physical X, Y and Z dimensions in meters. Images without alpha produce RGB; images with alpha produce RGBA. RGB stores no min/max values; RGBA stores only the alpha range. Native renderers and WebGPU display these colors directly without a transfer function.
Exporting a flat volume
TerminalConverterApp E <input.data> <output.nrrd> <lod>
Export reconstructs the selected level of detail as an uncompressed inline NRRD file. LoD 0 contains the full resolution; higher values select the stored downsampled levels. Brick overlap and boundary padding are removed, and physical voxel spacing is adjusted for the selected level.
Repacking BorgVR files
TerminalConverterApp R input.data repacked.data 32 2
TerminalConverterApp R input.data small.data 32 2 --quantize-8bit
TerminalConverterApp R color.data color-astc.data 64 2 --color-compression astc8x8 --no-lz4
Mode R reconstructs the full resolution into a temporary RAW file and rebuilds all levels of detail with a new brick size, overlap, quantization or compression. Descriptions, physical voxel spacing, channel interpretation, meta text and existing provenance are retained. The output receives a new UUID plus additional repacking and conversion history. Input and output must be different files. Temporary disk space is required for the decoded volume and, if requested, its quantized intermediate.
Without options, the original sample precision and physical size are retained; LZ4 is enabled and ASTC is disabled. --quantize-8bit maps each channel's observed range to 0–255. --no-lz4 disables outer compression. For RGB/RGBA, --color-compression none|astc4x4|astc8x8 selects the brick encoding. ASTC input is decoded first; encoding ASTC again is lossy. Mode R permits overlap 0.
Mode R also accepts additional --source-info entries and --force-size-x <meters> when physical size should be explicitly changed.
Synthetic datasets
TerminalConverterApp C <algorithm[,algorithm...]> <bytes-per-component> <components> \
<size-x> <size-y> <size-z> <output.data> <description> \
<brick-size> <overlap>
| ID | Generator | Execution |
|---|---|---|
L | Linear test data | CPU |
F | Single-precision Mandelbulb | Metal with automatic CPU fallback |
D | Double-precision Mandelbulb | CPU |
J | Quaternion sine Julia set | Metal with automatic CPU fallback |
B | Mandelbox | Metal with automatic CPU fallback |
G | Gyroid | Metal with automatic CPU fallback |
P | 3D Shepp-Logan phantom | Metal with automatic CPU fallback |
T | Frequency chirp with brick-boundary test | Metal with automatic CPU fallback |
U | Scalar full-range UInt32 test | CPU |
GPU generators operate slice by slice, allowing large volumes to be created without keeping the complete result in GPU memory. For multi-channel data, provide one comma-separated generator identifier per channel in channel order; one identifier is applied to every channel. Multi-channel data supports 8 or 16 bits per channel, while scalar data additionally supports 32 bits.
TerminalConverterApp C F,J 2 2 512 512 512 MandelbulbJulia.data \
"Mandelbulb and quaternion Julia set" 64 2
TerminalConverterApp --help shows complete syntax; --version prints the tool version.
TerminalServerApp
The Swift server publishes .data, .tf1d, .mesh, .marker, and .measurement files from one directory. By default, it refreshes the catalog every ten seconds.
TerminalServerApp --directory /path/to/datasets \
--port 12345 --web-port 8080
--directory, -d- Directory containing datasets, transfer functions, meshes, object files, and measurements; defaults to the home directory.
--port, -p- Native BorgVR protocol port.
--max-bricks, -m- Maximum number of bricks per GETBRICKS request.
--password- Optional password for native and WebGPU clients. Without this option,
BORGVR_SERVER_PASSWORDis used. An explicit value takes precedence; an empty value disables password protection. --scan-interval- Catalog refresh interval in seconds;
0disables rescanning. --web-port- Enables the embedded WebGPU server on this port.
--web-http- Uses local HTTP instead of HTTPS and binds only to
localhost. --web-certificate- PKCS#12 certificate as
.p12or.pfx; supply its password with--web-certificate-password. --log-file- Also appends log output to the specified file.
Automatic import
TerminalServerApp --directory /srv/borgvr \
--auto-import /srv/borgvr-inbox --auto-import-interval 10
The Swift command-line and GUI servers share an auto-importer. It waits for two identical snapshots of file sizes, timestamps, and the file list. The default interval is ten seconds. Directories are tried as Zarr, then DICOM; files use the existing volume readers. The CLI uses default import parameters; the GUI uses its import settings. Completed datasets immediately enter the catalog; existing output files are preserved.
Warning: processed sources are deleted, including unreadable files. Use a dedicated inbox; the output directory must be outside it. Cancellation, changes during import, and output I/O failures preserve pending data. Two stable checks are a completion heuristic: do not pause an unfinished copy for longer than the check interval. The reserved log.txt records successes and failures and is never imported or deleted.
Guided Import
TerminalServerApp --directory /srv/borgvr --auto-import /srv/borgvr-inbox \
--auto-import-mode guided
This mode checks only whether import.json is unchanged across two polls. Copy the data first and write the JSON file last. Unlisted files are untouched. In the GUI, the info button beside the mode selector copies this example to the clipboard:
[
{
"source": "scan.nrrd",
"destination": "head.data",
"description": "Head scan",
"sizeMeters": [0.2, 0.15, 0.1]
},
{ "source": "dicom-series" }
]
Only source is required and must name an existing direct file or directory. Paths, ., .., links, and reserved names are rejected. Optional destination must be a simple filename; .data is appended if no extension is supplied. Existing outputs are never overwritten. description is optional. Optional sizeMeters specifies positive total dimensions [X,Y,Z] in meters, not voxel size. JSON files are limited to 1 MiB and 1024 entries.
After processing, import.json is removed even if the JSON was invalid or an import failed. Results remain in log.txt. A replacement request arriving during processing is not deleted.
Synchronization
TerminalServerApp --directory /srv/borgvr \
--sync-server server-a.example 12345 300 secret \
--sync-server server-b.example 12345 300
--sync-server is repeatable. The interval must be at least ten seconds; the optional password is not echoed in runtime output. Datasets, transfer functions, marker files, and mesh assets are synchronized, incomplete dataset transfers resume, and alternate sources are tried after a stall.
BORGVRServerCPP
The C++17 server is the cross-platform alternative for macOS, Linux, and Windows. On macOS or Linux, make first builds a small bootstrap program that embeds the contents of web/ into the server using LZ4 compression.
cd BORGVRServerCPP
make
make CONFIG=debug
make run ARGS="--directory /path/to/datasets --port 12345 --max-bricks 64 --web-port 8080"
The C++ server uses the same option names as the Swift server, including --directory, --port, --max-bricks, --log-file, and repeatable --sync-server entries.
BORGVRServerCPP --directory /data/BorgVR --port 12345 --max-bricks 64 \
--sync-server 192.168.1.10 12345 300 secret
The client password can be supplied through BORGVR_SERVER_PASSWORD so it does not appear in the process list. An explicit --password overrides the environment variable.
A Visual Studio solution is also included for Windows. The generated files src/GeneratedWebAssets.cpp and src/GeneratedWebAssets.h are build artifacts and are not tracked in the repository.
Output and automation
While either server is running, l0 selects developer/debug output, l1 normal information, l2 warnings, and l3 errors only. l lists the available datasets; i repeats the startup and configuration information.
Both Swift tools report their version with --version and return a non-zero exit status for invalid arguments. The converter logs dimensions, brick counts, compression statistics, value range, metadata, file size, and elapsed time, making it suitable for reproducible pipelines.

