Skip to content

Latest commit

 

History

History
142 lines (97 loc) · 5.51 KB

README.md

File metadata and controls

142 lines (97 loc) · 5.51 KB
Raw

A library to create kaleidoscope effect on images. You can build on all platforms using CMake.

GitHub GitHub Workflow Status GitHub Workflow Status GitHub Workflow Status Codecov Codacy grade

C Badge C++ Badge Python Badge CUDA Badge

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

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


Image source: AC Valhalla

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

$$ 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>