Metadata-Version: 2.4
Name: cmd-viewer
Version: 0.2.0
Summary: Terminal-first molecular dynamics viewer for GROMACS trajectories.
Author: Wojciech Kopec
License: MIT
Project-URL: Homepage, https://github.com/Kopec-Lab/cmd-viewer
Project-URL: Repository, https://github.com/Kopec-Lab/cmd-viewer
Project-URL: Issues, https://github.com/Kopec-Lab/cmd-viewer/issues
Project-URL: Changelog, https://github.com/Kopec-Lab/cmd-viewer/blob/main/CHANGELOG.md
Keywords: molecular-dynamics,gromacs,terminal,viewer,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: MDAnalysis<3,>=2.6
Requires-Dist: numpy<3,>=1.24
Provides-Extra: dev
Requires-Dist: Pillow<13,>=10; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Provides-Extra: export
Requires-Dist: Pillow<13,>=10; extra == "export"
Dynamic: license-file

# cmd

<p align="center">
  <img src="https://raw.githubusercontent.com/Kopec-Lab/cmd-viewer/main/assets/cmd-intro.png" width="800" alt="CMD"/>
</p>

`cmd` is a terminal-first molecular dynamics viewer for quick trajectory checks
on local machines, remote shells, and HPC systems. It is designed for plain
terminal use: no GUI server, no OpenGL setup, and no heavy visualization stack.

The internal Python package is named `cmd_viewer` to avoid colliding with
Python's standard-library `cmd` module. The installed executable is `cmd`.

## Features

- `.pdb` / `.gro` structures with optional `.xtc` / `.dcd` trajectories.
- MDAnalysis-backed selections with VMD-like conveniences such as `atomname`
  normalization and a built-in `lipids` keyword.
- Water hidden by default, with optional dynamic nearby-water overlays for
  hydrated pockets and pores.
- View modes for fast checks: `points`, `trace`, `coarse`, and `cartoon`.
- Camera rotation, zoom, panning, playback, XYZ axis overlay, and orthorhombic
  box overlay.
- Saved view files for reusing manually oriented viewpoints.
- Native animated GIF export for sharing trajectories or adding them to slides.

## Install

From PyPI:

```bash
pip install cmd-viewer
```

With GIF export support:

```bash
pip install "cmd-viewer[export]"
```

For local development from this repository:

```bash
pip install -e .
pip install -e ".[export,dev]"
```

## Quick Start

Open a trajectory:

```bash
cmd system.gro traj.xtc
cmd system.pdb trajectory.dcd
```

Protein-focused view:

```bash
cmd system.gro traj.xtc --selection protein --view-mode cartoon
```

Membrane overview:

```bash
cmd system.gro traj.xtc --selection "protein or lipids or element K or element CL" --view-mode coarse
```

Track individual ions by residue id color:

```bash
cmd system.gro traj.xtc --selection "resname K" --color-mode resid
cmd system.gro traj.xtc --selection "resname CL" --color-mode resid
```

Show nearby pore or pocket water:

```bash
cmd system.gro traj.xtc --selection protein --near-water 5
```

Use bundled test systems:

```bash
cmd test-trajs/traak/after90ns-k.pdb test-trajs/traak/traj_comp.xtc --selection protein --view-mode cartoon
cmd test-trajs/popc/em.gro test-trajs/popc/whole.xtc --view-mode coarse
cmd test-trajs/ga/reference-structure-2M-KCl.gro test-trajs/ga/04-pt7scaling-11pA.xtc --selection "resname K" --color-mode resid
```

## Saved Views And GIFs

For systems that need a specific orientation, save the view once and reuse it.

1. Open the system and choose a view:

```bash
cmd system.gro traj.xtc --view-mode coarse --save-view pore-view.json
```

2. Rotate, zoom, and pan interactively, then press `v`.

3. Reuse that view later:

```bash
cmd system.gro traj.xtc --view-mode coarse --view-file pore-view.json
```

4. Export a GIF from the saved viewpoint:

```bash
cmd system.gro traj.xtc --view-mode coarse --view-file pore-view.json --save-gif pore.gif --gif-stride 5 --gif-fps 12
```

GIF export uses the same selections, view modes, smoothing, nearby-water
overlays, color modes, and box state as the terminal viewer. GIFs are
scene-only by default, so the exported frame does not include the header,
legend, or controls.

Useful GIF options:

- `--gif-start FRAME`: first 0-based frame to export.
- `--gif-stop FRAME`: stop before this 0-based frame.
- `--gif-stride N`: export every `N`th frame.
- `--gif-fps FPS`: animation playback rate.
- `--gif-width COLS` and `--gif-height ROWS`: output size in terminal cells.
- `--gif-scale PX`: final raster scale. The default is `2`.
- `--gif-hide-box`: hide orthorhombic box boundaries.
- `--gif-no-loop`: write a non-looping GIF.
- `--gif-show-ui`: include the header, legend, and controls in the GIF.

Examples:

```bash
cmd system.gro traj.xtc --view-mode coarse --save-gif overview.gif
cmd system.gro traj.xtc --view-mode cartoon --selection protein --save-gif protein.gif --gif-fps 15 --gif-stride 2
cmd system.gro traj.xtc --selection "resname K" --color-mode resid --save-gif ions.gif --gif-width 90 --gif-height 35
cmd system.pdb trajectory.dcd --view-file openmm-view.json --save-gif openmm.gif --gif-width 120 --gif-height 45
```

## Controls

- `q`: quit
- `h`: toggle help
- `f`: toggle full-window molecular view
- `space`: play / pause
- `n` or right arrow: next frame
- `b` or left arrow: previous frame
- `w` / `s`: tilt camera
- `a` / `d`: rotate camera
- `z` / `x`: roll camera
- `i` / `k`: translate view up / down
- `j` / `l`: translate view left / right
- `+` / `-`: zoom
- `r`: reset camera
- `o`: toggle box overlay
- `v`: save the current view to `--save-view`

The current zoom limit is `32x`. Translation is screen-space panning, which is
useful after zooming into a local region.

## View Modes

- `points`: atom-level point cloud for fast whole-system inspection.
- `trace`: residue-level backbone-like trace using `CA`, `BB`, `P`, `C4'`, or
  related trace atoms.
- `coarse`: protein as trace lines, lipid headgroups as `O`, ions as colored
  `*`, ligands as `D`, and water as `.`.
- `cartoon`: a coarse protein-focused mode with simple secondary-structure
  heuristics. Helix-like segments use `@` / `o`, sheet-like segments use
  directional arrows, and loops use lighter line glyphs.

Examples:

```bash
cmd system.gro traj.xtc --view-mode points
cmd system.gro traj.xtc --view-mode trace --selection protein
cmd system.gro traj.xtc --view-mode coarse --selection "protein or lipids"
cmd system.gro traj.xtc --view-mode cartoon --selection protein
```

## Selections

Selections are passed to MDAnalysis. Core selection terms such as `resname`,
`name`, `resid`, boolean operators, and ranges are available. `cmd` also
normalizes `atomname` to `name` and provides a `lipids` keyword that expands to
common lipid residue names.

Examples:

```bash
cmd system.gro traj.xtc --selection "protein"
cmd system.gro traj.xtc --selection "lipids"
cmd system.gro traj.xtc --selection "protein or lipids"
cmd system.gro traj.xtc --selection "resid 10:50 and atomname CA"
cmd system.gro traj.xtc --selection "resname POPC and name P"
cmd system.gro traj.xtc --selection "protein and around 6 resname LIG"
```

## Smoothing

`--smooth N` applies centered trajectory smoothing over `N` frames. By default,
smoothing targets proteins and lipid residues only; ions are excluded because
their fast jumps usually make smoothing misleading.

```bash
cmd system.gro traj.xtc --view-mode coarse --smooth 5
cmd system.gro traj.xtc --view-mode cartoon --smooth 7 --smoothres "protein"
```

## Dynamic Water Overlay

`--near-water 5` shows water oxygens within `5 A` of a target selection and
updates that subset every frame. The default target is `protein`; use
`--near-water-target` to override it.

```bash
cmd system.gro traj.xtc --selection protein --near-water 5
cmd system.gro traj.xtc --view-mode cartoon --selection protein --near-water 4
cmd system.gro traj.xtc --near-water 5 --near-water-target "protein or lipids"
```

## Notes And Limits

- Box drawing currently supports orthorhombic unit cells only.
- Large systems are downsampled to a bounded number of displayed primitives so
  the viewer remains responsive over SSH and on shared systems.
- The renderer is intentionally terminal-first; it is meant for quick checks,
  not publication-quality molecular graphics.

## Development And Releases

For the ongoing maintenance and release workflow, see
[`RELEASING.md`](./RELEASING.md).

The repository includes:

- `.github/workflows/package-checks.yml`: builds the package, checks version
  consistency, runs tests, and validates distributions on pushes and pull
  requests.
- `.github/workflows/release.yml`: builds and publishes to PyPI using Trusted
  Publishing when a GitHub release is published.

## Roadmap

- improve playback performance for very large systems
- add residue / chain / segment centering shortcuts
- add small-selection ball-and-stick or stick-like modes
- package for conda-based HPC installation
