# 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
