Add 1000 files (ocr-tech/tests/test_audit_limbu_book_missed_line_review_coverage.py ...)
d82db76 verified Download ocr-tech-mps-integration/src/ocrtech/capture.py from prosperious/ocr-projects-archive: direct link, hf CLI and curl.
- Browser
- Download file 43.7 kB
-
https://huggingface.co/prosperious/ocr-projects-archive/resolve/main/ocr-tech-mps-integration/src/ocrtech/capture.py
- Command line
-
hf download hf://prosperious/ocr-projects-archive/ocr-tech-mps-integration/src/ocrtech/capture.py
-
curl -L -o capture.py https://huggingface.co/prosperious/ocr-projects-archive/resolve/main/ocr-tech-mps-integration/src/ocrtech/capture.py
43.7 kB
"""Capture preparation helpers for operational OCR runs."""
from __future__ import annotations
import json
import math
import platform
import shutil
import socket
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from .errors import DataValidationError, EngineUnavailableError
from .manifest import sha256_file
_SUPPORTED_CAPTURE_SUFFIXES = {".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tif", ".tiff"}
PerspectiveQuad = tuple[tuple[int, int], tuple[int, int], tuple[int, int], tuple[int, int]]
@dataclass(slots=True)
class CapturePrepResult:
source_path: str
raw_copy_path: str
prepared_image_path: str
metadata_path: str
source_sha256: str
prepared_sha256: str
operations: list[dict[str, Any]]
image_quality: dict[str, Any] | None = None
created_at_utc: str | None = None
run_context: dict[str, Any] | None = None
def to_dict(self) -> dict[str, Any]:
return {
"source_path": self.source_path,
"raw_copy_path": self.raw_copy_path,
"prepared_image_path": self.prepared_image_path,
"metadata_path": self.metadata_path,
"source_sha256": self.source_sha256,
"prepared_sha256": self.prepared_sha256,
"operations": self.operations,
"image_quality": self.image_quality or {},
"created_at_utc": self.created_at_utc,
"run_context": self.run_context or {},
}
def prepare_limbu_capture(
input_path: str | Path,
output_dir: str | Path,
*,
rotate_degrees: float = 0.0,
crop_box: tuple[int, int, int, int] | None = None,
perspective_quad: PerspectiveQuad | None = None,
auto_detect_page: bool = False,
auto_deskew: bool = False,
max_auto_deskew_degrees: float = 8.0,
autocontrast: bool = True,
grayscale: bool = True,
run_context: dict[str, Any] | None = None,
) -> CapturePrepResult:
source = Path(input_path)
if not source.is_file():
raise DataValidationError(f"capture input does not exist or is not a file: {source}")
if source.suffix.lower() not in _SUPPORTED_CAPTURE_SUFFIXES:
raise DataValidationError(f"unsupported capture image suffix: {source.suffix or '<none>'}")
if auto_detect_page and perspective_quad is not None:
raise DataValidationError("auto_detect_page cannot be combined with an explicit perspective_quad")
if max_auto_deskew_degrees <= 0 or max_auto_deskew_degrees > 45:
raise DataValidationError(f"max_auto_deskew_degrees must be > 0 and <= 45, got {max_auto_deskew_degrees}")
try:
from PIL import Image, ImageOps
except ImportError as exc:
raise EngineUnavailableError("Pillow is required for capture preparation") from exc
out = Path(output_dir)
raw_dir = out / "raw"
prepared_dir = out / "prepared"
raw_dir.mkdir(parents=True, exist_ok=True)
prepared_dir.mkdir(parents=True, exist_ok=True)
raw_copy = raw_dir / source.name
shutil.copy2(source, raw_copy)
operations: list[dict[str, Any]] = [{"operation": "raw_copy", "path": str(raw_copy)}]
try:
with Image.open(source) as image:
prepared = ImageOps.exif_transpose(image)
operations.append({"operation": "exif_transpose", "mode": prepared.mode, "size": list(prepared.size)})
if crop_box is not None:
_validate_crop_box(crop_box, prepared.size)
prepared = prepared.crop(crop_box)
operations.append({"operation": "crop", "box": list(crop_box), "size": list(prepared.size)})
if auto_detect_page:
detected_quad, area_ratio, detection_method = _detect_page_quad(prepared)
perspective_quad = detected_quad
operations.append(
{
"operation": "auto_detect_page",
"method": detection_method,
"quad_order": "top_left,top_right,bottom_right,bottom_left",
"quad": [[x, y] for x, y in detected_quad],
"area_ratio": area_ratio,
"touches_image_border": _quad_touches_image_border(detected_quad, prepared.size),
}
)
if perspective_quad is not None:
_validate_perspective_quad(perspective_quad, prepared.size)
prepared, rectified_size = _rectify_perspective(prepared, perspective_quad)
operations.append(
{
"operation": "perspective_rectify",
"quad_order": "top_left,top_right,bottom_right,bottom_left",
"quad": [[x, y] for x, y in perspective_quad],
"size": list(rectified_size),
}
)
if auto_deskew:
detected_angle = _detect_skew_degrees(prepared, max_degrees=float(max_auto_deskew_degrees))
if detected_angle is None:
operations.append(
{
"operation": "auto_deskew",
"status": "skipped",
"reason": "insufficient near-horizontal line evidence",
"max_degrees": float(max_auto_deskew_degrees),
"size": list(prepared.size),
}
)
else:
prepared = prepared.rotate(detected_angle, expand=True, fillcolor="white")
operations.append(
{
"operation": "auto_deskew",
"status": "applied",
"detected_angle_degrees": detected_angle,
"applied_rotation_degrees": detected_angle,
"max_degrees": float(max_auto_deskew_degrees),
"size": list(prepared.size),
}
)
if rotate_degrees:
prepared = prepared.rotate(float(rotate_degrees), expand=True, fillcolor="white")
operations.append({"operation": "rotate", "degrees": float(rotate_degrees), "size": list(prepared.size)})
if grayscale:
prepared = prepared.convert("L")
operations.append({"operation": "grayscale", "mode": prepared.mode})
if autocontrast:
prepared = ImageOps.autocontrast(prepared)
operations.append({"operation": "autocontrast"})
prepared_path = prepared_dir / f"{source.stem}.prepared.png"
prepared.save(prepared_path)
except DataValidationError:
raise
except Exception as exc:
raise DataValidationError(f"failed to prepare capture image {source}: {type(exc).__name__}: {exc}") from exc
result = CapturePrepResult(
source_path=str(source),
raw_copy_path=str(raw_copy),
prepared_image_path=str(prepared_path),
metadata_path=str(out / "limbu-capture-prep.json"),
source_sha256=sha256_file(source),
prepared_sha256=sha256_file(prepared_path),
operations=operations,
image_quality={
"source": _capture_image_quality_metrics(source),
"prepared": _capture_image_quality_metrics(prepared_path),
},
created_at_utc=datetime.now(UTC).isoformat(),
run_context=_default_run_context(run_context),
)
Path(result.metadata_path).write_text(json.dumps(result.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
return result
def audit_limbu_capture(
capture_metadata: str | Path,
output_dir: str | Path | None = None,
*,
require_metadata_path_self: bool = False,
min_prepared_width: int | None = None,
min_prepared_height: int | None = None,
min_prepared_entropy: float | None = None,
min_prepared_luminance_stddev: float | None = None,
min_prepared_edge_stddev: float | None = None,
min_prepared_laplacian_variance: float | None = None,
require_auto_detect_page: bool = False,
min_auto_detect_page_area_ratio: float | None = None,
fail_on_auto_detect_page_border_touch: bool = False,
require_auto_deskew_applied: bool = False,
max_abs_auto_deskew_degrees: float | None = None,
) -> dict[str, Any]:
metadata_path = _resolve_capture_metadata_path(Path(capture_metadata))
issues: list[str] = []
warnings: list[str] = []
quality_policy = {
"require_metadata_path_self": require_metadata_path_self,
"min_prepared_width": min_prepared_width,
"min_prepared_height": min_prepared_height,
"min_prepared_entropy": min_prepared_entropy,
"min_prepared_luminance_stddev": min_prepared_luminance_stddev,
"min_prepared_edge_stddev": min_prepared_edge_stddev,
"min_prepared_laplacian_variance": min_prepared_laplacian_variance,
"require_auto_detect_page": require_auto_detect_page,
"min_auto_detect_page_area_ratio": min_auto_detect_page_area_ratio,
"fail_on_auto_detect_page_border_touch": fail_on_auto_detect_page_border_touch,
"require_auto_deskew_applied": require_auto_deskew_applied,
"max_abs_auto_deskew_degrees": max_abs_auto_deskew_degrees,
}
_validate_capture_quality_policy(quality_policy)
metadata = _read_capture_metadata(metadata_path, issues)
artifacts: list[dict[str, Any]] = []
if metadata is not None:
_audit_capture_metadata_shape(
metadata,
metadata_path,
issues,
warnings,
require_metadata_path_self=require_metadata_path_self,
)
artifacts.extend(_audit_capture_artifacts(metadata, metadata_path, issues, warnings))
_audit_capture_image_quality(metadata, metadata_path, issues, warnings)
_audit_capture_quality_policy(metadata, quality_policy, issues)
_audit_capture_operations(metadata, quality_policy, issues, warnings)
report = {
"pipeline_id": "limbu-first-ocr-pipeline-v1",
"audit_stage": "limbu_capture_prep_bundle",
"metadata_path": str(metadata_path),
"quality_policy": quality_policy,
"passed": not issues,
"issues": issues,
"warnings": warnings,
"artifacts": artifacts,
}
target_dir = Path(output_dir) if output_dir is not None else metadata_path.parent
_write_limbu_capture_audit(report, target_dir)
return report
def _default_run_context(run_context: dict[str, Any] | None) -> dict[str, Any]:
context = dict(run_context or {})
context.setdefault("hostname", socket.gethostname())
context.setdefault("platform", platform.platform())
context.setdefault("python_version", platform.python_version())
return context
def _resolve_capture_metadata_path(path: Path) -> Path:
if path.is_dir():
return path / "limbu-capture-prep.json"
return path
def _read_capture_metadata(path: Path, issues: list[str]) -> dict[str, Any] | None:
if not path.is_file():
issues.append(f"limbu-capture-prep.json is missing: {path}")
return None
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except json.JSONDecodeError as exc:
issues.append(f"limbu-capture-prep.json is invalid JSON: {exc}")
return None
if not isinstance(payload, dict):
issues.append("limbu-capture-prep.json must contain a JSON object")
return None
return payload
def _audit_capture_metadata_shape(
metadata: dict[str, Any],
metadata_path: Path,
issues: list[str],
warnings: list[str],
*,
require_metadata_path_self: bool = False,
) -> None:
required_strings = [
"source_path",
"raw_copy_path",
"prepared_image_path",
"metadata_path",
"source_sha256",
"prepared_sha256",
"created_at_utc",
]
for key in required_strings:
if not isinstance(metadata.get(key), str) or not str(metadata.get(key)).strip():
issues.append(f"limbu-capture-prep.json missing non-empty string field: {key}")
operations = metadata.get("operations")
if not isinstance(operations, list) or not operations:
issues.append("limbu-capture-prep.json operations must be a non-empty list")
image_quality = metadata.get("image_quality")
if image_quality is None:
warnings.append("limbu-capture-prep.json missing image_quality metrics")
elif not isinstance(image_quality, dict):
issues.append("limbu-capture-prep.json image_quality must be an object")
run_context = metadata.get("run_context")
if not isinstance(run_context, dict):
issues.append("limbu-capture-prep.json run_context must be an object")
else:
if not run_context.get("hostname"):
warnings.append("capture run_context.hostname is missing")
if not run_context.get("python_version"):
warnings.append("capture run_context.python_version is missing")
recorded_metadata_path = metadata.get("metadata_path")
if isinstance(recorded_metadata_path, str) and recorded_metadata_path.strip():
resolved = _resolve_capture_artifact_path(recorded_metadata_path, metadata_path.parent)
try:
if resolved.resolve() != metadata_path.resolve():
message = f"metadata_path points to a different path: {recorded_metadata_path}"
if require_metadata_path_self:
issues.append(message)
else:
warnings.append(message)
except OSError:
message = f"metadata_path could not be resolved: {recorded_metadata_path}"
if require_metadata_path_self:
issues.append(message)
else:
warnings.append(message)
def _audit_capture_artifacts(
metadata: dict[str, Any],
metadata_path: Path,
issues: list[str],
warnings: list[str],
) -> list[dict[str, Any]]:
artifacts: list[dict[str, Any]] = []
artifacts.append(
_audit_capture_artifact(
metadata.get("source_path"),
metadata.get("source_sha256"),
"source_path",
metadata_path.parent,
issues,
warnings,
required=False,
)
)
artifacts.append(
_audit_capture_artifact(
metadata.get("raw_copy_path"),
metadata.get("source_sha256"),
"raw_copy_path",
metadata_path.parent,
issues,
warnings,
required=True,
)
)
artifacts.append(
_audit_capture_artifact(
metadata.get("prepared_image_path"),
metadata.get("prepared_sha256"),
"prepared_image_path",
metadata_path.parent,
issues,
warnings,
required=True,
)
)
return artifacts
def _audit_capture_artifact(
path_value: object,
expected_sha: object,
label: str,
base_dir: Path,
issues: list[str],
warnings: list[str],
*,
required: bool,
) -> dict[str, Any]:
path_text = str(path_value or "")
path = _resolve_capture_artifact_path(path_text, base_dir) if path_text else Path("")
exists = bool(path_text) and path.is_file()
artifact = {
"label": label,
"path": path_text,
"exists": exists,
"sha256": sha256_file(path) if exists else None,
"expected_sha256": expected_sha if isinstance(expected_sha, str) else None,
"size_bytes": path.stat().st_size if exists else None,
}
if not path_text:
issues.append(f"{label} is missing from limbu-capture-prep.json")
return artifact
if not exists:
message = f"{label} does not exist: {path_text}"
if required:
issues.append(message)
else:
warnings.append(message)
return artifact
if not isinstance(expected_sha, str) or not expected_sha:
issues.append(f"{label} expected SHA-256 is missing")
return artifact
actual_sha = str(artifact["sha256"])
if actual_sha != expected_sha:
issues.append(f"{label} sha256 mismatch: metadata={expected_sha} actual={actual_sha}")
_audit_capture_image_decodable(path, label, artifact, issues, warnings)
return artifact
def _audit_capture_image_quality(
metadata: dict[str, Any],
metadata_path: Path,
issues: list[str],
warnings: list[str],
) -> None:
image_quality = metadata.get("image_quality")
if not isinstance(image_quality, dict):
return
for quality_label, path_field, required in (
("source", "source_path", False),
("prepared", "prepared_image_path", True),
):
recorded = image_quality.get(quality_label)
if recorded is None:
warnings.append(f"limbu-capture-prep.json image_quality missing {quality_label} metrics")
continue
if not isinstance(recorded, dict):
issues.append(f"limbu-capture-prep.json image_quality.{quality_label} must be an object")
continue
path_value = metadata.get(path_field)
path_text = str(path_value or "")
path = _resolve_capture_artifact_path(path_text, metadata_path.parent) if path_text else Path("")
if not path_text or not path.is_file():
message = f"image_quality.{quality_label} metrics cannot be replayed because {path_field} is unavailable: {path_text}"
if required:
issues.append(message)
else:
warnings.append(message)
continue
try:
actual = _capture_image_quality_metrics(path)
except Exception as exc:
issues.append(f"image_quality.{quality_label} metrics replay failed: {type(exc).__name__}: {exc}")
continue
comparable_actual = {key: actual.get(key) for key in recorded}
if recorded != comparable_actual:
issues.append(f"image_quality.{quality_label} metrics mismatch: metadata={recorded!r} actual={actual!r}")
missing_recorded_metrics = sorted(set(actual) - set(recorded))
if missing_recorded_metrics:
warnings.append(
f"image_quality.{quality_label} metrics missing newer replay fields: {', '.join(missing_recorded_metrics)}"
)
def _validate_capture_quality_policy(policy: dict[str, int | float | bool | None]) -> None:
bool_keys = {
"require_metadata_path_self",
"require_auto_detect_page",
"fail_on_auto_detect_page_border_touch",
"require_auto_deskew_applied",
}
for key, value in policy.items():
if value is None:
continue
if key in bool_keys:
if not isinstance(value, bool):
raise DataValidationError(f"{key} must be boolean, got {value!r}")
continue
if not isinstance(value, int | float):
raise DataValidationError(f"{key} must be numeric, got {value!r}")
if value < 0:
raise DataValidationError(f"{key} must be non-negative, got {value!r}")
def _audit_capture_quality_policy(
metadata: dict[str, Any],
policy: dict[str, int | float | bool | None],
issues: list[str],
) -> None:
checks = {
"min_prepared_width": "width",
"min_prepared_height": "height",
"min_prepared_entropy": "entropy",
"min_prepared_luminance_stddev": "luminance_stddev",
"min_prepared_edge_stddev": "edge_stddev",
"min_prepared_laplacian_variance": "laplacian_variance",
}
if not any(policy.get(policy_key) is not None for policy_key in checks):
return
image_quality = metadata.get("image_quality")
if not isinstance(image_quality, dict):
issues.append("capture quality policy requires image_quality metrics")
return
prepared = image_quality.get("prepared")
if not isinstance(prepared, dict):
issues.append("capture quality policy requires image_quality.prepared metrics")
return
for policy_key, metric_key in checks.items():
threshold = policy.get(policy_key)
if threshold is None:
continue
actual = prepared.get(metric_key)
if not isinstance(actual, int | float):
issues.append(f"capture quality policy requires numeric image_quality.prepared.{metric_key}")
elif float(actual) < float(threshold):
issues.append(
"prepared image quality below policy threshold: "
f"{metric_key}={actual!r} minimum={threshold!r}"
)
def _audit_capture_image_decodable(
path: Path,
label: str,
artifact: dict[str, Any],
issues: list[str],
warnings: list[str],
) -> None:
if path.suffix.lower() not in _SUPPORTED_CAPTURE_SUFFIXES:
return
try:
from PIL import Image
except ImportError:
warnings.append(f"{label} image decode check skipped because Pillow is unavailable")
return
try:
with Image.open(path) as image:
artifact["image_mode"] = image.mode
artifact["image_size"] = list(image.size)
image.verify()
except Exception as exc:
issues.append(f"{label} is not a decodable image: {type(exc).__name__}: {exc}")
def _capture_image_quality_metrics(path: Path) -> dict[str, Any]:
try:
from PIL import Image, ImageFilter, ImageOps, ImageStat
except ImportError as exc:
raise EngineUnavailableError("Pillow is required for capture quality metrics") from exc
with Image.open(path) as image:
image.load()
grayscale = ImageOps.grayscale(image)
luminance = ImageStat.Stat(grayscale)
edges = grayscale.filter(ImageFilter.FIND_EDGES)
edge_stat = ImageStat.Stat(edges)
mean = float(luminance.mean[0])
stddev = float(luminance.stddev[0])
edge_mean = float(edge_stat.mean[0])
edge_stddev = float(edge_stat.stddev[0])
return {
"width": int(image.width),
"height": int(image.height),
"mode": image.mode,
"luminance_mean": round(mean, 6),
"luminance_stddev": round(stddev, 6),
"edge_mean": round(edge_mean, 6),
"edge_stddev": round(edge_stddev, 6),
"laplacian_variance": _laplacian_variance(grayscale),
"entropy": round(float(grayscale.entropy()), 6),
}
def _laplacian_variance(grayscale: Any) -> float | None:
try:
import numpy as np
except ImportError:
return None
array = np.asarray(grayscale, dtype=np.float32)
if array.size == 0 or array.ndim != 2 or array.shape[0] < 3 or array.shape[1] < 3:
return None
center = array[1:-1, 1:-1] * -4.0
laplacian = center + array[:-2, 1:-1] + array[2:, 1:-1] + array[1:-1, :-2] + array[1:-1, 2:]
return round(float(laplacian.var()), 6)
def _resolve_capture_artifact_path(path_value: str, base_dir: Path) -> Path:
path = Path(path_value)
if path.is_absolute():
return path
if path.exists():
return path
return base_dir / path
def _audit_capture_operations(
metadata: dict[str, Any],
policy: dict[str, int | float | bool | None],
issues: list[str],
warnings: list[str],
) -> None:
operations = metadata.get("operations")
if not isinstance(operations, list) or not operations:
return
operation_names: list[str] = []
auto_detect_operations: list[dict[str, Any]] = []
auto_deskew_operations: list[dict[str, Any]] = []
for index, operation in enumerate(operations):
if not isinstance(operation, dict):
issues.append(f"capture operation {index} must be an object")
continue
name = operation.get("operation")
if not isinstance(name, str) or not name:
issues.append(f"capture operation {index} missing operation name")
continue
operation_names.append(name)
if name == "auto_deskew":
auto_deskew_operations.append(operation)
_audit_auto_deskew_operation(operation, index, issues)
elif name == "auto_detect_page":
auto_detect_operations.append(operation)
if "quad" not in operation or "area_ratio" not in operation:
issues.append(f"capture operation {index} auto_detect_page missing quad or area_ratio")
if operation.get("touches_image_border") is True:
message = f"capture operation {index} auto_detect_page touches image border; source may be clipped or include background"
if policy.get("fail_on_auto_detect_page_border_touch") is True:
issues.append(message)
else:
warnings.append(message)
threshold = policy.get("min_auto_detect_page_area_ratio")
if threshold is not None:
area_ratio = operation.get("area_ratio")
if not isinstance(area_ratio, int | float):
issues.append(f"capture operation {index} auto_detect_page missing numeric area_ratio")
elif float(area_ratio) < float(threshold):
issues.append(
"capture operation "
f"{index} auto_detect_page area_ratio below policy threshold: "
f"area_ratio={area_ratio!r} minimum={threshold!r}"
)
elif name == "perspective_rectify":
if "quad" not in operation or "size" not in operation:
issues.append(f"capture operation {index} perspective_rectify missing quad or size")
if operation_names and operation_names[0] != "raw_copy":
issues.append(f"first capture operation must be raw_copy, got {operation_names[0]!r}")
if "exif_transpose" not in operation_names:
warnings.append("capture operations do not include exif_transpose")
if "auto_detect_page" in operation_names and "perspective_rectify" not in operation_names:
issues.append("auto_detect_page operation must be followed by perspective_rectify")
if policy.get("require_auto_detect_page") is True and not auto_detect_operations:
issues.append("capture operation policy requires auto_detect_page")
if policy.get("min_auto_detect_page_area_ratio") is not None and not auto_detect_operations:
issues.append("capture operation policy requires auto_detect_page for min_auto_detect_page_area_ratio")
if policy.get("require_auto_deskew_applied") is True:
if not auto_deskew_operations:
issues.append("capture operation policy requires auto_deskew")
elif not any(operation.get("status") == "applied" for operation in auto_deskew_operations):
issues.append("capture operation policy requires applied auto_deskew")
max_abs_angle = policy.get("max_abs_auto_deskew_degrees")
if max_abs_angle is not None:
if not auto_deskew_operations:
issues.append("capture operation policy requires auto_deskew for max_abs_auto_deskew_degrees")
for index, operation in enumerate(operations):
if not isinstance(operation, dict) or operation.get("operation") != "auto_deskew" or operation.get("status") != "applied":
continue
angle = operation.get("applied_rotation_degrees")
if not isinstance(angle, int | float):
issues.append(f"capture operation {index} auto_deskew missing numeric applied_rotation_degrees")
elif abs(float(angle)) > float(max_abs_angle):
issues.append(
"capture operation "
f"{index} auto_deskew angle above policy threshold: "
f"applied_rotation_degrees={angle!r} maximum_abs={max_abs_angle!r}"
)
def _audit_auto_deskew_operation(operation: dict[str, Any], index: int, issues: list[str]) -> None:
status = operation.get("status")
if status not in {"applied", "skipped"}:
issues.append(f"capture operation {index} auto_deskew status must be applied or skipped")
return
if status == "applied":
angle = operation.get("applied_rotation_degrees")
max_degrees = operation.get("max_degrees")
if not isinstance(angle, int | float):
issues.append(f"capture operation {index} auto_deskew missing numeric applied_rotation_degrees")
if not isinstance(max_degrees, int | float):
issues.append(f"capture operation {index} auto_deskew missing numeric max_degrees")
elif isinstance(angle, int | float) and abs(float(angle)) > float(max_degrees):
issues.append(f"capture operation {index} auto_deskew angle exceeds max_degrees")
elif not operation.get("reason"):
issues.append(f"capture operation {index} skipped auto_deskew requires reason")
def _write_limbu_capture_audit(report: dict[str, Any], output_dir: Path) -> None:
output_dir.mkdir(parents=True, exist_ok=True)
(output_dir / "limbu-capture-audit.json").write_text(
json.dumps(report, ensure_ascii=False, indent=2) + "\n",
encoding="utf-8",
)
lines = [
"# Limbu Capture Audit",
"",
f"Metadata: `{report.get('metadata_path')}`",
f"Passed: `{'yes' if report.get('passed') else 'no'}`",
"",
"## Issues",
"",
]
issues = report.get("issues")
if isinstance(issues, list) and issues:
lines.extend(f"- {issue}" for issue in issues)
else:
lines.append("- none")
lines.extend(["", "## Warnings", ""])
warnings = report.get("warnings")
if isinstance(warnings, list) and warnings:
lines.extend(f"- {warning}" for warning in warnings)
else:
lines.append("- none")
lines.append("")
(output_dir / "limbu-capture-audit.md").write_text("\n".join(lines), encoding="utf-8")
def _validate_crop_box(crop_box: tuple[int, int, int, int], image_size: tuple[int, int]) -> None:
left, top, right, bottom = crop_box
width, height = image_size
if left < 0 or top < 0 or right > width or bottom > height:
raise DataValidationError(f"crop box {list(crop_box)} is outside image bounds {list(image_size)}")
if right <= left or bottom <= top:
raise DataValidationError(f"crop box must have positive width and height: {list(crop_box)}")
def _validate_perspective_quad(quad: PerspectiveQuad, image_size: tuple[int, int]) -> None:
width, height = image_size
unique_points = set(quad)
if len(unique_points) != 4:
raise DataValidationError(f"perspective quad must contain four unique points: {quad!r}")
for x, y in quad:
if x < 0 or y < 0 or x >= width or y >= height:
raise DataValidationError(f"perspective quad point {[x, y]} is outside image bounds {list(image_size)}")
output_width, output_height = _perspective_output_size(quad)
if output_width < 8 or output_height < 8:
raise DataValidationError(
f"perspective quad output is too small for OCR: width={output_width} height={output_height}"
)
def _rectify_perspective(image: Any, quad: PerspectiveQuad) -> tuple[Any, tuple[int, int]]:
try:
import cv2
import numpy as np
except ImportError as exc:
raise EngineUnavailableError("OpenCV and NumPy are required for perspective rectification") from exc
output_width, output_height = _perspective_output_size(quad)
rgb_image = image.convert("RGB")
source_points = np.array(quad, dtype="float32")
target_points = np.array(
[
[0, 0],
[output_width - 1, 0],
[output_width - 1, output_height - 1],
[0, output_height - 1],
],
dtype="float32",
)
matrix = cv2.getPerspectiveTransform(source_points, target_points)
warped = cv2.warpPerspective(
np.array(rgb_image),
matrix,
(output_width, output_height),
flags=cv2.INTER_CUBIC,
borderMode=cv2.BORDER_CONSTANT,
borderValue=(255, 255, 255),
)
from PIL import Image
return Image.fromarray(warped), (output_width, output_height)
def _detect_page_quad(image: Any) -> tuple[PerspectiveQuad, float, str]:
try:
import cv2
import numpy as np
except ImportError as exc:
raise EngineUnavailableError("OpenCV and NumPy are required for automatic page detection") from exc
rgb_image = image.convert("RGB")
array = np.array(rgb_image)
gray = cv2.cvtColor(array, cv2.COLOR_RGB2GRAY)
blurred = cv2.GaussianBlur(gray, (5, 5), 0)
edges = cv2.Canny(blurred, 50, 150)
contours, _hierarchy = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
image_area = max(1.0, float(rgb_image.width * rgb_image.height))
candidates: list[tuple[float, Any]] = []
for contour in contours:
area = float(cv2.contourArea(contour))
if area / image_area < 0.05:
continue
perimeter = cv2.arcLength(contour, True)
approx = cv2.approxPolyDP(contour, 0.02 * perimeter, True)
if len(approx) != 4 or not cv2.isContourConvex(approx):
continue
candidates.append((area, approx.reshape(4, 2)))
if not candidates:
return _detect_light_page_quad(rgb_image, cv2=cv2, np=np)
area, points = max(candidates, key=lambda item: item[0])
ordered = _order_quad_points(points, image_size=rgb_image.size)
_validate_perspective_quad(ordered, rgb_image.size)
return ordered, area / image_area, "edge_contour_quad"
def _detect_light_page_quad(image: Any, *, cv2: Any, np: Any) -> tuple[PerspectiveQuad, float, str]:
"""Fallback for phone captures where the paper edge is not a closed Canny contour.
The target capture domain often has a white textbook/newspaper page on a
laptop or table, with one or more sheet edges cut off by the photo boundary.
In that case the stricter four-corner contour detector correctly refuses the
image, but the runner still needs a bounded crop/rectification candidate and
an explicit warning. This fallback finds the dominant bright, low-saturation
region and uses its minimum-area rectangle as a conservative page candidate.
"""
array = np.array(image.convert("RGB"))
gray = cv2.cvtColor(array, cv2.COLOR_RGB2GRAY)
hsv = cv2.cvtColor(array, cv2.COLOR_RGB2HSV)
saturation = hsv[:, :, 1]
bright_threshold = max(110, int(np.percentile(gray, 55)))
mask = np.where((gray >= bright_threshold) & (saturation <= 90), 255, 0).astype("uint8")
close_kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (21, 21))
open_kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (9, 9))
mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, close_kernel, iterations=2)
mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, open_kernel, iterations=1)
contours, _hierarchy = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
image_area = max(1.0, float(image.width * image.height))
candidates: list[tuple[float, float, Any]] = []
for contour in contours:
area = float(cv2.contourArea(contour))
area_ratio = area / image_area
if area_ratio < 0.08:
continue
rect = cv2.minAreaRect(contour)
rect_width, rect_height = rect[1]
rect_area = max(1.0, float(rect_width * rect_height))
rectangularity = min(1.0, area / rect_area)
if rectangularity < 0.45:
continue
candidates.append((area_ratio, rectangularity, rect))
if not candidates:
raise DataValidationError("automatic page detection could not find a four-corner page contour")
area_ratio, _rectangularity, rect = max(candidates, key=lambda item: (item[0], item[1]))
points = cv2.boxPoints(rect)
ordered = _order_quad_points(points, image_size=image.size)
_validate_perspective_quad(ordered, image.size)
return ordered, area_ratio, "light_region_min_area_rect"
def _quad_touches_image_border(quad: PerspectiveQuad, image_size: tuple[int, int], *, margin: int = 4) -> bool:
width, height = image_size
for x, y in quad:
if x <= margin or y <= margin or x >= width - 1 - margin or y >= height - 1 - margin:
return True
return False
def _detect_skew_degrees(image: Any, *, max_degrees: float) -> float | None:
try:
import cv2
import numpy as np
except ImportError as exc:
raise EngineUnavailableError("OpenCV and NumPy are required for automatic deskew") from exc
gray = np.array(image.convert("L"))
if gray.size == 0:
return None
blurred = cv2.GaussianBlur(gray, (3, 3), 0)
thresholded = cv2.adaptiveThreshold(
blurred,
255,
cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
cv2.THRESH_BINARY_INV,
31,
15,
)
kernel_width = max(12, gray.shape[1] // 30)
horizontal_kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (kernel_width, 1))
horizontal = cv2.morphologyEx(thresholded, cv2.MORPH_OPEN, horizontal_kernel)
edges = cv2.Canny(horizontal, 50, 150)
min_line_length = max(20, gray.shape[1] // 8)
lines = cv2.HoughLinesP(
edges,
rho=1,
theta=np.pi / 180,
threshold=20,
minLineLength=min_line_length,
maxLineGap=max(8, gray.shape[1] // 40),
)
angles: list[float] = []
if lines is not None:
for raw_line in lines:
x1, y1, x2, y2 = [int(value) for value in raw_line[0]]
dx = x2 - x1
dy = y2 - y1
length = math.hypot(dx, dy)
if length < min_line_length:
continue
angle = math.degrees(math.atan2(dy, dx))
while angle <= -90:
angle += 180
while angle > 90:
angle -= 180
if angle > 45:
angle -= 90
elif angle < -45:
angle += 90
if abs(angle) <= max_degrees:
angles.append(angle)
if len(angles) < 3:
return _detect_projection_skew_degrees(thresholded, max_degrees=max_degrees, cv2=cv2, np=np)
median = float(np.median(np.array(angles, dtype="float32")))
if abs(median) < 0.05:
return None
return round(median, 3)
def _detect_projection_skew_degrees(binary_ink: Any, *, max_degrees: float, cv2: Any, np: Any) -> float | None:
height, width = binary_ink.shape[:2]
if height <= 0 or width <= 0:
return None
ys, xs = np.where(binary_ink > 0)
ink_pixels = int(len(xs))
if ink_pixels < max(50, int(width * height * 0.0005)):
return None
left = max(0, int(xs.min()) - 8)
right = min(width, int(xs.max()) + 9)
top = max(0, int(ys.min()) - 8)
bottom = min(height, int(ys.max()) + 9)
cropped = binary_ink[top:bottom, left:right]
crop_height, crop_width = cropped.shape[:2]
if crop_height < 20 or crop_width < 20:
return None
def score(angle: float) -> float:
center = (crop_width / 2.0, crop_height / 2.0)
matrix = cv2.getRotationMatrix2D(center, angle, 1.0)
rotated = cv2.warpAffine(
cropped,
matrix,
(crop_width, crop_height),
flags=cv2.INTER_NEAREST,
borderMode=cv2.BORDER_CONSTANT,
borderValue=0,
)
row_sums = np.count_nonzero(rotated > 0, axis=1).astype("float32")
if row_sums.size == 0:
return 0.0
total = float(row_sums.sum())
if total <= 0:
return 0.0
return float(np.sum(row_sums * row_sums) / total)
coarse_step = 0.5
coarse_angles = np.arange(-float(max_degrees), float(max_degrees) + coarse_step / 2.0, coarse_step)
coarse_scores = [(float(angle), score(float(angle))) for angle in coarse_angles]
if not coarse_scores:
return None
best_angle, best_score = max(coarse_scores, key=lambda item: item[1])
zero_score = score(0.0)
if best_score <= 0 or zero_score <= 0 or best_score < zero_score * 1.02:
return None
refine_start = max(-float(max_degrees), best_angle - coarse_step)
refine_stop = min(float(max_degrees), best_angle + coarse_step)
refine_step = 0.1
refined_angles = np.arange(refine_start, refine_stop + refine_step / 2.0, refine_step)
refined_scores = [(float(angle), score(float(angle))) for angle in refined_angles]
best_angle, best_score = max(refined_scores, key=lambda item: item[1])
if best_score < zero_score * 1.02 or abs(best_angle) < 0.05:
return None
return round(float(best_angle), 3)
def _order_quad_points(points: Any, *, image_size: tuple[int, int]) -> PerspectiveQuad:
width, height = image_size
pts = [(float(point[0]), float(point[1])) for point in points]
by_sum = sorted(pts, key=lambda point: point[0] + point[1])
top_left = by_sum[0]
bottom_right = by_sum[-1]
remaining = by_sum[1:3]
top_right, bottom_left = sorted(remaining, key=lambda point: point[0] - point[1], reverse=True)
def clamp(point: tuple[float, float]) -> tuple[int, int]:
x = min(max(0, int(round(point[0]))), width - 1)
y = min(max(0, int(round(point[1]))), height - 1)
return x, y
return (clamp(top_left), clamp(top_right), clamp(bottom_right), clamp(bottom_left))
def _perspective_output_size(quad: PerspectiveQuad) -> tuple[int, int]:
top_left, top_right, bottom_right, bottom_left = quad
width_top = _point_distance(top_left, top_right)
width_bottom = _point_distance(bottom_left, bottom_right)
height_left = _point_distance(top_left, bottom_left)
height_right = _point_distance(top_right, bottom_right)
output_width = max(1, int(round(max(width_top, width_bottom))))
output_height = max(1, int(round(max(height_left, height_right))))
return output_width, output_height
def _point_distance(first: tuple[int, int], second: tuple[int, int]) -> float:
return ((first[0] - second[0]) ** 2 + (first[1] - second[1]) ** 2) ** 0.5
def parse_crop_box(value: str | None) -> tuple[int, int, int, int] | None:
if value is None:
return None
parts = [part.strip() for part in value.split(",")]
if len(parts) != 4:
raise DataValidationError("crop box must be four comma-separated integers: left,top,right,bottom")
try:
return tuple(int(part) for part in parts) # type: ignore[return-value]
except ValueError as exc:
raise DataValidationError(f"crop box contains a non-integer value: {value}") from exc
def parse_perspective_quad(value: str | None) -> PerspectiveQuad | None:
if value is None:
return None
parts = [part.strip() for part in value.split(",")]
if len(parts) != 8:
raise DataValidationError(
"perspective quad must be eight comma-separated integers: "
"top_left_x,top_left_y,top_right_x,top_right_y,bottom_right_x,bottom_right_y,bottom_left_x,bottom_left_y"
)
try:
numbers = [int(part) for part in parts]
except ValueError as exc:
raise DataValidationError(f"perspective quad contains a non-integer value: {value}") from exc
return (
(numbers[0], numbers[1]),
(numbers[2], numbers[3]),
(numbers[4], numbers[5]),
(numbers[6], numbers[7]),
)
"""Capture preparation helpers for operational OCR runs."""
from __future__ import annotations
import json
import math
import platform
import shutil
import socket
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from .errors import DataValidationError, EngineUnavailableError
from .manifest import sha256_file
_SUPPORTED_CAPTURE_SUFFIXES = {".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tif", ".tiff"}
PerspectiveQuad = tuple[tuple[int, int], tuple[int, int], tuple[int, int], tuple[int, int]]
class CapturePrepResult:
source_path: str
raw_copy_path: str
prepared_image_path: str
metadata_path: str
source_sha256: str
prepared_sha256: str
operations: list[dict[str, Any]]
image_quality: dict[str, Any] | None = None
created_at_utc: str | None = None
run_context: dict[str, Any] | None = None
def to_dict(self) -> dict[str, Any]:
return {
"source_path": self.source_path,
"raw_copy_path": self.raw_copy_path,
"prepared_image_path": self.prepared_image_path,
"metadata_path": self.metadata_path,
"source_sha256": self.source_sha256,
"prepared_sha256": self.prepared_sha256,
"operations": self.operations,
"image_quality": self.image_quality or {},
"created_at_utc": self.created_at_utc,
"run_context": self.run_context or {},
}
def prepare_limbu_capture(
input_path: str | Path,
output_dir: str | Path,
*,
rotate_degrees: float = 0.0,
crop_box: tuple[int, int, int, int] | None = None,
perspective_quad: PerspectiveQuad | None = None,
auto_detect_page: bool = False,
auto_deskew: bool = False,
max_auto_deskew_degrees: float = 8.0,
autocontrast: bool = True,
grayscale: bool = True,
run_context: dict[str, Any] | None = None,
) -> CapturePrepResult:
source = Path(input_path)
if not source.is_file():
raise DataValidationError(f"capture input does not exist or is not a file: {source}")
if source.suffix.lower() not in _SUPPORTED_CAPTURE_SUFFIXES:
raise DataValidationError(f"unsupported capture image suffix: {source.suffix or '<none>'}")
if auto_detect_page and perspective_quad is not None:
raise DataValidationError("auto_detect_page cannot be combined with an explicit perspective_quad")
if max_auto_deskew_degrees <= 0 or max_auto_deskew_degrees > 45:
raise DataValidationError(f"max_auto_deskew_degrees must be > 0 and <= 45, got {max_auto_deskew_degrees}")
try:
from PIL import Image, ImageOps
except ImportError as exc:
raise EngineUnavailableError("Pillow is required for capture preparation") from exc
out = Path(output_dir)
raw_dir = out / "raw"
prepared_dir = out / "prepared"
raw_dir.mkdir(parents=True, exist_ok=True)
prepared_dir.mkdir(parents=True, exist_ok=True)
raw_copy = raw_dir / source.name
shutil.copy2(source, raw_copy)
operations: list[dict[str, Any]] = [{"operation": "raw_copy", "path": str(raw_copy)}]
try:
with Image.open(source) as image:
prepared = ImageOps.exif_transpose(image)
operations.append({"operation": "exif_transpose", "mode": prepared.mode, "size": list(prepared.size)})
if crop_box is not None:
_validate_crop_box(crop_box, prepared.size)
prepared = prepared.crop(crop_box)
operations.append({"operation": "crop", "box": list(crop_box), "size": list(prepared.size)})
if auto_detect_page:
detected_quad, area_ratio, detection_method = _detect_page_quad(prepared)
perspective_quad = detected_quad
operations.append(