Quickstart

Open a molecule, inspect what is in its archive, and save a result. This walkthrough uses a bundled water geometry, so you do not need a calculation of your own or a vibe-qc installation.

Outcome: vibe-view-demo.qvf, an interactive view, a terminal view, and optional exports. The demo contains geometry only: it has no calculated energy, electron density, orbitals or spectrum.

Already have ORCA results? Follow Using vibe-view with ORCA for a complete calculation workflow, from the original files to orbital and spectrum inspection and a portable QVF archive.

For a worked ORCA example, choose the starting point that matches your task:

What you want to try	Tutorial
Prepare an input, submit it and open the result	Water through ORCA and vq
Inspect calculated vibrations, Raman and VCD	Peroxide spectra
Combine selected normal modes into a new geometry	Selected-mode displacement
Calculate that geometry and inspect its new orbitals and charges	Displacement → vq → ORCA → vibe-view

The peroxide tutorial includes downloadable calculated QVF archives. You can open them directly without ORCA or vq; rerunning the calculations needs both programs configured as described in the tutorial.

1. Clone and install

You need Git and Python 3.11 or newer. These install commands are for macOS and Linux; the installation guide covers prerequisites and other options. If you already installed the viewer, skip to step 2.

Clone the public source repository:

git clone https://github.com/vibe-qc/vibe-view.git

Then install from the repository root:

cd vibe-view
./scripts/install.sh
source .venv/bin/activate

2. Check the installation

vibe-view doctor

Every optional mode gets a row saying whether it is ready and, when it is not, the command that would fix it. A Core install: ready line is enough to continue.

3. Make a file to look at

vibe-view demo

demo writes a bundled water structure as a real QVF archive and validates it. It needs neither vibe-qc nor an input file of your own. When it finishes it prints the browser, desktop, terminal and headless next steps for the file it just wrote.

-o FILE chooses the output path; --force replaces an existing demo.

Note

vibe-view quickstart is a different command. It runs a real vibe-qc calculation and then opens it, so it requires vibe-qc in the same environment. demo is the one that works on a bare viewer install.

4. Look at it

vibe-view open vibe-view-demo.qvf     # open the file created in step 3

The built-in demo after opening Structure and choosing the light background.

You should see one oxygen and two hydrogens. Drag to rotate, use the wheel to zoom, and press r to reset the camera. The viewer runs until you press Ctrl+C in its terminal; closing the browser tab alone does not stop it. Use another terminal for the inspection commands below, or stop the viewer first.

Or pick the surface that suits where you are:

vibe-view open vibe-view-demo.qvf      # browser          — needs the [viewer] extra
vibe-view desktop vibe-view-demo.qvf   # native window    — source checkout + Electron
vibe-view tui vibe-view-demo.qvf       # interactive TUI  — needs the [tui] extra
vibe-view show vibe-view-demo.qvf      # one frame of braille, then exit — needs nothing

show is the one to remember for a login node: it renders the real 3-D scene as Unicode braille with no display server, no OpenGL and no X forwarding.

The same water structure rendered by vibe-view show, directly from its terminal output.

5. Ask it questions without opening anything

vibe-view info vibe-view-demo.qvf              # metadata and section sizes
vibe-view info vibe-view-demo.qvf --json       # ... for a script
vibe-view validate vibe-view-demo.qvf          # SHA-256 integrity check of every section
vibe-view table vibe-view-demo.qvf             # list available scientific tables

info should list one structure section. validate should succeed. table reports no tabulatable sections: the geometry demo has no vibration, charge or orbital table. That is expected, not an incomplete installation.

Already have data?

Pick the shortest route:

Goal	Command
Open a QVF or a supported loose file in a browser	vibe-view open INPUT
Work over SSH with no display	vibe-view show FILE.qvf or vibe-view tui FILE.qvf
Use a native window from the source checkout	vibe-view desktop INPUT
See which loose formats this installation supports	vibe-view formats
Convert a loose file into a persistent QVF	vibe-view import INPUT
Render an archive with no display	vibe-view capture FILE.qvf -o figure.png
Compare two calculations	vibe-view diff a.qvf b.qvf or vibe-view compare a.qvf b.qvf

vibe-view open accepts loose structure files directly — you do not have to convert first. Use import when you want a persistent QVF to keep.

A figure, headlessly

PNG capture needs an offscreen OpenGL context. Check that the host supports it before rendering. If it fails, the terminal view above still works; see headless setup.

vibe-view capture-selftest
vibe-view capture vibe-view-demo.qvf -o structure.png
vibe-view batch *.qvf --volumes -o gallery/
vibe-view export vibe-view-demo.qvf -f html -o molecule.html      # standalone 3-D page

From Python

from vibeview import info, validate, capture_structure, render_terminal

data = info("vibe-view-demo.qvf")
print(data["sections"])              # the structure section
print(validate("vibe-view-demo.qvf")["valid"])

capture_structure("vibe-view-demo.qvf", "structure.png")

# Same renderers, text instead of a PNG — and no OpenGL context needed,
# so this one works on a headless compute node.
print(render_terminal("vibe-view-demo.qvf", size=(80, 24)))

The full surface is in the Python SDK reference.

Where to go next

• From input to a shareable result — a complete, reproducible import, inspection and export workflow.

• A tour of the viewer — panel by panel, with screenshots.

• What vibe-view can show you — every section kind and the surface that renders it.

• The browser viewer, terminal mode and figures without a display — the reference for each surface.

• CLI reference — every command, grouped by task.

• The QVF format — what is in the archive you just opened.

• Troubleshooting — when a mode will not start.

Run vibe-view examples to see worked workflows, and vibe-view examples --copy DIR to drop the bundled example files somewhere you can edit them.