v_ase
v_ase combines ASE's convenient terminal and Python workflow with flexible
3D structure manipulation in one local visualizer. It opens atomic structures
and trajectories in a browser, remains lightweight for viewing large systems,
and enables direct atom editing when requested.
Install
From PyPI:
python -m pip install v_ase-gui
From GitHub:
git clone https://github.com/lgyEthan/v_ase.git
cd v_ase
python -m pip install -e .
No Node.js installation is required.
Open
Start an empty workspace or open a file directly:
v_ase gui
v_ase gui FILE
Examples:
| Input | Command |
|---|---|
| POSCAR | v_ase gui POSCAR |
| VASP structure | v_ase gui structure.vasp |
| XYZ trajectory | v_ase gui trajectory.extxyz |
| ASE trajectory | v_ase gui relaxation.traj |
| Saved v_ase project | v_ase gui project.vase |
The terminal is released when the v_ase browser document closes.
When v_ase starts without a file, Open begins in the terminal directory
where v_ase gui was run. Navigate its subfolders directly, or choose
System Picker to open a file elsewhere on the computer.
The top-bar Open command offers three actions:
| Action | Result |
|---|---|
| Replace this tab | Replace the current structure or trajectory |
| Add to trajectory | Append the selected frames to the current movie |
| Open in new tab | Open an independent document beside the current tab |
Replacing a tab or opening a new tab with .vase restores the complete saved
project. Adding .vase to a trajectory imports its structures only and keeps
the active tab's camera, appearance, bonds, lighting, and other visual settings.
New labels and chemical types are added to the existing Appearance and
pairwise-bond controls automatically.
View And Edit Modes
View is the default. It is optimized for visualization, trajectories, measurements, bonds, supercells, appearance, wrapping, and export:
v_ase gui trajectory.extxyz
Use the View / Edit switch in the top bar at any time. Edit enables coordinate transforms, atom creation/deletion, constraints, undo, copy/paste, and relaxation. To start directly in Edit:
v_ase gui structure.vasp --interactive
The current structure, trajectory frame, camera, labels, appearance, bonds, and selection remain in place during a mode change. If individual atoms have different visual materials, switching to View creates numbered labels only for those visual variants. Position-only edits stay in the same label group.
Multiple Documents
Use + immediately after the document tabs to create an empty independent
tab. Tabs resize as documents are added. Each tab owns its structure or
trajectory, camera, selection, calculator, history, display settings,
relaxation state, and .vase project. Inactive tabs pause rendering and movie
playback.
Controls
| Input | Action |
|---|---|
| Left click | Select an atom or confirm a transform |
| Shift + left click | Add or remove selection |
| Left drag | Box selection |
| Middle drag | Orbit |
| Shift + middle drag | Pan |
| Wheel | Zoom |
G |
Move selected atoms |
R |
Rotate selected atoms |
X, Y, Z |
Lock a transform axis; otherwise align the camera |
| Number keys | Enter an exact distance or angle during G/R |
Enter / left click |
Confirm a transform |
Esc / right click |
Cancel a transform |
Ctrl+C, Ctrl+V, Ctrl+Z |
Copy, paste, undo |
Delete / Backspace |
Delete selected atoms |
Space |
Play or pause a trajectory |
Tab / Esc |
Open the collapsed control panel |
Esc |
Close the open panel and return focus to the viewport |
The ? button shows the complete shortcut list. The six toolbar arrows are ordered as up/down, left/right, and counterclockwise/clockwise roll. They move only the camera by the selected angle; roll direction follows the current screen view and atomic coordinates do not change.
Trajectories
Multi-frame inputs add a timeline below the viewport. Frame scrubbing updates
immediately, FPS changes apply during playback, and Skip advances by
skip + 1 frames per tick. Bond settings, appearance, and supercell display
remain active across all frames.
In interactive mode, relaxation creates a separate optimization timeline. Loaded trajectory frames and their corresponding relaxation paths remain visually distinct.
Constraints
ASE constraints remain authoritative during interactive transforms while Apply constraints is enabled.
FixedLine
The atom moves only along its permitted line.
v_ase gui examples/readme_scene_assets/fixedline.traj --show-bonds --interactive
FixedPlane And FixScaled
FixedPlane atoms move within their displayed plane. VASP selective dynamics
read as FixScaled are displayed from their allowed fractional directions.
v_ase gui examples/readme_scene_assets/fixedplane.traj --show-bonds --interactive
FixAtoms
Fixed atoms keep their element color and use a distinct constrained surface treatment. They remain visible without looking selected.
Hookean
Hookean constraints show the inactive cutoff, threshold, and active spring
state. The spring engages only after the constrained distance passes rt.
v_ase gui examples/readme_scene_assets/hookean.traj --show-bonds --interactive
Editing And Measurement
Move and angle increments, transform pivot, constraints, cell transforms, supercells, and wrapping are available from the control panel. Axis-locked rotation can show low-strain commensurate cell-boundary angles and optionally snap to them.
One through four ordered selections are marked a1 through a4. The viewport
shows point information, a1-a2 distance, the a1-a2-a3 angle centered on
a2, or the signed a1-a2-a3-a4 torsion. Distances report direct and
minimum-image-convention (MIC) values; selecting a displayed supercell image
also reports its unit-cell-mapped distance. Angles and torsions use the
displayed coordinates without an additional MIC value. Larger selections show
the total followed by counts for each atom label. Hovered-atom metadata is
displayed separately.
Appearance, Bonds, And Rendering
The Display workspace provides:
- orthographic or perspective projection;
- a true-white viewport background by default, with balanced modeling light for clear element colors and a dark background option;
- 3D spheres/cylinders or 2D atoms/flat bonds;
- live atomic scale in pixels per Angstrom;
- atom smoothness and anti-aliasing; new documents use a
0.60xatom radius; - per-label element TYPE, label, visibility, color, radius, and material;
- Modeling, Studio Sun, and Sun + Soft Shadow rendering;
- editable Sun intensity, source, target, and viewport handles;
- unit cell, axes, grid, supercell, and overlay controls.
Material presets are Standard, Metal, and Rubber. In View, a preset applies to a complete label group. In Edit, selected atoms can use independent materials and can be merged into an existing label by entering that exact label. Chemical TYPE remains synchronized with ASE while labels continue to control visual grouping. Metal uses a high-contrast studio reflection so it remains visually distinct from the glossy Standard preset.
Bonds support automatic covalent-radius inference, label-pair cutoffs, and
manual index pairs. A pairwise cutoff of 0 disables that label pair.
Thickness, cylinder/flat style, custom color, and midpoint-split atom colors are
configurable. New documents use a 0.25 A bond diameter. Interactive bonds
form and break during atom transforms.
Export And Save
| Option | Contents |
|---|---|
| Export POSCAR | Current atomic structure in VASP format |
| Export ASE Pickle | Current ASE Atoms, labels, constraints, arrays, and valid SinglePointCalculator results |
| Export Image | PNG using the Preview Area camera and crop |
| Export Video | Complete trajectory as MOV or AVI |
| Export Blender | Optimized Python scene with atoms, bonds, camera, Sun, optional cell, and trajectory animation |
| Export 3DM | Instanced Rhino geometry, metadata, and saved views |
| Export OBJ | OBJ/MTL plus camera and metadata JSON in a ZIP |
| Save Project | Self-contained .vase structure/trajectory and complete visual state |
| Save Settings | Reusable appearance, bonds, camera, lighting, quality, and supercell JSON |
Preview Area uses the exact image/video aspect ratio, camera, crop, display, and lighting profile used for export. The frame stays fixed while orbit and zoom change the structure inside it. Unit cell, grid, axes, background, atom smoothness, and renderer are independently selectable for output.
.vase files are self-contained; reopening one does not require the original
structure file. Opening an ordinary structure from an active workspace keeps
the current visual settings. Opening a .vase project restores its saved state.
Rhino export requires:
python -m pip install "v_ase-gui[rhino]"
OBJ export has no optional dependency.
Python
from ase.build import molecule
from v_ase.visualize import view
atoms = molecule("H2O")
view(atoms) # lightweight visualization mode
To edit and return an ASE object:
edited = view(atoms, viz_only=False)
print(edited.positions)
view() works with one Atoms, a sequence of frames, or a supported file path.
view_edit() remains as a compatibility alias for interactive mode.
File Formats
File type is normally detected automatically. Common inputs include POSCAR,
CONTCAR, VASP files, XDATCAR, vasprun.xml, XYZ/extxyz, ASE .traj, LAMMPS
dump/data files, and .vase.
Repeated POSCAR/CONTCAR species blocks remain separate visual groups. For
example, O Cu O with counts 1 14 5 appears as O1, Cu, and O2.
The ASE chemical symbols remain unchanged, so calculations and exports continue
to use the correct elements.
For an ambiguous filename, select the reader explicitly:
v_ase gui ABCD --format POSCAR
v_ase gui ABCD --format XDATCAR
v_ase gui ABCD --format vasprun.xml
v_ase gui ABCD --format lammpstrj
v_ase gui ABCD --format extxyz
v_ase gui ABCD --format data
Use --index : for all frames, --index -1 for the last frame, or an integer
for one frame.
Help
v_ase --help
v_ase gui --help
Report reproducible problems at GitHub Issues.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file v_ase_gui-0.0.85.tar.gz.
File metadata
- Download URL: v_ase_gui-0.0.85.tar.gz
- Upload date:
- Size: 31.5 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
098188b4bbe69e4be013eadcfc37bfc4427df03919a30036c3af1e1299c25c83
|
|
| MD5 |
c277ee829c612311138579f4b58b5fd5
|
|
| BLAKE2b-256 |
5c5dbf5c618e290f3f4988ea271d9674e319bb86b32e5e45066648ffb52e9322
|
File details
Details for the file v_ase_gui-0.0.85-py3-none-any.whl.
File metadata
- Download URL: v_ase_gui-0.0.85-py3-none-any.whl
- Upload date:
- Size: 1.2 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
907f523254cf8aeb2c241ef1e22cd0478ff8f8651a5c64a62fcf5dde036f1de4
|
|
| MD5 |
e463409f0f98cdf74e5cc4089a58a344
|
|
| BLAKE2b-256 |
93d9c048baf52b9221fd992a7fbae93f3a6f01bba35f385229a7a17b18cfa6cb
|
