> For the complete documentation index, see [llms.txt](https://docs.pd4ml.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pd4ml.com/features/html-to-raster-image-conversion.md).

# HTML to Raster Image Conversion

PD4ML's two-phase conversion model -- read the source once, write it out one or more times -- makes rasterized image output a natural sibling of PDF, RTF, and [DOCX](/features/rtf-and-docx-output.md) generation rather than a separate feature bolted on beside them. The same parsed HTML layout that would otherwise become a PDF stream can instead be rasterized page by page and handed back as PNG or TIFF, which is what makes it a convenient way to produce thumbnails, print previews, or archival page images from exactly the same source template and layout engine used everywhere else.

## Choosing an output format

The legacy API selects a raster format the same way it selects RTF or DOCX: set the desired `PD4Constants` format, then trigger a single combined `render()` call. The current API instead exposes rasterization as one of several possible destinations for an already-parsed document, via dedicated `renderAsImages()` overloads:

{% tabs %}
{% tab title="v4" %}

```java
pd4ml.readHTML(inputStream); // parse once

BufferedImage[] pages = pd4ml.renderAsImages();           // one image per page, in memory
byte[][] pngBytes     = pd4ml.renderAsImages("png");      // ... or already PNG-encoded
File dir              = pd4ml.renderAsImages(outDir, "page", "png");  // ... or written straight to disk
```

{% endtab %}

{% tab title="v3" %}

```java
pd4ml.outputFormat(PD4Constants.PNG8);
// or
pd4ml.outputFormat(PD4Constants.PNG24);
// or
pd4ml.outputFormat(PD4Constants.TIFF);

pd4ml.render(inputStream, outputStream); // parse and render in one call, using whichever format was set above
```

{% endtab %}
{% endtabs %}

(The current-API overloads are covered in full, alongside the rest of the two-phase read/write model, in the Programmer's Manual's [§6.3, Writing the output](/pd4ml-manual.md).) `PNG8` produces an 8-bit indexed-color PNG, trading color depth for a smaller file; `PNG24` keeps full 24-bit color; `TIFF` produces a single, potentially multi-page TIFF file rather than one file per page.

### JSP taglib

```jsp
<pd4ml:transform ... outputFormat="png8"> ... </pd4ml:transform>

<pd4ml:transform ... outputFormat="png24"> ... </pd4ml:transform>

<pd4ml:transform ... outputFormat="tiff"> ... </pd4ml:transform>
```

The taglib sets the corresponding HTTP `Content-Type` header automatically, matching whichever image format was requested.

### Command line

```
java -Xmx512m -Djava.awt.headless=true -cp ./pd4ml.jar Pd4Cmd <URL> 1200 -out thumbnail.png -outformat png8

java -Xmx512m -Djava.awt.headless=true -cp ./pd4ml.jar Pd4Cmd <URL> 1200 -out thumbnail.png -outformat png24

java -Xmx512m -Djava.awt.headless=true -cp ./pd4ml.jar Pd4Cmd <URL> 1200 -out thumbnail.tiff -outformat tiff
```

## What doesn't carry over to raster output

A raster image is a fundamentally simpler artifact than a PDF, and several PDF-oriented features have no equivalent once the target is a bitmap rather than a structured document:

* **Page breaks are handled differently per format.** PNG output ignores page breaks entirely and renders the whole laid-out document as one (potentially very tall) image; TIFF respects them, producing a proper multi-page TIFF with one page per image frame.
* **No headers or footers.** There's no repeating per-page decoration to speak of when PNG doesn't paginate in the first place, and TIFF's per-page images don't carry them either.
* **No footnotes.**
* **No hyperlinks** -- unsurprising, since a raster image has no notion of a clickable region.
* **A generated table of contents loses its page numbers.** The `<pd4ml:toc>` tag still works, but without discrete, numbered PDF pages to point at, its entries can't carry page references the way they do in PDF output.
* **Page insets (margins) aren't applied** -- though the source document's own CSS body margins still are, since those are just ordinary layout, not a PDF-specific page property.

## Memory footprint

Raster output is considerably more memory-hungry than PDF generation, because the entire page has to exist as decoded pixel data at once rather than as compact, structured PDF drawing operators. As a rule of thumb, even a modest 1000x5000px layout needs at least 20 MB just for the raw image bytes, before accounting for `BufferedImage`'s own object overhead -- worth budgeting for explicitly ahead of any batch job that rasterizes many pages or documents concurrently, rather than discovering the ceiling as an `OutOfMemoryError` in production.

## See also

* [PD4ML Programmer's Manual](/pd4ml-manual.md) -- §6.3 covers `renderAsImages()` alongside `writePDF`/`writeRTF`/`writeDOCX` in the current API's two-phase model.
* [RTF and DOCX Output](/features/rtf-and-docx-output.md) -- the other two non-PDF output formats PD4ML supports from the same conversion pipeline.
* [PD4ML v3 to v4 Migration Guide](/pd4ml-v3-to-v4-migration-guide.md) -- covers the broader `outputFormat(String)`-to-`write*()`/`renderAsImages()` API change referenced above.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pd4ml.com/features/html-to-raster-image-conversion.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.