feat: add image_bbox_to_pdf helper for image-pixel to PDF table_areas

[mvanhorn]

Summary

Users who detect table regions with an external image-based tool (Table Transformers, a pdf2image + detector pipeline, etc.) get bounding boxes in image-pixel space and can now convert them into PDF-space table_areas with a single call: camelot.image_bbox_to_pdf(bbox, image_size, pdf_size).

Why this matters

Issue #377 asks how to feed image-pixel bounding boxes to read_pdf(table_areas=...). Camelot already fully supports manual table-area selection; as bosd (COLLABORATOR) confirmed on 2026-05-21, the only missing piece is the coordinate conversion. Image space and PDF space differ in two ways: the origin (image is top-left, PDF is bottom-left) and the units (pixels vs points). Bridging them needs a y-axis flip plus an x/y scale by the page-to-image ratio. There was no public helper for this, and the internal scale_image requires a precomputed factors tuple and is not exposed for this purpose.

Changes

• camelot/utils.py: new public image_bbox_to_pdf(bbox, image_size, pdf_size, as_string=False). Reuses the existing scale/translate primitives, scales x by pdf_w/img_w and y by pdf_h/img_h, and flips the y-axis so the returned (x1, y1, x2, y2) has bottom-left origin with y1 > y2 - exactly what bbox_from_str and read_pdf(table_areas=...) expect. as_string=True returns the "x1,y1,x2,y2" form for direct use as a table_areas entry. Raises a clear ValueError on a zero/negative image or PDF dimension, or a zero-width/zero-height pixel bbox.
• camelot/__init__.py: export the helper as camelot.image_bbox_to_pdf.
• tests/test_utils.py: coverage for the happy path (300 DPI US-Letter), identity scale (y-flip only), string round-trip through bbox_from_str, top/bottom edge mapping, independent non-square x/y scaling, and the degenerate-input error paths.

Testing

• pytest tests/test_utils.py -> 18 passed
• ruff check and ruff format --check on the changed files -> clean

Fixes #377

[bosd]

Thanks @mvanhorn — this is a clean, useful helper for the recurring image-pixel↔PDF-coordinate confusion (#377/#780). Reviewed:

• Correctly reuses the existing scale/translate utils and returns coords in the (x1, y1, x2, y2) top-left/bottom-right convention that table_areas + bbox_from_str expect. I traced the y-flip: top = pdf_h - scale(min_y), bottom = pdf_h - scale(max_y), so top > bottom — matches PDF space. ✓
• Good input validation (positive image/PDF dims, non-zero bbox) with clear messages.
• as_string=True round-trips through bbox_from_str, and it's exported at camelot.image_bbox_to_pdf. Tests cover 300-dpi letter, identity-scale flip, and the string round-trip.

CI is fully green. LGTM — nice addition. (Would pair well with a short note in the advanced.rst 'Specify table areas' section, but that can be a follow-up.)