Detector

matmmextract.inference.detector

Batch panel detection using a YOLO fine-tuned checkpoint (Ultralytics).

Ported from infer.py (YOLO version) — globals → parameters, callable as API.

Flow

images → run() → one JSON file per image + _summary.json in output_dir

Each per-image JSON:

{
    "meta":         { weights, conf, iou, imgsz, timestamp, id2label },
    "file":         "img123.jpg",
    "path":         "/abs/path/img123.jpg",
    "width":        W,
    "height":       H,
    "n_detections": N,
    "detections":   [
        { "bbox": [x1,y1,x2,y2], "score": 0.91,
          "label_id": 0, "label_name": "A" },
        ...
    ]
}

class DetectionResult(n_images: 'int' = 0, n_saved: 'int' = 0, output_dir: 'str' = '', failed: 'list[str]' = <factory>)

failed: list[str]

n_images: int = 0

n_saved: int = 0

output_dir: str = ''

detect(image_dir: str | Path, output_dir: str | Path, checkpoint: str | Path = 'best.pt', conf: float = 0.6, iou: float = 0.4, imgsz: int = 1024, device: str = '', id2label: dict[int, str] | None = None, write_summary: bool = True, weights_cache_dir: str | Path = '.weights_cache', verbose: bool = True) → DetectionResult

Run YOLO panel detection on every image in image_dir.

Parameters:

• image_dir – Directory of input images.

• output_dir – Directory where one .json per image is written, plus _summary.json containing all records combined.

• checkpoint – Path to a YOLO .pt file, a directory containing best.pt / last.pt, a Google Drive share URL (e.g. https://drive.google.com/file/d/<ID>/view), or a Hugging Face Hub reference — a full URL (https://huggingface.co/<user>/<repo>/resolve/main/best.pt) or a bare repo ID ("<user>/<repo>" or "<user>/<repo>:best.pt").

• weights_cache_dir – Local directory to cache downloaded weights (default .weights_cache).

• conf – Confidence threshold (default 0.6).

• iou – NMS IoU threshold (default 0.4).

• imgsz – Inference image size (default 1024).

• device – Device string: "" for auto, "cpu", "0", "0,1", etc.

• id2label – Override the default label map. If None, uses the built-in map.

• write_summary – Write _summary.json combining all records (default True).

• verbose – Print progress.

Return type:

DetectionResult

find_images(folder: str | Path) → list[str]

resolve_weights(checkpoint: str | Path, cache_dir: str | Path = '.weights_cache') → str

Resolve weights to a local .pt path.

Accepts: - A direct local .pt file path - A local directory containing best.pt / last.pt - A Google Drive share URL (downloaded and cached in cache_dir)