Documentation

Overview

NVAP is a desktop application for two-channel 3D microscopy of brain tissue. It loads image stacks, cleans and aligns them, renders both channels together in interactive 3D, computes morphometric and spatial-association metrics, and exports them as CSV. It runs on CPU everywhere and uses a GPU automatically when a supported one is present.

Metrics are physically calibrated using voxel spacing in micrometres. The default spacing is x = 0.331, y = 0.331, z = 0.4 µm. The separate Z height scale control only changes how the volume is drawn in 3D; it does not change measurements.

Installation

Portable executable

Download the Windows build and double-click NVAP.exe. The public download is a CPU-safe portable build with the bundled sample dataset included.

Windows SmartScreen or your antivirus may flag the download. NVAP is not code-signed — it's a small, independently built app, and unsigned .exe files with no download history are routinely flagged by SmartScreen and heuristic antivirus scanners even when they contain nothing malicious. If you see “Windows protected your PC,” click More info, then Run anyway. If your browser blocks the download outright, use Keep / Keep anyway when prompted.

To confirm the file you received matches what we published, compare its hash against the one served on this site (also returned by /metadata):

# PowerShell — compare against the published hash below
Get-FileHash .\NVAP.exe -Algorithm SHA256

# Published SHA-256
…

DirectML build (AMD / Intel GPUs)

The default portable build above is deliberately CPU-only — it excludes Torch entirely so it stays small and avoids the antivirus/SmartScreen scrutiny that unsigned, torch-bundled executables tend to attract. If you have an AMD or Intel GPU and want GPU acceleration, download the DirectML build instead: same app, larger download (Torch + DirectML bundled), GPU-accelerated. It only runs on Windows.

# PowerShell — compare against the published hash below
Get-FileHash .\NVAP.exe -Algorithm SHA256

# Published SHA-256 (DirectML build)
…

From source

# From the repo root (Windows / PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
nvap --debug

For AMD or Intel GPUs on Windows, use a Python 3.12 environment with the DirectML extra:

uv venv --python 3.12 .venv-gpu
.\.venv-gpu\Scripts\Activate.ps1
python -m pip install -e ".[dev,directml]"
nvap --debug

Loading data

Recommended: use an RGB slice folder when you can. It is the easiest workflow because you do not have to split the stack into separate Green and Red folders first.

• Recommended: RGB slice folders. Put one image per z-slice in a single folder. Filenames must include a z-index such as sample_z030.png or sample_z030c1+2.png. Pixels should be red-only for vasculature, green-only for microglia, or black background. Blue signal is not accepted, and pixels that mix red and green in the same location will fail the red/green-only check.
• Separated per-slice folders. If your data is already split by channel, filenames can carry both a z-index and a channel marker: ..._z030c1.png (green) and ..._z030c2.png (red). A common layout is Input/Segmented/Green and Input/Segmented/Red.
• Single stack files. Each channel folder may instead hold one multi-page TIFF with all z-slices. A single red/green RGB stack file is also accepted when the red and green channels follow the same red-only, green-only, black-background rule.

In the app, click Load Dataset (or Ctrl+L). For an RGB slice folder, choose that folder as the dataset root. For manually separated sources, choose the vasculature (red) source first, then the microglia (green) source. NVAP interpolates missing z-slices, aligns the shared z-range, and renders the result.

Multi-sample project sets

A multi-sample project set is a parent folder that contains one loadable dataset folder per sample. Each sample can use the recommended RGB slice-folder layout, the separated Green/Red layout, or compatible TIFF stacks.

Study/
  Sample_001/
    sample001_z001.png
    sample001_z002.png
    sample001_z003.png
  Sample_002/
    sample002_z001.png
    sample002_z002.png
    sample002_z003.png
  Sample_003/
    Input/
      Segmented/
        Green/
          sample003_z001c1.png
        Red/
          sample003_z001c2.png

Click Load Dataset and choose the parent folder, such as Study/. NVAP scans the child folders for loadable datasets, opens the first sample, and shows a project-set bar with a sample dropdown plus previous/next controls.

Analysis is per selected sample. When you move through a project set, NVAP loads and processes each sample independently: missing z-slices are filled, channels are aligned, automatic cleanup is applied, default thresholds are prepared, and the volume is rendered. The metrics panel and CSV export reflect the currently selected sample, so step through the project set and export each sample when you want one result bundle per specimen.

For best comparisons across many samples, keep naming consistent, use the same voxel spacing unless the microscope settings changed, and avoid mixing RGB-folder and separated-folder conventions inside the same sample folder.

Using the app

NVAP starts in simple mode: Load Dataset → adjust thresholds → export. Toggle Show advanced controls for masking and preprocessing settings.

Rendering controls

• Threshold (green / red) — the intensity cutoff that defines each structure. The same threshold drives the 3D view and every metric.
• Opacity and isosurface toggles — how each channel is drawn.
• Trim first/last Z — exclude edge slices from both the view and all metrics.
• Offset (x/y/z) — shift green relative to red to correct registration; applied identically to the view and the overlap metric, snapped to the nearest voxel.
• Z height scale — a display-only depth scale. Metrics always use physical spacing.

Individual microglia viewer

Enable View one microglia and pick a Cell index to isolate a single component in 3D. Components are ranked largest-first at the current green threshold.

Automatic on load

Every time a dataset finishes loading — including each dataset when you page through a multi-stack project set — NVAP cleans it up automatically:

• Default thresholds (green 0.80, red 0.60) are applied.
• Enhance microglia (clean) runs the selected enhancement on the green channel. Skipped if the dataset already has a cached enhancement.
• Wipe specks removes small isolated blobs from both channels.

The two cleanup passes have on-load toggles in the Microglia Workbench (both on by default). They are always available, so you can turn them off before loading anything.

Keyboard shortcuts

How analytics work

Every metric is computed after applying the active threshold, slice trim, and (for overlap) the registration offset — so the numbers describe exactly the trimmed structure shown in 3D. All volumes are 3D (z, y, x) arrays; lengths are micrometres.

Basic metrics

Per channel: voxel count, physical volume, connected components (26-connectivity), largest component, and red–green overlap in the shared z-range after the green mask is shifted by the whole-voxel offset.

Vascular morphometry

The red mask is skeletonised and measured: volume fraction over retained tissue, centreline length and length density (mm/mm³), radius from a ridge-corrected distance transform along the medial axis, junctions and endpoints, segment length, tortuosity (geodesic ÷ straight-line), and surface-to-volume ratio (boundary faces excluded).

Per-cell microglia morphometry

Each cell is segmented into a soma and processes. Branch topology comes from the soma-excluded skeleton; process tips are the regional maxima of a geodesic field grown from the soma through the visible voxels. Sholl shells are one voxel-diagonal thick. Soma shape is reported as equivalent diameter, roundness and elongation. Distances to vasculature exclude voxels inside a vessel, so a distance is always to the nearest non-overlapping cell voxel.

Neurovascular association

Per-cell distances aggregate into population patterns: perivascular fractions within 5/10/20/50 µm, mean/median cell-, soma- and tip-to-vessel distances, and a tip-leading fraction — how often a process tip reaches a vessel at least as close as the soma does.

CSV exports

Exporting metrics writes a base CSV plus companion files alongside it. Saving as metrics.csv produces:

Snapshot export writes snapshot.png; mesh export writes PLY / OBJ / STL.

Command line

nvap also runs headless operations without opening the GUI.

# Print the selected backend / threads / memory profile
nvap --print-runtime-profile

# Run load + process + metrics without the GUI
nvap --headless-smoke --input Input

# Export meshes headless
nvap --export-mesh --input Input --mesh-format ply

# Force a compute backend
nvap --compute-backend cpu --cpu-workers 4

GPU & backends

NVAP selects a backend at startup, probing CUDA, ROCm, DirectML and Apple MPS in that order, then falling back to CPU if none is usable. Selection is defensive in three layers:

• Selection — the first backend whose device is present.
• Capability probe — a candidate must actually run NVAP's convolutions on the device before it is chosen, so an incompatible GPU is rejected rather than trusted.
• Per-operation fallback — any GPU filter that fails mid-run falls back to the CPU path, so it degrades instead of crashing.

The header status pill shows the active backend, e.g. GPU DirectML or CPU compute. On AMD/Intel Windows GPUs, DirectML requires Python 3.12.

← Back to home