Function _classify_visual_quality

scripts/extract_pdf_assets.py:136–212

Classify whether a caption-matched crop is visually usable. This is intentionally conservative. A label/caption match proves identity, but not that the rendered crop contains the figure or table body.

(
    *,
    kind: str,
    page_coverage_ratio: float,
    visual_rect_count: int,
    visual_body_ratio: float,
    paragraph_text_chars: int,
    table_body_rows: int,
    caption_text_chars: int,
    other_caption_labels: list[str] | None = None,
)

def _classify_visual_quality(
    *,
    kind: str,
    page_coverage_ratio: float,
    visual_rect_count: int,
    visual_body_ratio: float,
    paragraph_text_chars: int,
    table_body_rows: int,
    caption_text_chars: int,
    other_caption_labels: list[str] | None = None,
) -> dict:
    """Classify whether a caption-matched crop is visually usable.

    This is intentionally conservative. A label/caption match proves identity,
    but not that the rendered crop contains the figure or table body.
    """
    normalized_kind = kind.strip().lower()
    other_caption_labels = list(other_caption_labels or [])
    reasons: list[str] = []

    if normalized_kind == "table":
        text_per_table_row = paragraph_text_chars / max(1, table_body_rows)
        if table_body_rows <= 0:
            reasons.append("table_body_missing")
        if table_body_rows <= 1 and visual_body_ratio < 0.03 and caption_text_chars >= 40:
            reasons.append("caption_only_suspected")
        # Dense tables naturally contain many text spans. Treat prose-like text
        # as contamination when table structure is weak or the text density is
        # far higher than the detected table body can explain.
        if paragraph_text_chars >= 450 and (
            table_body_rows <= 2
            or (paragraph_text_chars >= 900 and visual_body_ratio <= 0.03 and text_per_table_row > 90)
            or text_per_table_row > 140
        ):
            reasons.append("table_text_contamination_suspected")
        if other_caption_labels:
            reasons.append("multiple_caption_regions_suspected")
        status = "reject" if reasons else "usable"
    else:
        if other_caption_labels:
            reasons.append("multiple_caption_regions_suspected")
        visual_dominant = visual_rect_count >= 3 and visual_body_ratio >= 0.18
        if paragraph_text_chars >= 450 and not visual_dominant:
            reasons.append("large_text_block_suspected")
        if page_coverage_ratio >= 0.70 and paragraph_text_chars >= 250:
            reasons.append("oversized_page_crop")
        if visual_rect_count <= 1 and visual_body_ratio < 0.03:
            reasons.append("low_visual_body_ratio")
        if any(
            code in reasons
            for code in (
                "multiple_caption_regions_suspected",
                "large_text_block_suspected",
                "oversized_page_crop",
                "low_visual_body_ratio",
            )
        ):
            status = "reject"