<div align="center">
<img src="https://github.com/egecetin/libKaleidoscope/blob/c1a603da36bcb27b31339bd1075c5e54b156f166/doc/images/logo-white.png" alt="LibKaleidoscope" width="850"/>
<h3>🌈✨ Transform Images into Mesmerizing Kaleidoscope Art ✨🌈</h3>
<p>
<strong>A blazingly fast, cross-platform library to create stunning kaleidoscope effects on images</strong><br>
<em>Built with ❤️ using C, C++, Python, and CUDA</em>
</p>
---
### 📊 **Project Status**
### 🛠️ **Technology Stack**
</div>
---
## 🎯 **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**
<div align="center">
| 🚀 **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 |
</div>
---
## 🎭 **Supported Languages**
<details>
<summary><strong>🔍 Click to see language details</strong></summary>
### 🎯 **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 |
</details>
---
## 📦 **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**
<details>
<summary><strong>🏗️ Standard Build</strong></summary>
```bash
# 🚀 Quick build commands
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel
```
</details>
<details>
<summary><strong>⚡ CUDA-Enabled Build</strong></summary>
> ⚠️ **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
```
</details>
<details>
<summary><strong>🔧 Custom Build Options</strong></summary>
```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
</details>
---
## 🎯 **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
```
<details>
<summary><strong>🔍 C API Reference</strong></summary>
| 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
</details>
### 🖥️ **Command Line Magic**
Transform images instantly with the command line tool:
```bash
# ✨ Create kaleidoscope effect (N=8 segments)
./kaleidoscope-cmd <Input_Image> <Output_Image> <N>
```
### 🎨 **Visual Example**
<div align="center">
<img src="https://github.com/egecetin/libKaleidoscope/blob/c1a603da36bcb27b31339bd1075c5e54b156f166/doc/images/ac-synin.jpg" width="400"/> ➡️ <img src="https://github.com/egecetin/libKaleidoscope/blob/c1a603da36bcb27b31339bd1075c5e54b156f166/doc/images/ac-synin-out.jpg" width="400"/>
<br>
<em>🎮 Original → Kaleidoscope (N=8)</em><br>
<small>Image source: AC Valhalla</small>
</div>
---
### 💻 **Programming Language Examples**
<details>
<summary><strong>⚡ C++ Header-Only Binding</strong></summary>
```cpp
#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
</details>
<details>
<summary><strong>🔥 CUDA GPU Backend</strong></summary>
```cpp
#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
</details>
> 🧪 **Examples**: See `tests/processingTest.cpp` and `tests/processingTest.cu` for complete implementations
---
## 🚀 **Performance Benchmarks**
### ⚡ **Lightning Fast Performance**
> **Hardware**: Intel i7-11800H CPU
<div align="center">
| 🎥 **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 |
</div>
### 📈 **Performance Visualization**
<div align="center">
<img src="https://github.com/egecetin/libKaleidoscope/blob/c1a603da36bcb27b31339bd1075c5e54b156f166/doc/images/performance-white.png" alt="Performance Chart" width="850"/>
</div>
<details>
<summary><strong>🔬 Mathematical Formula</strong></summary>
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}$
</details>
### 🏃♂️ **Benchmark Your System**
```bash
# 🎯 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.
---
<div align="center">
### 🌟 **Star this repo if you found it useful!** 🌟
Made with ❤️ by [egecetin](https://github.com/egecetin)
</div>
Raw data
{
"_id": null,
"home_page": "https://egecetin.github.io/libKaleidoscope/",
"name": "LibKaleidoscope",
"maintainer": "egecetin",
"docs_url": null,
"requires_python": null,
"maintainer_email": "egecetin@hotmail.com.tr",
"keywords": "image-processing, video-processing, image-manipulation, image-filtering, video-filtering",
"author": "egecetin",
"author_email": "egecetin@hotmail.com.tr",
"download_url": "https://files.pythonhosted.org/packages/bf/d8/8554f64990a29a434a3505ccb8ebb0b8caff92d03b02b3f87eda2cf13870/libkaleidoscope-1.4.2.tar.gz",
"platform": "any",
"description": "<div align=\"center\">\n\n<img src=\"https://github.com/egecetin/libKaleidoscope/blob/c1a603da36bcb27b31339bd1075c5e54b156f166/doc/images/logo-white.png\" alt=\"LibKaleidoscope\" width=\"850\"/>\n\n<h3>\ud83c\udf08\u2728 Transform Images into Mesmerizing Kaleidoscope Art \u2728\ud83c\udf08</h3>\n\n<p>\n<strong>A blazingly fast, cross-platform library to create stunning kaleidoscope effects on images</strong><br>\n<em>Built with \u2764\ufe0f using C, C++, Python, and CUDA</em>\n</p>\n\n---\n\n### \ud83d\udcca **Project Status**\n\n\n\n\n\n\n\n\n### \ud83d\udee0\ufe0f **Technology Stack**\n\n\n\n\n\n\n\n</div>\n\n---\n\n## \ud83c\udfaf **What is LibKaleidoscope?**\n\nLibKaleidoscope 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.\n\n> \ud83d\udd17 **Learn More**: Check out the [mathematical explanation](https://egecetin.github.io/Projects/kaleidoscope) of the kaleidoscope effect!\n\n\n## \ud83c\udf1f **Key Features**\n\n<div align=\"center\">\n\n| \ud83d\ude80 **Performance** | \ud83c\udf10 **Multi-Language** | \ud83c\udfa8 **Easy to Use** | \u26a1 **GPU Accelerated** |\n|:---:|:---:|:---:|:---:|\n| Ultra-fast processing with optimized algorithms | C, C++, Python, CUDA support | Simple 3-function API | CUDA backend for maximum speed |\n\n</div>\n\n---\n\n## \ud83c\udfad **Supported Languages**\n\n<details>\n<summary><strong>\ud83d\udd0d Click to see language details</strong></summary>\n\n### \ud83c\udfaf **Core Languages**\n\n| Language | Purpose | Features |\n|:---------|:--------|:---------|\n| **\ud83d\udd27 C** | Main programming language | Core library, maximum performance |\n| **\u26a1 C++** | Header-only binding | Easy integration, STL compatibility |\n| **\ud83d\udc0d Python** | Cython bindings | PyPI package, Pythonic interface |\n| **\ud83d\ude80 CUDA** | GPU computing | Parallel processing, extreme performance |\n\n</details>\n\n---\n\n## \ud83d\udce6 **Quick Installation**\n\n### \ud83d\udc0d **Python Users (Recommended)**\n\n```bash\n# \ud83c\udf89 One-liner installation from PyPI\npip install LibKaleidoscope\n```\n\n> \ud83d\udca1 **Pro Tip**: Check `python/python-test.py` for example usage!\n\n---\n\n## \ud83d\udee0\ufe0f **Building from Source**\n\n<details>\n<summary><strong>\ud83c\udfd7\ufe0f Standard Build</strong></summary>\n\n```bash\n# \ud83d\ude80 Quick build commands\nmkdir build && cd build\ncmake -DCMAKE_BUILD_TYPE=Release ..\ncmake --build . --parallel\n```\n\n</details>\n\n<details>\n<summary><strong>\u26a1 CUDA-Enabled Build</strong></summary>\n\n> \u26a0\ufe0f **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).\n\n```bash\n# \ud83d\udd25 GPU-accelerated build\nmkdir build && cd build\ncmake -DCMAKE_BUILD_TYPE=Release -DKALEIDOSCOPE_ENABLE_CUDA=ON ..\ncmake --build . --parallel\n```\n\n</details>\n\n<details>\n<summary><strong>\ud83d\udd27 Custom Build Options</strong></summary>\n\n```bash\n# \ud83c\udf9b\ufe0f Disable command line tool (reduces dependencies)\ncmake -DCMAKE_BUILD_TYPE=Release -DKALEIDOSCOPE_ENABLE_CMD_TOOL=OFF ..\n```\n\n> \ud83d\udcdd **Note**: The libjpeg-turbo dependency is only for testing and demo purposes\n\n</details>\n\n---\n\n## \ud83c\udfaf **Usage Guide**\n\n### \ud83c\udfaa **Simple 3-Step API**\n\nLibKaleidoscope makes image transformation incredibly simple with just **3 functions**:\n\n```mermaid\nflowchart LR\n A[\ud83c\udfaf Initialize] --> B[\ud83c\udfa8 Process] --> C[\ud83e\uddf9 Cleanup]\n B --> B\n```\n\n<details>\n<summary><strong>\ud83d\udd0d C API Reference</strong></summary>\n\n| Step | Function | Purpose |\n|:----:|:---------|:--------|\n| **1\ufe0f\u20e3** | `initKaleidoscope()` | Initialize transformation matrix |\n| **2\ufe0f\u20e3** | `processKaleidoscope()` | Process images (reusable for same dimensions) |\n| **3\ufe0f\u20e3** | `deInitKaleidoscope()` | Clean up resources |\n\n```c\n// \ud83c\udfaf Step 1: Initialize\nint initKaleidoscope(KaleidoscopeHandle *handler, int n, int width, int height, double scaleDown);\n\n// \ud83c\udfa8 Step 2: Process (use multiple times)\nvoid processKaleidoscope(KaleidoscopeHandle *handler, double k, unsigned char *imgIn, unsigned char *imgOut);\n\n// \ud83e\uddf9 Step 3: Cleanup\nvoid deInitKaleidoscope(KaleidoscopeHandle *handler);\n```\n\n> \ud83d\udcda **Example**: Check `src/kaleidoscope-cmd.c` for complete usage\n\n</details>\n\n### \ud83d\udda5\ufe0f **Command Line Magic**\n\nTransform images instantly with the command line tool:\n\n```bash\n# \u2728 Create kaleidoscope effect (N=8 segments)\n./kaleidoscope-cmd <Input_Image> <Output_Image> <N>\n```\n\n### \ud83c\udfa8 **Visual Example**\n\n<div align=\"center\">\n <img src=\"https://github.com/egecetin/libKaleidoscope/blob/c1a603da36bcb27b31339bd1075c5e54b156f166/doc/images/ac-synin.jpg\" width=\"400\"/> \u27a1\ufe0f <img src=\"https://github.com/egecetin/libKaleidoscope/blob/c1a603da36bcb27b31339bd1075c5e54b156f166/doc/images/ac-synin-out.jpg\" width=\"400\"/>\n <br>\n <em>\ud83c\udfae Original \u2192 Kaleidoscope (N=8)</em><br>\n <small>Image source: AC Valhalla</small>\n</div>\n\n---\n\n### \ud83d\udcbb **Programming Language Examples**\n\n<details>\n<summary><strong>\u26a1 C++ Header-Only Binding</strong></summary>\n\n```cpp\n#include <kaleidoscope.hpp>\n\nint main() {\n // \ud83c\udfaf One-line initialization with all parameters\n kalos::Kaleidoscope handler(n, width, height, nComponents, scaleDown, k);\n\n // \ud83c\udfa8 Process your image data\n handler.processImage(inData, outData, nPixel);\n\n // \ud83e\uddf9 Automatic cleanup when handler goes out of scope\n return 0;\n}\n```\n\n> \ud83d\ude80 **Advantage**: RAII-style resource management, exception safety\n\n</details>\n\n<details>\n<summary><strong>\ud83d\udd25 CUDA GPU Backend</strong></summary>\n\n```cpp\n#include <cuda/kaleidoscope.cuh>\n\nint main() {\n // \ud83d\ude80 GPU-accelerated kaleidoscope\n kalos::cuda::Kaleidoscope handler(n, width, height, nComponents, scaleDown, k);\n\n // \u26a1 Ultra-fast GPU processing\n // \u26a0\ufe0f Important: inData and outData must be device-allocated!\n handler.processImage(inData, outData, nPixel);\n\n return 0;\n}\n```\n\n> \ud83d\udca1 **Performance Tip**: Ensure your data is allocated on GPU memory for maximum speed\n\n</details>\n\n> \ud83e\uddea **Examples**: See `tests/processingTest.cpp` and `tests/processingTest.cu` for complete implementations\n\n---\n\n## \ud83d\ude80 **Performance Benchmarks**\n\n### \u26a1 **Lightning Fast Performance**\n\n> **Hardware**: Intel i7-11800H CPU\n\n<div align=\"center\">\n\n| \ud83c\udfa5 **Resolution** | \ud83d\udcca **FPS** | \ud83c\udfaf **Use Case** |\n|:------------------|:-----------|:----------------|\n| \ud83d\udd25 **4K UHD** (3840\u00d72160) | **~65 FPS** | Professional video editing |\n| \ud83c\udfac **Full HD** (1920\u00d71080) | **~265 FPS** | Real-time streaming |\n| \ud83d\udcfa **720p** (1280\u00d7720) | **~640 FPS** | Gaming overlays |\n| \ud83d\udcf1 **576p** (720\u00d7576) | **~1350 FPS** | Mobile apps |\n\n</div>\n\n### \ud83d\udcc8 **Performance Visualization**\n\n<div align=\"center\">\n <img src=\"https://github.com/egecetin/libKaleidoscope/blob/c1a603da36bcb27b31339bd1075c5e54b156f166/doc/images/performance-white.png\" alt=\"Performance Chart\" width=\"850\"/>\n</div>\n\n<details>\n<summary><strong>\ud83d\udd2c Mathematical Formula</strong></summary>\n\nThe performance follows an exponential decay model:\n\n$$\\Large FPS = a \\cdot e^{b \\cdot nPixels} + c \\cdot e^{d \\cdot nPixels}$$\n\n**Where:**\n- $a = 2492$\n- $b = -2.165 \\times 10^{-6}$\n- $c = 364.9$\n- $d = -2.08 \\times 10^{-7}$\n\n</details>\n\n### \ud83c\udfc3\u200d\u2642\ufe0f **Benchmark Your System**\n\n```bash\n# \ud83c\udfaf Test performance on your hardware\n./kaleidoscope-cmd <Input_Image> <Output_Image> <N> <Number_of_loops>\n```\n\n> \u26a0\ufe0f **Important**: Use `-DCMAKE_BUILD_TYPE=Release` for accurate benchmarks\n\n---\n\n## \ud83e\udd1d **Contributing**\n\nWe welcome contributions! Please feel free to submit issues, feature requests, or pull requests.\n\n## \ud83d\udcc4 **License**\n\nThis project is licensed under the terms of MIT License.\n\n---\n\n<div align=\"center\">\n\n### \ud83c\udf1f **Star this repo if you found it useful!** \ud83c\udf1f\n\nMade with \u2764\ufe0f by [egecetin](https://github.com/egecetin)\n\n</div>\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A library to create kaleidoscope effect on images.",
"version": "1.4.2",
"project_urls": {
"Download": "https://github.com/egecetin/libKaleidoscope/releases",
"Homepage": "https://egecetin.github.io/libKaleidoscope/"
},
"split_keywords": [
"image-processing",
" video-processing",
" image-manipulation",
" image-filtering",
" video-filtering"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bfd88554f64990a29a434a3505ccb8ebb0b8caff92d03b02b3f87eda2cf13870",
"md5": "d7dfa338938259d8b3a1c9b7ecb2a2a4",
"sha256": "3bc6301ca900255822a1c43492f637cf7e3be1e8b6773a31625c96f17b6de6cd"
},
"downloads": -1,
"filename": "libkaleidoscope-1.4.2.tar.gz",
"has_sig": false,
"md5_digest": "d7dfa338938259d8b3a1c9b7ecb2a2a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 69914,
"upload_time": "2025-08-29T07:30:04",
"upload_time_iso_8601": "2025-08-29T07:30:04.631477Z",
"url": "https://files.pythonhosted.org/packages/bf/d8/8554f64990a29a434a3505ccb8ebb0b8caff92d03b02b3f87eda2cf13870/libkaleidoscope-1.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 07:30:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "egecetin",
"github_project": "libKaleidoscope",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "libkaleidoscope"
}
JSON
