๐โจ Transform Images into Mesmerizing Kaleidoscope Art โจ๐
A blazingly fast, cross-platform library to create stunning kaleidoscope effects on images
Built with โค๏ธ using C, C++, Python, and CUDA
---
### ๐ **Project Status**
### ๐ ๏ธ **Technology Stack**
---
## ๐ฏ **What is LibKaleidoscope?**
LibKaleidoscope is a **high-performance**, **cross-platform** library that transforms ordinary images into breathtaking kaleidoscope patterns. Written in C with FFI support, it offers seamless integration with multiple programming languages and includes GPU acceleration for ultimate performance.
> ๐ **Learn More**: Check out the [mathematical explanation](https://egecetin.github.io/Projects/kaleidoscope) of the kaleidoscope effect!
## ๐ **Key Features**
| ๐ **Performance** | ๐ **Multi-Language** | ๐จ **Easy to Use** | โก **GPU Accelerated** |
|:---:|:---:|:---:|:---:|
| Ultra-fast processing with optimized algorithms | C, C++, Python, CUDA support | Simple 3-function API | CUDA backend for maximum speed |
---
## ๐ญ **Supported Languages**
๐ Click to see language details
### ๐ฏ **Core Languages**
| Language | Purpose | Features |
|:---------|:--------|:---------|
| **๐ง C** | Main programming language | Core library, maximum performance |
| **โก C++** | Header-only binding | Easy integration, STL compatibility |
| **๐ Python** | Cython bindings | PyPI package, Pythonic interface |
| **๐ CUDA** | GPU computing | Parallel processing, extreme performance |
---
## ๐ฆ **Quick Installation**
### ๐ **Python Users (Recommended)**
```bash
# ๐ One-liner installation from PyPI
pip install LibKaleidoscope
```
> ๐ก **Pro Tip**: Check `python/python-test.py` for example usage!
---
## ๐ ๏ธ **Building from Source**
๐๏ธ Standard Build
```bash
# ๐ Quick build commands
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel
```
โก CUDA-Enabled Build
> โ ๏ธ **IMPORTANT**: CUDA Toolkit must be installed and available on your system before building with CUDA support. Download from [NVIDIA Developer](https://developer.nvidia.com/cuda-downloads).
```bash
# ๐ฅ GPU-accelerated build
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DKALEIDOSCOPE_ENABLE_CUDA=ON ..
cmake --build . --parallel
```
๐ง Custom Build Options
```bash
# ๐๏ธ Disable command line tool (reduces dependencies)
cmake -DCMAKE_BUILD_TYPE=Release -DKALEIDOSCOPE_ENABLE_CMD_TOOL=OFF ..
```
> ๐ **Note**: The libjpeg-turbo dependency is only for testing and demo purposes
---
## ๐ฏ **Usage Guide**
### ๐ช **Simple 3-Step API**
LibKaleidoscope makes image transformation incredibly simple with just **3 functions**:
```mermaid
flowchart LR
A[๐ฏ Initialize] --> B[๐จ Process] --> C[๐งน Cleanup]
B --> B
```
๐ C API Reference
| Step | Function | Purpose |
|:----:|:---------|:--------|
| **1๏ธโฃ** | `initKaleidoscope()` | Initialize transformation matrix |
| **2๏ธโฃ** | `processKaleidoscope()` | Process images (reusable for same dimensions) |
| **3๏ธโฃ** | `deInitKaleidoscope()` | Clean up resources |
```c
// ๐ฏ Step 1: Initialize
int initKaleidoscope(KaleidoscopeHandle *handler, int n, int width, int height, double scaleDown);
// ๐จ Step 2: Process (use multiple times)
void processKaleidoscope(KaleidoscopeHandle *handler, double k, unsigned char *imgIn, unsigned char *imgOut);
// ๐งน Step 3: Cleanup
void deInitKaleidoscope(KaleidoscopeHandle *handler);
```
> ๐ **Example**: Check `src/kaleidoscope-cmd.c` for complete usage
### ๐ฅ๏ธ **Command Line Magic**
Transform images instantly with the command line tool:
```bash
# โจ Create kaleidoscope effect (N=8 segments)
./kaleidoscope-cmd
```
### ๐จ **Visual Example**
โก๏ธ
๐ฎ Original โ Kaleidoscope (N=8)
Image source: AC Valhalla
---
### ๐ป **Programming Language Examples**
โก C++ Header-Only Binding
```cpp
#include
int main() {
// ๐ฏ One-line initialization with all parameters
kalos::Kaleidoscope handler(n, width, height, nComponents, scaleDown, k);
// ๐จ Process your image data
handler.processImage(inData, outData, nPixel);
// ๐งน Automatic cleanup when handler goes out of scope
return 0;
}
```
> ๐ **Advantage**: RAII-style resource management, exception safety
๐ฅ CUDA GPU Backend
```cpp
#include
int main() {
// ๐ GPU-accelerated kaleidoscope
kalos::cuda::Kaleidoscope handler(n, width, height, nComponents, scaleDown, k);
// โก Ultra-fast GPU processing
// โ ๏ธ Important: inData and outData must be device-allocated!
handler.processImage(inData, outData, nPixel);
return 0;
}
```
> ๐ก **Performance Tip**: Ensure your data is allocated on GPU memory for maximum speed
> ๐งช **Examples**: See `tests/processingTest.cpp` and `tests/processingTest.cu` for complete implementations
---
## ๐ **Performance Benchmarks**
### โก **Lightning Fast Performance**
> **Hardware**: Intel i7-11800H CPU
| ๐ฅ **Resolution** | ๐ **FPS** | ๐ฏ **Use Case** |
|:------------------|:-----------|:----------------|
| ๐ฅ **4K UHD** (3840ร2160) | **~65 FPS** | Professional video editing |
| ๐ฌ **Full HD** (1920ร1080) | **~265 FPS** | Real-time streaming |
| ๐บ **720p** (1280ร720) | **~640 FPS** | Gaming overlays |
| ๐ฑ **576p** (720ร576) | **~1350 FPS** | Mobile apps |
### ๐ **Performance Visualization**
๐ฌ Mathematical Formula
The performance follows an exponential decay model:
$$\Large FPS = a \cdot e^{b \cdot nPixels} + c \cdot e^{d \cdot nPixels}$$
**Where:**
- $a = 2492$
- $b = -2.165 \times 10^{-6}$
- $c = 364.9$
- $d = -2.08 \times 10^{-7}$
### ๐โโ๏ธ **Benchmark Your System**
```bash
# ๐ฏ Test performance on your hardware
./kaleidoscope-cmd
```
> โ ๏ธ **Important**: Use `-DCMAKE_BUILD_TYPE=Release` for accurate benchmarks
---
## ๐ค **Contributing**
We welcome contributions! Please feel free to submit issues, feature requests, or pull requests.
## ๐ **License**
This project is licensed under the terms of MIT License.
---
### ๐ **Star this repo if you found it useful!** ๐
Made with โค๏ธ by [egecetin](https://github.com/egecetin)
