pyrenderer 0.1.0
A beautiful and simple rendering library for Python
License: MIT
Requires Python: >=3.8
Keywords: rendering, graphics, 2d, visualization, drawing, canvas

# PyRender 🎨

[![PyPI version](https://badge.fury.io/py/pyrender-lib.svg)](https://badge.fury.io/py/pyrender-lib)
[![Python Versions](https://img.shields.io/pypi/pyversions/pyrender-lib.svg)](https://pypi.org/project/pyrender-lib/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A beautiful and simple 2D rendering library for Python. PyRender provides an elegant API for creating graphics, visualizations, and animations with ease.

## ✨ Features

- **Simple & Intuitive API** - Clean, fluent interface for creating graphics
- **Rich Primitives** - Rectangles, circles, lines, polygons, text, gradients, and images
- **Flexible Transformations** - Position, rotation, and scale with matrix support
- **Camera System** - Pan, zoom, and navigate your scenes
- **Visual Effects** - Shadows, blur, glow, and outlines
- **Scene Management** - Organize and layer your graphics with z-indexing
- **Anti-aliasing** - Crisp, high-quality output with supersampling
- **Color Tools** - RGB, HSV, hex support with beautiful palettes

## 📦 Installation

```bash
pip install pyrender-lib
```

Or install from source:

```bash
git clone https://github.com/yourusername/pyrender.git
cd pyrender
pip install -e .
```

## 🚀 Quick Start

```python
from pyrender import Renderer, Scene, Rectangle, Circle, ColorPalette

# Create renderer and scene
renderer = Renderer(800, 600)
scene = Scene(background_color=ColorPalette.WHITE)

# Add some shapes
scene.add(Rectangle(100, 100, 200, 150, color=ColorPalette.BLUE))
scene.add(Circle(400, 300, 80, color=ColorPalette.RED))

# Render and save
renderer.save(scene, "output.png")
```

## 📚 Examples

### Creating Shapes

```python
from pyrender import *

renderer = Renderer(800, 600)
scene = Scene()

# Rectangle with rounded corners
rect = Rectangle(50, 50, 200, 100, color=ColorPalette.INDIGO)
rect.set_corner_radius(10)
scene.add(rect)

# Circle
circle = Circle(400, 300, 60, color=ColorPalette.PINK, fill=True)
scene.add(circle)

# Line
line = Line(100, 100, 700, 500, color=ColorPalette.GRAY_DARK, width=3)
scene.add(line)

# Polygon (triangle)
triangle = Polygon(
    [(300, 100), (250, 200), (350, 200)],
    color=ColorPalette.TEAL,
    fill=True
)
scene.add(triangle)

# Text
text = Text(400, 50, "Hello, PyRender!", color=ColorPalette.BLACK, font_size=32)
text.set_bold(True)
scene.add(text)

renderer.save(scene, "shapes.png")
```

### Working with Colors

```python
from pyrender import Color, ColorPalette

# Create colors in different ways
red = ColorPalette.RED
blue = Color.from_rgb(0, 100, 255)
green = Color.from_hex("#00FF00")
purple = Color.from_hsv(0.8, 0.6, 0.9)

# Blend colors
pink = red.blend(ColorPalette.WHITE, 0.5)

# Create gradient
gradient = ColorPalette.gradient(ColorPalette.BLUE, ColorPalette.PURPLE, steps=10)
```

### Transformations

```python
from pyrender import *

scene = Scene()

# Create and transform a rectangle
rect = Rectangle(0, 0, 100, 100, color=ColorPalette.ORANGE)
rect.transform.translate(200, 150)
rect.transform.rotate(0.785)  # 45 degrees in radians
rect.transform.scale(1.5, 1.5)

scene.add(rect)
```

### Camera Control

```python
renderer = Renderer(800, 600)
scene = Scene()

# Add some objects
for i in range(10):
    scene.add(Circle(i * 100, 300, 30, color=ColorPalette.BLUE))

# Move camera
renderer.camera.set_position(200, 0)
renderer.camera.set_zoom(1.5)

renderer.save(scene, "camera.png")
```

### Creating Gradients

```python
from pyrender import Gradient, Color

gradient = Gradient(
    0, 0, 800, 600,
    color_start=Color.from_hex("#FF6B6B"),
    color_end=Color.from_hex("#4ECDC4"),
    angle=0.785  # 45 degrees
)

scene = Scene()
scene.add(gradient)
```

### Layering with Z-Index

```python
scene = Scene()

# Background
bg = Rectangle(0, 0, 800, 600, color=ColorPalette.GRAY_LIGHT)
bg.z_index = 0
scene.add(bg)

# Middle layer
circle = Circle(400, 300, 100, color=ColorPalette.BLUE)
circle.z_index = 1
scene.add(circle)

# Foreground
text = Text(400, 300, "Front!", color=ColorPalette.WHITE, font_size=48)
text.z_index = 2
scene.add(text)
```

### Anti-aliasing

```python
renderer = Renderer(800, 600)

# Enable high-quality anti-aliasing
renderer.set_antialiasing(True, scale=4)  # 4x supersampling

scene = Scene()
# ... add your shapes ...

renderer.save(scene, "smooth.png")
```

## 🎨 Color Palettes

PyRender includes beautiful built-in colors:

```python
# Basic colors
ColorPalette.BLACK, WHITE, RED, GREEN, BLUE, YELLOW, CYAN, MAGENTA

# Grays
ColorPalette.GRAY_LIGHT, GRAY, GRAY_DARK

# Material Design colors
ColorPalette.INDIGO, PURPLE, PINK, ORANGE, TEAL

# Transparent
ColorPalette.TRANSPARENT
```

## 🛠️ Advanced Features

### Custom Transformations

```python
from pyrender import Transform, Matrix3x3

# Create custom transformation matrix
transform = Transform(x=100, y=100, rotation=0.5, scale_x=2.0, scale_y=1.5)
matrix = transform.to_matrix()

# Apply to points
new_x, new_y = matrix.transform_point(50, 50)
```

### Scene Queries

```python
scene = Scene()
# ... add primitives ...

# Find object at position
obj = scene.find_at_position(400, 300)

# Get scene bounds
x_min, y_min, x_max, y_max = scene.get_bounds()

# Get all visible objects sorted by z-index
objects = scene.get_primitives_sorted()
```

## 📖 API Reference

### Renderer

- `Renderer(width, height, mode=RenderMode.NORMAL)` - Create renderer
- `render(scene)` - Render scene to PIL Image
- `save(scene, filename)` - Render and save to file
- `set_antialiasing(enabled, scale=2)` - Configure anti-aliasing

### Scene

- `Scene(background_color=None)` - Create scene
- `add(primitive)` - Add primitive to scene
- `remove(primitive)` - Remove primitive
- `clear()` - Remove all primitives
- `find_at_position(x, y)` - Find primitive at position

### Primitives

- `Rectangle(x, y, width, height, color, fill, stroke_width)`
- `Circle(x, y, radius, color, fill, stroke_width)`
- `Line(x1, y1, x2, y2, color, width)`
- `Polygon(points, color, fill, stroke_width)`
- `Text(x, y, text, color, font_size, font_family)`
- `Gradient(x, y, width, height, color_start, color_end, angle)`
- `Image(x, y, image_path, width, height)`

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Pillow](https://python-pillow.org/) for image processing
- Inspired by modern graphics libraries and elegant API design

## 📞 Support

- **Documentation**: https://pyrender.readthedocs.io
- **Issues**: https://github.com/yourusername/pyrender/issues
- **Discussions**: https://github.com/yourusername/pyrender/discussions

---

Made with ❤️ by the PyRender Team