<div align="center">
<img src="https://raw.githubusercontent.com/egecetin/libKaleidoscope/master/doc/images/logo-black.png" alt="" width="850"/>
<br>
A library to create kaleidoscope effect on images. You can build on all platforms using CMake.
</div>
The library is written in C language so you can use Foreign Function Interface (FFI) to call functions from your favorite programming language. You can download from python package from PyPI. It also has C++ header only library to provide easier interface for C++ users and CUDA support for people who have doubts about performance. Check for mathematical explanation of the kaleidoscope effect from my [webpage](https://egecetin.github.io/Projects/kaleidoscope)
## Supported Languages
- C : Main programming language
- C++ : Header only binding for easier usage
- Python : Bindings using Cython
- CUDA : For GPU computing
## Install for Python
```
pip install LibKaleidoscope
```
Python users check python/python-test.py in GitHub for basic usage
## Building
Use the following commands,
```
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel
```
If you want to enable CUDA backend,
```
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DKALEIDOSCOPE_ENABLE_CUDA=ON ..
cmake --build . --parallel
```
There is no direct dependency for libjpeg-turbo inside from the library. It is just for test and demonstration purposes. If you don't want to install/compile just disable command line tool compilation with ``-DKALEIDOSCOPE_ENABLE_CMD_TOOL=OFF``
## Usage
The library has a simple usage and you need only three functions to use it. Check the sample usage at ``src/kaleidoscope-cmd.c``
- Initialization of the transformation matrix: ``int initKaleidoscope(KaleidoscopeHandle *handler, int n, int width, int height, double scaleDown)``
- Processing image (Can be used multiple times if the input images have same dimensions): ``void processKaleidoscope(KaleidoscopeHandle *handler, double k, unsigned char *imgIn, unsigned char *imgOut)``
- Deinitialization of the transformation matrix: ``void deInitKaleidoscope(KaleidoscopeHandle *handler)``
Alternatively you can directly use the command line program to create kaleidoscope effect with ``./kaleidoscope-cmd <Input Image Path> <Output Image Path> <N>``. You can see an example below for ``N=8``
<div align="center">
<img src="https://raw.githubusercontent.com/egecetin/libKaleidoscope/master/doc/images/ac-synin.jpg" width="425"/> <img src="https://raw.githubusercontent.com/egecetin/libKaleidoscope/master/doc/images/ac-synin-out.jpg" width="425"/>
<br>
Image source: AC Valhalla
</div>
For C++ and CUDA usage check the unit tests at ``tests/processingTest.cpp`` and ``tests/processingTest.cu``. It is very easy! Just include the header and construct the ``Kaleidoscope`` class from ``kalos`` namespace.
- For C++ header only binding,
```
#include <kaleidoscope.hpp>
int main()
{
kalos::Kaleidoscope handler(n, width, height, nComponents, scaleDown, k);
/* ... */
handler.processImage(inData, outData, nPixel);
/* ... */
return 0;
}
```
- For CUDA backend,
```
#include <cuda/kaleidoscope.cuh>
int main()
{
kalos::cuda::Kaleidoscope handler(n, width, height, nComponents, scaleDown, k);
/* ... */
// Make sure inData and outData is device allocated!
handler.processImage(inData, outData, nPixel);
/* ... */
return 0;
}
```
## Benchmark
It is really fast! On a Intel i7-11800H CPU it achieves,
- ~65 FPS for 4K UHD (3840 x 2160)
- ~265 FPS for Full HD (1920 x 1080)
- ~640 FPS for 720p (1280 x 720)
- ~1350 FPS for 576p (720 x 576)
resolution images. The performance estimation can be seen at the below
<div align="center">
<img src="https://raw.githubusercontent.com/egecetin/libKaleidoscope/master/doc/images/performance-black.png" alt="" width="850"/>
</div>
$$ FPS = a\text{ }e^{b\text{ }nPixels}+c\text{ }e^{d\text{ }nPixels} $$
$$ a = 2492 \text{, } b = -2.165\text{ }10^{-6} \text{, } c = 364.9 \text{, } d = -2.08\text{ }10^{-7} $$
If you want to benchmark code on your system make sure you configured with ```-DCMAKE_BUILD_TYPE=Release``` and use this command,
```./kaleidoscope-cmd <Input Image Path> <Output Image Path> <N> <Number of loop>```
Raw data
{
"_id": null,
"home_page": "https://egecetin.github.io/libKaleidoscope/",
"name": "LibKaleidoscope",
"maintainer": "egecetin",
"docs_url": null,
"requires_python": "",
"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/97/f2/8a513906b6ee5b059dbafc0ad14b6e6b48332cc8bb3482060c0b330739df/LibKaleidoscope-1.4.0.tar.gz",
"platform": "any",
"description": "<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/egecetin/libKaleidoscope/master/doc/images/logo-black.png\" alt=\"\" width=\"850\"/>\n<br>\n\nA library to create kaleidoscope effect on images. You can build on all platforms using CMake.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n</div>\n\nThe library is written in C language so you can use Foreign Function Interface (FFI) to call functions from your favorite programming language. You can download from python package from PyPI. It also has C++ header only library to provide easier interface for C++ users and CUDA support for people who have doubts about performance. Check for mathematical explanation of the kaleidoscope effect from my [webpage](https://egecetin.github.io/Projects/kaleidoscope)\n\n## Supported Languages\n\n- C : Main programming language\n- C++ : Header only binding for easier usage\n- Python : Bindings using Cython\n- CUDA : For GPU computing\n\n## Install for Python\n\n```\npip install LibKaleidoscope\n```\n\nPython users check python/python-test.py in GitHub for basic usage\n\n## Building\n\nUse the following commands,\n\n```\nmkdir build && cd build\ncmake -DCMAKE_BUILD_TYPE=Release ..\ncmake --build . --parallel\n```\n\nIf you want to enable CUDA backend,\n\n```\nmkdir build && cd build\ncmake -DCMAKE_BUILD_TYPE=Release -DKALEIDOSCOPE_ENABLE_CUDA=ON ..\ncmake --build . --parallel\n```\n\nThere is no direct dependency for libjpeg-turbo inside from the library. It is just for test and demonstration purposes. If you don't want to install/compile just disable command line tool compilation with ``-DKALEIDOSCOPE_ENABLE_CMD_TOOL=OFF``\n\n## Usage\n\nThe library has a simple usage and you need only three functions to use it. Check the sample usage at ``src/kaleidoscope-cmd.c``\n\n- Initialization of the transformation matrix: ``int initKaleidoscope(KaleidoscopeHandle *handler, int n, int width, int height, double scaleDown)``\n- Processing image (Can be used multiple times if the input images have same dimensions): ``void processKaleidoscope(KaleidoscopeHandle *handler, double k, unsigned char *imgIn, unsigned char *imgOut)``\n- Deinitialization of the transformation matrix: ``void deInitKaleidoscope(KaleidoscopeHandle *handler)``\n\nAlternatively you can directly use the command line program to create kaleidoscope effect with ``./kaleidoscope-cmd <Input Image Path> <Output Image Path> <N>``. You can see an example below for ``N=8``\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/egecetin/libKaleidoscope/master/doc/images/ac-synin.jpg\" width=\"425\"/> <img src=\"https://raw.githubusercontent.com/egecetin/libKaleidoscope/master/doc/images/ac-synin-out.jpg\" width=\"425\"/>\n <br>\n Image source: AC Valhalla\n</div>\n\nFor C++ and CUDA usage check the unit tests at ``tests/processingTest.cpp`` and ``tests/processingTest.cu``. It is very easy! Just include the header and construct the ``Kaleidoscope`` class from ``kalos`` namespace.\n\n- For C++ header only binding,\n\n```\n#include <kaleidoscope.hpp>\n\nint main()\n{\n kalos::Kaleidoscope handler(n, width, height, nComponents, scaleDown, k);\n\n /* ... */\n\n handler.processImage(inData, outData, nPixel);\n\n /* ... */\n\n return 0;\n}\n```\n\n- For CUDA backend,\n\n```\n#include <cuda/kaleidoscope.cuh>\n\nint main()\n{\n kalos::cuda::Kaleidoscope handler(n, width, height, nComponents, scaleDown, k);\n\n /* ... */\n\n // Make sure inData and outData is device allocated!\n handler.processImage(inData, outData, nPixel);\n\n /* ... */\n\n return 0;\n}\n```\n\n## Benchmark\n\nIt is really fast! On a Intel i7-11800H CPU it achieves,\n\n- ~65 FPS for 4K UHD (3840 x 2160)\n- ~265 FPS for Full HD (1920 x 1080)\n- ~640 FPS for 720p (1280 x 720)\n- ~1350 FPS for 576p (720 x 576)\n\nresolution images. The performance estimation can be seen at the below\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/egecetin/libKaleidoscope/master/doc/images/performance-black.png\" alt=\"\" width=\"850\"/>\n</div>\n\n$$ FPS = a\\text{ }e^{b\\text{ }nPixels}+c\\text{ }e^{d\\text{ }nPixels} $$\n\n$$ a = 2492 \\text{, } b = -2.165\\text{ }10^{-6} \\text{, } c = 364.9 \\text{, } d = -2.08\\text{ }10^{-7} $$\n\nIf you want to benchmark code on your system make sure you configured with ```-DCMAKE_BUILD_TYPE=Release``` and use this command,\n\n```./kaleidoscope-cmd <Input Image Path> <Output Image Path> <N> <Number of loop>```\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A library to create kaleidoscope effect on images.",
"version": "1.4.0",
"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": "",
"digests": {
"blake2b_256": "97f28a513906b6ee5b059dbafc0ad14b6e6b48332cc8bb3482060c0b330739df",
"md5": "851a72061ef0fe5bd180343d2c5b71ee",
"sha256": "21d68049e05ce835c86400c06e2e936063911bc42593e7a9467c9fff96636a3e"
},
"downloads": -1,
"filename": "LibKaleidoscope-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "851a72061ef0fe5bd180343d2c5b71ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 35991,
"upload_time": "2023-06-19T17:47:20",
"upload_time_iso_8601": "2023-06-19T17:47:20.653278Z",
"url": "https://files.pythonhosted.org/packages/97/f2/8a513906b6ee5b059dbafc0ad14b6e6b48332cc8bb3482060c0b330739df/LibKaleidoscope-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-19 17:47:20",
"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
