CircleDetector 1.0.0

Python based detector detecting position and orientation of circular pads. This detection is based on the positions of the partial shapes (inner halls) and ArUco marker(s).

Circle & ArUco Marker Detector

28.7.2025: Julia Škovierová, Pavel Krsek

The detector was developed within the framework of the DeKrys project to estimate the position of the destination plate. The plate is a circle made of metal (copper or aluminium). There are three small holes in the plate. The small holes are evenly spaced on a circle. The plate is usually provided by an ArUco marker. The ArUco marker is placed outside the main circle of the plate on the attached small square plate. The ArUco marker identifies the plate and defines a unique coordinate system.

This Python module provides a simple class-based interface to detect circles and ArUco markers in an image using OpenCV. It returns information such as the center, perimeter, and marker ID (if available).

---

Requirements

• Python 3.7+
• NumPy standard library
• OpenCV with ArUco support
• Instalation:

pip install -r requirements.txt

Instalation

Project can be isntalled directly trough pip

pip install CircleDetector

Usage in code

import CircleDetector

# 2. Load Image (as file path or NumPy array)

image = cv2.imread("path/to/image.png")

# 3. Create Detector Instance

circle_detector = CircleDetector()

# 4. Run Detection

large_circle_data = circle_detector.detect(image, True)

Output Format - example

List of "large circles" is output of the detector. Position of each "large circle" is described by many parametrs in the dictionary.

Parameters of large circle (for each):

• center - vector defines the position of the large circle center in the image coordinate system [columns, rows].
• radius - radius of the large circle in pixels.
• small_circles - matrix of the small circle parameters. 3 small circles should be inside the large circle. Each row of the matrix corresponds to one small circle and contains the position of the center and radius in pixels in order: [columns, rows, radius].
• marker_center - vector defines position of the ArUco marker center in the image coordinate system [columns, rows].
• marker_id - the numeric ID of the ArUco marker.
• marker_corners - positions of the ArUco marker corners written in the matrix, where each row corresponds to one corner.
• marker_angle - angle in radians between row and vector defined by points: circle_center, marker_center. The coordinates are in the image coordinate system in order (in each line): [columns, rows].

Note: All the positon parameters are in pixels.

Example of the output

    [{'center': array([1924, 1402]), 
      'radius': 389, 
      'small_circles': array([[2223., 1377.,   39.],
                              [1751., 1153.,   39.],
                              [1794., 1672.,   39.]], dtype=float32), 
      'marker_center': array([2391.  , 1364.25], dtype=float32), 
      'marker_id': 7, 
      'marker_corners': array([[2325., 1303.],
                               [2452., 1296.],
                               [2457., 1427.],
                               [2330., 1431.]], dtype=float32),
      'marker_angle':  0.08065973744726256}] 

Notes

In case that the refinement option is selected, but not enough points are found to recalculate the circle, the value for the center and radius remains unchanged