---
name: excel-screenshot
description: "Capture a live Excel range as a PNG using the COM clipboard method, then verify it visually."
---

## Taking Screenshots of Spreadsheet Ranges

The reliable way to get a PNG of a live Excel range:

1. In `execute_code`, copy the range as a picture to the clipboard:
   ```python
   ws._ws.Range("B2:G11").CopyPicture(Appearance=1, Format=2)  # xlScreen, xlBitmap
   ```
   (add a short sleep, ~0.5–1s, after the copy)
2. In a separate bash/Python step, grab it from the clipboard and save:
   ```python
   from PIL import ImageGrab
   img = ImageGrab.grabclipboard()
   img.convert("RGB").save(r"C:\path\out.png")
   ```
3. Verify it isn't blank: `img.convert("RGB").getextrema()` should span beyond pure
   white `(255,255,255)` or pure black `(0,0,0)`.

**What does NOT work reliably:** the chart-export route
(`ChartObjects.Add` → `Chart.Paste()` → `Chart.Export()`). The paste races the
clipboard and silently produces all-white or all-black images even with sleeps.
Avoid it.

### When to use screenshots

- Verifying visual formatting (colors, fonts, alignment, borders)
- Complex layouts, merged cells, conditional formatting, charts, sparklines
- Visual fidelity / "what the user sees" checks and printed-output appearance

### When NOT to use

- Reading cell values or data — read the cells directly instead
- As a substitute for code execution
- Extracting exact hex colors — vision models only approximate them

### Best practices

- Keep ranges small and legible (~40 rows × 10 cols max); large ranges crop or blur.
- Always validate the image (pixel extrema or a quick vision check) before trusting it —
  blank/cropped renders are common.
- To inspect the saved PNG, hand it to a vision model with a specific question; it
  answers only from what it sees.
