This page is a reference for how iText Core (and the iText Core add-ons which utilize iText Core’s image handling) process image formats in PDF documents.
Filters
iText Core uses a filter-based architecture to process image data in PDF streams. These filters are divided into two categories:
Lossless-decodable filters
These filters use lossless compression algorithms, such as zlib/deflate, Lempel-Ziv-Welch (LZW), simple run-length encoding etc. This category also includes binary-to-text filters which convert binary data to hexadecimal or compact ASCII representations.
|
Filter |
Decoded to raw pixels? |
Safe for lossless pixel editing? |
Notes |
|---|---|---|---|
|
FlateDecode |
Yes |
Yes |
Fully decoded to raw samples; main lossless pathway. |
|
LZWDecode |
Yes |
Yes |
Fully lossless; can be modified and re-encoded. |
|
RunLengthDecode |
Yes |
Yes |
Decodes into raw bitmap data. |
|
CCITTFaxDecode |
Yes |
Yes (monochrome) |
Produces a 1-bit bitmap; safe for lossless updates. |
|
ASCIIHexDecode |
Yes |
Yes |
Wrapper filter; removed before actual decoding. |
|
ASCII85Decode |
Yes |
Yes |
Wrapper filter; removed before actual decoding. |
Pass-through filters (NOT safe for pixel editing)
These filters do not modify the data; it is simply passed-through unchanged.
|
Filter |
Decoded to raw pixels? |
Safe for lossless pixel editing? |
Notes |
|---|---|---|---|
|
DCTDecode (JPEG) |
No |
❌ No |
JPEG is lossy; not rasterized by iText Core; must remain untouched. |
|
JPXDecode (JPEG2000) |
No |
❌ No |
Same as JPEG; no full pixel expansion. |
|
JBIG2Decode |
No |
❌ No |
Not expanded into a conventional pixel array; keep as-is. |
|
Filter chains |
Depends on inner filters |
Depends |
If the innermost filter is JPEG/JPX/JBIG2 → not editable. |
In order to create a BufferedImage from decoded JPEG2000 image bytes in Java, it’s possible to add the jai-imageio-jpeg2000 dependency: it will register itself with ImageIO, so it’ll be possible to read jp2 files as other formats.
Color Depth
The color depth defines the number of Bits Per Component (BPC) for an image.
|
Case |
Supported |
Rules |
|---|---|---|
|
Single-channel (Gray or mask) |
Yes |
Any BPC is allowed. |
|
Multi-channel (RGB, CMYK, etc.) |
Yes |
Only BPC 8 or 16 — otherwise an exception is thrown. |
|
Separation with tint transform |
Yes |
Tint mode requires BPC ≥ 8. |
|
Indexed color |
Yes |
BPC depends on base color space. 1-bit indexed B/W palette has special handling. |
Color Spaces
Color spaces define what the color components mean, and how they should be interpreted.
|
PDF Color Space |
Target Color Space |
Transparency (SMask) |
Output Format |
Notes |
|---|---|---|---|---|
|
|
Gray (1 channel) |
Optional alpha |
PNG |
|
|
|
RGB (3 channels) |
Optional alpha |
PNG |
Requires BPC 8 or 16. |
|
|
CMYK (4 channels) |
Optional alpha |
TIFF |
Requires BPC 8 or 16. |
|
|
Either Palette or Deindexed into base space |
Optional alpha |
PNG |
B/W 1-bit palette auto-converted to Gray; may auto-insert |
|
|
Default: Gray. With tint-transform: base CS (RGB/CalRGB) |
Optional alpha |
PNG |
Tint allowed only if base is RGB/CalRGB; BPC ≥ 8. |
|
|
Gray/RGB/CMYK according to ICC |
Optional alpha |
PNG (1/3 comps) or TIFF (4 comps) |
ICC profile embedded (iCCP or TIFF tag). Other ICC component counts unsupported. |
|
|
Gray / RGB |
Optional alpha |
PNG |
Supported, but Lab/CalRGB colors can appear slightly off because no fitted ICC profile is applied. |
|
|
Not supported |
— |
— |
Throws exception. |