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

cd molx
cargo run --release -- view protein.pdb

Install the molx command from this checkout:

cargo install --path molx
molx view protein.pdb

PDB viewer

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: 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:

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:

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.