Interactive, Terminal-Native Protein Structure Viewer

StrucTTY is a lightweight, terminal-based protein structure visualizer built in C++17. It renders 3D protein structures directly in the terminal using Unicode Braille sub-pixel rendering, providing 8x resolution compared to standard character-based rendering.

StrucTTY supports simultaneous visualization of up to 9 proteins, 7 color modes with 3-band depth fog, and integrates with Foldseek and FoldMason for structural search and multiple structure alignment.

• Braille sub-pixel rendering — each terminal cell maps to a 2×4 logical pixel grid
• Up to 9 proteins rendered simultaneously with independent controls
• 7 color modes — protein, chain, rainbow, plddt, interface, conservation, aligned
• 3-band depth fog — near (bright), mid (normal), far (dark with hue retention) for depth perception
• Secondary structure visualization — helix cylinders and sheet ribbons
• Foldseek integration — load .m8 results, navigate hits, auto-download structures or read directly from Foldseek DB
• FoldMason integration — MSA superposition with conservation coloring
• MSA conservation scoring — Shannon entropy from FASTA/A3M alignments
• Interface detection — inter-chain contact residue highlighting
• Alignment visualization — structural alignment region highlighting
• Screenshot export — PNG output via lodepng
• Chain selection — filter specific chains per protein

Supported platforms: Linux, macOS

git clone --recurse-submodules https://github.com/steineggerlab/StrucTTY.git
cd StrucTTY
mkdir build && cd build
cmake ..
make -j$(nproc)

git clone --recurse-submodules https://github.com/steineggerlab/StrucTTY.git
cd StrucTTY
mkdir build && cd build
brew install ncurses
cmake .. \
  -DCURSES_INCLUDE_PATH=/opt/homebrew/opt/ncurses/include \
  -DCURSES_LIBRARY=/opt/homebrew/opt/ncurses/lib/libncursesw.dylib \
  -DCMAKE_EXE_LINKER_FLAGS="-L/opt/homebrew/opt/ncurses/lib -lncursesw -Wl,-rpath,/opt/homebrew/opt/ncurses/lib" \
  -DCMAKE_CXX_FLAGS="-I/opt/homebrew/opt/ncurses/include"
make -j$(nproc)

The output binary will be generated at build/StrucTTY.

./StrucTTY ../example/1NPL-assembly1.cif --mode chain

./StrucTTY ../example/3HGM-assembly1.cif --mode chain
./StrucTTY ../example/3HGM-assembly1.cif --mode chain -s

./StrucTTY ../example/3A0C-assembly1.cif                  # protein (default)
./StrucTTY ../example/3A0C-assembly1.cif --mode chain
./StrucTTY ../example/3A0C-assembly1.cif --mode rainbow
./StrucTTY  ../example/colabfold_result/3A0C_e7fa1_unrelaxed_rank_005_alphafold2_ptm_model_5_seed_000.pdb --mode plddt
./StrucTTY ../example/3A0C-assembly1.cif --mode interface
./StrucTTY ../example/3A0C-assembly1.cif --mode conservation \
  --msa /home/lunajang/src/StrucTTY_luna/example/msa_result/query.a3m

./StrucTTY ../example/1CJK-assembly1.cif \
  ../example/1NPL-assembly1.cif \
  ../example/3A0C-assembly1.cif \
  ../example/3HGM-assembly1.cif \
  ../example/3OAG-assembly1.cif \
  ../example/9FL9-assembly1.cif \
  ../example/A0A0K2SDS1_CONEP_23_61_90b02_unrelaxed_rank_1_model_5.pdb \
  ../example/AF-A0A233SAX3-F1-model_v6.cif \
  ../example/AF-E3NU62-F1-model_v4_TED02.pdb

./StrucTTY ../example/1NPL-assembly1.cif ../example/3A0C-assembly1.cif
./StrucTTY ../example/1NPL-assembly1.cif ../example/3A0C-assembly1.cif \
  -ut ../example/utfile_1npl_3a0c.tsv

./StrucTTY ../example/9N47-assembly1.cif -m chain
./StrucTTY ../example/9N47-assembly1.cif -c ../example/chainfile_9N47.tsv -m chain

./StrucTTY ../example/3A0C-assembly1.cif \
  -fs ../example/foldseek_result/alis_afdb50.m8 \
  --db-path /path/to/pdb/

./StrucTTY ../example/3A0C-assembly1.cif  ../example/L7RCY6.pdb 
./StrucTTY ../example/3A0C-assembly1.cif  ../example/L7RCY6.pdb \
  -fm ../example/foldmason_result/foldmason.json -m aligned

./StrucTTY <input_files...> [OPTIONS]

Mouse hover displays residue information in the info panel.

All modes support 3-band depth fog: near (vivid), mid (normal), far (dark, hue-retaining).

StrucTTY reads Foldseek easy-search output (.m8 format) with support for 12, 17, 21, and 29 column formats. Features include:

• Interactive hit navigation with automatic structure downloading
• Direct Foldseek DB reading (--db) — read Cα coordinates directly from Foldseek _ca database, eliminating network dependency. Uses hit-based selective scanning for minimal memory usage (~152KB for 1000 hits, even on AFDB50)
• Structural superposition using U/T rotation-translation matrices
• Alignment string visualization (qaln/taln)
• Multi-database support: PDB, AlphaFold DB, ESMAtlas, CATH, BFVD, and more

Foldseek can launch StrucTTY directly after search completion using the --view flag. This automatically passes the query structure, result file, and target database to StrucTTY:

foldseek easy-search query.pdb targetDB result.m8 tmp --view 1
# Equivalent to running:
# StrucTTY query.pdb --foldseek result.m8 --db targetDB

Requires StrucTTY to be available in PATH. If not found, Foldseek prints a warning and exits normally — search results are always preserved regardless.

# Online mode (download structures)
./StrucTTY query.pdb --foldseek result.m8

# Offline mode (read from Foldseek DB)
./StrucTTY query.pdb --foldseek result.m8 --db /path/to/targetDB

# Hybrid (DB first, fallback to download)
./StrucTTY query.pdb --foldseek result.m8 --db /path/to/targetDB --db-path /path/to/pdbs/

StrucTTY loads FoldMason MSA results (JSON with Cα coordinates or FASTA) for:

• Kabsch-based structural superposition
• Column-wise conservation scoring
• Gap-aware alignment visualization

Load FASTA or A3M multiple sequence alignments to compute per-residue conservation scores via Shannon entropy, visualized with the conservation color mode.

See THIRD_PARTY_NOTICES.md for detailed license information.

This project is licensed under the GNU General Public License v3.0.

Developed by Luna Sung-eun Jang, Soo Young Cha — Steinegger Lab