Metadata-Version: 2.4
Name: aseview
Version: 1.0.0b1
Summary: A molecular viewer for ASE (Atomic Simulation Environment) data
Author-email: Mingi Kang <kangmg@kentech.ac.kr>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kangmg/aseview
Project-URL: Repository, https://github.com/kangmg/aseview
Project-URL: Documentation, https://kangmg.github.io/aseview
Project-URL: Bug Tracker, https://github.com/kangmg/aseview/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: ase
Requires-Dist: ipywidgets
Requires-Dist: jupyter
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: export
Requires-Dist: playwright<1.15,>=1.11.1; extra == "export"
Requires-Dist: pyee<9,>=8; extra == "export"
Provides-Extra: surface
Requires-Dist: cvve>=0.1.0; extra == "surface"
Requires-Dist: scikit-image>=0.22; extra == "surface"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: black>=26.3.1; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: cvve>=0.1.0; extra == "dev"
Requires-Dist: scikit-image>=0.22; extra == "dev"
Dynamic: license-file

# aseview

Interactive molecular viewer for ASE (Atomic Simulation Environment).

[![PyPI](https://img.shields.io/pypi/v/aseview?cacheSeconds=300)](https://pypi.org/project/aseview/) &nbsp;·&nbsp; [![Docs](https://img.shields.io/badge/docs-online-blue)](https://kangmg.github.io/aseview) &nbsp;·&nbsp; [![Playground](https://img.shields.io/badge/playground-try_it-orange)](https://kangmg.github.io/aseview/playground/) &nbsp;·&nbsp; [![DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/kangmg/aseview)

aseview turns ASE `Atoms` — structures, trajectories, normal modes and
volumetric data — into interactive 3D viewers. Every viewer is one
self-contained HTML page, and the same engine runs in Jupyter, saved files, the
CLI, any web page, and VS Code.

## Install

```bash
pip install aseview                 # Python 3.11+
pip install "aseview[surface]"      # + CUBE/CHGCAR isosurfaces
pip install "aseview[export]"       # + save_png()/save_gif() from Python
```

See [Installation](https://kangmg.github.io/aseview/getting-started/installation/) for details.
Upgrading from 0.0.x? Version 1.0 renames and validates settings; see
[Migrating to 1.0](https://kangmg.github.io/aseview/migration/).

## Use

```bash
aseview molecule.xyz                  # structure or trajectory
aseview reactant.xyz product.xyz      # overlay
aseview molecule.xyz --hess orca.hess # normal modes
aseview molecule.xyz -v frag          # fragment selector
aseview HOMO.cube -v surface          # isosurfaces
```

```python
from ase.io import read
from aseview import MolecularViewer, view

atoms = read("molecule.xyz")
MolecularViewer(atoms, style="glossy").show()   # Jupyter
MolecularViewer(atoms).save_html("molecule.html")
view(atoms, style="cinematic")                  # quick render, no sidebar
```

| Viewer | For |
|--------|-----|
| [MolecularViewer](https://kangmg.github.io/aseview/api/molecular-viewer/) | Structures and trajectories |
| [OverlayViewer](https://kangmg.github.io/aseview/api/overlay-viewer/) | Comparing structures, with Kabsch alignment |
| [NormalViewer](https://kangmg.github.io/aseview/api/normal-viewer/) | Vibrational modes from ASE, ORCA `.hess` or VASP `OUTCAR` |
| [FragSelector](https://kangmg.github.io/aseview/api/frag-selector/) | Picking atoms in synchronized 2D/3D panels |
| [SurfaceViewer](https://kangmg.github.io/aseview/api/surface-viewer/) | Orbital, density and density-difference isosurfaces |
| [LiteViewer / `view()`](https://kangmg.github.io/aseview/api/lite-viewer/) | Quick renders without the sidebar |

Every option is a validated [viewer setting](https://kangmg.github.io/aseview/api/settings/)
with the same name in Python, the [CLI](https://kangmg.github.io/aseview/cli-reference/)
and JavaScript. aseview ships ten rendering [styles](https://kangmg.github.io/aseview/styles/)
and five [themes](https://kangmg.github.io/aseview/theming/): `spring` (default), `simple`,
`glass`, `dark` and `darkgreen`.

## JavaScript

```html
<div id="viewer" style="width:100%; height:500px;"></div>
<script src="https://cdn.jsdelivr.net/gh/kangmg/aseview@main/aseview/viewer_assets/aseview-viewer.js"></script>
<script>
    const viewer = new ASEView.MolecularViewer('#viewer', { viewPreset: 'z' });
    viewer.setData({
        symbols: ['O', 'H', 'H'],
        positions: [[0, 0, 0.117], [0, 0.757, -0.469], [0, -0.757, -0.469]]
    });
</script>
```

See the [JavaScript module](https://kangmg.github.io/aseview/js-module/),
[live demo](https://kangmg.github.io/aseview/demo.html) and
[playground](https://kangmg.github.io/aseview/playground/).

## VS Code

`vscode-extension/` is a custom editor for `*.xyz`, `*.extxyz`, `*.cif`,
`*.pdb`, `*.vasp`, `POSCAR` and `CONTCAR`. It parses files with `ase-ts`, so no
Python is needed. Tagged releases attach `aseview-vscode-<version>.vsix` to the
GitHub Release; install it with **Extensions → Install from VSIX...**. See
[vscode-extension/README.md](vscode-extension/README.md#settings) for settings
and commands.

## Development

```bash
git clone https://github.com/kangmg/aseview.git
cd aseview
python3 scripts/run_locked_verification.py python -m pytest tests/test_imports.py -q
```

Checks use the committed hash-locked verification runner, not an editable
checkout install. [AGENTS.md](AGENTS.md) maps the code base and
[DEPLOY.md](DEPLOY.md) the release process.

## License

MIT
