Metadata-Version: 2.5
Name: molstar-cli
Version: 0.0.1
Summary: Open local structure and map files (mmCIF, PDB, EMDB maps, ...) in the Mol* viewer from the command line
Project-URL: Homepage, https://github.com/aozalevsky/molstar_cli
Project-URL: Issues, https://github.com/aozalevsky/molstar_cli/issues
Project-URL: Mol*, https://molstar.org
Author: Arthur Zalevsky
License-Expression: MIT
License-File: LICENSE
License-File: molstar_cli/static/molstar/LICENSE.molstar
Keywords: cryo-em,emdb,mmcif,mol*,molecular visualization,molstar,pdb,viewer
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# molstar-cli

Open local structure and map files in the [Mol*](https://molstar.org) viewer from the terminal.

```console
$ pip install molstar-cli
$ molstar 5me2.cif emd_3488.map.gz
Mol* viewer: http://127.0.0.1:34037/MtXDcbb3cYRnGhsxczKvZw/
Press Ctrl-C to stop.
```

All files open together in one Mol* scene in your default browser — e.g. a model fitted
into its cryo-EM map. The Mol* viewer is bundled, so it works offline; there are no
dependencies beyond Python ≥ 3.10.

## Usage

```
molstar FILE [FILE ...] [-p PORT] [--no-browser]
```

```console
$ molstar *.cif                      # several structures, one scene
$ molstar model.cif emd_1234.map.gz  # model + EMDB map
$ molstar PDBDEV_00000001.cif        # integrative (IHM) models, incl. coarse-grained beads
```

The command keeps serving while you look at the structures; stop it with Ctrl-C.
Reloading the browser tab re-reads the files from disk.

| Option | |
|---|---|
| `-p`, `--port PORT` | listen on a fixed port instead of a random free one |
| `--no-browser` | only print the URL |
| `-V`, `--version` | print the molstar-cli and bundled Mol* versions |

### Supported formats

Anything Mol*'s *Open Files* dialog accepts, detected by file extension, optionally
wrapped in `.gz` or `.zip`:

- **Structures:** mmCIF / PDBx (`.cif`, `.mmcif`, `.mcif`) including IHM integrative
  models, BinaryCIF (`.bcif`), PDB (`.pdb`, `.ent`), PDBQT, PQR, GRO, XYZ, SDF / MOL /
  MOL2, LAMMPS data/dump
- **Volumes:** CCP4 / MRC / MAP (`.map`, `.mrc`, `.ccp4` — EMDB maps), DSN6 / BRIX,
  DX, Cube, density server CIF, MTZ
- **Trajectories and topologies:** DCD, XTC, TRR, NetCDF, PSF, PRMTOP, TOP
- **Other:** PLY / OBJ meshes, MolViewSpec (`.mvsj`, `.mvsx`), Mol* sessions (`.molj`, `.molx`)

Unsupported files are skipped with a warning in the Mol* log panel.

Maps open at Mol*'s default isovalue (2σ) — the EMDB-recommended contour level is not
stored in the map file. Adjust it in the Volume panel on the right.

### Remote machines

With `--no-browser`, or on a Linux machine without a display (e.g. over SSH), `molstar`
doesn't start a browser; it prints an `ssh -L` command instead:

```console
server$ molstar model.cif
Mol* viewer: http://127.0.0.1:41235/Xy.../
On a remote machine? Run `ssh -L 41235:127.0.0.1:41235 server` on your computer, then open the URL above there.
Press Ctrl-C to stop.
```

Use `--port` to keep the same forwarded port between runs.

### Security

The server listens on `127.0.0.1` only, every URL carries a random token, and only the
files named on the command line can be read — no directory listing, no other paths.

## Development

```console
$ python -m venv .venv && .venv/bin/pip install -e . pytest
$ .venv/bin/pytest
```

### Updating the bundled Mol*

The prebuilt viewer from the [`molstar` npm package](https://www.npmjs.com/package/molstar)
is vendored in `molstar_cli/static/molstar/` (no Node.js needed):

```console
$ python scripts/update_molstar.py 5.11.0
```

Check that it loads, then commit the result.

### Releasing

Create a GitHub release with a tag like `v0.0.2`. The package version is taken from the
tag, so there is nothing to bump. The *Publish to PyPI* workflow builds and uploads it
using [trusted publishing](https://docs.pypi.org/trusted-publishers/) (PyPI publisher:
owner `aozalevsky`, repository `molstar_cli`, workflow `publish.yml`, environment `pypi`).

## Citing Mol*

If you use Mol* in your work, please cite:

> D. Sehnal, S. Bittrich, M. Deshpande, R. Svobodová, K. Berka, V. Bazgier, S. Velankar,
> S.K. Burley, J. Koča, A.S. Rose. Mol* Viewer: modern web app for 3D visualization and
> analysis of large biomolecular structures. *Nucleic Acids Research* 49(W1), W431–W437
> (2021). [doi:10.1093/nar/gkab314](https://doi.org/10.1093/nar/gkab314)

## License

MIT. The bundled Mol* viewer is © Mol* contributors, also MIT —
see [`LICENSE.molstar`](molstar_cli/static/molstar/LICENSE.molstar).
