README.md

Python Wrapper for STag - A Stable, Occlusion-Resistant Fiducial Marker System

📊 Comparison Between Different Marker Systems:

📖 Usage

Installation

pip install stag-python

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

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

🏷 Markers

• Markers can be downloaded here: Drive
• Reference code for Marker Generator: 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:

    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

• 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

📋 Build From Source

0. Install Prerequisites

   CMake >= 3.16

   • On Linux: apt install cmake

   OpenCV 4 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.