Metadata-Version: 2.4
Name: molarverse-pqviewer
Version: 0.1.0
Summary: Interactive molecular structure and trajectory viewing for PQ.
License-Expression: MIT
Project-URL: Repository, https://github.com/MolarVerse/PQViewer
Project-URL: Documentation, https://molarverse.github.io/PQViewer/
Project-URL: Changelog, https://github.com/MolarVerse/PQViewer/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/MolarVerse/PQViewer/issues
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: fastapi<1,>=0.115.12
Requires-Dist: numpy<3,>=2
Requires-Dist: PQAnalysis>=1.4.0
Requires-Dist: python-multipart<1,>=0.0.20
Requires-Dist: uvicorn<1,>=0.30
Provides-Extra: ase
Requires-Dist: ase<4,>=3.23; extra == "ase"
Provides-Extra: render
Requires-Dist: playwright<2,>=1.52; extra == "render"
Provides-Extra: jupyter
Requires-Dist: ipython<10,>=8; extra == "jupyter"
Provides-Extra: docs
Requires-Dist: furo<2027,>=2024.8.6; extra == "docs"
Requires-Dist: myst-parser<5,>=4; extra == "docs"
Requires-Dist: sphinx<9,>=8; extra == "docs"
Requires-Dist: sphinx-copybutton<1,>=0.5; extra == "docs"
Requires-Dist: sphinx-design<1,>=0.6; extra == "docs"
Provides-Extra: dev
Requires-Dist: ase<4,>=3.23; extra == "dev"
Requires-Dist: httpx2<3,>=2; extra == "dev"
Requires-Dist: pillow<13,>=11; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-cov<7,>=5; extra == "dev"
Dynamic: license-file

<img src="https://raw.githubusercontent.com/MolarVerse/PQViewer/main/frontend/public/pq-logo.png" alt="PQViewer logo" width="200">

# PQViewer

[![CI](https://github.com/MolarVerse/PQViewer/actions/workflows/ci.yml/badge.svg)](https://github.com/MolarVerse/PQViewer/actions/workflows/ci.yml)
[![Documentation](https://github.com/MolarVerse/PQViewer/actions/workflows/pages.yml/badge.svg)](https://molarverse.github.io/PQViewer/)
[![PyPI](https://img.shields.io/pypi/v/molarverse-pqviewer.svg)](https://pypi.org/project/molarverse-pqviewer/)
[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](https://github.com/MolarVerse/PQViewer/blob/main/pyproject.toml)
[![License: MIT](https://img.shields.io/badge/License-MIT-2f718f.svg)](https://github.com/MolarVerse/PQViewer/blob/main/LICENSE)

PQViewer opens molecular structures and trajectories from PQ in a local
browser, with optional ASE format support. It provides indexed playback,
centred periodic cells, measurements, and reproducible figure export.

[Documentation](https://molarverse.github.io/PQViewer/) ·
[Web demo](https://molarverse.github.io/PQViewer/viewer/) ·
[Jupyter example](https://github.com/MolarVerse/PQViewer/blob/main/examples/pqviewer-notebook.ipynb)

![PQViewer showing a 100-frame UMCM-9 trajectory](https://raw.githubusercontent.com/MolarVerse/PQViewer/main/docs/assets/screenshots/trajectory-workspace.png)

PQViewer is in public beta. File and Python interfaces may change before 1.0.

## Install

PQViewer requires Python 3.12 or newer.
The distribution is named `molarverse-pqviewer`; the application, import
package, and command remain `PQViewer`, `pqviewer`, and `pqviewer`.

```bash
python -m pip install molarverse-pqviewer
pqviewer
```

Node.js is not required. Optional ASE format support is installed with
`python -m pip install 'molarverse-pqviewer[ase]'`.

The CLI also accepts PQ inputs, run directories, ASE sources, and frame slices.
See [Getting started](https://molarverse.github.io/PQViewer/getting-started.html)
for examples.

## Viewer

- 3Dmol.js atoms, bonds, protein cartoons, surfaces, cells, and selections
- centred orthorhombic and triclinic cells, wrapping, and molecule reconstruction
- atom and cell editing with EXTXYZ download
- trajectory playback, measurements, analysis, forces, and collision indicators
- independent PNG and TIFF figure rendering with reusable recipes

Search atoms, settings, and commands with the central **Search** field,
`Cmd/Ctrl+K`, or `/`.

## Jupyter

```bash
python -m pip install 'molarverse-pqviewer[jupyter,ase]'
```

```python
from pqviewer import view

viewer = view("trajectory.xyz", height=620)
viewer
```

The notebook cell embeds the local viewer. Call `viewer.close()` when finished.
See the [Jupyter guide](https://molarverse.github.io/PQViewer/jupyter.html) for
files, ASE objects, companion data, and remote kernels.

## Project

[Contributing](https://github.com/MolarVerse/PQViewer/blob/main/CONTRIBUTING.md) ·
[Citation](https://github.com/MolarVerse/PQViewer/blob/main/CITATION.cff) ·
[Security](https://github.com/MolarVerse/PQViewer/blob/main/SECURITY.md) ·
[Changelog](https://github.com/MolarVerse/PQViewer/blob/main/CHANGELOG.md) ·
[License](https://github.com/MolarVerse/PQViewer/blob/main/LICENSE) ·
[Third-party notices](https://github.com/MolarVerse/PQViewer/blob/main/THIRD_PARTY_NOTICES.md)

PQViewer binds to `127.0.0.1` by default and does not provide authentication.
Do not expose the local server to an untrusted network.
