> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# .xlsx to PNG

A picture shows cells as the Copy Picture command in Microsoft Excel shows them: the cells as on screen, with charts and pictures. It does not show the selection or the frozen-pane lines. It shows row and column headers only when you set `labels: true` (see [Labels](#labels)).

You can make a picture in Node and in the browser:

| Where | Use | You get |
| - | - | - |
| Node | `book.toPng()` | One PNG for each sheet, or one PNG of a range |
| Node or browser | `range.getImage()` | Base64 PNG of one range, from the JS API |
| Browser, with a view | `view.rangeImage()` | A `Blob` of one range, with the column widths the user sees |

## In Node

`toPng` needs `skia-canvas` and `@reductoai/portable-fonts` (see [Installation](https://docs.reducto.ai/office/xlsx/getting-started/installation.md)).

### Every sheet

With no options, `toPng` makes one PNG for each visible sheet. Each picture holds the sheet's used cells, from A1.

```ts theme={null}
import { writeFile } from "node:fs/promises";
import { ExcelWorkbook } from "@reductoai/xlsx/node";

const book = await ExcelWorkbook.open("model.xlsx");
for (const { sheet, png, width, height } of await book.toPng({ scale: 2 })) {
  await writeFile(`${sheet}.png`, png);
  console.log(sheet, width, height);
}
```

Each entry is `{ sheet, width, height, png }`. `png` is a `Buffer`. `width` and `height` are in pixels.

### One sheet

Give the sheet names or zero-based indexes in `sheets`. Hidden sheets are included when you name them.

```ts theme={null}
import { writeFile } from "node:fs/promises";
import { ExcelWorkbook } from "@reductoai/xlsx/node";

const book = await ExcelWorkbook.open("model.xlsx");
const [summary] = await book.toPng({ sheets: ["Summary"] });
await writeFile("summary.png", summary!.png);
```

### One range

Give an A1 range in `range`. Put the sheet name before `!`, and `toPng` returns one entry. Without a sheet name, `toPng` makes a picture of that range on each sheet in `sheets`, or on each visible sheet.

```ts theme={null}
import { writeFile } from "node:fs/promises";
import { ExcelWorkbook } from "@reductoai/xlsx/node";

const book = await ExcelWorkbook.open("model.xlsx");
const [table] = await book.toPng({ range: "Summary!A1:H30", scale: 2 });
await writeFile("table.png", table!.png);
```

> [!TIP]
>
> To check an edit by eye, make a picture of only the range you changed.

### Options

| Option | Default | Notes |
| - | - | - |
| `sheets` | every visible sheet | Sheet names or zero-based indexes |
| `range` | each sheet's used cells | One A1 range, such as `"Summary!A1:H30"`. With a sheet name, `sheets` is not used |
| `gridlines` | `false` | `true` paints the gridlines. Excel's Copy Picture and print do not paint them |
| `labels` | `false` | `true` adds column letters and row numbers (see [Labels](#labels)) |
| `scale` | `1` | Image pixels for each sheet pixel: `2` for a sharp image, `0.25` for a thumbnail |

## From the JS API

`range.getImage()` returns a Base64 PNG of the range, at one image pixel for each sheet pixel. It is the Office.js `Range.getImage`. Office.js returns a `ClientResult` that you read after `context.sync()`. Here you `await` the string.

```ts theme={null}
import { ExcelWorkbook } from "@reductoai/xlsx/node";

const book = await ExcelWorkbook.open("model.xlsx");
const base64 = await book.worksheets.getItem("Summary").getRange("A1:H30").getImage();
const img = `<img src="data:image/png;base64,${base64}">`;
```

`getImage` needs a painter. `@reductoai/xlsx/node` brings one. In the browser, import `@reductoai/xlsx/view` once, anywhere in your app:

```ts theme={null}
import "@reductoai/xlsx/view";
import { ExcelWorkbook } from "@reductoai/xlsx/officejs";

const book = ExcelWorkbook.fromBytes(bytes);
const base64 = await book.worksheets.getItem("Summary").getRange("A1:H30").getImage();
```

Without a painter, `getImage` rejects with an error that names the two entries.

The image has gridlines when the sheet shows them, as in Office.js. Set `worksheet.showGridlines` to `false`, or give `gridlines: false`, to leave them out.

In Office.js, `getImage` has no parameters. Here it takes the options `labels`, `gridlines` and `scale`, as `toPng` does:

```ts theme={null}
import { ExcelWorkbook } from "@reductoai/xlsx/node";

const book = await ExcelWorkbook.open("model.xlsx");
const range = book.worksheets.getItem("Summary").getRange("A1:H30");
const base64 = await range.getImage({ labels: true, gridlines: true, scale: 2 });
```

## In the browser, from a view

When the workbook is already on screen in a [view](https://docs.reducto.ai/office/xlsx/rendering/view.md) or the [editor](https://docs.reducto.ai/office/xlsx/ui/editor.md), use `view.rangeImage`. It uses the view's layout, fonts and pictures. The picture has the column widths and row heights the user sees, also after the user resizes a column.

```ts theme={null}
import { Workbook } from "@reductoai/xlsx";
import { previewWorkbook } from "@reductoai/xlsx/view";

const view = previewWorkbook(document.getElementById("grid")!, Workbook.open(bytes));

const table = await view.rangeImage("Summary!A1:H30", { scale: 2 });
const selected = await view.rangeImage(); // the selected cells
document.querySelector("img")!.src = URL.createObjectURL(table);
```

Without a sheet name, the range is on the active sheet. With no range, the picture shows the selected cells. The options are `scale`, `gridlines` and `labels`, as for `toPng`.

The promise resolves after the fonts and pictures in the range have loaded, so the first picture is correct.

## Labels

`labels: true` adds column letters above the cells and row numbers to their left, as Excel's headers show them. Use it when a person or a language model must read a cell address from the picture. For example, a model can say "the border under C7 is missing" when it sees the labels. Without the labels, it can only describe the position.

```ts theme={null}
import { ExcelWorkbook } from "@reductoai/xlsx/node";

const book = await ExcelWorkbook.open("model.xlsx");
const [table] = await book.toPng({ range: "Summary!B2:H30", labels: true, gridlines: true });
```

* The labels name the sheet's own rows and columns, so a picture of `B2:H30` starts at column B and row 2.
* A hidden row or column has no label. The gap in the numbers shows where it is.
* A label that is wider than its column is left out.
* The labels are an extension. Excel's Copy Picture does not paint them.

## Limits

* A picture holds at most 1,000 rows and 100 columns, from the top-left cell of the range. A whole column such as `"A:A"` stops after 1,000 rows.
* A picture is at most 16,384 pixels on each side and 16,777,216 pixels in area, because browsers and `skia-canvas` cannot make a larger canvas. Rows and columns past this limit are not included. At `scale: 2`, the picture holds half as many rows and columns before it gets to the limit.
