Aspose.PDF FOSS
TypeScript
Developer Guide
Images

Images

Images

This page covers placing raster images on a page, inspecting the images already embedded in a document, and reducing their size. For rendering a page to an image, see Conversion.

Embedding an Image

Page.AddImage() places JPEG, PNG, BMP, or TIFF image bytes into a pixel-precise rectangle on the page.

// Source is 1280x1014; scaled to 60% of the page width, aspect preserved.
const srcW = 1280;
const srcH = 1014;
const imgW = pageWidth(page) * 0.6;
const imgH = (imgW * srcH) / srcW;
const x = (pageWidth(page) - imgW) / 2;
const y = (pageHeight(page) - imgH) / 2;

page.AddImage(imageBytes, [x, y, x + imgW, y + imgH]);

AddImageOptions accepts opacity, an explicit format when it cannot be sniffed from the bytes, a tag (a StructElement to attach the image to in a tagged document), and a layer for optional content.

Inspecting Embedded Images

Page.Images lists every image already on the page as ImageInfo[], without decoding any pixel data — each entry exposes Width, Height, Bits, ColorSpace, and Filter. Call Decode() on an ImageInfo to get its raw sample bytes, Replace() to swap in new image data in place, or Remove() to delete it from the page.

for (const img of page.Images) {
  console.log(img.Width, img.Height, img.ColorSpace, img.Filter);
}

Optimizing Images

Document.Optimize() reduces file size across the whole document; pass an images option (OptimizeImageOptions, with dpi and quality fields) to also downsample and re-encode embedded images as part of the same pass.

const report = doc.Optimize({ images: { dpi: 150, quality: 80 } });

Tips and Best Practices

  • Page.Images reads metadata only — decoding every image’s full pixel data with Decode() up front is unnecessary if you only need dimensions or color space.
  • Pass an explicit format in AddImageOptions when the source bytes come from a stream or buffer without a reliable file extension to sniff from.
  • Reach for Document.Optimize({ images: { dpi, quality } }) to shrink a document with many images, rather than manually decoding and re-adding each one.
  • Page.AddImage()’s rectangle sets the placed size directly — scale the target rectangle to the source image’s own aspect ratio to avoid stretching it.

Common Issues

IssueCauseFix
Image appears stretched or squashedThe target rect passed to AddImage() does not match the source image’s aspect ratioCompute the rectangle’s width/height from the source image’s own dimensions
Page.AddImage() places the wrong formatThe image bytes’ format could not be sniffed reliablyPass an explicit format in AddImageOptions
Document is much larger than expected after adding imagesImages were embedded at full resolution and qualityCall Document.Optimize({ images: { dpi, quality } }) to downsample and re-encode

FAQ

How do I place an image on a page?

Call page.AddImage(imageBytes, rect), where rect is a [x0, y0, x1, y1] rectangle in page-space points.

How do I list the images already on a page without decoding them?

Read page.Images — an ImageInfo[] exposing Width, Height, ColorSpace, and Filter for each image without decoding pixel data.

Can I reduce a document’s file size by compressing its images?

Yes — call Document.Optimize({ images: { dpi, quality } }), which downsamples and re-encodes embedded images as part of a document-wide optimization pass.

How is embedding an image different from rendering a page to an image?

Page.AddImage() places raster image bytes onto an existing page. Page.ToImage() (see Conversion) does the reverse — rendering the whole page to PNG bytes.

API Reference Summary

Class/MethodDescription
Page.AddImage()Place image bytes into a rectangle on the page
AddImageOptionsOptions for AddImage(): opacity, format, tag, layer
Page.ImagesEvery image already on the page, as metadata-only ImageInfo[]
ImageInfo.Decode() / Replace() / Remove()Read pixel data, swap in new bytes, or remove an image
Document.Optimize()Reduce file size document-wide, optionally downsampling images via images: { dpi, quality }

See Also