How to Work with Images and Graphics in TypeScript

This guide shows how to place images and vector graphics on a PDF page with Aspose.PDF FOSS for TypeScript. Page.AddImage() embeds raster bytes, Page.Graphics() returns a PageGraphics for shape drawing, and Document.OptionalContent groups either into togglable layers. It requires Node.js 22 or later.

Step-by-Step Guide

Step 1: Install the Package

asposefoss/pdf is not yet published — build from source until it ships. See the project README for build instructions.

Verify the installation by importing the Document class in a new TypeScript file — this line should resolve without error once the package is installed:

import { Document } from '@asposefoss/pdf';

Step 2: Import Required Classes

Import Document to open the file; AddImage(), Graphics(), and AddBarcode() are called directly on the Page instances it returns:

import { Document } from '@asposefoss/pdf';

Step 3: Embed a Raster Image

Page.AddImage(data, rect, opts) places JPEG or PNG bytes inside a bounding rect, scaled to fit:

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

const imgW = 300;
const imgH = 237; // aspect preserved from a 1280x1014 source
page.AddImage(imageBytes, [150, 400, 150 + imgW, 400 + imgH]);

Step 4: Draw Vector Graphics

Page.Graphics() returns a PageGraphics that buffers drawing calls until apply() commits them. Chain setStrokeColor(), setFillColor(), setLineWidth(), and shape methods such as rect(), circle(), and drawLine(), then stroke() / fill() / fillStroke():

const g = page.Graphics();

g.save()
  .setStrokeColor([0.55, 0.60, 0.75])
  .setLineWidth(1)
  .rect(80, 300, 435, 340)
  .stroke()
  .restore();

g.setFillColor([0.88, 0.91, 0.98])
  .setStrokeColor([0.45, 0.52, 0.75])
  .setLineWidth(1)
  .circle(120, 340, 13)
  .fillStroke();

g.apply();

Step 5: Bind Images and Graphics to Optional-Content Layers

doc.OptionalContent.AddLayer(name, opts) creates a Layer that can be toggled in a viewer’s layers panel. Pass it as layer to AddImage(), or wrap PageGraphics calls in BeginLayer() / EndLayer():

const oc = doc.OptionalContent;
const grid = oc.AddLayer('Grid', { visible: false }); // default off
const branding = oc.AddLayer('Branding');

const g2 = page.Graphics();
g2.BeginLayer(grid);
g2.save().setStrokeColor([0.72, 0.76, 0.88]).setLineWidth(0.4).setDash([3, 3]);
g2.drawLine(80, 300, 515, 300);
g2.stroke().restore();
g2.EndLayer();
g2.apply();

page.AddImage(logoBytes, [370, 606, 480, 640], { layer: branding });

Step 6: Add a Barcode

Page.AddBarcode(spec, rect, opts) draws a barcode symbol; spec.type selects the symbology and spec.data is the encoded payload. Like AddImage(), it accepts a layer option:

page.AddBarcode({ type: 'code128', data: 'ROOM-204' }, [370, 340, 500, 384], {
  layer: branding,
  text: true, // draw the human-readable payload beneath the symbol
});

Common Issues and Fixes

Graphics drawn with PageGraphics do not appear on the page. Calls buffer until apply() is called — every PageGraphics sequence needs a matching apply() before the page is saved.

A layer never appears in the viewer’s layers panel. Confirm AddLayer() was called through doc.OptionalContent, not created as a standalone object — layers must be registered on the document’s optional content configuration to be listed.

An image or barcode ignores a layer’s visibility toggle. Only AddImage(), AddBarcode(), and content wrapped in PageGraphics.BeginLayer() / EndLayer() bind to a layer via /OC — a page’s other base content (plain text drawn without a layer option, for example) is unaffected by any layer toggle.

Page.AddImage() distorts the image. rect sets the placed width and height directly — compute it from the source image’s own aspect ratio first if the image should not stretch.

Frequently Asked Questions

Can a layer default to hidden?

Yes — pass { visible: false } to OptionalContent.AddLayer().

Can one layer nest under another?

Yes — pass { parent: someLayer } when calling AddLayer() to nest the new layer under an existing one in the layers panel’s /D /Order.

What image formats does `Page.AddImage()` accept?

JPEG and PNG raster bytes.

Does drawing with `PageGraphics` support opacity and dashed lines?

Yes — setOpacity(alpha) sets fill/stroke alpha and setDash(pattern, phase) sets a dash pattern; both are chainable like the other PageGraphics setters.