Skip to content

Commit 5f87cc9

Browse files
andrestubbeandrestubbe
committed
FastImage v0.1.0: Final BluePrint Documentation Alignment (README, CHANGELOG, Installation Guide)
1 parent 5d09404 commit 5f87cc9

2 files changed

Lines changed: 96 additions & 78 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,13 @@
22

33
## [0.1.0] - 2026-05-08
44
### Added
5-
- Native SIMD-accelerated image processing core.
6-
- SSE4.1/AVX2 optimizations for Grayscale, Brightness, and Contrast.
7-
- O(N) Sliding Window Box Blur and Gaussian Blur approximation.
8-
- Zero-copy native handle integration for FastJava ecosystem.
9-
- Performance benchmark suite.
5+
- Native SIMD-accelerated image processing core (SSE4.1/AVX2).
6+
- **Runtime SIMD Dispatching**: Automatic switching between AVX2 and SSE4.1 based on CPU features.
7+
- **Robust Error Handling**: Introduced `FastImageException` and comprehensive JNI handle validation.
8+
- **Unit Testing Suite**: Full JUnit 5 coverage for lifecycle, validation, and pixel-level correctness.
9+
- **High-Performance Blurs**: O(N) Sliding Window Box Blur, Stack Blur (iOS-style), and Gaussian approximation.
10+
- **Advanced Filtering**: Saturated math for Brightness and Contrast adjustments.
11+
- **Optimized Memory**: 32-byte alignment for maximum AVX2 throughput.
12+
- **BluePrint Documentation**: Professional API Design and updated README.
1013
- High-quality Bilinear Resizing.
14+
- Zero-copy native handle integration for the FastJava ecosystem.

‎README.md‎

Lines changed: 87 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,85 @@
11
# FastImage — SIMD‑Accelerated, Off‑Heap Image Processing for Java
22

3-
[![FastJava](https://img.shields.io/badge/Ecosystem-FastJava-0078D4.svg?style=for-the-badge&logo=java)](https://github.com/andrestubbe)
4-
[![Release](https://img.shields.io/badge/Release-v0.1.0--STABLE-green.svg?style=for-the-badge)](https://github.com/andrestubbe/FastImage/releases)
5-
[![Performance](https://img.shields.io/badge/Performance-10--50x_Faster-blue.svg?style=for-the-badge)](https://github.com/andrestubbe/FastImage#benchmarks)
3+
**Ultra-fast native image processing using AVX2/SSE4.1 kernels and zero-GC memory management.**
64

7-
**FastImage** ist eine ultra‑schnelle, native‑beschleunigte Image‑Processing‑Engine für Java, gebaut für das FastJava‑Ecosystem. Es kombiniert AVX/SSE SIMD, off‑heap Storage, zero‑copy Pipelines und eine fluent API, um typische BufferedImage‑Operationen **10–50× schneller** auszuführen — ohne GC‑Pressure, ohne Pixel‑Loops, ohne JVM‑Overhead.
5+
[![Build](https://img.shields.io/github/actions/workflow/status/andrestubbe/FastImage/maven.yml?branch=main)](https://github.com/andrestubbe/FastImage/actions)
6+
[![Java](https://img.shields.io/badge/Java-17+-blue.svg)](https://www.java.com)
7+
[![Platform](https://img.shields.io/badge/Platform-Windows%20x64-lightgrey.svg)]()
8+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9+
[![JitPack](https://jitpack.io/v/andrestubbe/FastImage.svg)](https://jitpack.io/#andrestubbe/FastImage)
810

9-
### Highlights
10-
- ⚡ **SIMD Accelerated**: AVX2 & SSE4.1 optimierte Kernel für maximale CPU-Ausnutzung.
11-
- 📦 **Off-Heap Memory**: Pixel werden außerhalb des Java-Heaps gespeichert (kein GC-Overhead).
12-
- 🧬 **Fluent API**: Intuitive Verkettung von Operationen (`resize().blur().grayscale()`).
13-
- 🛡️ **Fail-Safe JNI**: Robuste Fehlerbehandlung und Bounds-Checks.
11+
FastImage ist eine ultra‑schnelle, native‑beschleunigte Image‑Processing‑Engine für Java, gebaut für das FastJava‑Ecosystem. Es kombiniert AVX/SSE SIMD, off‑heap Storage, zero‑copy Pipelines und eine fluent API, um typische BufferedImage‑Operationen **10–50× schneller** auszuführen — ohne GC‑Pressure, ohne Pixel‑Loops, ohne JVM‑Overhead.
1412

15-
---
13+
```java
14+
// Quick Start — SIMD-Accelerated Filtering
15+
import fastimage.FastImage;
1616

17-
### Tags
18-
`java` `image-processing` `simd` `avx` `sse` `native` `jni` `off-heap` `high-performance` `fastjava` `graphics` `zero-copy`
17+
public class Demo {
18+
public static void main(String[] args) {
19+
FastImage img = FastImage.load("input.jpg");
20+
21+
img.adjustContrast(1.2f)
22+
.blurStack(15.0f)
23+
.grayscale();
24+
25+
img.save("output.png");
26+
img.dispose(); // Free native memory
27+
}
28+
}
29+
```
1930

2031
---
2132

22-
## 📖 Table of Contents
33+
## Table of Contents
2334
- [Key Features](#key-features)
2435
- [Performance](#performance)
25-
- [Quick Start](#quick-start)
2636
- [Installation](#installation)
27-
- [Demos](#demos)
37+
- [Try the Demo](#try-the-demo)
2838
- [API Reference](#api-reference)
2939
- [Platform Support](#platform-support)
40+
- [Building from Source](#building-from-source)
41+
- [License](#license)
3042
- [Related Projects](#related-projects)
3143

3244
---
3345

34-
## 🚀 Key Features
46+
## Key Features
3547

36-
- **⚡ SIMD Acceleration** — Hand-optimized C++ kernels using **AVX2** and **SSE4.1** vector instructions.
48+
- **🚀 SIMD Acceleration** — Hand-optimized C++ kernels using **AVX2** and **SSE4.1** vector instructions.
3749
- **🧠 Zero-GC Overhead** — Pixels are stored in **off-heap** memory, preventing GC pauses during heavy manipulation.
38-
- **🌀 Advanced Blur Suite** — Real-time Gaussian, Stack (iOS-style), and Kawase blurs with $O(N)$ complexity.
39-
- **📦 Ecosystem Ready** — Native handle hand-off from **FastThumb** and **FastGraphics**.
50+
- **🌀 Advanced Blur Suite** — Real-time Gaussian, Stack (iOS-style), and Kawase blurs.
51+
- **🛡️ Fail-Safe JNI** — Robust error handling with `FastImageException` and native handle validation.
4052
- **🔄 Fast Conversion** — Optimized bit-copying between `BufferedImage` and native memory.
4153

4254
---
4355

44-
## 📊 Performance
56+
## Performance
4557

46-
*Tested on: 1920x1080 (1080p) ARGB Image*
58+
FastImage utilizes the full power of your CPU, outperforming standard Java2D loops by orders of magnitude:
4759

4860
| Operation | Java2D (BufferedImage) | FastImage (SIMD) | Speedup |
4961
| :--- | :--- | :--- | :--- |
5062
| **Brightness** | ~48.6 ms/op | **~1.5 ms/op** | **32x** |
5163
| **Gaussian Blur (r10)** | ~1100.0 ms/op | **~170.4 ms/op** | **6.5x** |
5264
| **Grayscale** | ~20.0 ms/op | **~1.3 ms/op** | **15x** |
5365

54-
---
55-
56-
## 🛠 Quick Start
57-
58-
```java
59-
import fastimage.FastImage;
60-
import java.awt.image.BufferedImage;
61-
62-
public class Demo {
63-
public static void main(String[] args) {
64-
// Wrap an existing image (copies data to native memory)
65-
FastImage img = FastImage.fromBufferedImage(myPhoto);
66-
67-
// Apply high-performance filters
68-
img.adjustContrast(1.2f);
69-
img.blurGaussian(15.0f);
70-
img.grayscale();
71-
72-
// Export back to Java UI
73-
BufferedImage result = img.toBufferedImage();
74-
75-
// CRITICAL: Free native memory when done
76-
img.dispose();
77-
}
78-
}
79-
```
66+
*Tested on: 1920x1080 (1080p) ARGB Image on Intel i7-12700K.*
8067

8168
---
8269

83-
## 📦 Installation
70+
## Installation
8471

85-
FastImage requires **FastCore** for native library management.
72+
FastJava modules require **two** dependencies: the module itself, and `FastCore` (which handles the native library extraction).
8673

8774
### Maven (JitPack)
8875
```xml
76+
<repositories>
77+
<repository>
78+
<id>jitpack.io</id>
79+
<url>https://jitpack.io</url>
80+
</repository>
81+
</repositories>
82+
8983
<dependencies>
9084
<dependency>
9185
<groupId>com.github.andrestubbe</groupId>
@@ -100,55 +94,75 @@ FastImage requires **FastCore** for native library management.
10094
</dependencies>
10195
```
10296

103-
---
97+
### Gradle (JitPack)
98+
```groovy
99+
repositories {
100+
maven { url 'https://jitpack.io' }
101+
}
102+
103+
dependencies {
104+
implementation 'com.github.andrestubbe:fastimage:0.1.0'
105+
implementation 'com.github.andrestubbe:fastcore:0.1.0'
106+
}
107+
```
104108

105-
## 🖥 Try the Demos
109+
### Option 3: Direct Download
110+
Download the latest JARs directly from the releases:
111+
1. 📦 **[fastimage-v0.1.0.jar](https://github.com/andrestubbe/FastImage/releases)**
112+
2. ⚙️ **[fastcore-v0.1.0.jar](https://github.com/andrestubbe/FastCore/releases)**
106113

107-
We provide several standalone demos to showcase the performance:
114+
---
108115

109-
1. **[Visual Editor](./examples/VisualEditor)** — Interactive split-screen editor (Real-time).
110-
2. **[Blur Gallery](./examples/BlurGallery)** — Comparison of different blur algorithms.
111-
3. **[Benchmark](./examples/Benchmark)** — Run the performance tests on your own machine.
116+
## Try the Demo
112117

113-
To run the main showcase:
114-
```powershell
115-
.\run-demo.bat
116-
```
118+
1. Clone this repository: `git clone https://github.com/andrestubbe/FastImage.git`
119+
2. Run the automated showcase: `.\run-demo.bat`
120+
121+
*Includes the interactive Visual Editor and the Blur Gallery.*
117122

118123
---
119124

120-
## 📖 API Reference
125+
## API Reference
121126

122127
| Method | Description |
123128
| :--- | :--- |
124-
| `void grayscale()` | Converts image to luminance-weighted grayscale via SSE4.1. |
125-
| `void adjustBrightness(float f)` | Scales RGB values. Supports factors > 1.0. |
126-
| `void adjustContrast(float f)` | Adjusts image contrast around the 128-midpoint. |
127-
| `void blurGaussian(float r)` | High-quality Gaussian blur approximation ($O(N)$). |
128-
| `void blurStack(float r)` | iOS-style soft blur, extremely fast. |
129-
| `void resize(int w, int h)` | Bilinear/Bicubic resizing using native kernels. |
129+
| `void grayscale()` | Converts image to luminance-weighted grayscale via SIMD. |
130+
| `void adjustBrightness(f)`| Scales RGB values with saturation clamping. |
131+
| `void adjustContrast(f)` | Adjusts image contrast around the midpoint. |
132+
| `void blurGaussian(r)` | High-quality Gaussian blur approximation ($O(N)$). |
133+
| `void blurStack(r)` | Extremely fast separable weighted blur. |
134+
| `void resize(w, h)` | Bilinear resizing using native kernels. |
130135

131136
---
132137

133-
## 💻 Platform Support
138+
## Platform Support
134139

135140
| Architecture | Instruction Set | OS |
136141
| :--- | :--- | :--- |
137-
| x64 | **AVX2** (Recommended) | Windows 10/11 |
142+
| x64 | **AVX2** (Runtime Dispatch) | Windows 10/11 |
138143
| x64 | **SSE4.1** (Fallback) | Windows 10/11 |
139144

140145
---
141146

142-
## 🗺 Related Projects
147+
## Building from Source
143148

144-
- [FastThumb](https://github.com/andrestubbe/FastThumb) — Native Shell Thumbnails.
145-
- [FastGraphics](https://github.com/andrestubbe/FastGraphics) — DirectX 12 Rendering Engine.
146-
- [FastCore](https://github.com/andrestubbe/FastCore) — Native Library Infrastructure.
149+
For detailed instructions on compiling the C++ JNI code and building the Maven FatJAR, see [COMPILE.md](COMPILE.md).
147150

148151
---
149152

153+
## License
154+
MIT License — See [LICENSE](LICENSE) file for details.
155+
156+
---
157+
158+
## Related Projects
159+
- [FastCore](https://github.com/andrestubbe/FastCore) — Native Library Loader
160+
- [FastTheme](https://github.com/andrestubbe/FastTheme) — Native Window Styling
161+
- [FastGraphics](https://github.com/andrestubbe/FastGraphics) — Hardware-accelerated 2D Rendering
162+
163+
---
150164
**Made with ⚡ by Andre Stubbe**
151165

152166
<!--
153-
SEO Keywords: java, jni, simd, avx2, sse4, image processing, blur, gaussian, fastjava
167+
SEO Keywords: java, jni, simd, avx2, sse4, image processing, blur, gaussian, fastjava, off-heap
154168
-->

0 commit comments

Comments
 (0)