pdbcat 0.1.0

Terminal-based PDB/mmCIF molecular structure viewer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

# pdbcat

![pdbcat demo](assets/demo.png)

A quick terminal viewer for PDB and mmCIF files. **Not a replacement for PyMOL or ChimeraX**—just a fast way to glance at a structure without leaving the terminal.

## Examples

### Representations

| Cartoon | Surface | Backbone |
|---------|---------|----------|
| ![cartoon](assets/cartoon.png) | ![surface](assets/surface.png) | ![backbone](assets/backbone.png) |

### Color Schemes

| Chain | Rainbow | Secondary Structure |
|-------|---------|---------------------|
| ![chain](assets/color-chain.png) | ![rainbow](assets/color-rainbow.png) | ![secondary](assets/color-secondary.png) |

### Half-Block Backend (any terminal)

![half-block](assets/half-block.png)

## Installation

### From crates.io

```bash
cargo install pdbcat
```

### Pre-built binaries

Download from [GitHub Releases](https://github.com/nanomind-bio/pdbcat/releases/latest).

Or install with the installer script:

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nanomind-bio/pdbcat/releases/latest/download/pdbcat-installer.sh | sh
```

### From source

```bash
cargo install --path .
```

## Usage

```bash
# Quick view (auto-detects terminal, renders to stdout)
pdbcat structure.pdb

# Different representations
pdbcat structure.pdb --repr cartoon      # default
pdbcat structure.pdb --repr surface
pdbcat structure.pdb --repr backbone

# Color schemes
pdbcat structure.pdb -c chain            # default
pdbcat structure.pdb -c rainbow
pdbcat structure.pdb -c secondary

# Force specific backend
pdbcat structure.pdb --backend iterm2
pdbcat structure.pdb --backend half

# Interactive mode (rotate with mouse, keyboard controls)
pdbcat structure.pdb -i

# Export to PNG
pdbcat structure.pdb -o output.png
```

## Command Line Options

| Option | Description |
|--------|-------------|
| `FILE` | Path to PDB or mmCIF file |
| `-i, --interactive` | Interactive mode with keyboard/mouse controls |
| `-o, --output PATH` | Export to PNG file |
| `-r, --resolution WxH` | Resolution (default: terminal size for stdout, 800x600 for -o) |
| `--repr MODE` | Representation: cartoon, surface, backbone |
| `-c, --color SCHEME` | Color scheme: chain, rainbow, secondary |
| `--bg COLOR` | Background: white, black (default), transparent |
| `--backend MODE` | Force render backend: iterm2, half (auto-detect if not set) |

## Interactive Mode Controls

| Key | Action |
|-----|--------|
| Mouse drag | Rotate |
| Scroll / `[` `]` | Zoom |
| Arrow keys | Pan |
| Tab | Cycle representation |
| `c` | Cycle color scheme |
| `0` | Reset view |
| `q` / Esc | Quit |

## Supported Formats

- **PDB** (.pdb)
- **mmCIF** (.cif, .mmcif)

## Terminal Compatibility

| Terminal | Backend | Quality |
|----------|---------|---------|
| iTerm2 | Inline images | Best |
| Any terminal | Half-block characters | Good |

The backend is auto-detected. Use `--backend` to override.

## License

MIT