v-ase-gui 0.0.1__tar.gz

v_ase_gui-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 v_ase contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

v_ase_gui-0.0.1/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-include v_ase/static *.html *.css *.js
+recursive-include v_ase/static/vendor *
+recursive-include docs *.md *.png
+recursive-include examples *.py
+recursive-include scripts *.py

v_ase_gui-0.0.1/PKG-INFO

@@ -0,0 +1,474 @@
+Metadata-Version: 2.4
+Name: v_ase-gui
+Version: 0.0.1
+Summary: v_ase: a Blender-style browser GUI and editor for ASE Atoms objects.
+Author: v_ase contributors
+License-Expression: MIT
+Keywords: ase,atoms,materials-science,visualization,editor,threejs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ase>=3.23
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: numpy>=1.24
+Requires-Dist: ipython>=8
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: playwright>=1.40; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Provides-Extra: jupyter
+Requires-Dist: notebook>=7; extra == "jupyter"
+Requires-Dist: jupyterlab>=4; extra == "jupyter"
+Dynamic: license-file
+
+# v_ase
+
+[![PyPI version](https://img.shields.io/pypi/v/v_ase-gui.svg)](https://pypi.python.org/pypi/v_ase-gui/)
+[![Python versions](https://img.shields.io/pypi/pyversions/v_ase-gui.svg)](https://pypi.python.org/pypi/v_ase-gui/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+`v_ase` is an interactive visualizer/editor for
+[ASE](https://wiki.fysik.dtu.dk/ase/) structures and trajectories. It is built
+for users who want to open a POSCAR/extxyz/traj file, inspect it as a movie when
+it has multiple frames, and manipulate atoms with Blender-like mouse and
+keyboard controls.
+
+It is intended to replace:
+
+```bash
+ase gui FILE
+```
+
+with:
+
+```bash
+v_ase gui FILE
+```
+
+For example:
+
+```bash
+v_ase gui POSCAR
+v_ase gui structure.vasp
+v_ase gui movie.extxyz
+v_ase gui relaxation.traj
+```
+
+The viewer opens locally in your browser. Middle mouse tumbles the camera,
+left click and box drag select atoms, `G` moves atoms, `R` rotates atoms,
+`X/Y/Z` lock axes, numeric input gives exact transforms, and trajectory files
+show playback controls for frame-by-frame movie inspection.
+
+![v_ase overview](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/readme_overview.png)
+
+## Highlights
+
+- `v_ase gui FILE` command-line workflow for structures and trajectories.
+- Python API: `from v_ase.visualize import view`.
+- Blender-style selection, camera control, and transforms: click, box select, `G`, `R`,
+  axis locking, numeric input, `Enter`, `Esc`, copy/paste/undo/delete.
+- ASE constraint-aware editing and visualization:
+  `FixAtoms`, `FixCartesian`, `FixedLine`, `FixedPlane`, `FixScaled`, and
+  `Hookean`.
+- Hookean constraints are visualized as threshold-aware hook/latch springs.
+- Trajectory playback with live frame slider, FPS control, image export, and
+  video export.
+- Periodic bonds, element-pair cutoff tables, manual bond pairs, supercell
+  preview, `make_supercell(P)` cell transform, and wrap atoms into cell.
+- Custom extxyz atom type labels such as `H_type5` are preserved for GUI type
+  settings even when ASE cannot parse them as real elements.
+- Export POSCAR, pickle, PNG image, WebM video, and Blender Python scene script.
+
+## Installation
+
+### From PyPI
+
+```bash
+python -m pip install v_ase-gui
+v_ase gui POSCAR
+```
+
+### From GitHub
+
+```bash
+git clone https://github.com/lgyEthan/v_ase.git
+cd v_ase
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+No conda and no Node.js are required. Three.js is vendored inside the package.
+
+### macOS
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+### Windows PowerShell
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+If activation is blocked:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+```
+
+### Linux
+
+Ubuntu/Debian:
+
+```bash
+sudo apt update
+sudo apt install python3 python3-venv python3-pip
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+### Optional Conda
+
+```bash
+conda create -n v_ase python=3.11
+conda activate v_ase
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+## Quick Start
+
+Open a structure file:
+
+```bash
+v_ase gui POSCAR
+v_ase gui structure.vasp
+v_ase gui trajectory.extxyz
+v_ase gui relaxation.traj
+```
+
+The direct file form also works:
+
+```bash
+v_ase POSCAR
+```
+
+Use from Python:
+
+```python
+from ase.build import molecule
+from v_ase.visualize import view
+
+atoms = molecule("H2O")
+edited = view(atoms)
+print(edited.positions)
+```
+
+Useful CLI options:
+
+```bash
+v_ase gui structure.vasp --show-bonds
+v_ase gui trajectory.extxyz --index :
+v_ase gui trajectory.extxyz --index -1
+v_ase gui POSCAR --output edited.vasp
+v_ase gui POSCAR --no-block
+```
+
+## Case 1: Selection, FixedLine, and FixedPlane
+
+Selected atoms get yellow Blender-style outlines. Fixed atoms are dimmed, and
+selected `FixedLine` / `FixedPlane` atoms show geometric guides so the allowed
+movement is visible before committing coordinates.
+
+![FixedLine and FixedPlane visualization](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/readme_constraints.png)
+
+Example:
+
+```python
+from ase.build import molecule
+from ase.constraints import FixAtoms, FixedLine, FixedPlane
+from v_ase.visualize import view
+
+atoms = molecule("H2O")
+atoms.set_constraint([
+    FixAtoms(indices=[0]),
+    FixedLine(1, [1, 0, 0]),
+    FixedPlane(2, [0, 0, 1]),
+])
+
+view(atoms)
+```
+
+When `Apply constraints` is enabled, move and rotate previews are projected onto
+the allowed line or plane and the backend commit uses
+`atoms.set_positions(..., apply_constraint=True)`.
+
+## Case 2: Hookean Constraints
+
+`Hookean` constraints are drawn with physical meaning. The `rt` threshold is
+placed in Angstroms along the constrained direction. Below the threshold the
+spring is inactive and shows slack. Beyond the threshold the latch engages and
+the spring becomes active.
+
+![Hookean threshold-aware spring](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/readme_hookean.png)
+
+Example:
+
+```python
+from ase.build import molecule
+from ase.constraints import Hookean
+from v_ase.visualize import view
+
+atoms = molecule("H2O")
+atoms.set_constraint(Hookean(1, 2, rt=1.8, k=5.0))
+view(atoms)
+```
+
+For trajectories, the Hookean graphic updates frame by frame, so inactive,
+near-threshold, and active states can be inspected as a movie.
+
+## Case 3: Rotate and Move
+
+Transforms follow Blender-style keyboard flow:
+
+```text
+G X 1.2 Enter
+R Z 30 Enter
+```
+
+Supported behavior:
+
+- `G`: move selected atoms.
+- `R`: rotate selected atoms.
+- `X`, `Y`, `Z`: lock transform axis in transform mode.
+- Numeric input: exact displacement or angle.
+- Left click or `Enter`: confirm.
+- `Esc`: cancel.
+- Optional move increment in Angstrom.
+- Optional rotate increment in degrees.
+- Rotate pivots: selection center, global origin, or unit-cell center.
+- Optional bond-strain guard for rejecting excessive periodic bond distortion.
+
+![Rotate mode](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/readme_rotate.png)
+
+## Case 4: Bonds, Periodicity, and Supercells
+
+Bonding can be automatic, element-pair based, or manually specified.
+
+- Auto cutoff uses covalent radii and respects periodic minimum-image distances.
+- Element-pair mode exposes pair-specific `rcut` rows.
+- Manual mode accepts pair strings such as `Na-Cl: 3.2` or `0-1, 1-2`.
+- Supercell preview shows repeated atoms and repeated unit-cell lines.
+- `Set Supercell as Cell` converts the preview into real editable atoms.
+- `Cell Transform` accepts a full integer `make_supercell(P)` matrix.
+
+For 2D periodic supercell/twist workflows, the cell transform applies:
+
+```text
+H' = P H
+```
+
+to every trajectory frame. Non-periodic axes are protected from accidental
+mixing, tilting, or repetition.
+
+## Case 5: Trajectories
+
+Multi-frame `Atoms` lists and ASE-readable trajectory files can be played as a
+movie.
+
+```bash
+v_ase gui relaxation.traj
+v_ase gui movie.extxyz --index :
+```
+
+Controls:
+
+- frame slider updates live while dragging
+- play/pause button
+- `Space`: play or pause
+- FPS control updates immediately while playback is running
+- export image and export video
+
+## Case 6: Custom Atom Types in extxyz
+
+Some workflows store type labels such as `H_type5`, `O_type2`, or `Si_type1`
+inside the `species` column. ASE itself cannot treat these strings as chemical
+elements, so v_ase reads them as GUI atom types while mapping them internally to
+valid ASE base elements.
+
+Example extxyz line:
+
+```text
+H_type5 82.30128 7.97802 11.47478
+```
+
+In v_ase:
+
+- ASE backend uses base element `H`.
+- GUI labels remain `H_type5`.
+- type-specific color variants are generated.
+- Appearance radius controls are grouped by `H_type5`, `O_type2`, etc.
+- Bond cutoff pair tables also use the preserved type labels.
+
+## Case 7: Export
+
+From the right panel:
+
+- `Export POSCAR`
+- `Export Pickle`
+- `Export Blender`
+- `Export Image`
+- `Export Video`
+
+Blender export downloads `v_ase_blender_scene.py`:
+
+```bash
+blender --python v_ase_blender_scene.py
+```
+
+The generated scene keeps atoms and constraint graphics as editable Blender
+objects where practical.
+
+## Python API
+
+```python
+from v_ase import view_edit, view_file
+
+edited_atoms = view_edit(
+    atoms,
+    notebook=False,
+    block=True,
+    show_cell=True,
+    show_axes=True,
+    show_bonds=False,
+    respect_constraints=True,
+    allow_relax=True,
+    return_mode="atoms",
+)
+
+view_file("trajectory.extxyz")
+```
+
+`return_mode` can be:
+
+- `"atoms"`: edited ASE `Atoms`
+- `"positions"`: edited `Nx3` positions array
+- `"none"`: no return value
+
+## Controls
+
+| Input | Action |
+| --- | --- |
+| Left click | Select atom or confirm transform |
+| Shift + left click | Add/remove selection |
+| Left drag | Box select |
+| Middle drag | Orbit viewport |
+| Shift + middle drag | Pan viewport |
+| Mouse wheel | Zoom |
+| `G` | Move selected atoms |
+| `R` | Rotate selected atoms |
+| `X`, `Y`, `Z` | Align view in select mode, lock axis in transform mode |
+| Number keys | Numeric transform input |
+| `Enter` | Confirm transform |
+| `Esc` | Cancel transform |
+| `Ctrl+C` / `Ctrl+V` | Copy / paste atoms |
+| `Ctrl+Z` / `Ctrl+Shift+Z` | Undo / redo |
+| `Delete` / `Backspace` | Delete selected atoms |
+| `Space` | Play/pause trajectory |
+
+## Development
+
+Install development tools:
+
+```bash
+python -m pip install -r requirements-dev.txt
+```
+
+Run tests:
+
+```bash
+python -m pytest tests -q
+```
+
+Open the all-in-one manual showcase:
+
+```bash
+python tests/manual_showcase.py
+```
+
+Regenerate README screenshots:
+
+```bash
+python scripts/capture_readme_screenshots.py
+```
+
+## Build for PyPI
+
+Build only:
+
+```bash
+python -m pip install -r requirements-dev.txt
+python -m build
+python -m twine check dist/*
+```
+
+Upload:
+
+```bash
+python -m twine upload dist/*
+```
+
+## Versioning
+
+The initial public release is `0.0.1`. Patch releases increment the last number:
+`0.0.2`, `0.0.3`, and so on. When code changes, update the version in
+`pyproject.toml`, the fallback version in `v_ase/__init__.py`, and the fallback
+CLI version in `v_ase/cli.py`, then rebuild and push to GitHub before uploading
+to PyPI.
+
+## Repository Layout
+
+```text
+v_ase/               Python package, CLI, server, and browser UI
+v_ase/static/        Three.js browser application and vendored Three.js
+docs/                Feature notes and README screenshots
+examples/            User examples
+scripts/             Release and documentation helper scripts
+tests/               Unit tests, regression tests, and manual showcase assets
+requirements.txt     Runtime dependencies
+requirements-dev.txt Development, test, and build dependencies
+pyproject.toml       Packaging metadata
+```
+
+## Notes
+
+- The local editor server binds to `127.0.0.1`.
+- Relaxation uses the calculator already attached to the `Atoms` object.
+- POSCAR export stores structural data. Pickle export can include the ASE object;
+  calculators may not always be pickleable.
+- The bundled browser UI is local-first; no Node.js build step is required.