Improved interface and implemented packaging

Author: ManfredStoiber

.github/workflows/python-publish.yml

@@ -0,0 +1,103 @@
+name: Build and upload to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  generate-wheels-matrix:
+    name: Generate wheels matrix
+    runs-on: ubuntu-latest
+    outputs:
+      include: ${{ steps.set-matrix.outputs.include }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install cibuildwheel
+        run: pipx install cibuildwheel==2.16.2
+      - id: set-matrix
+        run: |
+          MATRIX=$(
+            {
+              cibuildwheel --print-build-identifiers --platform linux \
+              | jq -nRc '{"only": inputs, "os": "ubuntu-latest"}' \
+              && \
+              cibuildwheel --print-build-identifiers --platform macos \
+              | jq -nRc '{"only": inputs, "os": "macos-latest"}' \
+              && cibuildwheel --print-build-identifiers --platform windows \
+              | jq -nRc '{"only": inputs, "os": "windows-latest"}'
+            } | jq -sc
+          )
+          echo "include=$MATRIX" >> $GITHUB_OUTPUT
+    env:
+      CIBW_ARCHS_LINUX: x86_64 i686 aarch64 ppc64le
+      CIBW_ARCHS_MACOS: x86_64 # arm64 not working due to linker errors
+      CIBW_ARCHS_WINDOWS: x86 AMD64
+      CIBW_SKIP: >
+        pp37-win_amd64 # not working due to compiler errors during numpy installation
+        pp310-win_amd64 # not working due to missing ndarrayobject.h. Warning from numpy: Numpy built with MINGW-W64 on Windows 64 bits is experimental, and only available for testing.
+      
+
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    needs: generate-wheels-matrix
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include: ${{ fromJson(needs.generate-wheels-matrix.outputs.include) }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up QEMU
+        if: runner.os == 'Linux'
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: all
+
+      - name: Build wheels
+        uses: pypa/[email protected]
+        with:
+          only: ${{ matrix.only }}
+        env:
+          CIBW_REPAIR_WHEEL_COMMAND_MACOS: ""
+
+      - uses: actions/upload-artifact@v3
+        with:
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Build SDist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v3
+        with:
+          path: dist/*.tar.gz
+
+  upload_pypi:
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/stag-python
+    permissions:
+      id-token: write
+    if: github.event_name == 'release' && github.event.action == 'published'
+    steps:
+      - uses: actions/download-artifact@v3
+        with:
+          name: artifact
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -5,6 +5,8 @@
 /lib/
 /stag_python.egg-info/
 /cmake-build-debug/
+/dist/
+/wheelhouse/
 
 # Compiled Object files
 *.slo

CMakeLists.txt

@@ -23,15 +23,14 @@ set(CMAKE_MODULE_PATH
         ${CMAKE_MODULE_PATH} "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
 find_package(OpenCV 4 REQUIRED)
-find_package(Eigen3 3.3 REQUIRED NO_MODULE)
 find_package(NumPy REQUIRED)
 
 add_subdirectory(submodules/pybind11)
 include_directories("submodules/pybind11/include")
 include_directories("submodules/pybind11_opencv_numpy")
 
-pybind11_add_module(stag
-        StagPy.cpp
+pybind11_add_module(_core
+        src/stag/StagModule.cpp
         submodules/pybind11_opencv_numpy/ndarray_converter.cpp
 )
 
@@ -40,6 +39,7 @@ file(GLOB SRC_FILE2 "submodules/stag/src/ED/*.c*")
 
 include_directories(
     ${OpenCV_INCLUDE_DIRS}
+    ${NUMPY_INCLUDES}
     stag/
     stag/ED/
 )
@@ -54,9 +54,7 @@ target_link_libraries(
 )
 
 target_link_libraries(
-    stag PRIVATE
+    _core PRIVATE
     ${OpenCV_LIBS}
     staglib
 )
-
-set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_SOURCE_DIR}/app)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Manfred Stoiber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,48 +1,88 @@
+[![Build and upload to PyPI](https://github.com/ManfredStoiber/stag-python/actions/workflows/python-publish.yml/badge.svg)](https://github.com/ManfredStoiber/stag-python/actions/workflows/python-publish.yml)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/stag-python)
+
+
 # Python Wrapper for [STag - A Stable, Occlusion-Resistant Fiducial Marker System](https://github.com/ManfredStoiber/stag)
 
 ## 📊 Comparison Between Different Marker Systems:
 [<img src="https://github.com/ManfredStoiber/stag/assets/47210077/668ca457-33dd-4ce7-8b94-662c7a5bb4d9" width="400" height="200" />](https://www.youtube.com/watch?v=vnHI3GzLVrY)
 
-## 📋 Getting Started
-0. Install Prerequisites
-    - [CMake >= 3.16](https://cmake.org/getting-started/)
-        - On Linux: `apt install cmake`
-    - [OpenCV 4](https://opencv.org/get-started/) for C++
-        - On Linux: `apt install libopencv-dev`
-    - [Eigen 3](https://gitlab.com/libeigen/eigen)
-        - On Linux: `apt install libeigen3-dev`
-    - Run `pip install numpy`
-        - On Linux: if during step 2.2 the error "numpy/ndarrayobject.h: No such file or directory" occurs, try one of following solutions:
-            - Run `apt install python-numpy` or
-            - Search for "ndarrayobject.h" (`find / -name ndarrayobject.h`) and create a symlink from its parent directory to "/usr/include/numpy" (e.g. `ln -s /usr/local/lib/python3.8/dist-packages/numpy/core/include/numpy /usr/include/numpy`)
-    - Run `pip install opencv-python`
-1. Clone this repository recursively: `git clone --recursive https://github.com/ManfredStoiber/stag-python`
-2. Build
-    1. cd into project: `cd stag-python`
-    2. `pip install .`
-3. Run test app
-    1. `cd example`
-    2. `python example.py`
-
 ## 📖 Usage
+### Installation
+`pip install stag-python`
+
 
-For an example how to use this library, refer to [example.py](https://github.com/ManfredStoiber/stag-python/blob/master/example/example.py)
+### Example
+Note: in this example cv2 is used for loading the image. To use cv2, you need to install opencv-python: `pip install opencv-python`
+```Python
+import stag
+import cv2
+
+# specify marker type
+libraryHD = 21
+
+# load image
+image = cv2.imread("example.jpg")
+
+# detect markers
+(corners, ids, rejected_corners) = stag.detectMarkers(image, libraryHD)
+```
+
+For a more comprehensive example refer to [example.py](https://github.com/ManfredStoiber/stag-python/blob/master/example/example.py)
 
 ## 🏷 Markers
 
-- Collection of markers: [Drive](https://drive.google.com/drive/folders/0ByNTNYCAhWbIV1RqdU9vRnd2Vnc?resourcekey=0-9ipvecbezW8EWUva5GBQTQ&usp=sharing)
-- Marker Generator: see [ref/marker generator](https://github.com/ManfredStoiber/stag/tree/master/ref/marker%20generator) for reference code for marker generation
+- Markers can be downloaded here: [Drive](https://drive.google.com/drive/folders/0ByNTNYCAhWbIV1RqdU9vRnd2Vnc?resourcekey=0-9ipvecbezW8EWUva5GBQTQ&usp=sharing)
+- Reference code for Marker Generator: [ref/marker_generator](https://github.com/ManfredStoiber/stag/tree/master/ref/marker_generator)
+
+## 🛠 Configuration
+Following parameters can be specified:
+- __`libraryHD`__:
+   - Sets the "family" or "type" of used STag markers
+      - Each library has a different amount of markers
+      - Only the markers of the chosen library will be detected
+   - The following HD libraries are possible:
 
-## 📔 Known Issues
-- Sometimes markers are detected multiple times
-    - Workaround: only use one of the detections
+        | __HD__           | 11     | 13    | 15  | 17  | 19 | 21 | 23 |
+        |------------------|--------|-------|-----|-----|----|----|----|
+        | __Library Size__ | 22,309 | 2,884 | 766 | 157 | 38 | 12 | 6  |
+
+   - Specifies the used Hamming Distance, for further information refer to the [original paper](https://arxiv.org/abs/1707.06292)
+
+
+- __`errorCorrection`__:
+   - Sets the amount of error correction
+   - Has to be in range `0 <= errorCorrection <= (libraryHD-1)/2`
+   - For further information refer to the [original paper](https://arxiv.org/abs/1707.06292)
+
+## 📋 Build From Source
+0. __Install__ Prerequisites
+
+   [__CMake__ >= 3.16](https://cmake.org/getting-started/)
+   - On Linux: `apt install cmake`
+
+   [__OpenCV__ 4](https://opencv.org/get-started/) for C++
+   - On Linux: `apt install libopencv-dev`
+   
+   __NumPy__: `pip install numpy`
+     - On Linux: if during step 2 the error `"numpy/ndarrayobject.h: No such file or directory"` occurs, try one of following solutions:
+         - Run `apt install python-numpy` or
+         - Search for "ndarrayobject.h" (`find / -name ndarrayobject.h`) and create a symlink from its parent directory to "/usr/include/numpy" (e.g. `ln -s /usr/local/lib/python3.8/dist-packages/numpy/core/include/numpy /usr/include/numpy`)
+1. __Clone__ this repository recursively:
+   - `git clone --recursive https://github.com/ManfredStoiber/stag-python`
+2. __Build__ the project
+
+   In the project directory, run the following command:
+
+   - `pip install .`
+3. __Run__ the example
+    1. `cd example`
+    2. `python example.py`
 
 ## 📰 Originally Published in the Following Paper:
 
 [B. Benligiray; C. Topal; C. Akinlar, "STag: A Stable Fiducial Marker System," Image and Vision Computing, 2019.](https://arxiv.org/abs/1707.06292)
 
-Some figures from the paper:
-
 <p align="center">
   <img src="https://user-images.githubusercontent.com/19530665/57179654-c0c11e00-6e88-11e9-9ca5-0c0153b28c91.png"/>
 </p>

StagPy.cpp

@@ -2,44 +2,17 @@
 import cv2
 import numpy as np
 
-img_path = "testimage.jpg"
-img = cv2.imread(img_path)
-img_gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
-(corners, ids) = stag.detectMarkers(img_gray)
+# load image
+image = cv2.imread("example.jpg")
 
-img_out = img
+# detect markers
+(corners, ids, rejected_corners) = stag.detectMarkers(image, 21)
 
-for bounding_box, id in zip(corners, ids):
-    bounding_box = np.round(bounding_box).astype(int)
-    green = (50, 255, 50)
-    red = (0, 0, 255)
-    white = (255, 255, 255)
+# draw detected markers with ids
+stag.drawDetectedMarkers(image, corners, ids)
 
-    center = tuple(np.round(np.mean(bounding_box, axis=0)).astype(int))
-
-    # draw white circle at top-left corner
-    img_out = cv2.circle(img_out, bounding_box[0], 6, white, -1, cv2.LINE_AA)
-    # draw white border
-    for i in range(4):
-        img_out = cv2.line(img_out, tuple(map(int, bounding_box[i])), tuple(map(int, bounding_box[(i+1)%4])), white, 3, cv2.LINE_AA)
-
-    # draw green circle at top-left corner
-    img_out = cv2.circle(img_out, bounding_box[0], 5, green, -1, cv2.LINE_AA)
-    # draw green border
-    for i in range(4):
-        img_out = cv2.line(img_out, tuple(map(int, bounding_box[i])), tuple(map(int, bounding_box[(i+1)%4])), green, 2, cv2.LINE_AA)
-
-    # draw white circle at center
-    img_out = cv2.circle(img_out, center, 6, white, -1, cv2.LINE_AA)
-    # draw green circle at center
-    img_out = cv2.circle(img_out, center, 6, green, -1, cv2.LINE_AA)
-
-    img_out = cv2.putText(img_out, f"{id}", center, cv2.FONT_HERSHEY_DUPLEX, 2, white, 5, cv2.LINE_AA)
-    img_out = cv2.putText(img_out, f"{id}", center, cv2.FONT_HERSHEY_DUPLEX, 2, red, 2, cv2.LINE_AA)
-
-
-cv2.imwrite("testimage_result.jpg", img_out)
-print("Detected Corners: ", corners)
-print("Detected Ids: ", ids)
-print("Results are visualized in testimage_result.jpg")
+# draw rejected quads without ids with different color
+stag.drawDetectedMarkers(image, rejected_corners, border_color=(255, 0, 0))
 
+# save resulting image
+cv2.imwrite("example_result.jpg", image)