proteinview 0.1.2

Terminal protein structure viewer

ProteinView

╔════════════════════════════════════════════════════════════════╗
║                                                                ║
║    ██████╗ ██████╗  ██████╗ ████████╗███████╗██╗███╗   ██╗     ║
║    ██╔══██╗██╔══██╗██╔═══██╗╚══██╔══╝██╔════╝██║████╗  ██║     ║
║    ██████╔╝██████╔╝██║   ██║   ██║   █████╗  ██║██╔██╗ ██║     ║
║    ██╔═══╝ ██╔══██╗██║   ██║   ██║   ██╔══╝  ██║██║╚██╗██║     ║
║    ██║     ██║  ██║╚██████╔╝   ██║   ███████╗██║██║ ╚████║     ║
║    ╚═╝     ╚═╝  ╚═╝ ╚═════╝    ╚═╝   ╚══════╝╚═╝╚═╝  ╚═══╝     ║
║                 ██╗   ██╗██╗███████╗██╗    ██╗                 ║
║                 ██║   ██║██║██╔════╝██║    ██║                 ║
║                 ██║   ██║██║█████╗  ██║ █╗ ██║                 ║
║                 ╚██╗ ██╔╝██║██╔══╝  ██║███╗██║                 ║
║                  ╚████╔╝ ██║███████╗╚███╔███╔╝                 ║
║                   ╚═══╝  ╚═╝╚══════╝ ╚══╝╚══╝                  ║
║                                                                ║
║   (=(    )=)~~(=(    )=)~~(=(    )=)~~(=(    )=)~~(=(    )=)   ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

Terminal protein structure viewer -- load, rotate, and explore PDB/CIF structures right in your terminal.

Features

• Braille character rendering -- high-resolution colored Unicode braille (2x4 dots per cell), works everywhere including SSH
• HD pixel rendering -- Sixel/Kitty/iTerm2 graphics protocol support via ratatui-image for pixel-perfect display (--hd)
• Cartoon ribbon visualization -- smooth ribbon/tube rendering with depth fog and Lambert shading for helices, beta-sheets, and coils
• 3 visualization modes -- Cartoon (ribbon), Backbone (CA trace), Wireframe (all-atom bonds)
• 6 color schemes -- secondary structure, pLDDT (when available), chain, element, B-factor, rainbow
• Interactive rotation, zoom, pan -- vim-style keybindings with auto-rotation
• Protein-protein interface analysis -- detect and highlight inter-chain contacts
• PDB and mmCIF format support -- including secondary structure parsing from both formats
• Fetch from RCSB PDB -- download structures by ID with --fetch (optional feature)
• Single static binary, zero runtime dependencies

Installation

Easy install via pip for x86 (for arm, it will try to build it on your machine using maturin)

pip install proteinview

or build it here from source

# Basic install
cargo install --path .

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

This builds the binary and places it in ~/.cargo/bin/, which is already on your PATH if you installed Rust via rustup. Then run proteinview from anywhere.

Usage

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

# HD pixel mode (Sixel/Kitty/iTerm2 terminals)
proteinview examples/4HHB.pdb --hd

# Choose color scheme
proteinview examples/1UBQ.pdb --color rainbow

# Color AlphaFold / ModelCIF structures by pLDDT
proteinview examples/AF3_TNFa.pdb --color plddt

# Choose visualization mode
proteinview examples/4HHB.pdb --mode wireframe

# Fetch from RCSB PDB (requires --features fetch)
proteinview --fetch 1UBQ

Keybindings

Key	Action
h / l	Rotate Y-axis
j / k	Rotate X-axis
u / i	Rotate Z-axis (roll)
+ / -	Zoom in / out
w/a/s/d	Pan
r	Reset view
c	Cycle color scheme
v	Cycle visualization mode
f	Toggle interface analysis
m	Toggle braille / HD
[ / ]	Previous / next chain
Space	Toggle auto-rotation
?	Help overlay
q	Quit

Visualization Modes

Mode	Description
Cartoon	Ribbon rendering with smooth helices, beta-sheet arrows, and coil tubes. Default.
Backbone	CA-trace with spheres at alpha-carbon positions connected by thick lines.
Wireframe	All-atom display showing every bond in the structure.

Color Schemes

Scheme	Description
Secondary Structure	Helix (red), sheet (yellow), coil (green), turn (blue). Default.
pLDDT	AlphaFold confidence colors when the file stores pLDDT scores.
Chain	Each chain gets a distinct color from a curated palette.
Element (CPK)	Atoms colored by element: C gray, N blue, O red, S yellow.
B-factor	Blue (low mobility) to red (high mobility) gradient.
Rainbow	N-terminus (blue) to C-terminus (red) by residue position.

Example PDB Files

File	Description
examples/1UBQ.pdb	Ubiquitin -- 76 residues, single chain, classic test protein
examples/4HHB.pdb	Hemoglobin -- 4 chains, 574 residues, good for multi-chain viewing
examples/1ZVH.cif	Antibody-antigen complex -- mmCIF format, good for interface analysis
examples/AF3_TNFa.pdb	AlphaFold-style PDB with pLDDT confidence values
examples/OBP5_model_0.cif	ModelCIF example with pLDDT-style confidence values

Interface Analysis

Press f to toggle the protein-protein interface panel, which detects inter-chain contacts and highlights interface residues.

Terminal Support

• Works in any terminal with Unicode support (braille mode).
• For best quality, use a terminal with Sixel or Kitty graphics protocol support (e.g., WezTerm, Kitty, foot, iTerm2) and pass --hd.
• The --hd flag auto-detects the best graphics protocol; falls back to colored braille if none available.

Building

cargo build --release

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

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

License

MIT