kaleidoscope

🌈✨ 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 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)

# 🎉 One-liner installation from PyPI
pip install LibKaleidoscope

‍💡 Pro Tip: Check python/python-test.py for example usage!

🛠️ Building from Source

🏗️ Standard Build

# 🚀 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.

# 🔥 GPU-accelerated build
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DKALEIDOSCOPE_ENABLE_CUDA=ON ..
cmake --build . --parallel

🔧 Custom Build Options

# 🎛️ 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:

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

// 🎯 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:

# ✨ Create kaleidoscope effect (N=8 segments)
./kaleidoscope-cmd <Input_Image> <Output_Image> <N>

🎨 Visual Example

➡️
🎮 Original → Kaleidoscope (N=8)
Image source: AC Valhalla

---

💻 Programming Language Examples

⚡ C++ Header-Only Binding

#include <kaleidoscope.hpp>
 
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

#include <cuda/kaleidoscope.cuh>
 
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

# 🎯 Test performance on your hardware
./kaleidoscope-cmd <Input_Image> <Output_Image> <N> <Number_of_loops>

‍⚠️ 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