Metadata-Version: 2.4
Name: vello
Version: 0.1.4
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Rust
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Dist: numpy>=1.20
Requires-Dist: pillow>=9.0 ; extra == 'image'
Requires-Dist: pytest>=7.0 ; extra == 'test'
Requires-Dist: pillow>=9.0 ; extra == 'test'
Provides-Extra: image
Provides-Extra: test
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: High-performance GPU compute-centric 2D vector graphics engine for Python
Keywords: vello,graphics,2d,vector,gpu,compute-shader,wgpu,canvas,rendering
Author: Linebender & Vello Python Contributors
License: Apache-2.0 OR MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://docs.rs/vello/latest/vello/
Project-URL: Homepage, https://github.com/linebender/vello
Project-URL: Repository, https://github.com/linebender/vello

# Vello: GPU-Accelerated 2D Vector Graphics for Python

[![PyPI version](https://img.shields.io/pypi/v/vello.svg)](https://pypi.org/project/vello/)
[![License](https://img.shields.io/badge/license-Apache--2.0%20%7C%20MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)

**Vello** is a high-performance, GPU compute-centric 2D vector graphics engine for Python, powered by [Linebender's Vello](https://github.com/linebender/vello) and [`wgpu`](https://wgpu.rs/).

Unlike traditional CPU renderers (like Cairo or CPU Skia) or traditional GPU renderers that rely on tessellation, Vello utilizes modern GPU **Compute Shaders** to perform sorting, path clipping, and antialiased rasterization in parallel on your graphics card.

---

## ✨ Features

- ⚡ **Pure GPU Compute Acceleration:** Path flattening, clipping, and rasterization run completely on GPU Compute Shaders.
- 🎨 **Pythonic Canvas API:** An intuitive, HTML5 Canvas-like API designed specifically for Python developers.
- 🚀 **Zero-Copy NumPy Integration:** Stream rendered frames directly into NumPy `(H, W, 4)` uint8 arrays without copying memory.
- ⚡ **Vectorized Batch Drawing:** Render tens of thousands to millions of circles, rectangles, and lines in a single native GPU dispatch via NumPy arrays.
- 🌈 **Rich Shading & Gradients:** Full support for Solid Colors, Linear Gradients, Radial Gradients, Angular / Conical Sweep Gradients, and Image Brushes.
- 🎬 **Built-in Animation Export:** Generate smooth animated GIF sequences directly with `Canvas.save_animation()`.
- 📐 **Vector Shapes & SVG Paths:** Native support for Rectangles, Rounded Rectangles, Circles, Ellipses, Lines, Bézier Curves, and complete SVG path `d="..."` strings.
- 🔤 **GPU Vector Typography:** High-quality TrueType/OpenType font rendering with exact subpixel glyph positioning.
- 🎭 **Compositing & Blend Modes:** Full W3C blend modes (Multiply, Screen, Overlay, etc.) and compositing operations.
- 💡 **Gaussian Drop Shadows:** Accelerated blurred rounded rectangles for realistic UI drop shadows.
- 🧵 **Non-blocking & Thread-Safe:** Releases the Python GIL during GPU execution for multi-threaded performance.
- 🐧 **Linux & Cloud Ready:** Fully supports headless Linux servers, Docker containers, and Cloud GPU environments with NVIDIA GPUs (T4, V100, A100, H100, RTX) via Vulkan.

---

## 📦 Installation

```bash
pip install vello
```

---

## 🚀 Quickstart

### 1. Basic Drawing & PNG Export

```python
import vello

# Create canvas with background color
canvas = vello.Canvas(800, 600, background="white")

# Fill and stroke shapes with CSS colors, hex, or RGB tuples
canvas.fill_circle(cx=400, cy=300, radius=120, fill="royalblue")
canvas.stroke_circle(cx=400, cy=300, radius=120, stroke="crimson", stroke_width=6.0)

# Draw rounded rectangle with GPU drop shadow
canvas.draw_shadow(x=50, y=50, width=200, height=100, radius=16, blur=20, color="#00000044")
canvas.fill_rounded_rect(x=50, y=50, width=200, height=100, radius=16, fill="#2ecc71")

# Draw an SVG path
canvas.fill_path("M 500 100 L 550 200 L 450 200 Z", fill="gold")

# Save directly to image
canvas.save("output.png")
```

---

### 2. High-Performance NumPy & Video / Game Pipelines

```python
import vello

canvas = vello.Canvas(1920, 1080, background="black")

# Draw vector elements
canvas.fill_circle(960, 540, 200, fill="coral")

# Get a NumPy array with zero-copy buffer mapping (shape: 1080, 1920, 4)
frame = canvas.to_numpy()
print(frame.shape, frame.dtype)  # (1080, 1920, 4) uint8
```

---

### 3. Linear & Radial Gradients

```python
import vello

canvas = vello.Canvas(400, 400, background="black")

# Linear gradient
gradient = vello.LinearGradient(
    start=(0, 0),
    end=(400, 400),
    stops=[
        vello.ColorStop(0.0, vello.Color.from_name("red")),
        vello.ColorStop(0.5, vello.Color.from_name("yellow")),
        vello.ColorStop(1.0, vello.Color.from_name("blue")),
    ]
)
canvas.fill_rect(0, 0, 400, 400, fill=gradient)
canvas.save("gradient.png")
```

---

### 4. Transformations & Layer Blending

```python
import vello

canvas = vello.Canvas(500, 500, background="white")

# Context manager for local coordinate transforms
with canvas.transform(translate=(250, 250), rotate_deg=45):
    canvas.fill_rect(-50, -50, 100, 100, fill="teal")

# Blending and opacity layers
with canvas.layer(alpha=0.8, blend_mode="multiply"):
    canvas.fill_circle(200, 200, 80, fill="cyan")
    canvas.fill_circle(260, 200, 80, fill="magenta")

canvas.save("layers.png")
```

---

### 5. Vector Typography

```python
import vello

canvas = vello.Canvas(600, 200, background="white")

# Load any TrueType or OpenType font
font = vello.Font.from_file("C:/Windows/Fonts/arial.ttf")

# Measure text bounds
width, height = font.measure_text("Vello on GPU", size=36.0)

# Draw vector text
canvas.draw_text("Vello on GPU", x=50, y=100, font=font, size=36.0, color="royalblue")
canvas.save("text.png")
```

---

### 6. Vectorized Batch Drawing (NumPy)

Render tens of thousands of shapes simultaneously without Python loop overhead:

```python
import vello
import numpy as np

canvas = vello.Canvas(1000, 1000, background="black")

# 50,000 random circles [x, y, radius]
n = 50_000
data = np.zeros((n, 3), dtype=np.float32)
data[:, 0] = np.random.uniform(0, 1000, n)
data[:, 1] = np.random.uniform(0, 1000, n)
data[:, 2] = np.random.uniform(1, 5, n)

# Single native GPU call!
canvas.fill_circles_batch(data, fill="#00ffcc88")
canvas.save("batch_circles.png")
```

---

### 7. Animation & GIF Export

```python
import vello
import numpy as np

frames = []
for i in range(30):
    c = vello.Canvas(300, 300, background="black")
    angle = (i / 30.0) * 360.0
    with c.transform(translate=(150, 150), rotate_deg=angle):
        c.fill_rect(-40, -40, 80, 80, fill="cyan")
    frames.append(c)

# Save smooth animated GIF
vello.Canvas.save_animation(frames, "spin.gif", fps=30)
```

---

### 8. Headless Linux & Cloud GPU Setup (`enable_vulkan_gpu`)

In cloud container environments or headless Linux servers, NVIDIA drivers may not have Vulkan configured out of the box (defaulting to CPU software rendering).

Vello includes an automatic, one-line setup utility that detects your NVIDIA GPU and configures Vulkan acceleration automatically:

```python
import vello

# Run once in your cloud notebook or script to enable 100% GPU acceleration:
vello.enable_vulkan_gpu()

# Verify active GPU hardware & physical limits:
gpu = vello.get_gpu_info()
print("Active GPU:", gpu["name"])           # e.g., 'Tesla T4' or 'RTX 4090'
print("Backend:", gpu["backend"])         # 'Vulkan'
print("Device Type:", gpu["device_type"]) # 'DiscreteGpu'
print("Max Buffer Binding:", gpu["max_storage_buffer_binding_size_mb"], "MB")
```

---

### 9. Millions of Vectors & GPU Buffer Scaling (`gpu_buffer`)

Vello automatically discovers and prioritizes your **Discrete GPU** (e.g. NVIDIA Tesla T4, RTX 3090/4090, AMD Radeon) over any integrated or software fallback adapters, maximizing the available hardware storage limits.

Furthermore, Vello features **hardware-safe buffer clamping**: it dynamically verifies your GPU's physical `max_storage_buffer_binding_size` so allocations never exceed your card's hardware capabilities.

By default, Vello allocates an ultra-safe **128 MB** GPU bump allocator profile, ensuring smooth operation on low-power devices and integrated graphics.

When working with **massive datasets** (e.g. rendering 1,000,000+ vector shapes in 4K) on high-memory GPUs (such as an NVIDIA Tesla T4 with 16GB VRAM, RTX 3090/4090, or A100/H100), you can unlock large buffer capacities:

#### Per-Canvas Configuration:
```python
import vello

# Allocate a high-capacity GPU bump buffer profile:
canvas = vello.Canvas(3840, 2160, background="#050510", gpu_buffer="2GB")

# Available profiles: "128MB" (default), "256MB", "512MB", "1GB", "2GB", "4GB"
```

#### Global Configuration (e.g. at the top of a Notebook):
```python
import vello

# Check active buffer profile
print(vello.get_gpu_buffer())  # '128MB'

# Set high-capacity profile for all canvases
vello.set_gpu_buffer("2GB")
```

#### 1,000,000 Vector Circles in 4K:
```python
import vello
import numpy as np

WIDTH, HEIGHT = 3840, 2160
N = 1_000_000

# 1. Initialize canvas with 4GB buffer
canvas = vello.Canvas(WIDTH, HEIGHT, background="#050510", gpu_buffer="4GB")

# 2. Generate 1,000,000 vector circles
data = np.zeros((N, 3), dtype=np.float32, order='C')
data[:, 0] = np.random.uniform(50, WIDTH - 50, N)
data[:, 1] = np.random.uniform(50, HEIGHT - 50, N)
data[:, 2] = np.random.uniform(2.0, 5.0, N)

# 3. Render all 1,000,000 shapes directly on GPU
canvas.fill_circles_batch(data, fill="#00ffcc")
canvas.save("galaxy_1m_4k.png")
```

---

## 📊 Performance

Vello parallelizes vector rendering on GPU compute shaders:
- **Instant scene builds:** Adding thousands of vector commands takes just a few milliseconds.
- **Fast GPU rendering:** 1080p full frame renders take **~5-10 ms** on standard GPUs (~120-200 FPS).
- **GIL-free execution:** Multi-threaded Python applications run concurrently without blocking.

---

## 📜 License

Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.

