https://github.com/manfredstoiber/stag-python

Python Package for STag - A Stable, Occlusion-Resistant Fiducial Marker System
https://github.com/manfredstoiber/stag-python

aruco-markers augmented-reality camera-calibration fiducial-markers opencv pose-estimation python robotics

Last synced: 5 months ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/manfredstoiber/stag-python
• Owner: ManfredStoiber
• License: mit
• Created: 2023-11-20T11:01:12.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2025-06-05T16:41:34.000Z (about 1 year ago)
• Last Synced: 2025-11-27T23:36:03.653Z (7 months ago)
• Topics: aruco-markers, augmented-reality, camera-calibration, fiducial-markers, opencv, pose-estimation, python, robotics
• Language: Python
• Homepage:
• Size: 1.71 MB
• Stars: 26
• Watchers: 2
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
[![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)

![Pepy Total Downlods](https://img.shields.io/pepy/dt/stag-python)

# Python Wrapper for [STag - A Stable, Occlusion-Resistant Fiducial Marker System](https://github.com/ManfredStoiber/stag)

## 📊 Comparison Between Different Marker Systems:

[](https://www.youtube.com/watch?v=vnHI3GzLVrY)

## 📖 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`

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

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

        | __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)