Skip to content

Commit 1420bd2

Browse files
offerrallofferrall
committed
0.0.2
1 parent d4bc369 commit 1420bd2

73 files changed

Lines changed: 2070 additions & 331 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ __pycache__/
33
build/
44
dist/
55
wheelhouse/
6+
site/
67
*.obj
78
*.lib
89
*.exp

‎README.md‎

Lines changed: 66 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,74 @@
1-
# PyImageCUDA
1+
# PyImageCUDA 0.0.2
22

3+
[![PyPI version](https://img.shields.io/pypi/v/pyimagecuda.svg)](https://pypi.org/project/pyimagecuda/)
34
[![Build Status](https://github.com/offerrall/pyimagecuda/actions/workflows/build.yml/badge.svg)](https://github.com/offerrall/pyimagecuda/actions)
5+
![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)
46

5-
> ⚠️ **STATUS: PRE-ALPHA / INFRASTRUCTURE TESTING**
6-
>
7-
> This repository is currently validating the build and distribution system.
8-
> **It is NOT ready for production use yet.**
7+
**GPU-accelerated image compositing for Python.**
98

10-
### Goal
11-
GPU-accelerated (CUDA) image processing library for Python.
12-
Designed to be installed via a simple `pip install` without requiring the user to have the CUDA Toolkit or Visual Studio installed.
9+
> PyImageCUDA focuses on creative image generation rather than computer vision. Expect GPU-accelerated effects for design workflows—blending modes, shadows, gradients, filters... not edge detection or object recognition.
1310
14-
### Verification (Testers Only)
11+
## Quick Example
12+
```python
13+
from pyimagecuda import Image, Fill, Effect, Blend, save
1514

16-
If you have installed a test build, you can verify that hardware acceleration is working correctly by running:
15+
with Image(1024, 1024) as bg:
16+
with Image(512, 512) as card:
17+
Fill.color(bg, (1, 1, 1, 1))
18+
Fill.gradient(card, (1, 0, 0, 1), (0, 0, 1, 1), 'radial')
19+
Effect.rounded_corners(card, 50)
1720

21+
with Effect.drop_shadow(card, blur=50, color=(0, 0, 0, 1)) as shadowed:
22+
Blend.normal(bg, shadowed, anchor='center')
23+
24+
save(bg, 'output.png')
25+
```
26+
<img src="docs/images/quick.png" alt="Demo" width="400">
27+
28+
## Key Features
29+
30+
* ✅ **Zero Dependencies:** No CUDA Toolkit, Visual Studio, or complex compilers needed. Is Plug & Play.
31+
* ✅ **Ultra-lightweight:** Core library weighs **<0.5 MB**.
32+
* ✅ **Studio Quality:** 32-bit floating-point precision (float32) to prevent color banding.
33+
* ✅ **Advanced Memory Control:** Reuse GPU buffers across operations and resize without reallocation—critical for video processing and batch workflows.
34+
* ✅ **API Simplicity:** Intuitive, Pythonic API designed for ease of use.
35+
36+
## Use Cases
37+
38+
* **Generative Art:** Create thousands of unique variations in seconds.
39+
* **Motion Graphics:** Process video frames or generate effects in real-time.
40+
* **Image Compositing:** Complex multi-layer designs with GPU-accelerated effects.
41+
* **Game Development:** Procedural UI assets, icons, and sprite generation.
42+
* **Marketing Automation:** Mass-produce personalized graphics from templates.
43+
* **Data Augmentation:** High-speed batch transformations for ML datasets.
44+
45+
## Installation
1846
```bash
19-
python -c "import pyimagecuda; pyimagecuda.check_system()"
20-
```
47+
pip install pyimagecuda
48+
```
49+
50+
**Note:** Automatically installs `pyvips` binary dependencies for robust image format support (JPG, PNG, WEBP, HEIC).
51+
52+
## Documentation
53+
54+
**⚠️ Alpha Release:** This is version 0.0.2 with core functionality. Many more features are planned and under development.
55+
56+
### Core Concepts
57+
* [Getting Started Guide](https://offerrall.github.io/pyimagecuda/)
58+
* [Image & Memory](https://offerrall.github.io/pyimagecuda/image/) (Buffer management)
59+
* [IO](https://offerrall.github.io/pyimagecuda/io/) (Loading and Saving)
60+
61+
### Operations (v0.0.2)
62+
* [Blend](https://offerrall.github.io/pyimagecuda/blend/) (Normal, Multiply, Screen, Add)
63+
* [Resize](https://offerrall.github.io/pyimagecuda/resize/) (Nearest, Bilinear, Bicubic, Lanczos)
64+
* [Filter](https://offerrall.github.io/pyimagecuda/filter/) (Gaussian Blur, Sharpen)
65+
* [Effect](https://offerrall.github.io/pyimagecuda/effect/) (Drop Shadow, Rounded Corners)
66+
* [Fill](https://offerrall.github.io/pyimagecuda/fill/) (Solid colors, Gradients)
67+
68+
## Requirements
69+
70+
* **OS:** Windows 10 or 11 (64-bit). *Linux support coming soon.*
71+
* **GPU:** NVIDIA GPU (Maxwell architecture / GTX 900 series or newer).
72+
* **Drivers:** Standard NVIDIA Drivers installed.
73+
74+
**NOT REQUIRED:** Visual Studio, CUDA Toolkit, or Conda.

‎docs/blend.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Blend
2+
3+
The `Blend` module provides GPU-accelerated layer compositing with multiple blend modes.
4+
5+
All blend operations modify the `base` image in-place by compositing the `overlay` on top of it.
6+
7+
---
8+
9+
## Positioning
10+
11+
### Anchors
12+
13+
Position overlays relative to common anchor points. By default, `anchor='top-left'`, which makes `offset_x` and `offset_y` behave as absolute pixel coordinates—just like standard graphics APIs.
14+
15+
**Example:**
16+
17+
<div style="display: flex; gap: 20px; align-items: start;">
18+
<div style="flex: 1;">
19+
20+
```python
21+
from pyimagecuda import Image, Fill, Blend, save
22+
23+
base = Image(800, 600)
24+
overlay = Image(200, 200)
25+
26+
Fill.color(base, (0.2, 0.2, 0.3, 1.0))
27+
Fill.color(overlay, (1.0, 0.0, 0.0, 1.0))
28+
29+
Blend.normal(base, overlay, anchor='center')
30+
save(base, 'output.png')
31+
```
32+
33+
</div>
34+
<div style="flex: 1;">
35+
<img src="https://offerrall.github.io/pyimagecuda/images/blend_anchor.png" alt="Anchor positioning" style="width: 100%;">
36+
</div>
37+
</div>
38+
39+
**Available anchors:** `'top-left'`, `'top-center'`, `'top-right'`, `'center-left'`, `'center'`, `'center-right'`, `'bottom-left'`, `'bottom-center'`, `'bottom-right'`
40+
41+
---
42+
43+
### Offsets
44+
45+
Add pixel offsets from the anchor point for fine-tuning.
46+
47+
**Example:**
48+
49+
<div style="display: flex; gap: 20px; align-items: start;">
50+
<div style="flex: 1;">
51+
52+
```python
53+
from pyimagecuda import Image, Fill, Blend, save
54+
55+
base = Image(800, 600)
56+
overlay = Image(200, 200)
57+
58+
Fill.color(base, (0.2, 0.2, 0.3, 1.0))
59+
Fill.color(overlay, (1.0, 0.0, 0.0, 1.0))
60+
61+
Blend.normal(base, overlay, anchor='center',
62+
offset_x=50, offset_y=-30)
63+
save(base, 'output.png')
64+
```
65+
66+
</div>
67+
<div style="flex: 1;">
68+
<img src="https://offerrall.github.io/pyimagecuda/images/blend_offset.png" alt="Offset positioning" style="width: 100%;">
69+
</div>
70+
</div>
71+
72+
---
73+
74+
## Blend Modes
75+
76+
### Normal
77+
78+
Standard alpha blending (Porter-Duff over operation).
79+
80+
**Example:**
81+
82+
<div style="display: flex; gap: 20px; align-items: start;">
83+
<div style="flex: 1;">
84+
85+
```python
86+
from pyimagecuda import Image, Fill, Blend, save
87+
88+
base = Image(800, 600)
89+
overlay = Image(400, 300)
90+
91+
c1 = (0.2, 0.2, 0.3, 1.0)
92+
c2 = (0.4, 0.3, 0.5, 1.0)
93+
c3 = (1.0, 0.5, 0.0, 0.8)
94+
c4 = (1.0, 0.0, 0.5, 0.8)
95+
96+
Fill.gradient(base, c1, c2, 'radial')
97+
Fill.gradient(overlay, c3, c4, 'horizontal')
98+
99+
Blend.normal(base, overlay, anchor='center')
100+
save(base, 'output.png')
101+
```
102+
103+
</div>
104+
<div style="flex: 1;">
105+
<img src="https://offerrall.github.io/pyimagecuda/images/blend_normal.png" alt="Normal blend" style="width: 100%;">
106+
</div>
107+
</div>
108+
109+
**Use for:** Standard layer compositing, logos, overlays.
110+
111+
---
112+
113+
### Multiply
114+
115+
Darkens the image by multiplying color values.
116+
117+
**Example:**
118+
119+
<div style="display: flex; gap: 20px; align-items: start;">
120+
<div style="flex: 1;">
121+
122+
```python
123+
from pyimagecuda import Image, Fill, Blend, save
124+
125+
base = Image(800, 600)
126+
overlay = Image(400, 300)
127+
128+
c1 = (0.2, 0.2, 0.3, 1.0)
129+
c2 = (0.4, 0.3, 0.5, 1.0)
130+
c3 = (1.0, 0.5, 0.0, 0.8)
131+
c4 = (1.0, 0.0, 0.5, 0.8)
132+
133+
Fill.gradient(base, c1, c2, 'radial')
134+
Fill.gradient(overlay, c3, c4, 'horizontal')
135+
136+
Blend.multiply(base, overlay, anchor='center')
137+
save(base, 'output.png')
138+
```
139+
140+
</div>
141+
<div style="flex: 1;">
142+
<img src="https://offerrall.github.io/pyimagecuda/images/blend_multiply.png" alt="Multiply blend" style="width: 100%;">
143+
</div>
144+
</div>
145+
146+
**Use for:** Shadows, darkening effects, texture overlays.
147+
148+
---
149+
150+
### Screen
151+
152+
Lightens the image (inverse of multiply).
153+
154+
**Example:**
155+
156+
<div style="display: flex; gap: 20px; align-items: start;">
157+
<div style="flex: 1;">
158+
159+
```python
160+
from pyimagecuda import Image, Fill, Blend, save
161+
162+
base = Image(800, 600)
163+
overlay = Image(400, 300)
164+
165+
c1 = (0.2, 0.2, 0.3, 1.0)
166+
c2 = (0.4, 0.3, 0.5, 1.0)
167+
c3 = (1.0, 0.5, 0.0, 0.8)
168+
c4 = (1.0, 0.0, 0.5, 0.8)
169+
170+
Fill.gradient(base, c1, c2, 'radial')
171+
Fill.gradient(overlay, c3, c4, 'horizontal')
172+
173+
Blend.screen(base, overlay, anchor='center')
174+
save(base, 'output.png')
175+
```
176+
177+
</div>
178+
<div style="flex: 1;">
179+
<img src="https://offerrall.github.io/pyimagecuda/images/blend_screen.png" alt="Screen blend" style="width: 100%;">
180+
</div>
181+
</div>
182+
183+
**Use for:** Highlights, light effects, glows.
184+
185+
---
186+
187+
### Add
188+
189+
Additive blending (colors add up, clamped to 1.0).
190+
191+
**Example:**
192+
193+
<div style="display: flex; gap: 20px; align-items: start;">
194+
<div style="flex: 1;">
195+
196+
```python
197+
from pyimagecuda import Image, Fill, Blend, save
198+
199+
base = Image(800, 600)
200+
overlay = Image(400, 300)
201+
202+
c1 = (0.2, 0.2, 0.3, 1.0)
203+
c2 = (0.4, 0.3, 0.5, 1.0)
204+
c3 = (1.0, 0.5, 0.0, 0.8)
205+
c4 = (1.0, 0.0, 0.5, 0.8)
206+
207+
Fill.gradient(base, c1, c2, 'radial')
208+
Fill.gradient(overlay, c3, c4, 'horizontal')
209+
210+
Blend.add(base, overlay, anchor='center')
211+
save(base, 'output.png')
212+
```
213+
214+
</div>
215+
<div style="flex: 1;">
216+
<img src="https://offerrall.github.io/pyimagecuda/images/blend_add.png" alt="Add blend" style="width: 100%;">
217+
</div>
218+
</div>
219+
220+
**Use for:** Light effects, lens flares, glowing elements.
221+
222+
---
223+
224+
## Parameters
225+
226+
All blend modes share the same parameters:
227+
228+
- `base` (Image): Base layer (modified in-place)
229+
- `overlay` (Image): Layer to composite on top
230+
- `anchor` (str): Position anchor point (default: `'top-left'`)
231+
- `offset_x` (int): Horizontal offset from anchor in pixels (default: 0)
232+
- `offset_y` (int): Vertical offset from anchor in pixels (default: 0)
233+
- `opacity` (float): Blend opacity from 0.0 (transparent) to 1.0 (opaque) (default: 1.0)

0 commit comments

Comments
 (0)