jomade / stag

STag: A Stable, Occlusion-Resistant Fiducial Marker System

STag - A Stable, Occlusion-Resistant Fiducial Marker System

This repository is an improved and updated fork of the stable fiducial marker system, using OpenCV 4.

Note

For the corresponding Python package, refer to: https://github.com/ManfredStoiber/stag-python.

📊 Comparison Between Different Marker Systems:

📖 Usage

// load image
cv::Mat image = cv::imread("example.jpg");

// set HD library
int libraryHD = 21;

auto corners = std::vector<std::vector<cv::Point2f>>();
auto ids = std::vector<int>();
auto rejectedImgPoints = std::vector<std::vector<cv::Point2f>>(); // optional, helpful for debugging

// detect markers
stag::detectMarkers(image, libraryHD, corners, ids, rejectedImgPoints);

// draw and save results
stag::drawDetectedMarkers(image, corners, ids);
cv::imwrite("example_result.jpg", image);

For an explanation of libraryHD = 21 refer to Configuration

🏷 Markers

• Markers are downloadable here: Drive
• Reference code for Marker Generator: ref/marker_generator

📋 Getting Started

0. Install Prerequisites

   CMake >= 3.16

   • On Linux: apt install cmake

   OpenCV 4 for C++

   • On Linux: apt install libopencv-dev

1. Clone this repository

   • git clone https://github.com/ManfredStoiber/stag

2. Build the project.

   In the project directory, run the following commands:

   1. mkdir build
   2. cd build
   3. cmake ..
   4. cmake --build .

3. Run the example

   • On Linux: Run ./stag_example
   • On Windows: Run stag_example.exe

   This example application detects the markers in ../example.jpg and saves the visualized results to example_result.jpg

Note

The library is created as static by default. If you want to create a shared library instead, use the cmake option BUILD_SHARED_LIBS=ON.

🛠 Configuration

When initializing the library, 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

📰 Originally Published in the Following Paper:

B. Benligiray; C. Topal; C. Akinlar, "STag: A Stable Fiducial Marker System," Image and Vision Computing, 2019.