mblt-vision-python 0.0.0__py3-none-any.whl

mblt_vision/utils/evaluation/eval_widerface.py

@@ -0,0 +1,440 @@
+"""Evaluation script for WiderFace face detection."""
+
+from __future__ import annotations
+
+import math
+import os
+from pathlib import Path
+from time import time
+from typing import TYPE_CHECKING, Any, NamedTuple, cast
+
+import numpy as np
+from mblt_vision.utils.postprocess.base import YOLODetectionPostBase
+from scipy.io import loadmat
+from tqdm import tqdm
+
+from ..datasets import CustomWiderFaceDataset, get_widerface_loader
+from ..datasets.readiness import (
+    _load_widerface_image_names,
+    _widerface_image_shapes,
+    _widerface_difficulty_metadata_ready,
+)
+
+if TYPE_CHECKING:
+    from ...wrapper import MBLT_Engine
+
+CustomWiderface = CustomWiderFaceDataset
+
+
+class WiderFaceResult(NamedTuple):
+    """WiderFace AP metrics."""
+
+    easy_ap: float
+    medium_ap: float
+    hard_ap: float
+
+    @property
+    def mean_ap(self) -> float:
+        """Return the mean AP across Easy, Medium, and Hard."""
+
+        return (self.easy_ap + self.medium_ap + self.hard_ap) / 3.0
+
+    @property
+    def primary_score(self) -> float:
+        """Return mean AP across the three validation splits."""
+
+        return self.mean_ap
+
+    @property
+    def secondary_score(self) -> float:
+        """Return Hard-set AP."""
+
+        return self.hard_ap
+
+
+def _empty_prediction() -> np.ndarray:
+    """Return an empty WiderFace prediction array."""
+
+    return np.zeros((0, 5), dtype=np.float32)
+
+
+def _initialize_predictions(
+    dataset: CustomWiderFaceDataset,
+) -> dict[str, dict[str, np.ndarray]]:
+    """Initialize empty predictions for every WiderFace sample."""
+
+    predictions: dict[str, dict[str, np.ndarray]] = {}
+    for _, event_name, file_name in dataset.samples:
+        predictions.setdefault(event_name, {})[os.path.splitext(file_name)[0]] = (
+            _empty_prediction()
+        )
+    return predictions
+
+
+def _boxes_scores_to_prediction(
+    boxes: list[list[float]], scores: list[float]
+) -> np.ndarray:
+    """Convert xywh boxes and scores to a WiderFace prediction array."""
+
+    if len(boxes) != len(scores):
+        raise ValueError(
+            "WiderFace postprocess returned unequal box and score counts: "
+            f"boxes={len(boxes)}, scores={len(scores)}."
+        )
+    if not boxes:
+        return _empty_prediction()
+    prediction = np.zeros((len(boxes), 5), dtype=np.float32)
+    for index, (box, score) in enumerate(zip(boxes, scores)):
+        prediction[index, :4] = np.asarray(box, dtype=np.float32)
+        prediction[index, 4] = float(score)
+    return prediction
+
+
+def eval_widerface(
+    model: MBLT_Engine,
+    data_path: str,
+    batch_size: int,
+    conf_thres: float | None = None,
+    iou_thres: float | None = None,
+) -> WiderFaceResult:
+    """Evaluate a face-detection model on WiderFace validation data.
+
+    Args:
+        model: The face-detection engine to evaluate.
+        data_path: Organized WiderFace dataset root.
+        batch_size: Validation batch size.
+        conf_thres: Optional confidence threshold override.
+        iou_thres: Optional IoU threshold override.
+
+    Returns:
+        WiderFace Easy, Medium, and Hard AP metrics.
+    """
+
+    if model.post_cfg["task"] != "face_detection":
+        raise NotImplementedError(
+            f"Task {model.post_cfg['task']} is not supported for WiderFace evaluation."
+        )
+    dataset_name = model.post_cfg.get("dataset")
+    if not isinstance(dataset_name, str) or dataset_name.lower() != "widerface":
+        raise ValueError(
+            "WiderFace evaluation requires model post_cfg.dataset to be 'widerface', "
+            f"got {dataset_name!r}."
+        )
+
+    dataset_root = Path(data_path)
+    expected_images = _load_widerface_image_names(dataset_root / "wider_face_val.mat")
+    image_shapes = (
+        _widerface_image_shapes(dataset_root, expected_images)
+        if expected_images is not None
+        else None
+    )
+    if (
+        expected_images is None
+        or image_shapes is None
+        or not _widerface_difficulty_metadata_ready(
+            dataset_root, expected_images, image_shapes=image_shapes
+        )
+    ):
+        raise ValueError(
+            "WiderFace evaluation metadata is malformed or has inconsistent difficulty indices."
+        )
+
+    dataset = CustomWiderface(os.path.join(data_path, "images"))
+    actual_images: dict[str, set[str]] = {}
+    for _, event_name, file_name in dataset.samples:
+        actual_images.setdefault(event_name, set()).add(file_name)
+    if actual_images != expected_images or sum(
+        len(file_names) for file_names in actual_images.values()
+    ) != len(dataset.samples):
+        raise ValueError(
+            "WiderFace image tree does not match the validation metadata identities."
+        )
+    dataloader = get_widerface_loader(
+        dataset, batch_size, model.preprocess_with_metadata
+    )
+    model.set_postprocess_thresholds(conf_thres=conf_thres, iou_thres=iou_thres)
+
+    predictions = _initialize_predictions(dataset)
+    num_data = len(dataset)
+    total_iter = math.ceil(num_data / batch_size)
+    pbar = tqdm(dataloader, total=total_iter, desc="Evaluating WiderFace")
+    inference_time = 0.0
+    cum_num_data = 0
+
+    for input_npu, org_shape, ratio_pad, target_classes, fnames in pbar:
+        cum_num_data += len(fnames)
+        tic = time()
+        out_npu = model(input_npu)
+        inference_time += time() - tic
+        nms_outs = model.postprocess(out_npu)
+        input_shape = (int(input_npu.shape[1]), int(input_npu.shape[2]))
+        img0_shapes = [(int(shape[0]), int(shape[1])) for shape in org_shape.tolist()]
+        postprocessor = cast(YOLODetectionPostBase, model.postprocessor)
+        _, boxes_list, scores_list = postprocessor.nmsout2eval(
+            nms_outs.output,
+            input_shape,
+            img0_shapes,
+            ratio_pad=ratio_pad,
+        )
+        batch_lengths = {
+            "input batch": int(input_npu.shape[0]),
+            "original shapes": len(org_shape),
+            "ratio pads": len(ratio_pad),
+            "target classes": len(target_classes),
+            "file names": len(fnames),
+            "boxes": len(boxes_list),
+            "scores": len(scores_list),
+        }
+        if len(set(batch_lengths.values())) != 1:
+            details = ", ".join(
+                f"{name}={length}" for name, length in batch_lengths.items()
+            )
+            raise ValueError(f"WiderFace evaluation batch length mismatch: {details}.")
+
+        for event_name, file_name, boxes, scores in zip(
+            target_classes, fnames, boxes_list, scores_list, strict=True
+        ):
+            predictions[event_name][os.path.splitext(file_name)[0]] = (
+                _boxes_scores_to_prediction(boxes, scores)
+            )
+
+        pbar.set_postfix_str(f"NPU FPS: {cum_num_data / inference_time:.3f}")
+
+    pbar.close()
+    aps = evaluation(norm_score(predictions), data_path)
+    print("WiderFace evaluation completed")
+    return WiderFaceResult(*aps)
+
+
+def bbox_overlaps(boxes: np.ndarray, query_boxes: np.ndarray) -> np.ndarray:
+    """Compute pairwise IoU overlaps between boxes and query boxes."""
+
+    boxes = boxes.astype(np.float32)
+    query_boxes = query_boxes.astype(np.float32)
+
+    boxes = boxes[:, None, :]
+    query_boxes = query_boxes[None, :, :]
+
+    iw = (
+        np.minimum(boxes[..., 2], query_boxes[..., 2])
+        - np.maximum(boxes[..., 0], query_boxes[..., 0])
+        + 1
+    )
+    ih = (
+        np.minimum(boxes[..., 3], query_boxes[..., 3])
+        - np.maximum(boxes[..., 1], query_boxes[..., 1])
+        + 1
+    )
+    iw = np.maximum(iw, 0)
+    ih = np.maximum(ih, 0)
+    inter = iw * ih
+
+    box_area = (boxes[..., 2] - boxes[..., 0] + 1) * (boxes[..., 3] - boxes[..., 1] + 1)
+    query_area = (query_boxes[..., 2] - query_boxes[..., 0] + 1) * (
+        query_boxes[..., 3] - query_boxes[..., 1] + 1
+    )
+    union = box_area + query_area - inter
+
+    return inter / union
+
+
+def get_gt_boxes(gt_dir: str) -> tuple[Any, ...]:
+    """Load WiderFace evaluation `.mat` files from the organized dataset."""
+
+    gt_mat = loadmat(os.path.join(gt_dir, "wider_face_val.mat"))
+    hard_mat = loadmat(os.path.join(gt_dir, "wider_hard_val.mat"))
+    medium_mat = loadmat(os.path.join(gt_dir, "wider_medium_val.mat"))
+    easy_mat = loadmat(os.path.join(gt_dir, "wider_easy_val.mat"))
+
+    facebox_list = gt_mat["face_bbx_list"]
+    event_list = gt_mat["event_list"]
+    file_list = gt_mat["file_list"]
+    hard_gt_list = hard_mat["gt_list"]
+    medium_gt_list = medium_mat["gt_list"]
+    easy_gt_list = easy_mat["gt_list"]
+
+    return (
+        facebox_list,
+        event_list,
+        file_list,
+        hard_gt_list,
+        medium_gt_list,
+        easy_gt_list,
+    )
+
+
+def norm_score(pred: dict[str, Any]) -> dict[str, Any]:
+    """Normalize WiderFace prediction scores to ``[0, 1]``."""
+
+    max_score = -1e9
+    min_score = 1e9
+    found = False
+
+    for _, event_predictions in pred.items():
+        for _, image_predictions in event_predictions.items():
+            if len(image_predictions) == 0:
+                continue
+            found = True
+            _min = float(np.min(image_predictions[:, -1]))
+            _max = float(np.max(image_predictions[:, -1]))
+            if _max > max_score:
+                max_score = _max
+            if _min < min_score:
+                min_score = _min
+
+    if not found:
+        return pred
+
+    diff = max_score - min_score
+    if diff <= 0:
+        return pred
+
+    for _, event_predictions in pred.items():
+        for _, image_predictions in event_predictions.items():
+            if len(image_predictions) == 0:
+                continue
+            image_predictions[:, -1] = (image_predictions[:, -1] - min_score) / diff
+
+    return pred
+
+
+def image_eval(
+    pred: np.ndarray, gt: np.ndarray, ignore: np.ndarray, iou_thresh: float
+) -> tuple[np.ndarray, np.ndarray]:
+    """Evaluate one image worth of WiderFace predictions."""
+
+    _pred = pred.copy()
+    _gt = gt.copy()
+    pred_recall = np.zeros(_pred.shape[0])
+    recall_list = np.zeros(_gt.shape[0])
+    proposal_list = np.ones(_pred.shape[0])
+
+    _pred[:, 2] = _pred[:, 2] + _pred[:, 0]
+    _pred[:, 3] = _pred[:, 3] + _pred[:, 1]
+    _gt[:, 2] = _gt[:, 2] + _gt[:, 0]
+    _gt[:, 3] = _gt[:, 3] + _gt[:, 1]
+
+    overlaps = bbox_overlaps(_pred[:, :4], _gt)
+
+    for prediction_index in range(_pred.shape[0]):
+        gt_overlap = overlaps[prediction_index]
+        max_overlap = np.max(gt_overlap)
+        max_idx = np.argmax(gt_overlap)
+        if max_overlap >= iou_thresh:
+            if ignore[max_idx] == 0:
+                recall_list[max_idx] = -1
+                proposal_list[prediction_index] = -1
+            elif recall_list[max_idx] == 0:
+                recall_list[max_idx] = 1
+
+        r_keep_index = np.where(recall_list == 1)[0]
+        pred_recall[prediction_index] = len(r_keep_index)
+    return pred_recall, proposal_list
+
+
+def img_pr_info(
+    thresh_num: int,
+    pred_info: np.ndarray,
+    proposal_list: np.ndarray,
+    pred_recall: np.ndarray,
+) -> np.ndarray:
+    """Compute precision and recall contributions for one image."""
+
+    pr_info = np.zeros((thresh_num, 2), dtype=np.float32)
+    for threshold_index in range(thresh_num):
+        thresh = 1 - (threshold_index + 1) / thresh_num
+        recall_index = np.where(pred_info[:, 4] >= thresh)[0]
+        if len(recall_index) == 0:
+            pr_info[threshold_index, 0] = 0
+            pr_info[threshold_index, 1] = 0
+        else:
+            last_index = recall_index[-1]
+            proposal_index = np.where(proposal_list[: last_index + 1] == 1)[0]
+            pr_info[threshold_index, 0] = len(proposal_index)
+            pr_info[threshold_index, 1] = pred_recall[last_index]
+    return pr_info
+
+
+def dataset_pr_info(
+    thresh_num: int, pr_curve: np.ndarray, count_face: int
+) -> np.ndarray:
+    """Normalize a WiderFace precision-recall accumulator."""
+
+    _pr_curve = np.zeros((thresh_num, 2), dtype=np.float32)
+    for threshold_index in range(thresh_num):
+        proposals = pr_curve[threshold_index, 0]
+        matched = pr_curve[threshold_index, 1]
+        _pr_curve[threshold_index, 0] = matched / proposals if proposals > 0 else 0.0
+        _pr_curve[threshold_index, 1] = matched / count_face if count_face > 0 else 0.0
+    return _pr_curve
+
+
+def voc_ap(rec: np.ndarray, prec: np.ndarray) -> float:
+    """Compute VOC-style average precision."""
+
+    mrec = np.concatenate((np.array([0.0]), rec, np.array([1.0])))
+    mpre = np.concatenate((np.array([0.0]), prec, np.array([0.0])))
+
+    for index in range(mpre.size - 1, 0, -1):
+        mpre[index - 1] = np.maximum(mpre[index - 1], mpre[index])
+
+    recall_change_index = np.where(mrec[1:] != mrec[:-1])[0]
+    ap = np.sum(
+        (mrec[recall_change_index + 1] - mrec[recall_change_index])
+        * mpre[recall_change_index + 1]
+    )
+    return float(ap)
+
+
+def evaluation(
+    pred: dict[str, Any], gt_path: str, iou_thresh: float = 0.5
+) -> list[float]:
+    """Evaluate WiderFace predictions against Easy, Medium, and Hard settings."""
+
+    facebox_list, event_list, file_list, hard_gt_list, medium_gt_list, easy_gt_list = (
+        get_gt_boxes(gt_path)
+    )
+    event_num = len(event_list)
+    thresh_num = 1000
+    settings = ["easy", "medium", "hard"]
+    setting_gts = [easy_gt_list, medium_gt_list, hard_gt_list]
+    aps = []
+    for setting_id in range(3):
+        gt_list = setting_gts[setting_id]
+        count_face = 0
+        pr_curve = np.zeros((thresh_num, 2), dtype=np.float32)
+        pbar = tqdm(range(event_num))
+        for event_index in pbar:
+            pbar.set_description(f"Processing {settings[setting_id]}")
+            event_name = str(event_list[event_index][0][0])
+            img_list = file_list[event_index][0]
+            pred_list = pred[event_name]
+            sub_gt_list = gt_list[event_index][0]
+            gt_bbx_list = facebox_list[event_index][0]
+            for image_index, img_info in enumerate(img_list):
+                pred_info = pred_list[str(img_info[0][0])]
+                gt_boxes = np.array(gt_bbx_list[image_index][0], dtype=np.float32)
+                keep_index = np.array(sub_gt_list[image_index][0], dtype=np.int64)
+                count_face += len(keep_index)
+
+                if len(gt_boxes) == 0 or len(pred_info) == 0:
+                    continue
+                ignore = np.zeros(gt_boxes.shape[0])
+                if len(keep_index) != 0:
+                    ignore[keep_index - 1] = 1
+                pred_recall, proposal_list = image_eval(
+                    pred_info, gt_boxes, ignore, iou_thresh
+                )
+                pr_curve += img_pr_info(
+                    thresh_num, pred_info, proposal_list, pred_recall
+                )
+        pbar.close()
+        pr_curve = dataset_pr_info(thresh_num, pr_curve, count_face)
+        aps.append(voc_ap(pr_curve[:, 1], pr_curve[:, 0]))
+
+    print("==================== Results ====================")
+    print(f"Easy   Val AP: {aps[0]}")
+    print(f"Medium Val AP: {aps[1]}")
+    print(f"Hard   Val AP: {aps[2]}")
+    print("=================================================")
+    return aps

mblt_vision/utils/letterbox.py

@@ -0,0 +1,118 @@
+"""Shared forward and inverse geometry for aspect-preserving letterboxing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypeAlias
+
+RatioPad: TypeAlias = tuple[tuple[float, float], tuple[float, float]]
+
+
+@dataclass(frozen=True)
+class LetterBoxGeometry:
+    """Geometry shared by letterbox preprocessing and output restoration."""
+
+    input_shape: tuple[int, int]
+    original_shape: tuple[int, int]
+    ratio: float
+    resized_shape: tuple[int, int]
+    pad: tuple[int, int]
+
+    @classmethod
+    def from_shapes(
+        cls,
+        input_shape: tuple[int, int],
+        original_shape: tuple[int, int],
+    ) -> LetterBoxGeometry:
+        """Calculate YOLO-style centered letterbox geometry.
+
+        Args:
+            input_shape: Target shape as ``(height, width)``.
+            original_shape: Source shape as ``(height, width)``.
+
+        Returns:
+            Calculated resize ratio, resized shape, and top-left padding.
+        """
+
+        input_height, input_width = input_shape
+        original_height, original_width = original_shape
+        ratio = min(input_height / original_height, input_width / original_width)
+        resized_height = int(round(original_height * ratio))
+        resized_width = int(round(original_width * ratio))
+        left = int(round((input_width - resized_width) / 2 - 0.1))
+        top = int(round((input_height - resized_height) / 2 - 0.1))
+        return cls(
+            input_shape=input_shape,
+            original_shape=original_shape,
+            ratio=ratio,
+            resized_shape=(resized_height, resized_width),
+            pad=(left, top),
+        )
+
+    @property
+    def ratio_pad(self) -> RatioPad:
+        """Return metadata consumed by inverse letterbox operations."""
+
+        return ((self.ratio, self.ratio), self.pad)
+
+    @property
+    def borders(self) -> tuple[int, int, int, int]:
+        """Return OpenCV border widths as ``(top, bottom, left, right)``."""
+
+        input_height, input_width = self.input_shape
+        resized_height, resized_width = self.resized_shape
+        left, top = self.pad
+        return (
+            top,
+            input_height - resized_height - top,
+            left,
+            input_width - resized_width - left,
+        )
+
+    def crop_bounds(
+        self,
+        output_shape: tuple[int, int],
+        pad: tuple[float, float] | None = None,
+    ) -> tuple[int, int, int, int]:
+        """Scale inverse-letterbox crop bounds to a dense output shape.
+
+        Args:
+            output_shape: Dense output shape as ``(height, width)``.
+            pad: Optional exact top-left padding metadata as ``(x, y)``.
+
+        Returns:
+            Crop bounds as ``(top, bottom, left, right)``.
+        """
+
+        output_height, output_width = output_shape
+        input_height, input_width = self.input_shape
+        scale_x = output_width / input_width
+        scale_y = output_height / input_height
+        pad_x, pad_y = self.pad if pad is None else pad
+        left = int(round(pad_x * scale_x))
+        top = int(round(pad_y * scale_y))
+        resized_height, resized_width = self.resized_shape
+        right = left + int(round(resized_width * scale_x))
+        bottom = top + int(round(resized_height * scale_y))
+        return top, bottom, left, right
+
+
+def resolve_ratio_pad(
+    input_shape: tuple[int, int],
+    original_shape: tuple[int, int],
+    ratio_pad: RatioPad | None = None,
+) -> RatioPad:
+    """Return supplied letterbox metadata or derive it from image shapes.
+
+    Args:
+        input_shape: Letterboxed shape as ``(height, width)``.
+        original_shape: Source shape as ``(height, width)``.
+        ratio_pad: Optional metadata recorded during preprocessing.
+
+    Returns:
+        Resize ratios and top-left padding as ``((ratio_x, ratio_y), (pad_x, pad_y))``.
+    """
+
+    if ratio_pad is not None:
+        return ratio_pad
+    return LetterBoxGeometry.from_shapes(input_shape, original_shape).ratio_pad

mblt_vision/utils/postprocess/__init__.py

@@ -0,0 +1,9 @@
+"""
+Postprocessing utilities for vision models.
+"""
+
+from .build_post import build_postprocess
+from .depth_post import DepthPost
+from .semantic_seg_post import SemanticSegPost
+
+__all__ = ["DepthPost", "SemanticSegPost", "build_postprocess"]

mblt_vision/utils/postprocess/_letterbox.py

@@ -0,0 +1,102 @@
+"""Private helpers shared by dense prediction postprocessors."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+import torch
+
+from ..letterbox import LetterBoxGeometry, RatioPad, resolve_ratio_pad
+from .common import normalize_ratio_pads
+
+
+def get_letterbox_input_shape(
+    pre_cfg: dict[str, Any],
+    requirement_name: str,
+    size_name: str | None = None,
+) -> tuple[int, int]:
+    """Validate and return a dense task's configured letterbox input shape.
+
+    Args:
+        pre_cfg: Model preprocessing configuration.
+        requirement_name: Task name used when LetterBox is absent.
+        size_name: Optional shorter name used for invalid-size errors.
+
+    Returns:
+        Configured input height and width.
+
+    Raises:
+        ValueError: If LetterBox or its two-item image size is missing or invalid.
+    """
+
+    letterbox_cfg = pre_cfg.get("LetterBox")
+    if not isinstance(letterbox_cfg, dict) or "img_size" not in letterbox_cfg:
+        raise ValueError(
+            f"{requirement_name} requires a LetterBox configuration in pre_cfg."
+        )
+    image_size = letterbox_cfg["img_size"]
+    if not isinstance(image_size, list) or len(image_size) != 2:
+        raise ValueError(
+            f"{size_name or requirement_name} LetterBox img_size must be a two-item [height, width] list."
+        )
+    return int(image_size[0]), int(image_size[1])
+
+
+def resolve_ratio_pads(
+    ratio_pad: RatioPad | Sequence[RatioPad | None] | None,
+    batch_size: int,
+    shapes: Sequence[tuple[int, int]],
+    input_shape: tuple[int, int],
+) -> list[RatioPad]:
+    """Normalize letterbox metadata and derive values missing from a dense task batch.
+
+    Args:
+        ratio_pad: Shared or per-image letterbox metadata.
+        batch_size: Number of images in the output batch.
+        shapes: Original image shapes.
+        input_shape: Configured model input shape.
+
+    Returns:
+        One resolved ratio/padding pair per batch item.
+
+    Raises:
+        ValueError: If ratio/padding metadata is invalid for the batch.
+    """
+
+    pads = normalize_ratio_pads(ratio_pad, batch_size)
+    return [
+        resolve_ratio_pad(input_shape, shape, pad) for pad, shape in zip(pads, shapes)
+    ]
+
+
+def crop_letterbox(
+    output: torch.Tensor,
+    shape: tuple[int, int],
+    ratio_pad: RatioPad,
+    input_shape: tuple[int, int],
+    task_name: str,
+) -> torch.Tensor:
+    """Crop letterbox padding from a dense two-dimensional output.
+
+    Args:
+        output: Dense two-dimensional model output.
+        shape: Original image height and width.
+        ratio_pad: Resize ratio and padding applied during preprocessing.
+        input_shape: Configured model input height and width.
+        task_name: Task label used in validation errors.
+
+    Returns:
+        Output with letterbox padding removed.
+
+    Raises:
+        ValueError: If inverse letterboxing produces an empty crop.
+    """
+
+    geometry = LetterBoxGeometry.from_shapes(input_shape, shape)
+    output_shape = (int(output.shape[0]), int(output.shape[1]))
+    top, bottom, left, right = geometry.crop_bounds(output_shape, pad=ratio_pad[1])
+    cropped = output[top:bottom, left:right]
+    if cropped.numel() == 0:
+        raise ValueError(f"{task_name} letterbox restoration produced an empty crop.")
+    return cropped