WITAN

Witan Exec · Render · Calc · Lint · Alternatives · Pricing · Agent Skills · Install Witan

---

# Witan Render

High-fidelity rendering of any cell range in your spreadsheet.
Targeted & auto-scaled for vision models, with built-in pixel diffing.

Example: render a region of any .xlsx file

    $ witan xlsx render report.xlsx -r "Sheet1!A1:Z50"
    /var/folders/xx/.../witan-render-123456.png
    Sheet1!A1:Z50 | ~3328x1500px | dpr=2

## The alternative

LibreOffice headless is the standard rendering approach in most
spreadsheet agent skills. Here is how the two compare:

### LibreOffice

- ✗ Renders entire sheets as PDFs
- ✗ Requires 2GB install
- ✗ Diverges from Excel appearance
- ✗ No range targeting
- ✗ No diffing capability
- ✗ Slow startup per invocation

### Witan xlsx Render

- ✓ Renders specific cell ranges
- ✓ Zero local deps (single binary)
- ✓ Matches Excel appearance
- ✓ Built-in pixel diff
- ✓ Auto-scales for vision models
- ✓ Sub-second renders

The fundamental difference: LibreOffice renders a full sheet and
hopes the relevant part is visible. Witan renders exactly the range
your agent needs, at the right resolution for the vision model
consuming it.

## The rendering engine

The rendering engine reproduces Excel's visual output with full
formatting fidelity. This is the same engine that powers the Witan
spreadsheet viewer used by end users.

### Fills

- ✓ Solid fills
- ✓ Gradient fills (linear and path)
- ✓ All 17 pattern fill types
- ✓ Font colors

### Fonts

- ✓ Font families and sizes
- ✓ Bold, italic, underline, strikethrough
- ✓ Superscript and subscript
- ✓ Rich text (mixed formatting per cell)

### Alignment

- ✓ All 8 horizontal modes
- ✓ Center-across-selection spanning
- ✓ Fill repetition
- ✓ Text rotation (-90° to +90°)
- ✓ Wrap text
- ✓ Shrink to fit
- ✓ Indent levels

### Borders

- ✓ All 4 edges + diagonals
- ✓ All Excel border styles: hair, dotted, dashed, dash-dot, dash-dot-dot, thin, medium, medium-dashed, medium-dash-dot, medium-dash-dot-dot, thick, double, slant-dash-dot
- ✓ Border colors

### Layout

- ✓ Merged cells
- ✓ Hidden rows and columns
- ✓ Custom row heights and column widths
- ✓ Text overflow into adjacent empty cells

### Number formatting

- ✓ All Excel format patterns
- ✓ Fractions and scientific notation
- ✓ Accounting and currency formats
- ✓ 150+ locale-aware built-in formats
- ✓ 4-section conditional formats with color directives
- ✓ 5 date systems

### Conditional formatting

- ✓ 8 comparison operators (equal, not equal, greater than, less than, between, not between, etc.)
- ✓ 4 text rules (contains, not contains, begins with, ends with)
- ✓ 4 blank/error rules
- ✓ Expression-based rules
- ✓ 10 time period rules
- ✓ 6 statistical rules (above/below average and standard deviations)
- ✓ 4 top/bottom rules (top N, bottom N, top N%, bottom N%)
- ✓ Unique and duplicate value rules
- ✓ 2-color and 3-color scales
- ✗ Data bars (not yet supported)
- ✗ Icon sets (not yet supported)

### Drawings

- ✓ Images (PNG, JPEG, BMP, GIF)
- ✓ Shapes: rectangle, ellipse, rounded rectangle, line
- ✓ Shape fill, border, and text content
- ✓ Z-order preserved
- ✓ Rotation and flip transforms

## Targeted rendering

Full-sheet screenshots waste tokens. Most of the pixels are
irrelevant cells. The rendering engine targets exactly the region
you specify:

    witan xlsx render report.xlsx -r "Sheet1!A1:Z50"

Any valid sheet-qualified range can be rendered. Practical limits are
based on output size (65,535px per side, 100MP total), so if a render
fails, reduce the range and/or DPR.

### Auto DPR scaling

The --dpr flag controls the device pixel ratio (1x, 2x, or 3x).
When omitted, it defaults to auto: the engine estimates pixel
dimensions from the range and picks the highest DPR that keeps the
image under 1568px on its longest side — the recommended maximum
for vision models like GPT-4o and Claude.

For small ranges, auto selects 2x for sharp text. For larger ranges,
it drops to 1x to avoid exceeding vision model limits. You can
always override with an explicit value.

### Output

PNG (default) or WebP. PNG is required for the --diff workflow.

    Sheet1!A1:Z50 | ~3328x1500px | dpr=2

## Pixel diff

When your agent edits a spreadsheet, it needs to verify that only the
intended cells changed. The --diff flag compares the current render
against a baseline and produces a visual diff image.

### The workflow

1. Save a baseline before editing.

    witan xlsx render report.xlsx -r "Sheet1!A1:F20" -o before.png

2. Edit the spreadsheet with your tools (openpyxl, pandas, xlwings, etc.).

3. Diff against the baseline to see what changed.

    witan xlsx render report.xlsx -r "Sheet1!A1:F20" --diff before.png

### How the diff works

The diff image shows:

- Changed pixels at full color, with a black-and-white double-stroke outline for visibility
- Unchanged areas desaturated and dimmed to gray

The metadata line includes a diff summary:

    /var/folders/xx/.../witan-render-654321.png
    Sheet1!A1:F20 | ~768x600px | dpr=2 | diff: 1,204 pixels changed (3.2%)

If nothing changed:

    Sheet1!A1:F20 | ~768x600px | dpr=2 | diff: no changes

Tip: The diff requires both images to have identical dimensions. Use
the same --range and --dpr for both the baseline and the comparison
render.

## CLI reference

    witan xlsx render <file> [flags]

| Flag | Description | Default |
|------|-------------|---------||
| -r, --range | Sheet-qualified range to render. Required. | |
| --dpr | Device pixel ratio (1, 2, or 3). Controls image resolution. | Auto |
| --format | Image format: png or webp. | .png |
| -o, --output | Output file path. If omitted, writes to a temp file. | Temp file |
| --diff | Path to a baseline PNG image. Outputs a pixel-diff highlight. Requires --format png. | |

### Output format

Every invocation prints two lines to stdout:

    <image-path>
    <range> | ~<width>x<height>px | dpr=<n>

When --diff is used, the metadata line appends a diff summary:

    <image-path>
    <range> | ~<width>x<height>px | dpr=<n> | diff: <count> pixels changed (<percent>%)

If the rendered image exceeds 1568px on either axis, a warning is printed:

    Warning: Image exceeds 1568px. Vision models may downscale, reducing detail. Consider a smaller --range.

### Usage examples

    # Basic render
    witan xlsx render report.xlsx -r "Sheet1!A1:Z50"

    # High-res render of a small table
    witan xlsx render report.xlsx -r "Sheet1!B2:F10" --dpr 3

    # Save to a specific path
    witan xlsx render report.xlsx -r "Sheet1!A1:M30" -o output/table.png

    # WebP output
    witan xlsx render report.xlsx -r "Sheet1!A1:Z50" --format webp

    # Baseline + diff workflow
    witan xlsx render report.xlsx -r "Sheet1!A1:F20" -o before.png
    # ... edit the spreadsheet ...
    witan xlsx render report.xlsx -r "Sheet1!A1:F20" --diff before.png

---

© Witan Labs Inc. 2026
hello@witanlabs.com · API Docs · GitHub · Research · Terms · Privacy