x4d-devkit 0.1.0__py3-none-any.whl

x4d_devkit/eval/detection.py

@@ -0,0 +1,350 @@
+"""3D object detection evaluation: mAP, TP metrics, NDS.
+
+The evaluator is **not** tied to any fixed set of categories.
+All class names, distance ranges, and category mappings are injected
+via ``DetectionConfig``.  Two ready-made presets are provided:
+
+* ``nusc_detection_config()`` — nuScenes CVPR 2019 (10 classes)
+* ``detzero_detection_config()`` — DetZero 3-class (Vehicle / Pedestrian / Cyclist)
+
+Users can create their own ``DetectionConfig`` for any category set.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from x4d_devkit.eval.matching import MetricData, accumulate
+from x4d_devkit.eval.metrics import center_distance
+
+if TYPE_CHECKING:
+    from x4d_devkit.core.loader import ClipLoader
+
+TP_METRICS = ["trans_err", "scale_err", "orient_err", "vel_err", "attr_err"]
+
+# ── Presets (convenience constants, NOT used by the evaluator directly) ──
+
+NUSC_DETECTION_NAMES = [
+    "car", "truck", "bus", "trailer", "construction_vehicle",
+    "pedestrian", "motorcycle", "bicycle", "traffic_cone", "barrier",
+]
+
+NUSC_CLASS_RANGE = {
+    "car": 50, "truck": 50, "bus": 50, "trailer": 50,
+    "construction_vehicle": 50, "pedestrian": 40, "motorcycle": 40,
+    "bicycle": 40, "traffic_cone": 30, "barrier": 30,
+}
+
+NUSC_CATEGORY_MAP: dict[str, str] = {
+    "vehicle.car": "car",
+    "vehicle.truck": "truck",
+    "vehicle.bus.bendy": "bus",
+    "vehicle.bus.rigid": "bus",
+    "vehicle.trailer": "trailer",
+    "vehicle.construction": "construction_vehicle",
+    "human.pedestrian.adult": "pedestrian",
+    "human.pedestrian.child": "pedestrian",
+    "human.pedestrian.wheelchair": "pedestrian",
+    "human.pedestrian.stroller": "pedestrian",
+    "human.pedestrian.personal_mobility": "pedestrian",
+    "human.pedestrian.police_officer": "pedestrian",
+    "human.pedestrian.construction_worker": "pedestrian",
+    "vehicle.motorcycle": "motorcycle",
+    "vehicle.bicycle": "bicycle",
+    "movable_object.trafficcone": "traffic_cone",
+    "movable_object.barrier": "barrier",
+}
+
+DETZERO_DETECTION_NAMES = ["Vehicle", "Pedestrian", "Cyclist"]
+
+DETZERO_CLASS_RANGE = {
+    "Vehicle": 75, "Pedestrian": 50, "Cyclist": 50,
+}
+
+DETZERO_CATEGORY_MAP: dict[str, str] = {
+    # nuScenes full names → DetZero classes
+    "vehicle.car": "Vehicle",
+    "vehicle.truck": "Vehicle",
+    "vehicle.bus.bendy": "Vehicle",
+    "vehicle.bus.rigid": "Vehicle",
+    "vehicle.trailer": "Vehicle",
+    "vehicle.construction": "Vehicle",
+    "human.pedestrian.adult": "Pedestrian",
+    "human.pedestrian.child": "Pedestrian",
+    "human.pedestrian.wheelchair": "Pedestrian",
+    "human.pedestrian.stroller": "Pedestrian",
+    "human.pedestrian.personal_mobility": "Pedestrian",
+    "human.pedestrian.police_officer": "Pedestrian",
+    "human.pedestrian.construction_worker": "Pedestrian",
+    "vehicle.motorcycle": "Cyclist",
+    "vehicle.bicycle": "Cyclist",
+    # Short names
+    "car": "Vehicle", "truck": "Vehicle", "bus": "Vehicle",
+    "trailer": "Vehicle", "construction_vehicle": "Vehicle",
+    "pedestrian": "Pedestrian",
+    "motorcycle": "Cyclist", "bicycle": "Cyclist",
+}
+
+# Backwards-compatible aliases
+DETECTION_NAMES = NUSC_DETECTION_NAMES
+CLASS_RANGE = NUSC_CLASS_RANGE
+CATEGORY_MAP = NUSC_CATEGORY_MAP
+
+
+def map_category(
+    raw_category: str,
+    category_map: dict[str, str] | None = None,
+    class_names: list[str] | None = None,
+) -> str | None:
+    """Map a raw annotation category to a detection class name.
+
+    Args:
+        raw_category: The raw category string from the annotation.
+        category_map: Mapping from raw names to detection class names.
+            Falls back to ``NUSC_CATEGORY_MAP`` if *None*.
+        class_names: Set of valid detection class names.
+            If the raw category is already a valid class name, it is
+            returned as-is.  Falls back to ``NUSC_DETECTION_NAMES``
+            if *None*.
+
+    Returns:
+        Detection class name, or *None* if unrecognized.
+    """
+    if category_map is None:
+        category_map = NUSC_CATEGORY_MAP
+    if class_names is None:
+        class_names = NUSC_DETECTION_NAMES
+
+    if raw_category in category_map:
+        return category_map[raw_category]
+    if raw_category in class_names:
+        return raw_category
+    return None
+
+
+@dataclass(frozen=True)
+class DetectionConfig:
+    """Evaluation configuration — fully user-controlled.
+
+    All fields (class names, distance ranges, category mapping) are
+    injected here.  Nothing is hardcoded in the evaluator.
+    """
+    class_names: list[str]
+    dist_thresholds: list[float]
+    dist_th_tp: float
+    min_recall: float
+    min_precision: float
+    max_boxes_per_sample: int
+    class_range: dict[str, float]
+    category_map: dict[str, str] = field(default_factory=dict)
+    num_recall_points: int = 101
+    mean_ap_weight: int = 5
+
+
+def nusc_detection_config() -> DetectionConfig:
+    """Return nuScenes CVPR2019 standard detection evaluation config (10 classes)."""
+    return DetectionConfig(
+        class_names=list(NUSC_DETECTION_NAMES),
+        dist_thresholds=[0.5, 1.0, 2.0, 4.0],
+        dist_th_tp=2.0,
+        min_recall=0.1,
+        min_precision=0.1,
+        max_boxes_per_sample=500,
+        class_range=dict(NUSC_CLASS_RANGE),
+        category_map=dict(NUSC_CATEGORY_MAP),
+    )
+
+
+def detzero_detection_config() -> DetectionConfig:
+    """Return DetZero 3-class detection evaluation config."""
+    return DetectionConfig(
+        class_names=list(DETZERO_DETECTION_NAMES),
+        dist_thresholds=[0.5, 1.0, 2.0, 4.0],
+        dist_th_tp=2.0,
+        min_recall=0.1,
+        min_precision=0.1,
+        max_boxes_per_sample=500,
+        class_range=dict(DETZERO_CLASS_RANGE),
+        category_map=dict(DETZERO_CATEGORY_MAP),
+    )
+
+
+@dataclass
+class DetectionResult:
+    mean_ap: float
+    nd_score: float
+    label_aps: dict[str, dict[str, float]]
+    mean_dist_aps: dict[str, float]
+    tp_errors: dict[str, float]
+    label_tp_errors: dict[str, dict[str, float]]
+    tp_scores: dict[str, float]
+
+
+def _calc_ap(md: MetricData, min_recall: float, min_precision: float) -> float:
+    """Calculate Average Precision from MetricData."""
+    prec = np.copy(md.precision)
+    prec = prec[round(100 * min_recall) + 1:]
+    prec -= min_precision
+    prec[prec < 0] = 0
+    if len(prec) == 0:
+        return 0.0
+    return float(np.mean(prec) / (1.0 - min_precision))
+
+
+def _calc_tp(md: MetricData, min_recall: float, metric_name: str) -> float:
+    """Calculate mean TP metric between min_recall and max_recall."""
+    first_ind = round(100 * min_recall) + 1
+    last_ind = md.max_recall_ind
+    if last_ind < first_ind:
+        return 1.0
+    metric_arr = getattr(md, metric_name)
+    return float(np.nanmean(metric_arr[first_ind:last_ind + 1]))
+
+
+def _extract_boxes(
+    clip: ClipLoader,
+    config: DetectionConfig,
+    max_boxes: int | None = None,
+) -> dict[str, list[dict]]:
+    """Extract annotation boxes grouped by sample_token, with distance filtering."""
+    ep_by_token = {ep.token: ep for ep in clip.ego_poses}
+    category_map = config.category_map or {}
+    class_names = config.class_names
+    class_range = config.class_range
+
+    # Map sample_token → ego position (for distance filtering)
+    sample_ego_pos: dict[str, np.ndarray] = {}
+    for sd in clip.sample_data:
+        if sd.sample_token not in sample_ego_pos and sd.is_keyframe:
+            ep = ep_by_token.get(sd.ego_pose_token)
+            if ep is not None:
+                sample_ego_pos[sd.sample_token] = ep.translation
+
+    result: dict[str, list[dict]] = {}
+    for sample in clip.samples:
+        ego_pos = sample_ego_pos.get(sample.token)
+        anns = clip.annotations_for_sample(sample.token)
+        boxes = []
+        for ann in anns:
+            det_name = map_category(ann.category, category_map, class_names)
+            if det_name is None or det_name not in class_range:
+                continue
+            if ego_pos is not None:
+                dist = float(np.linalg.norm(ann.translation[:2] - ego_pos[:2]))
+                if dist > class_range[det_name]:
+                    continue
+            boxes.append({
+                "translation": ann.translation,
+                "size": ann.size,
+                "rotation": ann.rotation,
+                "category": det_name,
+                "score": ann.score,
+                "velocity": ann.velocity,
+                "attributes": ann.attributes,
+            })
+
+        if max_boxes is not None and len(boxes) > max_boxes:
+            boxes.sort(key=lambda b: b["score"] or 0, reverse=True)
+            boxes = boxes[:max_boxes]
+
+        result[sample.token] = boxes
+
+    return result
+
+
+class DetectionEval:
+    """3D object detection evaluator."""
+
+    def __init__(
+        self,
+        gt_clips: list[ClipLoader],
+        pred_clips: list[ClipLoader],
+        config: DetectionConfig | None = None,
+    ) -> None:
+        self._gt_clips = gt_clips
+        self._pred_clips = pred_clips
+        self._config = config or nusc_detection_config()
+
+    def evaluate(self) -> DetectionResult:
+        cfg = self._config
+
+        gt_by_id = {c.meta.clip_id: c for c in self._gt_clips}
+        pred_by_id = {c.meta.clip_id: c for c in self._pred_clips}
+
+        all_gt: dict[str, list[dict]] = {}
+        all_pred: dict[str, list[dict]] = {}
+
+        for clip_id, gt_clip in gt_by_id.items():
+            gt_boxes = _extract_boxes(gt_clip, cfg)
+            for st, boxes in gt_boxes.items():
+                all_gt[st] = boxes
+
+            pred_clip = pred_by_id.get(clip_id)
+            if pred_clip is not None:
+                pred_boxes = _extract_boxes(pred_clip, cfg, max_boxes=cfg.max_boxes_per_sample)
+                for st, boxes in pred_boxes.items():
+                    all_pred[st] = boxes
+
+        for st in all_gt:
+            if st not in all_pred:
+                all_pred[st] = []
+
+        # Accumulate per class per distance threshold
+        metric_data: dict[str, dict[str, MetricData]] = {}
+        for class_name in cfg.class_names:
+            metric_data[class_name] = {}
+            for dist_th in cfg.dist_thresholds:
+                metric_data[class_name][str(dist_th)] = accumulate(
+                    all_gt, all_pred, class_name, dist_th
+                )
+
+        # AP per class per threshold
+        label_aps: dict[str, dict[str, float]] = {}
+        for class_name in cfg.class_names:
+            label_aps[class_name] = {}
+            for dist_th in cfg.dist_thresholds:
+                md = metric_data[class_name][str(dist_th)]
+                label_aps[class_name][str(dist_th)] = _calc_ap(md, cfg.min_recall, cfg.min_precision)
+
+        mean_dist_aps = {
+            cn: float(np.mean(list(label_aps[cn].values())))
+            for cn in cfg.class_names
+        }
+
+        all_ap_values = [ap for cn_aps in label_aps.values() for ap in cn_aps.values()]
+        mean_ap = float(np.mean(all_ap_values)) if all_ap_values else 0.0
+
+        # TP errors per class at dist_th_tp
+        label_tp_errors: dict[str, dict[str, float]] = {}
+        for class_name in cfg.class_names:
+            md = metric_data[class_name][str(cfg.dist_th_tp)]
+            label_tp_errors[class_name] = {}
+            for metric_name in TP_METRICS:
+                if class_name == "traffic_cone" and metric_name in ("attr_err", "vel_err", "orient_err"):
+                    label_tp_errors[class_name][metric_name] = float("nan")
+                elif class_name == "barrier" and metric_name in ("attr_err", "vel_err"):
+                    label_tp_errors[class_name][metric_name] = float("nan")
+                else:
+                    label_tp_errors[class_name][metric_name] = _calc_tp(md, cfg.min_recall, metric_name)
+
+        tp_errors = {}
+        for metric_name in TP_METRICS:
+            values = [label_tp_errors[cn][metric_name] for cn in cfg.class_names]
+            tp_errors[metric_name] = float(np.nanmean(values))
+
+        tp_scores = {m: max(0.0, 1.0 - tp_errors[m]) for m in TP_METRICS}
+
+        nd_score = (cfg.mean_ap_weight * mean_ap + sum(tp_scores.values())) / (cfg.mean_ap_weight + len(tp_scores))
+
+        return DetectionResult(
+            mean_ap=mean_ap,
+            nd_score=nd_score,
+            label_aps=label_aps,
+            mean_dist_aps=mean_dist_aps,
+            tp_errors=tp_errors,
+            label_tp_errors=label_tp_errors,
+            tp_scores=tp_scores,
+        )

x4d_devkit/eval/matching.py

@@ -0,0 +1,184 @@
+# x4d_devkit/eval/matching.py
+"""Detection matching: accumulate GT/Pred pairs into precision-recall curves."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from x4d_devkit.eval.metrics import (
+    center_distance,
+    scale_iou,
+    yaw_diff,
+    attr_acc,
+    cummean,
+)
+
+NELEM = 101  # Number of recall interpolation points
+
+
+@dataclass
+class MetricData:
+    """Interpolated precision, recall, and TP error curves (101 points)."""
+
+    recall: np.ndarray       # (101,)
+    precision: np.ndarray    # (101,)
+    confidence: np.ndarray   # (101,)
+    trans_err: np.ndarray    # (101,)
+    scale_err: np.ndarray    # (101,)
+    orient_err: np.ndarray   # (101,)
+    vel_err: np.ndarray      # (101,)
+    attr_err: np.ndarray     # (101,)
+
+    @property
+    def max_recall_ind(self) -> int:
+        """Index of last non-zero confidence (= max achieved recall point)."""
+        non_zero = np.nonzero(self.confidence)[0]
+        if len(non_zero) == 0:
+            return 0
+        return int(non_zero[-1])
+
+    @classmethod
+    def no_predictions(cls) -> MetricData:
+        """Return a zero-valued MetricData for when there are no predictions."""
+        return cls(
+            recall=np.linspace(0, 1, NELEM),
+            precision=np.zeros(NELEM),
+            confidence=np.zeros(NELEM),
+            trans_err=np.ones(NELEM),
+            scale_err=np.ones(NELEM),
+            orient_err=np.ones(NELEM),
+            vel_err=np.ones(NELEM),
+            attr_err=np.ones(NELEM),
+        )
+
+
+def accumulate(
+    gt_boxes: dict[str, list[dict]],
+    pred_boxes: dict[str, list[dict]],
+    class_name: str,
+    dist_th: float,
+) -> MetricData:
+    """Match predictions to ground truth and compute interpolated curves.
+
+    Args:
+        gt_boxes: {sample_token: [box_dict, ...]} — all GT boxes across samples.
+        pred_boxes: {sample_token: [box_dict, ...]} — all pred boxes across samples.
+        class_name: Class to evaluate (e.g. "car").
+        dist_th: Center distance threshold for matching.
+
+    Each box_dict has: translation (3,), size (3,), rotation (4,) [qx,qy,qz,qw],
+    category (str), score (float, pred only), velocity (3,) or None, attributes (list[str]).
+
+    Returns:
+        MetricData with interpolated curves at 101 recall points.
+    """
+    # Filter by class
+    gt_by_sample: dict[str, list[dict]] = {}
+    npos = 0
+    for sample_token, boxes in gt_boxes.items():
+        class_boxes = [b for b in boxes if b["category"] == class_name]
+        gt_by_sample[sample_token] = class_boxes
+        npos += len(class_boxes)
+
+    pred_by_sample: dict[str, list[dict]] = {}
+    all_preds = []
+    for sample_token, boxes in pred_boxes.items():
+        class_boxes = [b for b in boxes if b["category"] == class_name]
+        class_boxes.sort(key=lambda b: b["score"], reverse=True)
+        pred_by_sample[sample_token] = class_boxes
+        for i, b in enumerate(class_boxes):
+            all_preds.append((b["score"], sample_token, i))
+
+    if npos == 0:
+        return MetricData.no_predictions()
+
+    # Sort all predictions globally by score descending
+    all_preds.sort(key=lambda x: x[0], reverse=True)
+
+    # Greedy matching
+    tp_list = []
+    conf_list = []
+    match_data = {k: [] for k in ["trans_err", "scale_err", "orient_err", "vel_err", "attr_err"]}
+    matched_gt: dict[str, set[int]] = {st: set() for st in gt_by_sample}
+
+    for score, sample_token, pred_idx in all_preds:
+        pred = pred_by_sample[sample_token][pred_idx]
+        gt_list = gt_by_sample.get(sample_token, [])
+
+        min_dist = float("inf")
+        min_gt_idx = -1
+        for gt_idx, gt in enumerate(gt_list):
+            if gt_idx in matched_gt.get(sample_token, set()):
+                continue
+            d = center_distance(pred["translation"], gt["translation"])
+            if d < min_dist:
+                min_dist = d
+                min_gt_idx = gt_idx
+
+        is_tp = min_dist < dist_th and min_gt_idx >= 0
+        tp_list.append(1 if is_tp else 0)
+        conf_list.append(score)
+
+        if is_tp:
+            matched_gt[sample_token].add(min_gt_idx)
+            gt = gt_list[min_gt_idx]
+            match_data["trans_err"].append(center_distance(pred["translation"], gt["translation"]))
+            match_data["scale_err"].append(1.0 - scale_iou(pred["size"], gt["size"]))
+            period = np.pi if class_name == "barrier" else 2 * np.pi
+            match_data["orient_err"].append(yaw_diff(pred["rotation"], gt["rotation"], period=period))
+            if pred["velocity"] is not None and gt["velocity"] is not None:
+                vel_diff = float(np.linalg.norm(
+                    np.asarray(pred["velocity"])[:2] - np.asarray(gt["velocity"])[:2]
+                ))
+                match_data["vel_err"].append(vel_diff)
+            else:
+                match_data["vel_err"].append(float("nan"))
+            match_data["attr_err"].append(1.0 - attr_acc(gt["attributes"], pred["attributes"]))
+        else:
+            for key in match_data:
+                match_data[key].append(float("nan"))
+
+    # Compute precision / recall
+    tp_arr = np.array(tp_list, dtype=float)
+    conf_arr = np.array(conf_list, dtype=float)
+    tp_cum = np.cumsum(tp_arr)
+    fp_cum = np.cumsum(1 - tp_arr)
+    precision_raw = tp_cum / (tp_cum + fp_cum)
+    recall_raw = tp_cum / npos
+
+    # Interpolate to NELEM recall points
+    recall_interp = np.linspace(0, 1, NELEM)
+    precision_interp = np.zeros(NELEM)
+    confidence_interp = np.zeros(NELEM)
+
+    for i, r in enumerate(recall_interp):
+        mask = recall_raw >= r - 1e-10
+        if mask.any():
+            precision_interp[i] = precision_raw[mask].max()
+            confidence_interp[i] = conf_arr[mask].min()
+
+    # Interpolate TP errors using cumulative mean
+    tp_metric_interp = {}
+    for key in match_data:
+        raw = np.array(match_data[key], dtype=float)
+        cm = cummean(raw)
+        interp = np.ones(NELEM)
+        for i, r in enumerate(recall_interp):
+            mask = recall_raw >= r - 1e-10
+            if mask.any():
+                idx = np.where(mask)[0][0]
+                interp[i] = cm[idx]
+        tp_metric_interp[key] = interp
+
+    return MetricData(
+        recall=recall_interp,
+        precision=precision_interp,
+        confidence=confidence_interp,
+        trans_err=tp_metric_interp["trans_err"],
+        scale_err=tp_metric_interp["scale_err"],
+        orient_err=tp_metric_interp["orient_err"],
+        vel_err=tp_metric_interp["vel_err"],
+        attr_err=tp_metric_interp["attr_err"],
+    )

x4d_devkit/eval/metrics.py

@@ -0,0 +1,83 @@
+"""Pure metric functions for detection evaluation."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from x4d_devkit.core.transform import quat_to_rotation_matrix
+
+
+def center_distance(
+    translation_a: list[float] | np.ndarray,
+    translation_b: list[float] | np.ndarray,
+) -> float:
+    """L2 distance between two 3D points in the XY plane (Z ignored)."""
+    a = np.asarray(translation_a, dtype=float)
+    b = np.asarray(translation_b, dtype=float)
+    return float(np.linalg.norm(a[:2] - b[:2]))
+
+
+def scale_iou(
+    size_a: list[float] | np.ndarray,
+    size_b: list[float] | np.ndarray,
+) -> float:
+    """Axis-aligned scale IoU between two 3D box sizes [l, w, h]."""
+    sa = np.asarray(size_a, dtype=float)
+    sb = np.asarray(size_b, dtype=float)
+    min_s = np.minimum(sa, sb)
+    intersection = float(np.prod(min_s))
+    vol_a = float(np.prod(sa))
+    vol_b = float(np.prod(sb))
+    union = vol_a + vol_b - intersection
+    if union <= 0:
+        return 0.0
+    return intersection / union
+
+
+def quaternion_yaw(quat: list[float] | np.ndarray) -> float:
+    """Extract yaw angle from quaternion [qx, qy, qz, qw]."""
+    qx, qy, qz, qw = quat[0], quat[1], quat[2], quat[3]
+    R = quat_to_rotation_matrix(qx, qy, qz, qw)
+    v = R @ np.array([1.0, 0.0, 0.0])
+    return float(np.arctan2(v[1], v[0]))
+
+
+def _angle_diff(x: float, y: float, period: float) -> float:
+    """Smallest signed angle difference, respecting periodicity."""
+    diff = (x - y + period / 2) % period - period / 2
+    if diff > np.pi:
+        diff -= period
+    return diff
+
+
+def yaw_diff(
+    quat_a: list[float] | np.ndarray,
+    quat_b: list[float] | np.ndarray,
+    period: float = 2 * np.pi,
+) -> float:
+    """Absolute yaw angle difference between two quaternions [qx,qy,qz,qw]."""
+    yaw_a = quaternion_yaw(quat_a)
+    yaw_b = quaternion_yaw(quat_b)
+    return abs(_angle_diff(yaw_a, yaw_b, period))
+
+
+def attr_acc(
+    gt_attrs: list[str],
+    pred_attrs: list[str],
+) -> float:
+    """Attribute classification accuracy. Returns NaN if either is empty."""
+    if not gt_attrs or not pred_attrs:
+        return float("nan")
+    return 1.0 if gt_attrs[0] == pred_attrs[0] else 0.0
+
+
+def cummean(arr: np.ndarray) -> np.ndarray:
+    """NaN-aware cumulative mean. Returns ones if all NaN."""
+    mask = ~np.isnan(arr)
+    count = np.cumsum(mask).astype(float)
+    count[count == 0] = 1.0
+    filled = np.where(mask, arr, 0.0)
+    result = np.cumsum(filled) / count
+    if not mask.any():
+        return np.ones_like(arr)
+    return result

x4d_devkit/validation/__init__.py

@@ -0,0 +1,4 @@
+from x4d_devkit.validation.validator import validate_clip
+from x4d_devkit.validation.report import ValidationReport
+
+__all__ = ["validate_clip", "ValidationReport"]

x4d_devkit/validation/report.py

@@ -0,0 +1,46 @@
+"""Validation report dataclass."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ValidationIssue:
+    """A single validation issue."""
+
+    check: str
+    level: str  # "error" or "warning"
+    message: str
+    detail: str = ""
+
+
+@dataclass
+class ValidationReport:
+    """Result of validating a clip directory."""
+
+    clip_id: str
+    issues: list[ValidationIssue] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not any(i.level == "error" for i in self.issues)
+
+    @property
+    def errors(self) -> list[ValidationIssue]:
+        return [i for i in self.issues if i.level == "error"]
+
+    @property
+    def warnings(self) -> list[ValidationIssue]:
+        return [i for i in self.issues if i.level == "warning"]
+
+    def __str__(self) -> str:
+        status = "PASS" if self.ok else "FAIL"
+        lines = [
+            f"[{status}] {self.clip_id}: {len(self.errors)} errors, {len(self.warnings)} warnings"
+        ]
+        for issue in self.issues:
+            prefix = "ERROR" if issue.level == "error" else "WARN"
+            lines.append(f"  [{prefix}] {issue.check}: {issue.message}")
+            if issue.detail:
+                lines.append(f"           {issue.detail}")
+        return "\n".join(lines)