Metadata-Version: 2.4
Name: CircleDetector
Version: 1.0.0
Summary: 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). 
Author-email: Julia Škovierová <Julia.Skovierova@cvut.cz>, Pavel Krsek <pavel.krsek@cvut.cz>
License: MIT
        
        Copyright (c) 2024
        Julia Škovierová, Pavel Krsek
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: opencv-contrib-python
Requires-Dist: matplotlib
Dynamic: license-file

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

```bash
pip install -r requirements.txt
```

## Instalation

Project can be isntalled directly trough pip  
```bash
pip install CircleDetector
```

## Usage in code

```python
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
        
```python        
    [{'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

 
