Skip to main content
The detection module uses OpenCV color-based segmentation in HSV color space to identify archaeological objects in images, followed by morphological cleaning and contour extraction. 
from archeo_cluster.core.detection import ObjectDetector
from archeo_cluster.models import DetectionConfig

​
ObjectDetector

Detector for archaeological objects using color-based segmentation. 
from dataclasses import dataclass, field
from archeo_cluster.core.detection import ObjectDetector
from archeo_cluster.models import DetectionConfig

detector = ObjectDetector(
    config=DetectionConfig(target_color="#A98876", min_area=50, max_area=5000),
    save_intermediate=True,
)

​
Constructor

​
config
DetectionConfig
default:"DetectionConfig()"
Detection configuration parameters. Controls target color, area filters, morphological kernel, and HSV tolerances.
​
save_intermediate
bool
default:"True"
When True, intermediate processing images (HSV conversion, masks, contours) are stored in each DetectionResult.processing_steps dictionary.

​
detect

Detect objects in a single in-memory image. 
import cv2

image = cv2.imread("artifact.jpg")
result = detector.detect(image, image_name="artifact")
print(f"Found {result.count} objects")
Parameters
​
image
NDArray[Any]
required
Input image in BGR format as a NumPy array.
​
image_name
str
default:"image"
Name identifier used in logging and stored in the returned DetectionResult.
Returns DetectionResult

​
detect_from_path

Detect objects in an image loaded from disk. 
result = detector.detect_from_path("./data/raw/images/photo.jpg")
Parameters
​
image_path
Path | str
required
Path to the image file to process.
Returns DetectionResult

​
process_directory

Process all images in a directory and collect results in a BatchDetectionResult. 
batch = detector.process_directory(
    input_dir="./data/raw/images",
    output_dir="./output",
)
print(f"{batch.total_objects} objects in {batch.image_count} images")
Parameters
​
input_dir
Path | str
required
Directory containing input images. All supported image formats are processed.
​
output_dir
Path | str | None
default:"None"
Optional directory for saving intermediate processing images. When None and save_intermediate=True, intermediate images are stored in memory only.
Returns BatchDetectionResult

​
DetectionConfig

Pydantic model holding all detection parameters. All fields have defaults so you only need to supply values you want to change. 
from archeo_cluster.models import DetectionConfig

config = DetectionConfig(
    target_color="#A98876",
    min_area=50,
    max_area=5000,
    kernel_size=(5, 5),
    hue_offset=10,
    saturation_offset=50,
    value_offset=50,
)
​
target_color
str
default:"#A98876"
Target color in hex format (e.g. "#A98876"). The detector converts this to HSV and applies hue_offset, saturation_offset, and value_offset tolerances to produce the color range mask.
​
min_area
int
default:"50"
Minimum contour area in pixels. Contours smaller than this are discarded. Must be ≥ 1.
​
max_area
int
default:"5000"
Maximum contour area in pixels. Contours larger than this are discarded. Must be ≥ 1.
​
kernel_size
tuple[int, int]
default:"(5, 5)"
Size of the morphological operation kernel used for closing and opening passes on the mask.
​
hue_offset
int
default:"10"
Tolerance for the hue channel in HSV color matching. Range 0–90.
​
saturation_offset
int
default:"50"
Tolerance for the saturation channel in HSV color matching. Range 0–127.
​
value_offset
int
default:"50"
Tolerance for the value channel in HSV color matching. Range 0–127.

​
Return types

​
DetectionResult

Result of running detection on a single image. This is a dataclass (not a Pydantic model).
​
image_name
str
required
Name of the processed image (the file stem when loaded from disk).
​
contours
list[NDArray[Any]]
default:"[]"
List of filtered OpenCV contour arrays that passed the area constraints.
​
objects
list[DetectedObject]
default:"[]"
List of detected objects with extracted features.
​
processing_steps
dict[str, NDArray[Any]]
default:"{}"
Intermediate images keyed by step name (e.g. "01_hsv", "02_mask_initial"). Populated only when save_intermediate=True.
​
count
int
Read-only property. Number of detected objects (len(objects)).

​
BatchDetectionResult

Aggregated results from processing a directory of images. This is a dataclass.
​
results
list[DetectionResult]
default:"[]"
One DetectionResult per successfully processed image.
​
total_objects
int
Read-only property. Sum of detected objects across all images.
​
image_count
int
Read-only property. Number of images in results.

​
DetectedObject

A single detected object with its metadata and extracted features.
​
image_name
str
required
Filename of the source image.
​
contour_index
int
required
Zero-based index of this contour within the image. Must be ≥ 0.
​
features
ContourFeatures
required
Extracted geometric features for this object.

​
ContourFeatures

Features extracted from a single contour. See the expandable above for field descriptions. 
from archeo_cluster.models import ContourFeatures

features = ContourFeatures(
    area=342.5,
    perimeter=78.2,
    centroid_x=120,
    centroid_y=88,
    circularity=0.71,
    aspect_ratio=1.05,
    solidity=0.93,
    extent=0.68,
)