Metadata-Version: 2.4
Name: ceraviz
Version: 0.1.0
Summary: Crystal structure visualization and Materials Project search tool
Author-email: Siddharth Kumar <mm21b061@smail.iitm.ac.in>
License: MIT
Project-URL: Homepage, https://github.com/SiddharthKumar/ceraviz
Project-URL: Repository, https://github.com/SiddharthKumar/ceraviz
Project-URL: Issues, https://github.com/SiddharthKumar/ceraviz/issues
Keywords: crystal,materials,visualization,pymatgen,pyvista,materials-project
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 :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mp-api>=0.45
Requires-Dist: numpy<3,>=2.0
Requires-Dist: pymatgen>=2024.1
Requires-Dist: pyvista>=0.44
Requires-Dist: rich>=13.0
Requires-Dist: vtk>=9.3
Provides-Extra: jupyter
Requires-Dist: ipykernel; extra == "jupyter"
Requires-Dist: trame>=3.6; extra == "jupyter"
Requires-Dist: trame-vtk>=2.8; extra == "jupyter"
Requires-Dist: trame-vuetify>=3.0; extra == "jupyter"
Requires-Dist: pyvistaqt>=0.11; extra == "jupyter"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# CeraViz

Crystal structure visualization and Materials Project search tool.

Render 3D crystal structures from the [Materials Project](https://materialsproject.org/) database with **PyVista**, complete with CrystalNN bond detection, split-bond coloring, and interactive atom inspection.

## Features

- **3D crystal visualization** with atoms, bonds, and unit cell wireframe
- **CrystalNN bond detection** with split-bond coloring per element
- **Jmol/CPK color scheme** for all elements
- **Interactive CLI search** across the Materials Project database
- **Supercell expansion** (arbitrary nx×ny×nz)
- **Click-to-inspect** atom info (element, coordinates, oxidation state)

## Installation

```bash
pip install ceraviz
```

For Jupyter notebook support:

```bash
pip install ceraviz[jupyter]
```

## Setup

You need a **free** Materials Project API key:

1. Sign up at [materialsproject.org](https://next-gen.materialsproject.org/api)
2. Set the environment variable:

```bash
export MP_API_KEY="your_api_key_here"
```

## Quick Start

### Python API

```python
from ceraviz import render_material

# Render a crystal structure by Materials Project ID
render_material("mp-1234")

# With supercell expansion
render_material("mp-1234", supercell=(2, 2, 2))
```

### CLI Search

```bash
ceraviz
```

This launches an interactive CLI where you can:
1. Search by elements (e.g., `Li,Fe`)
2. Search by chemical system (e.g., `Li-Fe`)
3. Search with wildcards (e.g., `Li-Fe-*-*`)
4. Search by exact formula (e.g., `Li3Fe`)
5. View any result as a 3D crystal structure

## Dependencies

- [pymatgen](https://pymatgen.org/) — crystal structure analysis
- [PyVista](https://docs.pyvista.org/) — 3D visualization
- [mp-api](https://github.com/materialsproject/api) — Materials Project API client
- [Rich](https://rich.readthedocs.io/) — CLI formatting

## License

MIT
