visual-verifier 0.3.0__py3-none-any.whl

visual_verifier/config/__init__.py

@@ -0,0 +1,15 @@
+"""Expose supported Visual Verifier configuration interfaces."""
+
+from visual_verifier.config.defaults import DEFAULT_DETECTION_CONFIG
+from visual_verifier.config.tracking import (
+    DEFAULT_TRACKING_CONFIG,
+    TrackingConfig,
+)
+from visual_verifier.models import DetectionConfig
+
+__all__ = [
+    "DEFAULT_DETECTION_CONFIG",
+    "DEFAULT_TRACKING_CONFIG",
+    "DetectionConfig",
+    "TrackingConfig",
+]

visual_verifier/config/defaults.py

@@ -0,0 +1,45 @@
+"""Define immutable default values for visual region verification."""
+
+from visual_verifier.models import DetectionConfig
+
+DEFAULT_DIFF_THRESHOLD_INT = 30
+DEFAULT_MIN_BOX_AREA_INT = 80
+DEFAULT_MIN_BOX_WIDTH_INT = 6
+DEFAULT_MIN_BOX_HEIGHT_INT = 6
+DEFAULT_MERGE_KERNEL_SIZE_INT = 9
+DEFAULT_BOX_PADDING_INT = 3
+DEFAULT_MIN_CHANGED_RATIO_FLOAT = 0.03
+DEFAULT_MIN_MEAN_DIFF_FLOAT = 5.0
+DEFAULT_MIN_SEVERITY_SCORE_FLOAT = 8.0
+DEFAULT_DIFF_NORMALIZER_FLOAT = 80.0
+DEFAULT_CHANGED_RATIO_NORMALIZER_FLOAT = 0.75
+
+DEFAULT_DETECTION_CONFIG = DetectionConfig(
+    diff_threshold=DEFAULT_DIFF_THRESHOLD_INT,
+    min_box_area=DEFAULT_MIN_BOX_AREA_INT,
+    min_box_width=DEFAULT_MIN_BOX_WIDTH_INT,
+    min_box_height=DEFAULT_MIN_BOX_HEIGHT_INT,
+    merge_kernel_size=DEFAULT_MERGE_KERNEL_SIZE_INT,
+    box_padding=DEFAULT_BOX_PADDING_INT,
+    min_changed_ratio=DEFAULT_MIN_CHANGED_RATIO_FLOAT,
+    min_mean_diff=DEFAULT_MIN_MEAN_DIFF_FLOAT,
+    min_severity_score=DEFAULT_MIN_SEVERITY_SCORE_FLOAT,
+    diff_normalizer=DEFAULT_DIFF_NORMALIZER_FLOAT,
+    changed_ratio_normalizer=(DEFAULT_CHANGED_RATIO_NORMALIZER_FLOAT),
+)
+"""Validated immutable defaults used by public verification calls."""
+
+__all__ = [
+    "DEFAULT_BOX_PADDING_INT",
+    "DEFAULT_CHANGED_RATIO_NORMALIZER_FLOAT",
+    "DEFAULT_DETECTION_CONFIG",
+    "DEFAULT_DIFF_NORMALIZER_FLOAT",
+    "DEFAULT_DIFF_THRESHOLD_INT",
+    "DEFAULT_MERGE_KERNEL_SIZE_INT",
+    "DEFAULT_MIN_BOX_AREA_INT",
+    "DEFAULT_MIN_BOX_HEIGHT_INT",
+    "DEFAULT_MIN_BOX_WIDTH_INT",
+    "DEFAULT_MIN_CHANGED_RATIO_FLOAT",
+    "DEFAULT_MIN_MEAN_DIFF_FLOAT",
+    "DEFAULT_MIN_SEVERITY_SCORE_FLOAT",
+]

visual_verifier/config/targets.py

@@ -0,0 +1,101 @@
+"""Configure target-aware verification.
+
+The defaults are deliberately strict. A target is the reviewer's
+statement that a specific region had to be anonymized, so accepting
+partial coverage by default would quietly reintroduce the failure this
+feature exists to catch.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+from visual_verifier.exceptions import ConfigurationError
+
+MINIMUM_RATIO_FLOAT: Final[float] = 0.0
+MAXIMUM_RATIO_FLOAT: Final[float] = 1.0
+MAXIMUM_SENSIBLE_GAP_INT: Final[int] = 300
+
+
+@dataclass(frozen=True, slots=True)
+class TargetConfig:
+    """Configure how targets are interpolated and scored.
+
+    Attributes:
+        min_covered_ratio: Fraction of a target's area that accepted
+            processing must cover before the target counts as
+            anonymized.
+        interpolate_missing_frames: Fill frames between two reviewed
+            boxes of the same target.
+        max_interpolation_gap: Longest run of missing frames that may be
+            interpolated. A longer gap is left empty, because a target
+            can leave and re-enter a scene and inventing boxes across
+            that would fabricate evidence.
+        fail_on_uncovered_target: Let an uncovered required target fail
+            verification. Turn it off to collect target evidence without
+            changing the verdict.
+    """
+
+    min_covered_ratio: float = 0.9
+    interpolate_missing_frames: bool = True
+    max_interpolation_gap: int = 5
+    fail_on_uncovered_target: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate the configuration immediately after construction.
+
+        Raises:
+            ConfigurationError: When a value cannot be applied safely.
+        """
+
+        self._validate_covered_ratio()
+        self._validate_interpolation_gap()
+
+    def _validate_covered_ratio(self) -> None:
+        """Validate the minimum coverage ratio.
+
+        Raises:
+            ConfigurationError: When the ratio is outside zero to one.
+        """
+
+        if not (
+            MINIMUM_RATIO_FLOAT < self.min_covered_ratio <= MAXIMUM_RATIO_FLOAT
+        ):
+            raise ConfigurationError(
+                "Target coverage ratio must be above 0 and at most 1.",
+                context_mapping={
+                    "min_covered_ratio": self.min_covered_ratio,
+                },
+            )
+
+    def _validate_interpolation_gap(self) -> None:
+        """Validate the interpolation gap limit.
+
+        Raises:
+            ConfigurationError: When the gap is negative or implausible.
+        """
+
+        if self.max_interpolation_gap < 0:
+            raise ConfigurationError(
+                "Target interpolation gap cannot be negative.",
+                context_mapping={
+                    "max_interpolation_gap": self.max_interpolation_gap,
+                },
+            )
+        if self.max_interpolation_gap > MAXIMUM_SENSIBLE_GAP_INT:
+            raise ConfigurationError(
+                "Target interpolation gap is implausibly long.",
+                context_mapping={
+                    "max_interpolation_gap": self.max_interpolation_gap,
+                    "maximum_supported": MAXIMUM_SENSIBLE_GAP_INT,
+                },
+            )
+
+
+DEFAULT_TARGET_CONFIG: Final[TargetConfig] = TargetConfig()
+
+__all__ = [
+    "DEFAULT_TARGET_CONFIG",
+    "TargetConfig",
+]

visual_verifier/config/tracking.py

@@ -0,0 +1,97 @@
+"""Define immutable configuration for temporal region tracking."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from visual_verifier.exceptions import ConfigurationError
+
+DEFAULT_ASSOCIATION_IOU_THRESHOLD_FLOAT = 0.20
+DEFAULT_MINIMUM_CONFIRMATION_HITS_INT = 2
+DEFAULT_MAXIMUM_GAP_FRAMES_INT = 3
+DEFAULT_LINEAGE_OVERLAP_THRESHOLD_FLOAT = 0.20
+
+
+@dataclass(frozen=True, slots=True)
+class TrackingConfig:
+    """Configure deterministic temporal association and track lifecycle.
+
+    Attributes:
+        association_iou_threshold: Minimum intersection-over-union required
+            to associate one detection with an active track.
+        minimum_confirmation_hits: Consecutive or recovered observations
+            required before a tentative track becomes confirmed.
+        maximum_gap_frames: Number of consecutive missing frames tolerated
+            before an active track is closed.
+        lineage_overlap_threshold: Minimum overlap used when detecting
+            split and merge lineage events.
+        detect_lineage_events: Whether split and merge evidence is produced.
+    """
+
+    association_iou_threshold: float = DEFAULT_ASSOCIATION_IOU_THRESHOLD_FLOAT
+    minimum_confirmation_hits: int = DEFAULT_MINIMUM_CONFIRMATION_HITS_INT
+    maximum_gap_frames: int = DEFAULT_MAXIMUM_GAP_FRAMES_INT
+    lineage_overlap_threshold: float = DEFAULT_LINEAGE_OVERLAP_THRESHOLD_FLOAT
+    detect_lineage_events: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate temporal tracking settings after construction.
+
+        Raises:
+            ConfigurationError: When one or more settings are invalid.
+        """
+
+        invalid_fields_list = self._find_invalid_fields()
+        if not invalid_fields_list:
+            return
+
+        raise ConfigurationError(
+            "Tracking configuration contains invalid values.",
+            context_mapping={
+                "invalid_fields": sorted(set(invalid_fields_list)),
+            },
+        )
+
+    def _find_invalid_fields(self) -> list[str]:
+        """Return configuration field names that fail validation.
+
+        Returns:
+            Names of invalid threshold or lifecycle settings.
+        """
+
+        invalid_fields_list: list[str] = []
+
+        if not 0.0 <= self.association_iou_threshold <= 1.0:
+            invalid_fields_list.append("association_iou_threshold")
+        if self.minimum_confirmation_hits < 1:
+            invalid_fields_list.append("minimum_confirmation_hits")
+        if self.maximum_gap_frames < 0:
+            invalid_fields_list.append("maximum_gap_frames")
+        if not 0.0 <= self.lineage_overlap_threshold <= 1.0:
+            invalid_fields_list.append("lineage_overlap_threshold")
+
+        return invalid_fields_list
+
+    def to_dict(self) -> dict[str, object]:
+        """Return serializable temporal tracking settings.
+
+        Returns:
+            Dictionary containing each configuration field.
+        """
+
+        return {
+            field_name_str: getattr(self, field_name_str)
+            for field_name_str in self.__dataclass_fields__
+        }
+
+
+DEFAULT_TRACKING_CONFIG = TrackingConfig()
+
+__all__ = [
+    "DEFAULT_ASSOCIATION_IOU_THRESHOLD_FLOAT",
+    "DEFAULT_LINEAGE_OVERLAP_THRESHOLD_FLOAT",
+    "DEFAULT_MAXIMUM_GAP_FRAMES_INT",
+    "DEFAULT_MINIMUM_CONFIRMATION_HITS_INT",
+    "DEFAULT_TRACKING_CONFIG",
+    "TrackingConfig",
+]

visual_verifier/demo.py

@@ -0,0 +1,310 @@
+"""Generate and verify a self-contained demonstration.
+
+A new user should be able to see a real anonymization failure without
+cloning the repository, downloading fixtures, or supplying media of their
+own. This module synthesizes a short scene in which a licence plate is
+blurred on every frame except three, then verifies it.
+
+The sample is generated rather than shipped: it keeps the wheel small,
+needs no network access, and is reproducible on every platform. The clip
+is deliberately synthetic, and the command says so.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from visual_verifier.api import verify_video
+from visual_verifier.media.video_writer import open_annotated_writer
+from visual_verifier.models import BoundingBox, VerificationResult
+from visual_verifier.type_aliases import ImageArray, PathInput
+
+DEMONSTRATION_DIRECTORY_NAME_STR = "visual-verifier-demo"
+REFERENCE_FILENAME_STR = "reference.mp4"
+CANDIDATE_FILENAME_STR = "candidate.mp4"
+REPORT_DIRECTORY_NAME_STR = "report"
+
+DEMONSTRATION_FRAME_COUNT_INT = 15
+DEMONSTRATION_FRAME_RATE_FLOAT = 2.0
+DEMONSTRATION_WIDTH_INT = 640
+DEMONSTRATION_HEIGHT_INT = 360
+UNPROCESSED_FRAMES_TUPLE = (4, 8, 12)
+
+PLATE_WIDTH_INT = 96
+PLATE_HEIGHT_INT = 40
+PLATE_START_X_INT = 210
+PLATE_TOP_Y_INT = 232
+PLATE_STEP_X_INT = 14
+PLATE_BLUR_PADDING_INT = 6
+PLATE_BLUR_KERNEL_TUPLE = (31, 31)
+PLATE_CHARACTER_COUNT_INT = 6
+
+ROAD_TOP_Y_INT = 250
+LANE_MARK_TOP_Y_INT = 320
+LANE_MARK_HEIGHT_INT = 10
+LANE_MARK_WIDTH_INT = 46
+LANE_MARK_SPACING_INT = 90
+LANE_MARK_SPEED_INT = 18
+
+ROAD_COLOR_BGR = (70, 70, 74)
+LANE_COLOR_BGR = (225, 225, 225)
+VEHICLE_COLOR_BGR = (48, 44, 52)
+WINDOW_COLOR_BGR = (30, 28, 34)
+PLATE_COLOR_BGR = (242, 242, 238)
+PLATE_CHARACTER_COLOR_BGR = (24, 24, 28)
+
+
+@dataclass(frozen=True, slots=True)
+class DemonstrationResult:
+    """Report where the demonstration wrote its media and evidence.
+
+    Attributes:
+        reference_path: Generated original clip.
+        candidate_path: Generated processed clip with three gaps.
+        report_directory: Directory holding the generated evidence.
+        verification_result: Result produced by the normal video API.
+        expected_unprocessed_frames: Frames deliberately left unblurred.
+    """
+
+    reference_path: Path
+    candidate_path: Path
+    report_directory: Path
+    verification_result: VerificationResult
+    expected_unprocessed_frames: tuple[int, ...]
+
+    @property
+    def behaved_as_documented(self) -> bool:
+        """Return whether the demonstration found exactly the gaps sown."""
+
+        return (
+            self.verification_result.failed
+            and self.verification_result.failed_frames
+            == self.expected_unprocessed_frames
+        )
+
+
+def run_demonstration(
+    output_dir: PathInput | None = None,
+) -> DemonstrationResult:
+    """Generate a sample anonymization failure and verify it.
+
+    Args:
+        output_dir: Directory for the generated media and evidence.
+            Defaults to ``./visual-verifier-demo``.
+
+    Returns:
+        Paths to every generated artefact and the verification result.
+
+    Raises:
+        ReportWriteError: When the sample media cannot be written, which
+            usually means this OpenCV build has no usable video codec.
+    """
+
+    demonstration_path_obj = Path(
+        output_dir or DEMONSTRATION_DIRECTORY_NAME_STR
+    ).expanduser()
+    demonstration_path_obj.mkdir(parents=True, exist_ok=True)
+    reference_path_obj = demonstration_path_obj / REFERENCE_FILENAME_STR
+    candidate_path_obj = demonstration_path_obj / CANDIDATE_FILENAME_STR
+    report_path_obj = demonstration_path_obj / REPORT_DIRECTORY_NAME_STR
+
+    _write_demonstration_video(reference_path_obj, apply_blur_bool=False)
+    _write_demonstration_video(candidate_path_obj, apply_blur_bool=True)
+
+    return DemonstrationResult(
+        reference_path=reference_path_obj,
+        candidate_path=candidate_path_obj,
+        report_directory=report_path_obj,
+        verification_result=verify_video(
+            reference_path_obj,
+            candidate_path_obj,
+            output_dir=report_path_obj,
+        ),
+        expected_unprocessed_frames=UNPROCESSED_FRAMES_TUPLE,
+    )
+
+
+def _write_demonstration_video(
+    output_path_obj: Path,
+    *,
+    apply_blur_bool: bool,
+) -> None:
+    """Write one generated clip, optionally blurring the licence plate.
+
+    Args:
+        output_path_obj: Destination MP4 path.
+        apply_blur_bool: Blur the plate on every frame except the three
+            deliberately unprocessed ones.
+
+    Raises:
+        ReportWriteError: When no supported codec can be opened.
+    """
+
+    video_writer_obj = open_annotated_writer(
+        output_path_obj,
+        DEMONSTRATION_FRAME_RATE_FLOAT,
+        (DEMONSTRATION_WIDTH_INT, DEMONSTRATION_HEIGHT_INT),
+    )
+    try:
+        for frame_number_int in range(1, DEMONSTRATION_FRAME_COUNT_INT + 1):
+            frame_ndarray = _render_scene_frame(frame_number_int)
+            if apply_blur_bool and (
+                frame_number_int not in UNPROCESSED_FRAMES_TUPLE
+            ):
+                _blur_plate_region(frame_ndarray, frame_number_int)
+            video_writer_obj.write(frame_ndarray)
+    finally:
+        video_writer_obj.release()
+
+
+def _render_scene_frame(frame_number_int: int) -> ImageArray:
+    """Render one deterministic frame of the sample scene.
+
+    Args:
+        frame_number_int: One-based frame number.
+
+    Returns:
+        Rendered frame containing a road, a vehicle, and a plate.
+    """
+
+    frame_ndarray: ImageArray = np.zeros(
+        (DEMONSTRATION_HEIGHT_INT, DEMONSTRATION_WIDTH_INT, 3),
+        dtype=np.uint8,
+    )
+    _draw_sky_and_road(frame_ndarray)
+    _draw_lane_markings(frame_ndarray, frame_number_int)
+    _draw_vehicle(frame_ndarray, _plate_box(frame_number_int))
+    return frame_ndarray
+
+
+def _draw_sky_and_road(frame_ndarray: ImageArray) -> None:
+    """Fill the frame with a graded sky above a flat road surface."""
+
+    for row_index_int in range(DEMONSTRATION_HEIGHT_INT):
+        frame_ndarray[row_index_int, :] = (
+            170 - row_index_int // 4,
+            140 - row_index_int // 6,
+            110 - row_index_int // 8,
+        )
+    cv2.rectangle(
+        frame_ndarray,
+        (0, ROAD_TOP_Y_INT),
+        (DEMONSTRATION_WIDTH_INT, DEMONSTRATION_HEIGHT_INT),
+        ROAD_COLOR_BGR,
+        thickness=-1,
+    )
+
+
+def _draw_lane_markings(
+    frame_ndarray: ImageArray,
+    frame_number_int: int,
+) -> None:
+    """Draw lane markings that advance with the frame number."""
+
+    total_span_int = DEMONSTRATION_WIDTH_INT + LANE_MARK_SPACING_INT
+    for marking_index_int in range(-1, 9):
+        left_x_int = (
+            marking_index_int * LANE_MARK_SPACING_INT
+            + frame_number_int * LANE_MARK_SPEED_INT
+        ) % total_span_int - LANE_MARK_SPACING_INT // 2
+        cv2.rectangle(
+            frame_ndarray,
+            (left_x_int, LANE_MARK_TOP_Y_INT),
+            (
+                left_x_int + LANE_MARK_WIDTH_INT,
+                LANE_MARK_TOP_Y_INT + LANE_MARK_HEIGHT_INT,
+            ),
+            LANE_COLOR_BGR,
+            thickness=-1,
+        )
+
+
+def _draw_vehicle(
+    frame_ndarray: ImageArray,
+    plate_box_obj: BoundingBox,
+) -> None:
+    """Draw the vehicle body, window, and readable licence plate."""
+
+    cv2.rectangle(
+        frame_ndarray,
+        (plate_box_obj.x1 - 62, plate_box_obj.y1 - 96),
+        (plate_box_obj.x2 + 62, plate_box_obj.y2 + 26),
+        VEHICLE_COLOR_BGR,
+        thickness=-1,
+    )
+    cv2.rectangle(
+        frame_ndarray,
+        (plate_box_obj.x1 - 54, plate_box_obj.y1 - 84),
+        (plate_box_obj.x2 + 54, plate_box_obj.y1 - 30),
+        WINDOW_COLOR_BGR,
+        thickness=-1,
+    )
+    cv2.rectangle(
+        frame_ndarray,
+        (plate_box_obj.x1, plate_box_obj.y1),
+        (plate_box_obj.x2, plate_box_obj.y2),
+        PLATE_COLOR_BGR,
+        thickness=-1,
+    )
+    for character_index_int in range(PLATE_CHARACTER_COUNT_INT):
+        character_x_int = plate_box_obj.x1 + 8 + character_index_int * 14
+        cv2.rectangle(
+            frame_ndarray,
+            (character_x_int, plate_box_obj.y1 + 9),
+            (character_x_int + 9, plate_box_obj.y2 - 9),
+            PLATE_CHARACTER_COLOR_BGR,
+            thickness=-1,
+        )
+
+
+def _plate_box(frame_number_int: int) -> BoundingBox:
+    """Return the licence-plate box for one frame of the sample scene.
+
+    Args:
+        frame_number_int: One-based frame number.
+
+    Returns:
+        Plate box that drifts steadily across the clip.
+    """
+
+    left_x_int = PLATE_START_X_INT + PLATE_STEP_X_INT * (frame_number_int - 1)
+    return BoundingBox(
+        left_x_int,
+        PLATE_TOP_Y_INT,
+        left_x_int + PLATE_WIDTH_INT,
+        PLATE_TOP_Y_INT + PLATE_HEIGHT_INT,
+    )
+
+
+def _blur_plate_region(
+    frame_ndarray: ImageArray,
+    frame_number_int: int,
+) -> None:
+    """Blur the licence-plate region of one frame in place.
+
+    Args:
+        frame_ndarray: Frame modified in place.
+        frame_number_int: One-based frame number.
+    """
+
+    plate_box_obj = _plate_box(frame_number_int)
+    top_int = plate_box_obj.y1 - PLATE_BLUR_PADDING_INT
+    bottom_int = plate_box_obj.y2 + PLATE_BLUR_PADDING_INT
+    left_int = plate_box_obj.x1 - PLATE_BLUR_PADDING_INT
+    right_int = plate_box_obj.x2 + PLATE_BLUR_PADDING_INT
+    frame_ndarray[top_int:bottom_int, left_int:right_int] = cv2.GaussianBlur(
+        frame_ndarray[top_int:bottom_int, left_int:right_int],
+        PLATE_BLUR_KERNEL_TUPLE,
+        0,
+    )
+
+
+__all__ = [
+    "UNPROCESSED_FRAMES_TUPLE",
+    "DemonstrationResult",
+    "run_demonstration",
+]

visual_verifier/detection/__init__.py

@@ -0,0 +1,29 @@
+"""Expose stable region-detection interfaces for Visual Verifier."""
+
+from visual_verifier.detection.filtering import (
+    RegionFilterDecision,
+    evaluate_region_filtering,
+    is_region_accepted,
+    rejection_reasons,
+)
+from visual_verifier.detection.region_extraction import (
+    RegionDetectionResult,
+    detect_regions,
+)
+from visual_verifier.detection.severity import (
+    SeverityLabel,
+    calculate_severity,
+    severity_label,
+)
+
+__all__ = [
+    "RegionDetectionResult",
+    "RegionFilterDecision",
+    "SeverityLabel",
+    "calculate_severity",
+    "detect_regions",
+    "evaluate_region_filtering",
+    "is_region_accepted",
+    "rejection_reasons",
+    "severity_label",
+]