Metadata-Version: 2.4
Name: crysviz
Version: 0.11.0
Summary: Browser-based crystal structure visualisation and analysis
Author: Florian Trybel, Abhijith S Parackal, Oscar Bulancea-Lindvall, Rickard Armiento
License-Expression: AGPL-3.0-or-later
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pywebview<7,>=6.2
Provides-Extra: qt
Requires-Dist: pywebview[qt]<7,>=6.2; extra == "qt"
Provides-Extra: gtk
Requires-Dist: pywebview[gtk]<7,>=6.2; extra == "gtk"
Dynamic: license-file


<img src="https://raw.githubusercontent.com/CrysViz/crysviz/main/docs/data/CrysViz_logo_clear_back.png" width="400">

# CrysViz - Crystal Structure Visualisation & Analysis

## Light-weight browser-based crystal structure visualisation and analysis with on-device rendering.

Run it in your browser at [crysviz.org](https://crysviz.org).

<img width="600" alt="Screenshot_crysviz" src="https://raw.githubusercontent.com/CrysViz/crysviz/deploy/docs/data/CrysViz_screenshot.png" />


CrysViz is a standalone visualisation tool built on top of Three.js. Paste a POSCAR/OUTCAR/CIF snippet, drop a local file (POSCAR, OUTCAR, CIF or QE input/output), or grab an OPTIMADE endpoint (or just Materials Project or Alexandria IDs). Your crystal structures will NOT leave your device!

Copyright (C) 2025-2026 Florian Trybel, Abhijith S Parackal, Oscar Bulancea-Lindvall, Henricus R.A. ten Eikelder and Rickard Armiento


## Key Features
- No backend required; runs entirely in the browser, no data leaves your machine. Runs in nearly every device (in particular smartphons and tablets) and in every browser. 
- Visualise Input and output from VASP, Quantum Espresso, and CIF files.
- Measure distances and angles.
- Use custom bond lengths with the optional ability to display atoms outside the unit cell that are bonded neighbours.
- Customizable color schemes can be choosen for any individual atoms 
- Forces and spin visualisation. Dynamically for relaxaton or MD trajectories
- Trajectory player. Load VASP OUTCARs and Quantum Espresso vc-relax output files directly and visualise the trajectories. Long MD trajecetories might be beyond your browsers memory limits.
- Symmetry anlysis and structure refinement (powered by Moyo WASM)
- Relxations and molecular dynamics simulations directly on your device with NEP potentials with upt to several hundred atoms. 
- Possibility to activate a calculation backend. This allows structural relaxations with any ASE compatible calculater, e.g., MACE, UPET, VASP, QE; trajectory is added and can be played using the trajectory player.
- Bond length histogram (angles and coordiantion numbers are comming soon).
- and many more...


This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.


## Maintainer
- **[Florian Trybel](https://github.com/ftrybel)** - Project lead
- **[Abhijith S Parackal](https://github.com/Abhivega)**
- **[Rickard Armiento](https://github.com/rartino)**
- **[Oscar Bulancea-Lindvall](https://github.com/oscarlindbul)**
- **[Henricus R.A. ten Eikelder](https://github.com/RicktenE)**


### Local in-browser installation and use

If you do not want to use CrysViz over the Internet, you can run it via a webserver on your own computer:

* Clone the CrysViz repository from GitHub

* Start the local server:

   ```bash
   make serve
   ```
* Visit the URL shown.


### Run CrysViz as a stand-alone application

The stand-alone application uses pywebview, which requires a native GUI backend.
This sometimes works automatically via CrysViz dependency handling,
but if not, follow the [installation instructions for pywebview](https://pywebview.flowrl.com/guide/installation.html)).

We suggest that you set up pywebview and CrysViz in a venv.
For pywebview to access its required system packages, you may need to create it as, e.g.:
```bash
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
python -m pip install pywebview
```
And then test that the pywebview backend works:
```python
import webview
webview.create_window('Hello world', 'https://pywebview.flowrl.com/')
webview.start()
```
Now you can install CrysViz into the venv as:
```bash
python -m pip install -e .
```
(Good alternatives are via `pipx install` or `uv tool install` if you have these tools available.)

And then run the standalone application with:
```
crysviz
```

### Python API

If you have the standalone application installed, you can also use the Python API for visualization and remote-control from Python. For example:

```python
from crysviz import Payload, Viewer, show

payload = Payload("silicon.cif", "data_Si\n_cell_length_a 5.43\n")
with Viewer([payload]) as viewer:
    structures = viewer.list_structures()
    viewer.select(structures[0].id, frame=0)
    viewer.update_lattice([[5.7, 0.0, 0.0], [0.2, 5.4, 0.0], [0.0, 0.0, 5.2]])
    viewer.update_fractional_positions([[0.0, 0.0, 0.0]], commit=False)
    viewer.commit_positions()
    viewer.recenter_camera()

# Equivalent concise construction; returns once the window is ready.
viewer = show(["structure.cif"])
```

For more, see [examples](https://github.com/CrysViz/crysviz/tree/deploy/examples).

## Widget mode / embedding

CrysViz can be embedded in another site as a compact interactive viewer with
`?widget=1`. The full guide, with the integration steps, the complete message
protocol and the rules for changing widget code, is
[`agent_guides/Widget.md`](agent_guides/Widget.md); a working host page is
[`docs/widget-embed-demo.html`](docs/widget-embed-demo.html).

Widget mode shows only the 3D structure view (with spin arrows), a locked
composition legend (lower right), a small axes gizmo (lower left) and a camera
control (top right: view along a, b or c, and reset). The CrysViz logo (top
left) is the menu:

- **Open in CrysViz**: the same structure in the full UI, in a new tab
- **Structures**: As loaded / Conventional / Primitive
- **Shading**: Metallic / Matte / Cel shading (plus Ray tracing / Path tracing
  with `tracers=1`)
- **Bonds** and **Polyhedra** toggles
- **Download POSCAR / CIF** of the cell shown
- any links the embedder adds (`menuLinks`, below)

**URL contract** — the embedder points an `<iframe>` at:

```
https://crysviz.org/index.html?widget=1[&control=1][&tracers=1][&theme=dark|light][&prefs=1]#<route>
```

| Query | Effect |
|---|---|
| `widget=1` | widget mode (required) |
| `control=1` | let the host page drive the widget over `postMessage` (below) |
| `tracers=1` | offer ray and path tracing (downloads the tracer pipelines; skipped by default) |
| `theme=dark` / `light` | force the UI theme at boot instead of following the OS; not persisted |
| `prefs=1` | re-apply the per-structure customisations (per-atom colours, focus regions) this browser saved in the full app. Off by default: the embed has no UI to see or reset them |

The fragment says where the structure comes from:

| Route | Use |
|---|---|
| `#load-file=<name>\|<base64>` | the file in the URL: name and base64 of its UTF-8 text, each URL-encoded. Simplest, for small text files; browsers cap URL length |
| `#load-url=<url>[\|<name>]` | fetched from an http(s) URL without cookies; the server must send `Access-Control-Allow-Origin` |
| `#load-message` | posted by the embedding page: no size limit, binary allowed. The widget posts `{source:'crysviz-widget', type:'awaitingSession'}` to its parent, which answers `{target:'crysviz-widget', type:'loadSession', name, data}` (`data`: string, ArrayBuffer, typed array or Blob) |

The file can be any format CrysViz reads, or a frames-style `.crysviz` session
(the "CrysViz" download format; `"format": "crysviz"` is required). The minimal
session is a single frame with `spins` and the display toggle on:

```json
{
  "format": "crysviz",
  "version": "2.16",
  "frames": [{
    "elements": ["Fe", "Fe", "O", "O"],
    "lattice": [[a,0,0],[0,a,0],[0,0,c]],
    "positions": [[0,0,0], ...],
    "spins": [{ "vector": [0,0,2] }, ...]
  }],
  "selectedFrameIndex": 0,
  "display": { "spinsActive": true }
}
```

Spin vectors are Cartesian magnetic moments, index-aligned to `positions`. The
Conventional/Primitive options symmetrise the cell (via moyo) on first pick
and remap the moments onto the new cell; a magnetic order that the smaller cell
cannot carry (a magnetic supercell) greys that option out. "Open in CrysViz"
opens the launch data in the full UI, on the frame shown when it is a
`.crysviz` session (a moyo-built cell, or any other file, opens as loaded): by
URL for a `#load-file=` launch that fits, otherwise by handing the data to the
new tab over `postMessage`.

**Precomputed cells (`frameKinds`)** — a database that already knows the
conventional and primitive cells can ship them as extra frames instead of
paying for the in-browser symmetrisation. Send a multi-frame session whose
`frames` are `[as-loaded, conventional?, primitive?]` and add a top-level
`frameKinds` array, order-aligned with `frames`, labelling each with
`"loaded"`, `"conventional"`, or `"primitive"` (kinds after the first are
optional):

```json
{
  "format": "crysviz",
  "version": "2.16",
  "frames": [ { …loaded… }, { …conventional… }, { …primitive… } ],
  "frameKinds": ["loaded", "conventional", "primitive"],
  "selectedFrameIndex": 0,
  "display": { "spinsActive": true }
}
```

When `frameKinds` is present the widget's Structures menu lists **exactly the
shipped frames**, one entry per kind (`"loaded"` reads "As loaded", other
strings are capitalised), and picking one selects that frame — no moyo runs
and no in-browser spin remapping happens. `frameKinds` must be an array of
strings with one entry per frame; otherwise it is dropped and the menu falls
back to the moyo build path above. The key is widget-only: the full app
ignores `frameKinds` entirely (a session with it loads as an ordinary
multi-frame trajectory).

**Menu links (`menuLinks`)** — the embedder can add its own dropdown items that
open URLs. A top-level `menuLinks` array of `{label, url}` (same channel as
`frameKinds`) renders as plain items in the widget menu after the Download
items; clicking one opens `url` in a new tab. The altermagnets DB uses this
for links to its files endpoint. Validated strictly: each `label` a non-empty
string (≤40 chars), each `url` an `http`/`https` URL that parses; invalid
entries are dropped, an empty result shows no group. Widget-only — the full
app ignores it.

```json
{ "menuLinks": [
  { "label": "Database entry", "url": "https://altermagnets.example/entry/x" },
  { "label": "Download VASP inputs", "url": "https://altermagnets.example/files/x.zip" }
] }
```

**Host control (`control=1`)** — the host page can step a trajectory, switch
between several structures loaded as frames, and link the cameras of two
widgets. Commands go to the iframe as
`{target:'crysviz-widget', type, …}`: `getState`, `setFrame {index, recenter?}`,
`fitView`, `play {fps?, loop?}`, `pause`, `getCamera`, `setCamera {view}`. The
widget answers with `{source:'crysviz-widget', type, …}`: `ready`, `state`,
`frame`, and `camera` (the user moved the camera; moves made by host commands
are never reported, so two linked widgets do not echo). Only the iframe's
direct parent can drive it. See [`agent_guides/Widget.md`](agent_guides/Widget.md)
for the fields and examples.

**Sandboxing** — the iframe does **not** need `allow-same-origin`; give it
`sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox allow-downloads"`
(popups for "Open in CrysViz" and menu links, downloads for POSCAR/CIF). Widget
mode runs correctly in an opaque origin where browser storage and web workers
are unavailable (preferences fall back to defaults, heavy work runs on the
main thread). An opaque-origin embed does, however, require the CrysViz host to
serve CORS headers (`Access-Control-Allow-Origin`) for its ES-module and WASM
fetches — true on GitHub Pages (where crysviz.org is served) and in
`make serve`, and something self-hosters must configure.

## Third-Party Libraries

1. THREE.js
   - Repository: https://github.com/mrdoob/three.js/
   - License: MIT
   - Copyright: THREE.js authors
   - See docs/external/three/LICENSE for the full license text.
   - License and code can be found in docs/external/three/
   
2. Moyo
   - Repository: https://github.com/spglib/moyo
   - License: MIT or Apache-2.0
   - Copyright: Kohei Shinohara
   - See docs/external/moyo-test/LICENSE for the full license text.
   - Explicitly moyo-wasm is used.
   - License and code can be found in docs/external/moyo-test/

3. NEP_CPU
   - Repository: https://github.com/brucefan1983/NEP_CPU
   - License: GPL-3.0
   - Copyright: NEP_CPU authors
   - See docs/external/nep_wasm/LICENSE-NEP_CPU for the full license text.
   - Explicitly NEP_CPU is compliled into a WASM module. 
   - License and code can be found in docs/external/nep_wasm/

4. NEP89 Weights (from GPUMD)
   - Repository: https://github.com/brucefan1983/GPUMD
   - License: GPL-3.0
   - Copyright: GPUMD authors
   - The weights can be found in docs/external/nep_wasm/
   - See docs/external/nep_wasm/LICENSE-GPUMD for the full license text.

5. three-wboit
   - Repository: https://github.com/stevinz/three-wboit
   - License: MIT
   - Copyright: Stephens Nunnally (@stevinz); portions mrdoob and three.js authors, Alexander Rose
   - See docs/external/three-wboit/LICENSE for the full license text.
   - Used by the optional "Weighted blended (WBOIT)" rendering pipeline.
   - License and code can be found in docs/external/three-wboit/

6. three-depthpeeling-demo
   - Repository: https://github.com/gkjohnson/three-depthpeeling-demo
   - License: MIT
   - Copyright: Garrett Johnson
   - See docs/external/three-depthpeeling/LICENSE for the full license text.
   - Adapted (not verbatim) for the optional "Depth peeling" rendering pipeline;
     see docs/external/three-depthpeeling/README.md for the divergences.
   - License and code can be found in docs/external/three-depthpeeling/

7. THREE.js-RayTracing-Renderer
   - Repository: https://github.com/erichlof/THREE.js-RayTracing-Renderer
   - License: CC0 1.0 (public domain; attribution given as a courtesy)
  The CC0 dedication applies to the upstream original only; CrysViz's
     local adaptations in docs/external/three-raytracing/ and the first-party ray/path
     tracing code under docs/render/pipeline/ are licensed AGPL-3.0.
   - Author: Erich Loftis (@erichlof)
   - See docs/external/three-raytracing/LICENSE for the full license text.
   - GLSL chunk library adapted for the optional "Ray tracing" rendering
     pipeline; see docs/external/three-raytracing/README.md for the adaptations.
   - License and code can be found in docs/external/three-raytracing/

8. THREE.js-PathTracing-Renderer
   - Repository: https://github.com/erichlof/THREE.js-PathTracing-Renderer
   - License: CC0 1.0 (public domain; attribution given as a courtesy)
  The CC0 dedication applies to the upstream original only; CrysViz's
     local adaptations in docs/external/three-pathtracing/ and the first-party ray/path
     tracing code under docs/render/pipeline/ are licensed AGPL-3.0.
   - Author: Erich Loftis (@erichlof)
   - See docs/external/three-pathtracing/LICENSE for the full license text.
   - GLSL chunk library adapted for the optional "Path tracing" rendering
     pipeline; see docs/external/three-pathtracing/README.md for the adaptations.
   - License and code can be found in docs/external/three-pathtracing/

9. QR Code generator
   - Repository: https://github.com/nayuki/QR-Code-generator
   - License: MIT
   - Copyright: Project Nayuki
   - Loaded on demand from jsDelivr (npm `nayuki-qr-code-generator`) to draw the
     QR code in the share-link dialog.

10. httk data-generators
   - Repository: https://github.com/httk/data-generator
   - License: CC-BY-4.0 (https://creativecommons.org/licenses/by/4.0/)
   - Copyright: Rickard Armiento
   - Generated with cctbx (https://cctbx.github.io/) and spglib
     (https://spglib.readthedocs.io/).
   - Space-group settings, symmetry operations, Wyckoff positions and
     asymmetric units. The dataset carries its own license and provenance
     metadata; both live in docs/data/symmetry_basics.json.

## Other Attributions

- CrysViz uses some color maps from the [Scientific colour maps by Fabio Crameri](https://doi.org/10.5281/zenodo.1243862) (Version 8)
- [OPTIMADE](https://www.optimade.org/) compatible structure providers including Materials Project and Alexandria.
