Package: beatmup
OverviewBeatmup is an extensible asynchronous image and signal processing framework.Beatmup is for image processing, mainly.It enables low-level user-defined processing tasks executionin parallel and using hardware acceleration for the maximum speed,asynchronously, in an application-friendly fashion.It implements basic building blocks and predefined processing operations:Image resampling and geometric operationsBasic color filteringFlood fill and contour extractionRealtime renderingBeatmup runs quite everywhere.Used inlinux,WindowsandAndroidWritten inC++11, it hasJavaandPythonbindingsPrebuilt Python packagesare available for x64 desktop Windows and Ubuntu-based linux distributionsFew to no dependencies: Beatmup is extremely easy to build for a different platformgit, CMake and a C++ compiler is all you needBeatmup compiles with gcc, clang and msvcBeatmup speeds up processing by using GPU regardless its vendor, price and release year.It runs ondesktop GPUs from mainstream vendors,integrated desktop GPUs,Android GPUs,Raspberry Pi GPU (all models including Pi Zero W),NVIDIA Jetson Nano,...It uses the GPU forx2, neural network-based image upscaling technique,running inference of small user-defined neural nets,applying user-defined GLSL shaders to process images,realtime camera image processing in Android,scene rendering and predefined image processing tasks.Highlightsx2: a neural net-based image upscalerBeatmup is arguably the easiest way to get a fast hardware-accelerated neural network-based image superresolution running on any decent GPU. It does not provide a state-of-the-art PSNR score, but can run at a hundred of images per second on a desktop machine.More details on the neural network design and the inference implementation:Inferring a super-resolution neural network on Raspberry Pi GPUUpdate in 2.1 release: the fine-tuned version of the model (trained with multiple degradation kernels) achieves now 32.64 dB on DIV2K validation set compared to the initial score of 32.57 dB.Available resourcesDocsC++ documentation is availablehere. This is the most extensive documentation, it also contains additional explanations that do not relate to a specific programming language:Programming modelNNets module overviewJava package API documentation ishere.Python documentation ishere.C++There is a number of test apps showcasing the use of Beatmup with additional explanations inappsfolder. The code is in C++, but can be universally helpful. Few examples:apps/shadererprocesses images with a custom GLSL fragment shader read from the standard input.apps/x2is a test app for thex2neural net.apps/classifyis a dog image classifier, a variant of ResNeXt trained on a subset of ImageNet containing 120 classes of dogs and cats images. The inference is implemented with OpenGL shaders. Top-1 validation accuracy achieved on Raspberry Pi Zero W is 72.08%. Classifying a 385*385 image takes ~595 ms there.Pythonpython/examplesfolder contains detailed examples of scripts using Beatmup in Python.cifar100.pyexplains how to train a neural net with TensorFlow/Keras, convert it into a Beatmup-compliant model and run its inference on CIFAR100 test set.x2_superresolution.pyandx2_superresolution_video.pyshowcase applying x2 upsampling neural net to an image and a video.Unit tests in Python are available inpython/tests/test.pyandpython/tests/test_nnets.py.Java (Android)An Android test app is available inandroid/appfolder. It consists of independent examples showing how to use Beatmup in Android.BasicCameraUse.javashows how to get the camera preview, apply a simple shader and display the result.UpsamplingConvnetOnCamera.javaimplements the application of x2 upsampling neural net to the camera preview.DogClassifier.javaimplements the dog classifier taking the camera preview image as input.Quick start: compiling BeatmupTo get things running, make sure you havegitandCMakeinstalled, then pick one of the following copy-paste recipes.LinuxBuildingX2app upscaling an image using a neural net inferred with OpenGL:git clone https://github.com/lnstadrum/beatmup.git
cd beatmup
git submodule update --init --recursive
mkdir -p build && cd build
cmake -DUSE_GLX=ON ..
make X2Try to use-DUSE_OPENGL=ONinstead-DUSE_GLX=ONstarting from a clean build folder if you run into trouble.OnRaspberry Pi prior to series 4use the EGL backend with following CMake command:cmake -DUSE_EGL=ON -DUSE_BRCM_LIBS=ON -DGLES_VERSION=20 ..More details on Raspberry Pi setuphere.OnRaspberry Pi 4rather use the following CMake command:cmake -DUSE_EGL_DRM=ON -DGLES_VERSION=20 ..More details on Raspberry Pi 4 setuphere.Once the app is built, you can feed it with an image of your choice and get the upscaled result as follows:./X2 <your-image>.bmp x2-result.bmpWindowsTo build theX2app in Windows you may installVisual Studioand generate the VS solution as follows:git clone https://github.com/lnstadrum/beatmup.git
cd beatmup
git submodule update --init --recursive
mkdir build && cd build
cmake -DUSE_OPENGL=ON ..Then open the.slnsolution file in Visual Studio and build the executable.AndroidThere is Android project containing a library and a test app modules (libandapp). To build them install Android Studio and Android NDK bundle, clone the repository and open the project situated inandroidfolder in Android studio.You can build an apk in a docker container as well. Having docker installed, you can run the following script to buildbeatmupApp.apkinstallation package which you may then copy to your Android phone and open it there to install the test app:git clone https://github.com/lnstadrum/beatmup.git
cd beatmup
git submodule update --init --recursive
docker build -f dockerfiles/android.Dockerfile -t beatmup-android .
docker run -v $(pwd):/opt/android-build beatmup-androidQuicker start with PythonWindowsPrebuilt python packages are available in 64-bit Windows for Python versions from3.6to3.11:python -m pip install --upgrade pip
python -m pip install beatmupUbuntu-based linuxPrebuilt packages for x64 desktop Ubuntu-based linux distributions are available for downloading on thereleases page.Compiling Python packageIf there is no prebuilt package available for your platform/OS, you can easily build a Python wheel installable withpipon your own.First, get the code and try to compile an app as explained above. Then in the repository root folder runcd build
make beatmup
cd ../python
python3 setup.py bdist_wheel cleanThe installation package is now available inpython/distfolder. You can install it and make sure it works:python3 -m pip install --no-index --find-links=dist beatmup
python3 -c "import beatmup; beatmup.say_hi()"Licence and contributionsThe project is licensed under the GNU GPL v3 licence.The contributions are governed by theContribution Licence Agreement (CLA). In short, under this Agreement you remain the copyright owner of your contribution, but you allow us to use and distribute your contribution under the terms of a possibly different licence.If you want to contribute:make sure you own the copyright of your contribution,raise a pull request,send a signed CLA onbeatmup.imaging@gmail.com.Otherwise:raise an issue if you have a question or a feature request,contact us by email.