Introduction

Viso is a GPU-accelerated 3D protein visualization engine built in Rust on top of wgpu. It powers the molecular graphics in Foldit, rendering proteins, ligands, nucleic acids, and constraint visualizations at interactive frame rates.

Viso is designed as an embeddable library – you give it a window or surface, feed it structure data, and it produces a 2D texture. The host decides what to do with that texture: display it in a winit window, paint it onto an HTML canvas, write it to a PNG, or drop it into a dioxus/egui texture slot.

#![allow(unused)]
fn main() {
use viso::Viewer;

Viewer::builder()
    .with_path("1ubq")           // PDB code or local .cif/.pdb/.bcif path
    .with_title("My Viewer")
    .build()
    .run()?;
}

Features

Rendering

• Ray-marched impostors for pixel-perfect spheres and capsules at any zoom
• Post-processing pipeline – SSAO, bloom, FXAA, depth-based outlines, fog, tone mapping

Interaction

• Arcball camera with animated transitions, panning, zoom, and auto-rotate
• GPU picking – click to select residues, double-click for SS segments, triple-click for chains, shift-click for multi-select

Animation

• Smooth interpolation, cascading reveals, collapse/expand mutations
• Per-entity targeted animation with configurable behaviors

Performance

• Background mesh generation on a dedicated thread with triple-buffered results
• Per-group mesh caching – only changed groups are regenerated
• Lock-free communication between main and background threads

Configuration

• TOML-serializable options for display, lighting, color, geometry, and camera
• Load/save presets, per-section diffing on update

How It Works

File (.cif/.pdb/.bcif)  ──or──  Vec<MoleculeEntity>
        │                                │
        ▼                                │
 molex::parse ───▶ MoleculeEntity◄─┘
        │
        ▼
     Scene (live renderable state, dirty-flagged)
        │
        ├───▶ SceneProcessor (background thread)
        │         mesh generation + triple buffer
        │
        ▼
     Renderer (geometry → picking → post-process)
        │
        ▼
     2D texture ───▶ winit / canvas / PNG / embed

For the full architecture, see Architecture Overview.

Where to Start

Embed viso in your application:

• Quick Start – standalone viewer walkthrough
• Engine Lifecycle – creation, initialization, shutdown
• The Render Loop – per-frame sequence
• Handling Input – mouse and keyboard wiring

Understand how Foldit uses viso:

• Scene Management – groups, entities, focus
• Dynamic Structure Updates – Rosetta and ML integration
• Options and Presets – TOML configuration

Dig into viso internals:

• Architecture Overview – system diagram and data flow
• Rendering Pipeline – geometry pass and post-processing
• Background Scene Processing – threading model
• Animation System – transitions, behaviors, and interpolation