# MolX
MolX is an interactive protein-structure viewer for graphical terminals. It
opens PDB files, renders a smooth protein ribbon as a high-resolution raster,
and lets you rotate and zoom without leaving the command line. It also connects
to the ESM Metagenomic Atlas to fetch existing predictions, display predicted
aligned error (PAE), or fold a short amino-acid sequence with the public
ESMFold service.
The viewer uses the repository's `rstui` runtime and automatically selects
Kitty graphics, iTerm2 images, Sixel, or an ANSI truecolor fallback.
Interactive labels are emitted as native terminal characters, including the
title, sequence panel, residue cards, PAE labels, and status bars. This keeps
text sharp at the terminal's configured font and DPI while the 3D structure
and PAE heatmap remain high-resolution raster graphics. PNG snapshots retain
their embedded bitmap labels because they are standalone images.
Sequence letters use the same chain, element, or pLDDT colors as their
corresponding residues, with automatic dark/light foreground contrast.
## Build and run
```bash
cd molx
cargo run --release -- view protein.pdb
```
Install the `molx` command from this checkout:
```bash
cargo install --path molx
molx view protein.pdb
```
## PDB viewer
```bash
molx view protein.pdb
molx view protein.pdb --representation ribbon
molx view protein.pdb --representation atoms --color element
molx view prediction.pdb --representation combined --color confidence
molx info protein.pdb
molx snapshot protein.pdb --output protein.png
molx snapshot protein.pdb --select A:121 --output residue-121.png
```
MolX reads the first model in a PDB file, keeps the primary alternate location,
shows `ATOM` and `HETATM` records, and constructs a gap-aware ribbon/cartoon
from the protein backbone. The ribbon uses backbone torsion angles to recognize
alpha helices and beta strands, smooths the path between C-alpha atoms, and
builds a continuously oriented local frame along the curve. Coils use round
tubes, helices use smooth elliptical profiles, and beta strands use shaded
box profiles with arrowheads, side walls, and end caps. Available
representations are `ribbon`, `atoms`, and `combined`; `backbone` remains
accepted as an alias for `ribbon`.
The cartoon geometry follows the design principles of the open-source
[Mol* polymer trace mesh](https://github.com/molstar/molstar): secondary
structure-specific cross-sections, interpolated curve frames, and
normal-based surface lighting, implemented natively in Rust for MolX's
terminal rasterizer.
Controls:
- Move the mouse over the cartoon to inspect a residue. MolX highlights the
residue in the 3D structure and in the sequence panel, and shows its chain,
name, number, secondary structure, atom count, and pLDDT/B-factor.
- Click a residue to lock the selection and focus the camera. MolX overlays
the selected residue and complete nearby residues as element-colored,
lit ball-and-stick geometry. Covalent topology is inferred without joining
unrelated close atoms; carbonyl double bonds, aromatic ring marks, and cyan
dashed polar contacts are rendered explicitly.
- Click the selected residue again or press `x` to clear the local detail view.
- Drag with the left mouse button, or use arrow keys / `h`, `j`, `k`, `l`, to rotate.
- Use the mouse wheel or `+` / `-` to zoom.
- Press `m` to cycle molecular representations.
- Press `c` to cycle chain, element, and pLDDT/B-factor colors.
- Press Space to toggle automatic rotation.
- Press `r` to reset the camera and `q` or Escape to quit.
The sequence panel follows the hovered or selected chain, displays standard
one-letter amino-acid codes and PDB residue numbers, and automatically windows
long chains around the active residue.
For ESMFold structures, `--color auto` selects the pLDDT palette used by the
Atlas: vivid blue is high confidence and red is low confidence. Ribbon
lighting preserves saturation in shadowed regions instead of washing colors
toward gray.
## ESM Atlas
Download an existing prediction by MGnify protein identifier:
```bash
molx atlas fetch MGYP002537940442
molx atlas fetch MGYP002537940442 --output example.pdb --view
molx snapshot example.pdb --atlas-id MGYP002537940442 --output atlas.png
```
Fold one sequence using the public ESMFold endpoint:
```bash
molx atlas fold --sequence MKTAYIAKQRQISFVKSHFSRQ --output folded.pdb --view
molx atlas fold --fasta protein.fasta --output folded.pdb
```
Existing output files are preserved unless `--force` is passed. The public API
is rate-limited and intended for a small number of interactive predictions, not
bulk folding. MolX limits requests to 1,024 residues and uses a five-minute
request timeout. The Atlas data is distributed under CC BY 4.0; retain the
appropriate attribution when redistributing downloaded structures.
`atlas fetch --view` retrieves the entry's PAE matrix and displays it in a
right-hand heatmap next to the 3D ribbon. The live `atlas fold` endpoint returns
a PDB prediction but no PAE matrix, so its viewer panel reports PAE as
unavailable.
Official resources:
- <https://esmatlas.com/about#api>
- <https://github.com/facebookresearch/esm>
## Current scope
This first version focuses on local PDB viewing and stable public ESM Atlas
operations. mmCIF parsing, residue selection, surfaces, ligand bond inference,
measurements, and sequence/structure search are natural next modules.