Metadata-Version: 2.4
Name: aseview
Version: 0.0.26
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 :: 3 - Alpha
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

Molecular structure 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)

## Features

- Interactive structure, trajectory, overlay, normal-mode, and fragment-selection viewers
- Optional cube-backed `SurfaceViewer` for orbital, density, and delta-density isosurfaces
- ASE-backed Python API and CLI, plus a browser-only JavaScript module
- Cell/PBC display, bonds, hydrogen bonds, charges, magnetic moments, forces, and fixed-atom constraint highlighting
- Energy and max-force (Fmax) trajectory plots with independent force-plot toggling
- Radius Contrast control for reducing or restoring element-radius size differences
- Visual styles including default, cartoon, glossy, metallic, cinematic, rowan, bubble, neon, grey, and 2D
- Hide hydrogens without deleting data, and apply optional render blur to saved images
- Clipboard export for current frame or full trajectory as `xyz`, `extxyz`, `cif`, or `POSCAR`
- Cell-aware camera presets and browser PNG/GIF export for rendered viewers

## Installation

aseview 0.0.14 and newer require Python 3.11 or newer. If you need
Python 3.10 support, install the last compatible release, 0.0.13:

```bash
pip install "aseview<0.0.14"
```

Recommended:

```bash
uv venv -p 3.11
uv pip install aseview
aseview -h
```

```bash
pip install aseview
```

For 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
```

Contributor validation uses the committed hash-locked verification runner so
docs, release artifacts, and CI checks exercise the declared dependency locks
instead of an editable checkout install.

See [Installation](https://kangmg.github.io/aseview/getting-started/installation/) for optional PNG/GIF export setup and dependency details.

For Gaussian CUBE orbital or density surfaces, install the optional surface dependencies.
This uses the published `cvve` package for cube/CHGCAR grid parsing:

```bash
pip install "aseview[surface]"
```

## CLI Usage

```bash
aseview molecule.xyz
aseview trajectory.xyz -i 0:10 --style neon
```

See the [CLI Reference](https://kangmg.github.io/aseview/cli-reference/) for the full option list — frame indexing, viewer/style/theme selection, overlay colormaps, normal-mode Hessian input, and server options. For SSH port forwarding to a remote server, see [Quick Start](https://kangmg.github.io/aseview/getting-started/quickstart/#ssh-remote-usage).

## Jupyter Notebook

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

atoms = read('molecule.xyz')
viewer = MolecularViewer(atoms)
viewer.show()
```

```python
# PyMOL-style quick render, no control panel
from aseview import view

view(atoms, styles='cinematic', hide_hs=True, center=True)
```

```python
from aseview import SurfaceViewer

viewer = SurfaceViewer(
    "HOMO.cube",
    surface_kind="orbital",
    isovalue="0.03:0.09:4",
    positive_color="#ef4444",
    negative_color="#2563eb",
    opacity_ramp=[0.25, 0.45, 0.65, 0.8],
)
viewer.show()
```

Surface isovalues accept explicit lists, comma lists, `start:stop:count`, and
`linspace(start,stop,count)` specs. Density grids accept signed nonzero levels;
negative shells use `negative_color`. Orbital and delta-density values are
nonzero magnitudes and always generate both signed phases. Contour surfaces use
a denser default extraction grid for tighter line spacing.

Every viewer accepts extensive settings — styles, camera presets, energy/force plots, constraint and polyhedron highlighting, charge/magmom coloring, and more. See the Python API reference for each class:

- [MolecularViewer](https://kangmg.github.io/aseview/api/molecular-viewer/) — structures and trajectories
- [SurfaceViewer](https://kangmg.github.io/aseview/api/surface-viewer/) — cube-backed orbital, density, and delta-density isosurfaces
- [LiteViewer / view()](https://kangmg.github.io/aseview/api/lite-viewer/) — lightweight wrapper, no control panel
- [OverlayViewer](https://kangmg.github.io/aseview/api/overlay-viewer/) — compare multiple structures
- [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/) — synchronized 2D/3D fragment picker

## Viewer Types

| Viewer | Description |
|--------|-------------|
| MolecularViewer | Single structure or trajectory animation |
| SurfaceViewer | CUBE orbital, density, and delta-density isosurfaces |
| LiteViewer / `view(...)` | Lightweight wrapper around MolecularViewer for quick renders — no control panel |
| NormalViewer | Normal mode vibration visualization |
| OverlayViewer | Compare multiple structures overlaid |
| FragSelector | Interactive 2D+3D atom selection with rect/lasso |

## VS Code Extension

The `vscode-extension/` package provides a native VS Code custom editor for structure files. It uses `ase-ts` for parsing and writing, so it does not require a Python runtime inside VS Code.

Supported default file patterns include `*.xyz`, `*.extxyz`, `*.cif`, `*.pdb`, `*.vasp`, `POSCAR`, and `CONTCAR`. See [vscode-extension/README.md](vscode-extension/README.md#settings) for the extension's settings (default viewer/style, read format/index) and commands.

```bash
cd vscode-extension
npm install
npm run compile
npm run package
```

Install the generated `.vsix` from VS Code with **Extensions -> Install from VSIX...**.
On tag releases, the VS Code workflow builds the same verified package and
attaches `aseview-vscode-<version>.vsix` plus `aseview-latest.vsix` to the
GitHub Release assets.

## Themes

aseview ships with multiple visual themes. Each theme is a complete HTML template set that controls the viewer's colour scheme, background, and UI style.

| Theme | Description |
|-------|-------------|
| `dark` | Dark theme with deep grey background |
| `darkgreen` | Dark theme with green accent colours |
| `simple` | Minimal, low-distraction theme |
| `spring` | Spring theme (default) with bright, airy colours |
| `glass` | Frosted-glass aesthetic with translucent UI panels |

```bash
aseview molecule.xyz --theme spring
aseview molecule.xyz -t glass -o out.html
```

See the [Theming guide](https://kangmg.github.io/aseview/theming/) for the Python/JavaScript theme API and instructions on creating custom themes.

Each full theme directory contains five runtime templates:
`molecular_viewer.html`, `normal_viewer.html`, `overlay_viewer.html`,
`frag_selector.html`, and `surface_viewer.html`. `LiteViewer` uses its own
fixed lightweight template and is not themed per instance.

## JavaScript Module

Use aseview in any web page without Python:

```html
<div id="viewer" style="width:100%; height:500px;"></div>

<script src="https://cdn.jsdelivr.net/gh/kangmg/aseview@main/aseview/static/js/aseview.js"></script>
<script>
    const viewer = new ASEView.MolecularViewer('#viewer', { viewPreset: 'top-c' });
    viewer.setData({
        symbols: ['O', 'H', 'H'],
        positions: [
            [0.0, 0.0, 0.117],
            [0.0, 0.757, -0.469],
            [0.0, -0.757, -0.469]
        ]
    });

    viewer.setView({ preset: 'front' }).then(() => {
        return viewer.savePNG({ returnDataUrl: true, download: false });
    }).then((png) => {
        console.log(png.filename, png.dataUrl.length);
    });
</script>
```

See the [JavaScript Module documentation](https://kangmg.github.io/aseview/js-module/) for the full API reference — camera control, PNG/GIF export options and promise shapes — or try the [live demo](https://kangmg.github.io/aseview/demo.html) and [playground](https://kangmg.github.io/aseview/playground/).

Python viewers expose the equivalent headless `save_png()` and `save_gif()` methods when installed with the `export` extra (see [Installation](https://kangmg.github.io/aseview/getting-started/installation/)).

## Supported Formats

Input files are handled through ASE in Python and `ase-ts` in the VS Code extension. Common formats include `xyz`, `extxyz`, `cif`, `pdb`, `vasp`, `POSCAR`, and `CONTCAR` — see [File Formats](https://kangmg.github.io/aseview/file-formats/) for the full list and viewer clipboard export details.

## License

MIT
