# pyvista-js

[![PyPI](https://img.shields.io/pypi/v/pyvista-js.svg)](https://pypi.org/project/pyvista-js/)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Documentation Status](https://readthedocs.org/projects/pyvista-js/badge/?version=latest)](https://pyvista-js.readthedocs.io/en/latest/?badge=latest)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/tkoyama010/pyvista-js/main.svg)](https://results.pre-commit.ci/latest/github/tkoyama010/pyvista-js/main)
[![JupyterLite](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://tkoyama010.github.io/pyvista-js/)
![All Contributors](https://img.shields.io/github/all-contributors/tkoyama010/pyvista-js?color=ee8449)

PyVista-like API for vtk.js - Bring intuitive 3D visualization to the browser.

## Vision

Provide a familiar PyVista interface that works seamlessly in browser environments (Pyodide, stlite, JupyterLite) by leveraging vtk.js under the hood.

## Quick Example (Goal)

```python
import pyvista_js as pv
import streamlit as st

# Create a plotter
plotter = pv.Plotter()

# Add a mesh
mesh = pv.Sphere()
plotter.add_mesh(mesh, color="red", opacity=0.8)

# Display in browser
plotter.show()
```

## Features (Planned)

- 🎨 **PyVista-like API** - Familiar interface for PyVista users
- 🌐 **Browser-native** - Runs entirely in the browser via Pyodide
- ⚡ **vtk.js powered** - Leverages the power of vtk.js for rendering
- 📊 **Streamlit/stlite support** - Easy integration with web frameworks
- 🔧 **Lightweight** - No server required, pure client-side

## Installation

```bash
pip install pyvista-js
```

For Pyodide/stlite:

```python
import micropip

await micropip.install("pyvista-js")
```

## Usage

### Basic Example

```python
import pyvista_js as pv

# Create a plotter
plotter = pv.Plotter()

# Add a mesh
mesh = pv.Sphere(radius=1.0)
plotter.add_mesh(mesh, color="red", opacity=0.8)

# Display (in Pyodide/browser environment)
plotter.show()
```

### Streamlit/stlite Example

```python
import streamlit as st
import pyvista_js as pv

st.title("3D Visualization")

# Create visualization
plotter = pv.Plotter()
sphere = pv.Sphere()
plotter.add_mesh(sphere, color="blue")

# Display in Streamlit
pv.pyvista_chart(plotter, height=600)
```

## API Design

### Core Classes

```python
# Plotter - Main visualization interface
plotter = pv.Plotter()
plotter.add_mesh(mesh, **kwargs)
plotter.show()

# Geometric objects
sphere = pv.Sphere(radius=1.0, center=(0, 0, 0))
cube = pv.Cube()
cylinder = pv.Cylinder()

# Mesh operations
mesh.points  # NumPy array of vertices
mesh.faces  # Cell connectivity
```

## Comparison with PyVista

| Feature | PyVista | pyvista-js |
|---------|---------|------------|
| Backend | VTK (C++) | vtk.js (WebGL) |
| Environment | Desktop | Browser |
| Installation | `pip install pyvista` | `pip install pyvista-js` |
| Rendering | Native OpenGL | WebGL |
| Server Required | Optional | No |

## Status

🚀 **Beta** - Core functionality implemented!

- [x] Core Plotter API
- [x] Basic geometric primitives (Sphere, Cube, Cylinder)
- [x] Mesh rendering with vtk.js
- [x] PyVista compatibility layer
- [x] Streamlit/stlite integration
- [ ] Advanced mesh operations
- [ ] Comprehensive documentation
- [ ] More examples

## Contributing

Contributions are welcome! This project aims to:

1. Provide PyVista-like API for browser environments
1. Leverage vtk.js for efficient WebGL rendering
1. Enable 3D visualization in Pyodide/stlite applications

## Related Projects

- [PyVista](https://github.com/pyvista/pyvista) - 3D plotting and mesh analysis
- [vtk.js](https://github.com/Kitware/vtk-js) - VTK for the Web
- [stlite](https://github.com/whitphx/stlite) - Serverless Streamlit

## License

BSD 3-Clause License - See [LICENSE](LICENSE) for details.

This project uses vtk.js which is also licensed under BSD 3-Clause License.

## Acknowledgments

- Built on top of [vtk.js](https://kitware.github.io/vtk-js/)
- Inspired by [PyVista](https://www.pyvista.org/)
- Designed for [Pyodide](https://pyodide.org/) environments

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->

<!-- prettier-ignore-start -->

<!-- markdownlint-disable -->

<table>
  <tbody>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/tkoyama010"><img src="https://avatars.githubusercontent.com/u/7513610?v=4?s=100" width="100px;" alt="Tetsuo Koyama"/><br /><sub><b>Tetsuo Koyama</b></sub></a><br /><a href="#ideas-tkoyama010" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/tkoyama010/pyvista-js/commits?author=tkoyama010" title="Documentation">📖</a> <a href="https://github.com/tkoyama010/pyvista-js/commits?author=tkoyama010" title="Code">💻</a> <a href="https://github.com/tkoyama010/pyvista-js/pulls?q=is%3Apr+reviewed-by%3Atkoyama010" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/tkoyama010/pyvista-js/issues?q=author%3Atkoyama010" title="Bug reports">🐛</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://allcontributors.org"><img src="https://avatars.githubusercontent.com/u/46410174?v=4?s=100" width="100px;" alt="All Contributors"/><br /><sub><b>All Contributors</b></sub></a><br /><a href="https://github.com/tkoyama010/pyvista-js/commits?author=all-contributors" title="Documentation">📖</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://pre-commit.com"><img src="https://avatars.githubusercontent.com/u/6943086?v=4?s=100" width="100px;" alt="pre-commit"/><br /><sub><b>pre-commit</b></sub></a><br /><a href="#maintenance-pre-commit" title="Maintenance">🚧</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://anthropic.com/claude-code"><img src="https://avatars.githubusercontent.com/u/81847?v=4?s=100" width="100px;" alt="Claude"/><br /><sub><b>Claude</b></sub></a><br /><a href="https://github.com/tkoyama010/pyvista-js/issues?q=author%3Aclaude" title="Bug reports">🐛</a></td>
    </tr>
  </tbody>
</table>

<!-- markdownlint-restore -->

<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
