feat: add debug module with PageImage for visualization (#18)

* feat: add debug module with PageImage for visualization

* feat: support string color names and RGBA tuples in debug methods

* fix: fix lint errors in debug module

Author: monchin

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add `Page.page_idx` property: zero-based index of the page within its document
 - Add `Page.rotation_degrees` property: clockwise rotation of the page in degrees
 - Add `Page.clear_cache()` method as the canonical name for clearing cached objects
+- Add `tablers.debug` module with `PageImage` class for visualizing detected tables and edges on a rendered page image; requires the optional `debug` extra (`pip install tablers[debug]`)
 
 ### Changed
 

docs/getting_started/installation.md

@@ -18,6 +18,18 @@ The recommended way to install Tablers is via pip:
 pip install tablers
 ```
 
+## Optional Dependencies
+
+### Debug / Visualization
+
+The `tablers.debug` module provides tools for visualizing detected tables, edges, and intersection points on a rendered page image. It requires two additional packages:
+
+```bash
+pip install tablers[debug]
+```
+
+This installs `pillow` and `pypdfium2` alongside Tablers. If these packages are not present, importing `tablers.debug` will raise an `ImportError`.
+
 ## Building from Source
 
 If you need to build Tablers from source, follow these steps:

docs/reference/api.md

@@ -548,3 +548,137 @@ v_edge = Edge("v", 50.0, 0.0, 50.0, 100.0, width=2.0, color=(255, 0, 0, 255))
 | `Point` | `tuple[float, float]` | A 2D point (x, y) |
 | `BBox` | `tuple[float, float, float, float]` | Bounding box (x1, y1, x2, y2) |
 | `Color` | `tuple[int, int, int, int]` | RGBA color (0-255 each) |
+
+---
+
+## Debug Module (`tablers.debug`)
+
+!!! note "Optional dependency"
+    The debug module requires the `debug` extra. Install it with:
+    ```bash
+    pip install tablers[debug]
+    ```
+
+### PageImage
+
+Renders a PDF page to a PIL image and provides drawing primitives for annotating detected tables, edges, and intersection points.
+
+```python
+from tablers.debug import PageImage
+
+class PageImage:
+    def __init__(
+        self,
+        page: Page,
+        original: PIL.Image.Image | None = None,
+        resolution: int | float = 72,
+        antialias: bool = False,
+    )
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | `Page` | - | The page to render |
+| `original` | `Optional[PIL.Image.Image]` | `None` | Pre-rendered image. If `None`, the page is rendered at the given resolution |
+| `resolution` | `Union[int, float]` | `72` | Rendering resolution in DPI |
+| `antialias` | `bool` | `False` | Enable anti-aliasing during rendering |
+
+**Raises:** `RuntimeError` — If `original` is `None` and the document has already been closed.
+
+!!! note "Password-protected PDFs"
+    PageImage rendering supports only documents **without a password**. For password-protected PDFs, use `Document.save_to_bytes()` to obtain a decrypted copy, then open it with `Document(bytes=...)` and pass the resulting page to PageImage.
+
+**Attributes:**
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `original` | `PIL.Image.Image` | The unmodified rendered page image |
+| `annotated` | `PIL.Image.Image` | The working copy with all annotations applied |
+| `scale` | `float` | Ratio of image pixels to page points (`image_width / page_width`) |
+| `bbox` | `BBox` | Page coordinate space: `(0, 0, page.width, page.height)` |
+| `resolution` | `Union[int, float]` | The DPI used for rendering |
+
+**Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `reset()` | `PageImage` | Discard all annotations and restore `annotated` to `original` |
+| `copy()` | `PageImage` | Return a new `PageImage` sharing the same `original` but with an independent `annotated` copy |
+| `save(dest, format, quantize, colors, bits, **kwargs)` | `None` | Save the annotated image to a file path or `BytesIO` |
+| `show()` | `None` | Display the annotated image (calls `PIL.Image.show`) |
+| `_repr_png_()` | `bytes` | Return PNG bytes for Jupyter notebook inline display |
+
+**Drawing methods** (all return `self` for chaining):
+
+| Method | Description |
+|--------|-------------|
+| `draw_line(points, stroke, stroke_width)` | Draw a polyline. Accepts a tuple or list of two `(x, y)` points |
+| `draw_lines(list_of_lines, stroke, stroke_width)` | Draw multiple lines |
+| `draw_vline(location, stroke, stroke_width)` | Draw a vertical line spanning the full page height at `x = location` |
+| `draw_vlines(locations, stroke, stroke_width)` | Draw multiple vertical lines |
+| `draw_hline(location, stroke, stroke_width)` | Draw a horizontal line spanning the full page width at `y = location` |
+| `draw_hlines(locations, stroke, stroke_width)` | Draw multiple horizontal lines |
+| `draw_rect(bbox, fill, stroke, stroke_width)` | Draw a filled rectangle. Accepts a 4-tuple bbox `(x1, y1, x2, y2)` |
+| `draw_rects(list_of_rects, fill, stroke, stroke_width)` | Draw multiple rectangles |
+| `draw_circle(center, radius, fill, stroke)` | Draw a circle. Accepts a `(cx, cy)` center tuple |
+| `draw_circles(list_of_circles, radius, fill, stroke)` | Draw multiple circles |
+| `debug_table(table, fill, stroke, stroke_width)` | Draw a filled rectangle over every cell in a `Table` |
+| `debug_tablefinder(tf_settings, **kwargs)` | Draw all detected tables (cell outlines) and detected edges |
+
+**Color arguments** (`fill`, `stroke` in the methods above): accept either an RGBA tuple `(r, g, b, a)` or a string. String colors are resolved via PIL's [`ImageColor.getrgb`](https://pillow.readthedocs.io/en/stable/reference/ImageColor.html). For the list of supported string formats, see the [ImageColor reference](https://pillow.readthedocs.io/en/stable/reference/ImageColor.html). Alpha is set to 255 (opaque) for string colors; for transparency use an RGBA tuple.
+
+**Default color constants** (importable from `tablers.debug`):
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `DEFAULT_FILL` | `(0, 0, 255, 50)` | Semi-transparent blue fill |
+| `DEFAULT_STROKE` | `(255, 0, 0, 200)` | Near-opaque red stroke |
+| `DEFAULT_STROKE_WIDTH` | `1` | Stroke width in pixels |
+| `DEFAULT_RESOLUTION` | `72` | Default rendering DPI |
+
+**Example — visualize table detection in Jupyter:**
+
+```python
+from tablers import Document
+from tablers.debug import PageImage
+
+with Document("example.pdf") as doc:
+    page = doc.get_page(0)
+    img = PageImage(page, resolution=150)
+
+    # Draw tables, edges, and intersection points in one call
+    img.debug_tablefinder()
+
+    # Display inline (Jupyter auto-calls _repr_png_)
+    img
+```
+
+**Example — annotate and save:**
+
+```python
+from tablers import Document, find_tables
+from tablers.debug import PageImage
+
+with Document("example.pdf") as doc:
+    page = doc.get_page(0)
+    tables = find_tables(page, extract_text=False)
+
+    img = PageImage(page)
+    for table in tables:
+        img.debug_table(table)
+    img.save("annotated.png", quantize=False)
+```
+
+**Example — method chaining:**
+
+```python
+img = (
+    PageImage(page)
+    .draw_hline(200.0)
+    .draw_vline(300.0)
+    .debug_tablefinder()
+)
+img.save("debug.png", quantize=False)
+```

docs/usage/advanced.md

@@ -401,6 +401,92 @@ except RuntimeError as e:
     print(f"Runtime error: {e}")
 ```
 
+## Visualizing Table Detection
+
+The optional `tablers.debug` module lets you render a page to an image and annotate it with detected tables, edges, and intersection points. Install the extra dependencies first:
+
+```bash
+pip install tablers[debug]
+```
+
+Rendering supports only **documents without a password**. For password-protected PDFs, use `Document.save_to_bytes()` to get a decrypted copy, then open it with `Document(bytes=...)` and pass the resulting page to `PageImage`.
+
+### Quick Visual Debug
+
+`debug_tablefinder()` renders all detection results in one call: cell outlines (blue fill, red border) and detected edges (red lines). You can pass custom colors to `debug_table()` and the drawing methods; `fill` and `stroke` accept either RGBA tuples or strings. For supported string color formats, see the [PIL ImageColor reference](https://pillow.readthedocs.io/en/stable/reference/ImageColor.html).
+
+```python
+from tablers import Document
+from tablers.debug import PageImage
+
+with Document("example.pdf") as doc:
+    page = doc.get_page(0)
+    img = PageImage(page, resolution=150)
+    img.debug_tablefinder()
+
+    # Save to file
+    img.save("debug.png", quantize=False)
+
+    # Or display inline in Jupyter (auto-detected via _repr_png_)
+    img
+```
+
+Pass `TfSettings` or keyword arguments to use non-default detection settings:
+
+```python
+img.debug_tablefinder(vertical_strategy="lines", horizontal_strategy="text")
+```
+
+### Annotating Individual Tables
+
+Use `debug_table()` to annotate specific tables, or combine it with other drawing methods. Color arguments (`fill`, `stroke`) accept RGBA tuples or strings; for supported string formats see the [PIL ImageColor reference](https://pillow.readthedocs.io/en/stable/reference/ImageColor.html).
+
+```python
+from tablers import Document, find_tables
+from tablers.debug import PageImage
+
+with Document("example.pdf") as doc:
+    page = doc.get_page(0)
+    tables = find_tables(page, extract_text=False)
+
+    img = PageImage(page)
+
+    # Annotate all tables individually (optional: custom colors; same as default blue/red here)
+    for table in tables:
+        img.debug_table(table, fill="blue", stroke="red")
+
+    img.save("tables.png", quantize=False)
+```
+
+### Drawing Primitives
+
+`PageImage` provides low-level drawing helpers that all return `self` for chaining:
+
+```python
+img = (
+    PageImage(page)
+    .draw_hline(200.0)                        # horizontal guide line
+    .draw_vline(300.0)                        # vertical guide line
+    .draw_rect((50, 100, 250, 400))           # arbitrary bbox
+    .draw_circle((150.0, 250.0), radius=5)    # point of interest
+)
+img.save("annotated.png", quantize=False)
+```
+
+### Resetting and Copying
+
+```python
+img = PageImage(page)
+img.debug_tablefinder()
+
+# Remove all annotations and start fresh
+img.reset()
+
+# Create an independent copy to try different annotations
+img2 = img.copy()
+img2.debug_tablefinder(vertical_strategy="text")
+```
+
 ## Next Steps
 
 - See [Settings Reference](../reference/settings.md) for all configuration options