Metadata-Version: 2.4
Name: ase-ovito
Version: 0.1.0
Summary: ASE plugin providing file I/O and visualization capabilities via OVITO
Project-URL: Homepage, https://gitlab.com/ovito-org/ase-ovito
Project-URL: Repository, https://gitlab.com/ovito-org/ase-ovito
Project-URL: Bug Tracker, https://gitlab.com/ovito-org/ase-ovito/-/issues
Author-email: Alexander Stukowski <stukowski@ovito.org>
Maintainer-email: "OVITO GmbH, Germany" <support@ovito.org>
License: MIT
License-File: LICENSE
Keywords: ase,atomistic,molecular-dynamics,ovito,simulation,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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
Requires-Dist: ase>=3.22
Requires-Dist: ovito>=3.15
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# ase-ovito

An [ASE](https://ase-lib.org) plugin that integrates the [OVITO](https://www.ovito.org) software package as a file I/O backend and visualization engine for atomic structures. 

This ASE extension is maintained by the OVITO development team and is available under the MIT license. You **don't** need a paid license to use it and you **don't** need to install the OVITO Basic/Pro desktop applications.

## Features

- Read atomic structure files via OVITO's Python API - [supports all formats that OVITO can read](https://docs.ovito.org/reference/file_formats/file_formats_input.html#file-formats-input)
- Visualize ASE `Atoms` objects using OVITO's [interactive rendering functions](https://docs.ovito.org/python/modules/ovito_gui.html)

## Installation

```bash
pip install ase-ovito
```

This will automatically pull in the following dependencies:

- [ase](https://ase-lib.org) >= 3.22
- [ovito](https://docs.ovito.org/python/) >= 3.15

## Quick start

Read a file using OVITO as the I/O backend:

```python
import ase.io

atoms = ase.io.read('CoCrNi.POSCAR', format='ovito')
```

Use this to load [all file formats supported by OVITO](https://docs.ovito.org/reference/file_formats/file_formats_input.html#file-formats-input). The format is auto-detected from the file contents. See [ovito.io.import_file](https://docs.ovito.org/python/modules/ovito_io.html#ovito.io.import_file) documentation for futher arguments that can be passed to the function.

Visualize an ASE `Atoms` object using an OVITO interactive viewport:

```python
import ase.visualize

ase.visualize.view(atoms, viewer='ovito')
```

When called from a **Jupyter notebook**, this displays an embedded interactive widget directly in the browser cell output. When called from a **standalone Python script**, it opens a native Qt viewport window instead. The `ipywidgets` package must be installed for the Jupyter widget to work.

## Implementation details

The functions in this plugin are based on the [ovito.gui](https://docs.ovito.org/python/modules/ovito_gui.html) and [ovito.io.ase](https://docs.ovito.org/python/modules/ovito_io_ase.html) modules. The latter provides a low-level bridge between ASE and OVITO. You can use this module directly to convert between ASE `Atoms` objects and OVITO `DataCollection` objects, which can then be used as input for any OVITO pipeline or visualization function. See the [ovito.io.ase](https://docs.ovito.org/python/modules/ovito_io_ase.html) documentation for details.

## Requirements

- Python >= 3.10
- [ASE](https://ase-lib.org) >= 3.22
- [OVITO Python Package](https://docs.ovito.org/python/) >= 3.15

## License

MIT — Copyright (c) 2026 OVITO GmbH, Germany

## Source code

[https://gitlab.com/ovito-org/ase-ovito](https://gitlab.com/ovito-org/ase-ovito)
