Skip to content

README.md

Latest commit

 

History

History
305 lines (199 loc) · 9.19 KB

README.md

File metadata and controls

305 lines (199 loc) · 9.19 KB
Raw
LibKaleidoscope

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

GitHub GitHub Workflow Status GitHub Workflow Status Sonarcloud Analysis Scorecard score

🛠️ Technology Stack

C Badge C++ Badge Python Badge CUDA Badge CMake Badge

🎯 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!

AI Usage Disclosure

This is not a vibe coding project. Project utilizes generative AI tools to create and fix documentation only.

  • Tools Used: Github Copilot
  • Scope of Use:
    • Documentation: Most of the README sections and function descriptions were AI-generated. But only for documentation purposes!

🌟 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
Loading
🔍 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

Performance Chart
🔬 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