Implement py bindings and py wheel

Author: michelerenzullo

.github/workflows/ci.yml

@@ -196,6 +196,9 @@ jobs:
       - name: Run tests
         run: |
           docker run --rm ${{ secrets.DOCKER_USERNAME }}/libgaussianblur:linux ./GaussianBlurTests
+      - name: Run python bindings tests
+        run: |
+          docker run --rm ${{ secrets.DOCKER_USERNAME }}/libgaussianblur:linux sh -c "pip3 install \$(realpath gaussianblur.whl) && pytest python/tests/*.py"
 
   coverage:
     name: Generate Coverage Report

.gitignore

@@ -11,4 +11,5 @@ external/linux
 external/android
 external/ios
 .docker/
-coverage/
+coverage/
+**/__pycache__

CMakeLists.txt

@@ -14,11 +14,16 @@ option(WITH_EXAMPLES "Include examples" OFF)
 option(WITH_TESTS "Include tests" OFF)
 # Coverage
 option(WITH_COVERAGE "Include coverage" OFF)
+# Bindings
+option(WITH_BINDINGS "Build Python bindings" OFF)
 
 if(WITH_COVERAGE AND WITH_EXAMPLES)
     message(FATAL_ERROR "Coverage can affect the performance of the examples. Pick one or the other.")
 endif()
 
+if(WITH_COVERAGE AND WITH_BINDINGS)
+    message(FATAL_ERROR "Coverage can affect the performance of the bindings. Pick one or the other.")
+endif()
 
 # If compiling to WebAssembly
 if(WASM)
@@ -56,10 +61,12 @@ endif()
 # Append additional flags for WebAssembly
 if(WASM)
     set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -msimd128")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -msimd128")
 endif()
 
 if(ENABLE_MULTITHREADING)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DENABLE_MULTITHREADING -pthread")
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -pthread")
 endif()
 
 # Add Framework Accelerate for macOS (SIMD)
@@ -118,38 +125,44 @@ set_target_properties(GaussianBlurLib PROPERTIES OUTPUT_NAME "Gaussianblur")
 if(WITH_EXAMPLES)
     message(STATUS "Building examples")
     if(WASM)
-        add_executable(GaussianBlur "${CMAKE_SOURCE_DIR}/examples/wasm/main.cpp")
+        add_executable(GaussianBlurExample "${CMAKE_SOURCE_DIR}/examples/wasm/main.cpp")
         set(WASM_COMMON_LINK_OPTIONS 
             "SHELL: --closure 1"
-            "-sALLOW_MEMORY_GROWTH=1"
-            "-sMAXIMUM_MEMORY=4GB"
-            "-sINITIAL_MEMORY=314572800"
             "-O3"
             "--bind"
-            "-sWASM_BIGINT"
             "-sEXPORTED_FUNCTIONS=['_malloc']"
             "-msimd128"
         )
 
         # Append specific options based on SINGLE or ENABLE_MULTITHREADING
         if(ENABLE_MULTITHREADING)
             list(APPEND WASM_COMMON_LINK_OPTIONS 
-                "-pthread"
+                "-pthread"                 # Enable multithreading
+                "-sMALLOC=mimalloc"        # Use mimalloc
+                "-sINITIAL_MEMORY=4095mb"  # Use maximum memory and avoid memory growth
                 "-sPTHREAD_POOL_SIZE=navigator.hardwareConcurrency"
             )
+        else()
+            list(APPEND WASM_COMMON_LINK_OPTIONS 
+                "-sINITIAL_MEMORY=300mb"
+                "-sMAXIMUM_MEMORY=4GB"
+                "-sALLOW_MEMORY_GROWTH=1"
+            )
         endif()
 
         # Apply the options to the target
-        target_link_options(GaussianBlur PRIVATE ${WASM_COMMON_LINK_OPTIONS})
+        target_link_options(GaussianBlurExample PRIVATE ${WASM_COMMON_LINK_OPTIONS})
 
         # Install the WASM file
+        set_target_properties(GaussianBlurExample PROPERTIES OUTPUT_NAME "GaussianBlur")
         install(FILES "${CMAKE_BINARY_DIR}/GaussianBlur.wasm" DESTINATION bin)
     else()
-        add_executable(GaussianBlur "${CMAKE_SOURCE_DIR}/examples/desktop/main.cpp")
+        add_executable(GaussianBlurExample "${CMAKE_SOURCE_DIR}/examples/desktop/main.cpp")
+        set_target_properties(GaussianBlurExample PROPERTIES OUTPUT_NAME "GaussianBlur")
     endif()
 
-    target_link_libraries(GaussianBlur GaussianBlurLib)
-    install(TARGETS GaussianBlur
+    target_link_libraries(GaussianBlurExample GaussianBlurLib)
+    install(TARGETS GaussianBlurExample
         BUNDLE DESTINATION Applications
         RUNTIME DESTINATION bin
     )
@@ -184,4 +197,47 @@ if(WITH_TESTS)
     target_link_libraries(GaussianBlurTests GaussianBlurLib gtest_main)
     add_test(NAME GaussianBlurTests COMMAND GaussianBlurTests)
     install(TARGETS GaussianBlurTests DESTINATION bin)
+endif()
+
+
+if(WITH_BINDINGS)
+    if(WASM OR ANDROID OR IOS)
+        message(FATAL_ERROR "Python bindings are not supported for this platform")
+    endif()
+
+    message(STATUS "Building Python bindings")
+    find_package(pybind11 REQUIRED)
+
+
+    set(BINDING_SOURCES ${CMAKE_SOURCE_DIR}/python/bindings/gaussianblur_py.cpp)
+
+    pybind11_add_module(gaussianblur MODULE ${BINDING_SOURCES})
+
+    target_link_libraries(gaussianblur PRIVATE GaussianBlurLib)
+
+
+    # Set the output directory for the shared library to:
+    # <repo_root>/python/bindings/gaussianblur/
+    set_target_properties(gaussianblur PROPERTIES
+        LIBRARY_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/python/gaussianblur
+    )
+
+    # Optionally, add an install rule for the bindings.
+    install(TARGETS gaussianblur
+        LIBRARY DESTINATION python/gaussianblur
+    )
+
+    # Build the wheel (under-the-hood just copies the shared libraries in a whl package)
+    add_custom_target(build_py_wheel ALL
+        DEPENDS gaussianblur
+        COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_BINARY_DIR}/py_wheel
+        COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/py_wheel/gaussianblur
+        COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_FILE:gaussianblur> ${CMAKE_BINARY_DIR}/py_wheel/gaussianblur/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/python/gaussianblur/__init__.py ${CMAKE_BINARY_DIR}/py_wheel/gaussianblur/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/python/setup.py ${CMAKE_BINARY_DIR}/py_wheel/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/python/pyproject.toml ${CMAKE_BINARY_DIR}/py_wheel/
+        COMMAND python3 -m build ${CMAKE_BINARY_DIR}/py_wheel
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/py_wheel/dist/*.whl ${CMAKE_SOURCE_DIR}/python/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/py_wheel/dist/*.whl ${PrefixPath}/python/
+    )
 endif()

Dockerfile

@@ -1,9 +1,17 @@
 FROM debian:bookworm-slim AS base
 
+
 # Install dependencies
 RUN apt-get -qq update; \
     apt-get install -qqy --no-install-recommends gnupg2 wget ca-certificates \
-    apt-transport-https curl unzip make cmake xz-utils cppcheck
+    apt-transport-https curl unzip make cmake xz-utils cppcheck 
+
+# Install python3.11 and pybind11 for bindings.
+ENV PIP_BREAK_SYSTEM_PACKAGES=1 PIP_ROOT_USER_ACTION=ignore
+RUN apt-get install -qqy --no-install-recommends curl python3.11 python3-venv python3-dev && \
+    ln -sf /usr/bin/python3.11 /usr/bin/python3 && \
+    curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11 && \
+    pip install pybind11 pytest numpy build
 
 # Install LLVM
 RUN echo "deb https://apt.llvm.org/bookworm llvm-toolchain-bookworm-16 main" \
@@ -31,6 +39,8 @@ FROM builder-env AS linux
 # Build gaussian_blur
 RUN bootstrap/bootstrap.sh linux && rm -rf build
 RUN ln -s /app/external/linux/x86_64/bin/GaussianBlurTests /app/GaussianBlurTests
+RUN find /app/external/linux/x86_64/python/ -name "gaussianblur-*.whl" -exec ln -s {} /app/gaussianblur.whl \;
+RUN mkdir /app/python && ln -s /app/.deps/gaussian_blur/python/tests /app/python/tests
 
 FROM builder-env AS coverage
 RUN mkdir -p /app/.deps/gaussian_blur/build
@@ -73,8 +83,8 @@ RUN bootstrap/bootstrap.sh android && rm -rf build
 
 
 FROM builder-env AS wasm
-# Download emsdk 3.1.66
-RUN wget -q https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.74.zip -O /opt/emsdk.zip
+# Download emsdk 4.0.5
+RUN wget -q https://github.com/emscripten-core/emsdk/archive/refs/tags/4.0.5.zip -O /opt/emsdk.zip
 # Extract emsdk and create in symlink in /root (aka $HOME)
 ENV EMSDK=/opt/emsdk
 RUN unzip /opt/emsdk.zip -d /opt/ && mv /opt/emsdk-* /opt/emsdk && rm /opt/emsdk.zip && ln -s /opt/emsdk /root/emsdk

README.md

@@ -158,12 +158,12 @@ This will generate the necessary files in the `external/ios` folder.
 
 #### Manual Build
 
-##### Desktop (Linux, macOS)
+##### Desktop (Linux, macOS) with python bindings and examples
 
 ```sh
 mkdir build
 cd build
-cmake -DENABLE_MULTITHREADING=ON -DWITH_EXAMPLES=ON -DWITH_TESTS=ON -DWITH_COVERAGE=OFF ..
+cmake -DENABLE_MULTITHREADING=ON -DWITH_EXAMPLES=ON -DWITH_BINDINGS=ON -DWITH_TESTS=ON -DWITH_COVERAGE=OFF ..
 cmake --build .
 ```
 
@@ -196,9 +196,21 @@ make
 ```
 
 
-## Usage
+## Usage in Python
 
-  When building with `WITH_EXAMPLES=ON`, you can try the library. These examples are intended to provide a simple idea of how the library is used.
+  If you build the library with `WITH_BINDINGS=ON`, a Python wheel will be generated. You will find the wheel under `external/PLATFORM/ABI/python/` along with the shared library.
+
+A basic example has been provided about how to use the module.  
+First, install the wheel with pip, and then, replace with your input/output image paths:
+
+```sh
+pip3 install gaussianblur*.whl
+python3 examples/python/main.py
+```
+
+## Usage in C++
+
+  When building with `WITH_EXAMPLES=ON`, you can try the library. These examples are intended to provide a simple idea of how the library is used.  
 
 ### Command Line (desktop)
 
@@ -261,6 +273,7 @@ LibGaussianBlur implements a robust Continuous Integration and Continuous Deploy
   - Tests must pass successfully before generating the coverage report and build the Android and WASM libraries.
 
 ## Roadmap
+- Python wheel packages
 - Doxygen
 - Flutter plugin with native bindings
 

bootstrap/bootstrap.gaussianblur.sh

@@ -5,7 +5,7 @@
 
 PREFIX="gaussian_blur"
 TEMP_EXTERNAL_BUILD_DIR=.deps
-GAUSSIANBLUR_VERSION="1.0.4"
+GAUSSIANBLUR_VERSION="1.0.5"
 GAUSSIANBLUR_FOLDER="v${GAUSSIANBLUR_VERSION}"
 GAUSSIANBLUR_BUILD_DIR="${PREFIX}-${GAUSSIANBLUR_FOLDER}"
 
@@ -56,6 +56,7 @@ compile_gaussian_blur() {
             -DANDROID_PLATFORM=23 \
             -DANDROID_ABI=$ABI \
             -DBUILD_SHARED_LIBS=ON \
+            -DWITH_BINDINGS=OFF \
             -DWITH_TESTS=OFF \
             -DWITH_COVERAGE=OFF \
             -DANDROID_STL="c++_shared" ..
@@ -75,6 +76,9 @@ compile_gaussian_blur() {
             -DCMAKE_INSTALL_PREFIX="$TEMP_PREFIX_DIR" \
             -DCMAKE_INSTALL_RPATH=$FINAL_PREFIX_DIR/lib \
             -DBUILD_SHARED_LIBS=ON \
+            -DPYBIND11_FINDPYTHON=ON \
+            -Dpybind11_DIR=$(python3 -m pybind11 --cmakedir) \
+            -DWITH_BINDINGS=ON \
             -DWITH_TESTS=ON \
             -DWITH_COVERAGE=OFF \
             ..
@@ -91,12 +95,19 @@ compile_gaussian_blur() {
         mv ${TEMP_PREFIX_DIR}/include/gaussianblur ${FINAL_PREFIX_DIR}/include/
         mv ${TEMP_PREFIX_DIR}/lib/*.so* ${FINAL_PREFIX_DIR}/lib/
         mv ${TEMP_PREFIX_DIR}/bin/* ${FINAL_PREFIX_DIR}/bin/
+
+        # Copy Python bindings
+        if [ -d ${FINAL_PREFIX_DIR}/python/gaussianblur ] ; then rm -rf ${FINAL_PREFIX_DIR}/python/gaussianblur ; fi
+        mkdir -p ${FINAL_PREFIX_DIR}/python/gaussianblur
+        cp -R ../python/gaussianblur ${FINAL_PREFIX_DIR}/python/
+        cp ../python/gaussianblur*.whl ${FINAL_PREFIX_DIR}/python/
     elif [ "$PLATFORM" = "wasm" ] ; then
         cmake -DENABLE_MULTITHREADING=ON \
             -DCMAKE_INSTALL_PREFIX="$TEMP_PREFIX_DIR" \
             -DCMAKE_INSTALL_RPATH=$FINAL_PREFIX_DIR/lib \
             -DBUILD_SHARED_LIBS=OFF \
             -DWASM=ON \
+            -DWITH_BINDINGS=OFF \
             -DWITH_EXAMPLES=ON \
             -DWITH_TESTS=OFF \
             -DWITH_COVERAGE=OFF \
@@ -161,6 +172,7 @@ compile_gaussian_blur() {
             -DCMAKE_TOOLCHAIN_FILE="$IOS_TOOLCHAIN" \
             -DENABLE_MULTITHREADING=ON \
             -DWITH_EXAMPLES=OFF \
+            -DWITH_BINDINGS=OFF \
             -DWITH_TESTS=OFF \
             -DWITH_COVERAGE=OFF \
             -DCMAKE_XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER="$BUNDLE_ID" \
@@ -192,14 +204,17 @@ compile_gaussian_blur() {
             && ln -s "Versions/Current/Resources" "Resources" \
             && ln -s "Versions/Current/Gaussianblur" "Gaussianblur")
     elif [ "$PLATFORM" = "macos" ] && [ "$ABI" = "x86_64" ] ; then
-        # MacOS arm64
+        # MacOS x86_64
         cmake -DENABLE_MULTITHREADING=ON \
             -DWITH_EXAMPLES=ON \
             -DCMAKE_INSTALL_PREFIX=${TEMP_PREFIX_DIR} \
             -DCMAKE_INSTALL_RPATH=$FINAL_PREFIX_DIR/lib \
             -DBUILD_SHARED_LIBS=ON \
+            -DPYBIND11_FINDPYTHON=ON \
+            -Dpybind11_DIR=$(python3 -m pybind11 --cmakedir) \
             -DWITH_TESTS=ON \
             -DWITH_COVERAGE=OFF \
+            -DWITH_BINDINGS=ON \
             -DCMAKE_OSX_ARCHITECTURES="$ABI" \
             ..
         printf "${GREEN}Compiling with ${N_CPU_CORES} cores. This might still take some time\n"
@@ -214,6 +229,12 @@ compile_gaussian_blur() {
         mv ${TEMP_PREFIX_DIR}/include/gaussianblur ${FINAL_PREFIX_DIR}/include/
         mv ${TEMP_PREFIX_DIR}/lib/*.dylib ${FINAL_PREFIX_DIR}/lib/
         mv ${TEMP_PREFIX_DIR}/bin/* ${FINAL_PREFIX_DIR}/bin/
+
+        # Copy Python bindings
+        if [ -d ${FINAL_PREFIX_DIR}/python/gaussianblur ] ; then rm -rf ${FINAL_PREFIX_DIR}/python/gaussianblur ; fi
+        mkdir -p ${FINAL_PREFIX_DIR}/python/gaussianblur
+        cp -R ../python/gaussianblur ${FINAL_PREFIX_DIR}/python/
+        cp ../python/gaussianblur*.whl ${FINAL_PREFIX_DIR}/python/
     else
         # MacOS arm64
         cmake -DENABLE_MULTITHREADING=ON \
@@ -223,6 +244,9 @@ compile_gaussian_blur() {
             -DBUILD_SHARED_LIBS=ON \
             -DWITH_TESTS=ON \
             -DWITH_COVERAGE=OFF \
+            -DPYBIND11_FINDPYTHON=ON \
+            -Dpybind11_DIR=$(python3 -m pybind11 --cmakedir) \
+            -DWITH_BINDINGS=ON \
             -DCMAKE_OSX_ARCHITECTURES=arm64 \
             ..
         printf "${GREEN}Compiling with ${N_CPU_CORES} cores. This might still take some time\n"
@@ -237,6 +261,12 @@ compile_gaussian_blur() {
         mv ${TEMP_PREFIX_DIR}/include/gaussianblur ${FINAL_PREFIX_DIR}/include/
         mv ${TEMP_PREFIX_DIR}/lib/*.dylib ${FINAL_PREFIX_DIR}/lib/
         mv ${TEMP_PREFIX_DIR}/bin/* ${FINAL_PREFIX_DIR}/bin/
+
+        # Copy Python bindings
+        if [ -d ${FINAL_PREFIX_DIR}/python/gaussianblur ] ; then rm -rf ${FINAL_PREFIX_DIR}/python/gaussianblur ; fi
+        mkdir -p ${FINAL_PREFIX_DIR}/python/gaussianblur
+        cp -R ../python/gaussianblur ${FINAL_PREFIX_DIR}/python/
+        cp ../python/gaussianblur*.whl ${FINAL_PREFIX_DIR}/python/
     fi
 }
 

examples/python/main.py

@@ -0,0 +1,34 @@
+from PIL import Image as PILImage
+import numpy as np
+import gaussianblur
+
+# This is a simple example of how to use the gaussianblur module in Python.
+# The example loads an image, applies a gaussian blur to it, and saves the output image.
+def main():
+    input_file = "input.png"
+    output_file = "output.png"
+    # Load image
+    pil_img = PILImage.open(input_file)
+
+    # Set the geometry of the image and copy data buffer in the gaussianblur.Image object
+    img = gaussianblur.Image()
+    img.geom.rows = pil_img.size[1]
+    img.geom.cols = pil_img.size[0]
+    img.geom.channels = len(pil_img.getbands())
+    img.data = np.array(pil_img).flatten().tolist()
+
+    # sigma
+    sigma = 7.5
+    # apply_to_alpha_channel: If True, the alpha channel will be blurred as well (if present)
+    apply_to_alpha_channel = True
+    # Apply gaussian blur
+    gaussianblur.gaussianblur(img, sigma, apply_to_alpha_channel)
+    print("Gaussian blur applied.")
+
+    # Save the output image
+    out_np_img = np.array(img.data, dtype=np.uint8).reshape(img.geom.rows, img.geom.cols, img.geom.channels)
+    PILImage.fromarray(out_np_img, pil_img.mode).save(output_file)
+    print("Output written to", output_file)
+
+if __name__ == "__main__":
+    main()