CircleDetector 1.1.2

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

01.02.2026: Julia Škovierová, Pavel Krsek, David Svitak

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.10+
• NumPy standard library
• OpenCV with ArUco support
• Instalation:

pip install -r requirements.txt

or better using the uv python packaging manager

uv venv
uv lock --upgrade
uv sync --dev

Instalation

Project can be installed directly trough pip

pip install CircleDetector

Usage

The CircleDetector require specification of shape it is looking for in the image.

Shape specification file

Here is json file containing the shape of an specific pad. Note that the plate abd aruco_code keys are required.

{
  "plate": {
    "type": "circle",
    "diameter": 30.0
  },
  "aruco_code": {
    "id": 5,
    "size": 5.0,
    "type": "DICT_4X4_50"
  },
  "holes": [
    {
      "type": "circle",
      "diameter": 3.0,
      "dist_from_center": 11.5,
      "angle_deg": 0.0
    },
    {
      "type": "circle",
      "diameter": 3.0,
      "dist_from_center": 11.5,
      "angle_deg": 120.0
    },
    {
      "type": "circle",
      "diameter": 3.0,
      "dist_from_center": 11.5,
      "angle_deg": 240.0
    }
  ]
}

Example

import CircleDetector

# 1. Prepare the image as np.ndarraz

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

# 2. Create Detector Instance with the shape configuration file. 
# It also help if you know the ppm of the camera that took the picture

with open("path/to/file/shape_config.json", "r") as config:
  shape_config = json.load(config)
circle_detector = CircleDetector(config=shape_config, ppm = 27.001)

# 3. Run Detection

large_circle_data = circle_detector.detect(original_image=image, refine_circles = True)

Output Format - example

List of "large circles" is output of the detector. It is list of CircleDetection dataclasses described in the typeClass.

Parameters of CircleDetection dataclass:

• 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": [2043.7399455436005, 1168.2050984495788], 
        "radius": 394.06181273076515, 
        "small_circles": [
            [1755.4770265994944, 1076.191785488278, 39.22459052417032], 
            [2262.807828140135, 962.7916276277658, 39.09135996015619], 
            [2107.1382180760556, 1456.9808042095924, 37.638359777725334]
        ], 
        "marker_center": [2388.75, 849.0], 
        "marker_id": 7, 
        "marker_corners": [
            [2298.0, 843.0], 
            [2396.0, 759.0], 
            [2479.0, 856.0], 
            [2382.0, 938.0]
        ], 
        "marker_angle": 0.7465673948230674
    }
]

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

Authors & contributions

• Julia Škovierová — Alghoritm development:
• Pavel Krsek — Alghoritm development:
• David Sviták (@DavidSvitak) — Integration and testing:
• Štěpán Venclík (@StepanVenclik) — Automatization and Integration: