P R O T E I N V I E W

Explore molecular structures in your terminal

_{Nucleosome core particle — histone octamer wrapped in DNA, rendered with Kitty graphics protocol}

---

Terminal molecular structure viewer — load, rotate, and explore proteins, nucleic acids, and small molecules from PDB/CIF files right in your terminal. No browser, no GUI, no dependencies.

Features

• 3-tier render modes — Braille, HD, and FullHD (Sixel/Kitty) with automatic SSH detection
• PNG-compressed Kitty protocol — ~10-20x smaller than raw RGBA, making FullHD viable over SSH
• Cartoon ribbon visualization — Lambert-shaded ribbons with depth fog for helices, sheets, and coils
• RNA/DNA support — backbone, wireframe, and cartoon modes with base-type coloring
• Small molecule rendering — ligands as ball-and-stick, ions as spheres
• Interface analysis — inter-chain contacts, binding pockets, and interaction visualization (H-bonds, salt bridges, hydrophobic contacts)
• 7 color schemes — structure, chain, element (CPK), B-factor, rainbow, pLDDT (AlphaFold)
• Interactive controls — vim-style rotation, zoom, pan with auto-rotation
• PDB & mmCIF — both formats supported, with RCSB PDB fetch (--fetch)
• Headless FullHD export — render a pixel-perfect PNG for agents and scripts without starting a nested TUI
• Single static binary — zero runtime dependencies

Render Modes

Three rendering tiers to match your terminal and connection:

_{Left: Braille (works everywhere, including SSH/tmux) · Middle: HD (Lambert-shaded braille) · Right: FullHD (Kitty pixel graphics)}

Mode	Key	Quality	SSH Performance
Braille	default	Text-based, monochrome per cell	Excellent
HD	m	Shaded braille with lighting + depth fog	Excellent
FullHD	M	Sixel/Kitty pixel graphics	Good (PNG compressed)

--hd is SSH-aware: defaults to HD over SSH, FullHD locally. Use --fullhd to force pixel graphics.

Visualization Modes

_{Left: Cartoon (ribbon) · Middle: Wireframe (all-atom) · Right: Backbone (CA trace)}

Mode	Description
Cartoon	Smooth ribbon rendering — helices, beta-sheets, and coils with Lambert shading. Default.
Wireframe	All-atom bonds including inter-residue peptide and phosphodiester linkages.
Backbone	CA trace (proteins) / C4' trace (nucleic acids) with spheres and thick connecting lines.

Interface Analysis & Interactions

_{Left: Interface residue coloring with sidebar panel · Right: Dashed interaction lines (H-bonds, salt bridges, hydrophobic contacts)}

Press f to toggle interface mode — highlights contact residues across chain boundaries with a detailed sidebar. Press I to overlay interaction lines:

Color	Interaction	Distance
Cyan	Hydrogen bond	≤ 3.5 Å
Red	Salt bridge	≤ 4.0 Å
Yellow	Hydrophobic contact	≤ 4.5 Å
Gray	Other	≤ 4.5 Å

Nucleic Acids

_{B-DNA dodecamer in wireframe mode with CPK element coloring}

Full support for DNA and RNA structures — backbone traces, wireframe bonds, and cartoon ribbons with nucleotide base-type coloring (A=red, U/T=blue, G=green, C=yellow).

AlphaFold & pLDDT

_{AlphaFold prediction with pLDDT confidence coloring — blue (high confidence) to orange/yellow (low confidence)}

Automatically detects AlphaFold structures and offers pLDDT confidence coloring. Cycle through color schemes with c.

Installation

Requires Rust 1.85+. If you don't have Rust, install it with:

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

Then install proteinview:

git clone https://github.com/001TMF/ProteinView.git
cd ProteinView

# Basic install
cargo install --path .

# With RCSB PDB fetch support
cargo install --path . --features fetch

# Update an existing installation
cargo install --path . --force

Quick Start

# View a local PDB file
proteinview examples/1AOI.pdb

# HD mode (fast text-based shading)
proteinview examples/4HHB.pdb --hd

# FullHD pixel mode (Kitty/Sixel terminals)
proteinview examples/4HHB.pdb --fullhd

# Headless FullHD pixel snapshot (no alternate screen or terminal probing)
proteinview examples/4HHB.pdb --snapshot 4HHB.png

# Fetch from RCSB and export a 1200x800 FullHD frame for inline display
proteinview --fetch 1UBQ --snapshot 1UBQ.png \
  --snapshot-width 1200 --snapshot-height 800

# Fetch from RCSB PDB
proteinview --fetch 1UBQ

# Choose color scheme and visualization
proteinview examples/1UBQ.pdb --color rainbow --mode wireframe

# FullHD biological interface view focused on chain A
proteinview examples/4HHB.pdb --snapshot interface.png \
  --snapshot-interface-chain A --snapshot-interactions

# Hide ligands and ions in a snapshot
proteinview examples/4HHB.pdb --snapshot polymer-only.png \
  --snapshot-hide-ligands

# Color exact residues (blank insertion code A:42 and insertion-coded A:42[A])
proteinview examples/4HHB.pdb --snapshot selected.png \
  --residue-color A:42=FF0000 \
  --residue-color 'A:42[A]=00FFFF'

--snapshot always uses the software pixel renderer behind FullHD and writes a PNG before any raw-mode, alternate-screen, or graphics-protocol setup. It is therefore safe to call from another terminal application. This is distinct from HD, which is the shaded text-cell renderer. Snapshot dimensions default to 1920×1080 and are capped at 4096 pixels per side and 8,388,608 total pixels. Snapshots can also focus one chain's interface, overlay classified inter-chain interaction lines, retain or hide ligands, and use any regular ProteinView color or visualization mode. These controls make the headless renderer suitable for iterative, conversational analysis in an agent chat. Interface highlighting uses its own green/orange focus/partner palette rather than a regular color scheme. Exact residue colors identify polymer residues by case-sensitive chain ID, signed sequence number, and optional insertion code. Omitting the insertion code selects only the blank code, not every residue with that number. Overrides use strict uppercase RRGGBB and take precedence over regular, element, pLDDT, and interface colors.

For a live agent-owned panel, start the persistent headless server with one private PNG path:

proteinview examples/1UBQ.pdb --panel-server \
  --output /tmp/proteinview-live.png \
  --panel-width 960 --panel-height 540

The server renders the initial frame, then writes a ready JSON object to stdout. It accepts one NDJSON command per stdin line, for example {"id":1,"command":"rotate","axis":"y","delta":0.1} or {"id":2,"command":"resize","width":1200,"height":800}. Successful state changes atomically replace the same PNG before their response is emitted. Responses include the request ID, monotonic revision, camera and presentation state, and exact frame path and dimensions. Use get_state without rendering or shutdown to acknowledge and exit. Diagnostics remain on stderr, and the server never emits terminal graphics escapes. Protocol requests and responses are each capped at 64 KiB; display-only structure names are sanitized and bounded, while structures whose required chain metadata cannot fit are rejected before the initial frame is rendered.

An agent can replace all exact residue colors atomically with:

{"id":3,"command":"set_residue_colors","residues":[{"chain":"A","residue_number":42,"color":"FF0000"},{"chain":"B","residue_number":101,"insertion_code":"A","color":"00FFFF"}]}

An empty residues array clears the overrides. Invalid or duplicate targets leave the prior frame, state, and revision unchanged.

Keybindings

Key	Action
h/l	Rotate Y
j/k	Rotate X
u/i	Roll
+/-	Zoom
w/a/s/d	Pan
r	Reset view
c	Cycle color scheme
v	Cycle viz mode
m	Braille / HD
M	HD / FullHD
f	Interface analysis
I	Interface interactions
g	Toggle ligands
[/]	Prev/next chain
Space	Auto-rotate
?	Help
q	Quit

Color Schemes

Scheme	Description
Structure	Helix (red), sheet (yellow), coil (green). Default.
Chain	Distinct color per chain.
Element	CPK coloring (C, N, O, S, P, metals).
B-factor	Blue (rigid) to red (flexible).
Rainbow	N-terminus (blue) to C-terminus (red).
pLDDT	AlphaFold confidence (blue=high, orange=low).

Terminal Support

Terminal	Braille	HD	FullHD
Any Unicode terminal	Yes	Yes	--
Kitty	Yes	Yes	Yes (PNG)
WezTerm	Yes	Yes	Yes (Sixel)
iTerm2	Yes	Yes	Yes
foot	Yes	Yes	Yes (Sixel)
tmux/screen	Yes	Yes	--

Building

cargo build --release

# With RCSB fetch support
cargo build --release --features fetch

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes and add tests
4. Run cargo test to verify
5. Open a pull request against develop

Please open an issue first for major changes to discuss the approach.

License

MIT