Viso

Viso is a GPU-accelerated 3D protein visualization engine written in Rust. It renders interactive, real-time views of macromolecular structures from PDB and mmCIF files on the GPU via wgpu.

It includes a post-processing pipeline (bloom, SSAO, FXAA, tone mapping), background mesh generation, and an animation system for structural transitions.

For architecture details, integration guides, and deep dives into individual subsystems, see the full documentation.

Features

• Post-processing pipeline: bloom, screen-space ambient occlusion, FXAA anti-aliasing, edge outlines, tone mapping
• Ray-marched impostors: pixel-perfect sidechains and ball-and-stick atoms at any zoom level
• Interactive camera: arcball rotation, panning, zoom, auto-rotation
• GPU picking: click to select individual residues, double-click to select segments, triple-click to select chains, shift-click for multi-select
• Animation system: snap, smooth (cubic-hermite), and cascade transitions, with per-entity overrides
• RCSB integration: pass a 4-character PDB ID and Viso downloads the structure automatically
• TOML-based presets: configure display, lighting, coloring, geometry, and post-processing via preset files
• Background scene processing: mesh generation runs on a dedicated CPU thread to keep the render loop responsive

Prerequisites

Viso requires a Rust toolchain. Install one via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then add the nightly toolchain (used for formatting):

rustup toolchain install nightly
rustup component add rustfmt --toolchain nightly

Verify both are available:

cargo --version
cargo +nightly fmt --version

GUI panel (viso-ui)

The default build embeds a WASM-based options panel. On first cargo build, the build script runs Trunk automatically to compile it. Two extra tools are required:

# WASM compilation target
rustup target add wasm32-unknown-unknown

# Trunk (WASM bundler); install once
cargo install trunk

If Trunk or the WASM target is missing, the build still succeeds but the panel will be non-functional. To skip the GUI entirely, build with --no-default-features --features viewer.

Platform-specific dependencies

Linux: the default build includes a GUI webview panel, which requires GTK3 and WebKit2GTK:

# Debian/Ubuntu
sudo apt-get install libgtk-3-dev libwebkit2gtk-4.1-dev

# Fedora
sudo dnf install gtk3-devel webkit2gtk4.1-devel

# Arch
sudo pacman -S gtk3 webkit2gtk-4.1

macOS and Windows require no additional system dependencies beyond those listed in GUI panel above.

Building

# Debug build
cargo build

# Optimized build (recommended for interactive use)
cargo build --release

Running

Viso takes a single argument: either a 4-character PDB ID or a path to a local .cif/.pdb file.

# Download and visualize a structure from RCSB PDB
cargo run --release -- 1ubq

# Visualize a local file
cargo run --release -- ./my_structure.cif

When given a PDB ID, Viso downloads the corresponding mmCIF file from RCSB and caches it in assets/models/.

Controls

Input	Action
Left-click drag	Rotate
Shift + drag	Pan
Scroll wheel	Zoom
Click	Select residue
Double-click	Select secondary structure segment
Triple-click	Select chain
Shift + click	Multi-select
Q	Recenter camera on focus
Tab	Cycle focus through entities
` (backtick)	Reset focus to all entities
R	Toggle auto-rotation
T	Toggle trajectory playback
I	Toggle ion visibility
U	Toggle water visibility
O	Toggle solvent visibility
L	Cycle lipid display mode
Escape	Clear selection

Key bindings are defined in the KeyBindings table in code.

Logging

Viso uses env_logger. Set the RUST_LOG environment variable to control log output:

RUST_LOG=info cargo run --release -- 1ubq

License

All rights reserved. See LICENSE.md for details.

Contributions are welcome under the terms of the Contributor License Agreement.