<p align="center">
    <br />
    <br />
    <a href="https://pypi.org/project/fluxion-engine/"><img src="https://img.shields.io/pypi/v/fluxion-engine.svg?style=flat&logo=pypi" alt="PyPI Latest Release"></a>
    <a href="http://choosealicense.com/licenses/mit/"><img src="https://img.shields.io/badge/license-MIT-red.svg?style=flat" alt="MIT License"></a>
    <a href="https://github.com/Fluxion-engine/fluxion"><img src="https://img.shields.io/github/stars/Fluxion-engine/fluxion?style=social" alt="GitHub Stars"></a>
    <br />
    <br />
    <i>A powerful Python framework for creating mathematical animations programmatically</i>
</p>
<hr />

# 🌌 Fluxion

**Fluxion** is designed to be the next evolution of programmatic animation systems — built for speed, simplicity, and powerful visual storytelling.

### Fluxion is:

- ⚡ **Fast** - Optimized rendering pipeline for quick iterations
- 🎨 **Beautiful** - High-quality vector graphics and smooth animations
- 📐 **Mathematically expressive** - Intuitive API for complex mathematical visualizations
- 🧠 **Built for creators, educators, and engineers** - Perfect for educational content, presentations, and technical demonstrations
- 🧩 **Fully scriptable with Python** - Leverage the full power of Python for your animations
- 📦 **Easily extensible** - Plugin system for custom functionality

## 📚 Table of Contents

- [Features](#-features)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [CLI Usage](#-cli-usage)
- [Jupyter Support](#-jupyter-support)
- [API Overview](#-api-overview)
- [Contributing](#-contributing)
- [License](#-license)

## 🚀 Features

### 🎨 High-Quality Vector Rendering
Create crisp, scalable animations with Cairo and OpenGL rendering backends.

### 🧩 Modular Scene System
Build complex animations by composing simple, reusable components.

### ⚡ GPU-Ready Architecture
Leverage modern graphics capabilities for real-time rendering and previews.

### 📊 Math-First API
Intuitive interfaces for mathematical objects, transformations, and animations.

### 📝 Jupyter Notebook Magic
Seamlessly integrate animations into your Jupyter workflows with `%%fluxion` magic commands.

### 🖥️ Command Line Renderer
Powerful CLI for batch rendering and automation.

### 🧱 Plugin System
Extend Fluxion with custom functionality through a flexible plugin architecture.

### 🖼 Export Formats
Export to MP4, GIF, PNG sequences, and more.

## 🧰 Installation

### Install via pip

```bash
pip install fluxion-engine
```

### Developer Installation

```bash
git clone https://github.com/Fluxion-engine/fluxion.git
cd fluxion
pip install -e .
```

## ⚡ Quick Start

Create a file named `example.py`:

```python
from fluxion import *

class SquareToCircle(Scene):
    def construct(self):
        square = Square()
        circle = Circle().set_fill("#EF6BBB", 0.5)
        
        self.play(Create(square))
        self.play(Transform(square, circle))
        self.play(FadeOut(square))
```

Render:

```bash
fluxion -p -ql example.py SquareToCircle
```

You should see your native video player pop up and play a simple scene where a square transforms into a circle!

## 🔧 CLI Usage

General syntax:

```bash
fluxion [flags] file.py SceneName
```

### Common Flags

- `-p` - Preview the animation after rendering
- `-ql` - Quick render at low quality (faster)
- `-qh` - High quality render
- `-s` - Skip to the end and show the final frame
- `-n <number>` - Skip ahead to the n'th animation
- `-f` - Show the file in the file browser

For a complete list of options:

```bash
fluxion --help
```

## 📓 Jupyter Support

Fluxion ships with a `%%fluxion` IPython magic for use in JupyterLab and Jupyter notebooks:

```python
%%fluxion -v WARNING -ql

from fluxion import *

class MyScene(Scene):
    def construct(self):
        circle = Circle()
        self.play(Create(circle))
```

## 🔠 API Overview

### Shapes

```python
Circle(), Square(), Triangle(), Rectangle(), Line(), Arrow(), Dot()
```

### Colors

```python
RED, BLUE, GREEN, YELLOW, PURPLE, ORANGE, PINK, WHITE, BLACK
# Or use hex colors
obj.set_color("#FF5733")
```

### Animations

```python
Create(), FadeIn(), FadeOut(), Transform(), Write(), DrawBorderThenFill()
```

### Camera Controls

```python
self.camera.frame.move_to(point)
self.camera.frame.scale(2)
```

## 🛣️ Roadmap

### ✔ v0.1.0 (Current)
- Core animation engine
- CLI renderer
- Jupyter integration
- Basic shapes and animations
- Cairo and OpenGL backends

### 🚧 v0.2.0 (Planned)
- Enhanced 3D support
- Real-time preview improvements
- Performance optimizations
- Extended plugin API

### 🧪 Future
- Web-based editor
- Cloud rendering
- Collaborative features
- AI-assisted animation generation

## ❓ FAQ

**Q: What Python versions are supported?**  
A: Fluxion requires Python 3.11 or higher.

**Q: Can I use Fluxion for commercial projects?**  
A: Yes! Fluxion is MIT licensed and free for commercial use.

**Q: How do I contribute?**  
A: Check out our [Contributing Guide](CONTRIBUTING.md) to get started!

## 🤝 Contributing

Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started.

## 📜 License

Fluxion is licensed under the MIT License. See [LICENSE](LICENSE) for more information.

---

<p align="center">
    Made with ❤️ by The Fluxion Community
</p>
