Embedded raster images inside SVG

SVG isn't pure vector — its <image> tag lets you embed raster images alongside vector shapes. A logo with a photographic background, an icon with an embedded screenshot, an illustration with a texture overlay all use this. The conversion preserves embedded rasters as PDF Image XObjects, with the surrounding vector content intact.

How SVG references rasters

The <image> tag has an href attribute (or the legacy xlink:href) that names the image source:

• Relative file path: href="logo.png". The renderer looks for logo.png in the same directory as the SVG.
• Absolute URL: href="https://example.com/logo.png". The renderer fetches over HTTP.
• Data URI: href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...". The image bytes are inline, base64-encoded.

How each href style fares

Data URIs work universally. The base64 bytes are decoded and the resulting raster is embedded as a PDF Image XObject. The conversion library decides the exact PDF filter and structure used for the embedded image data.

Relative file paths don't work because the conversion only sees the SVG file you upload, not the surrounding directory. References to logo.png resolve to no file; the image is missing in the rendered PDF.

Absolute URLs don't work either — the conversion doesn't fetch over the internet during rendering. References to remote URLs fail the same way as broken relative paths.

Rule of thumb: before uploading, embed all raster references as data URIs.

Embedding rasters as data URIs

Most graphics tools have an "embed images" option in their SVG export:

• Open-source desktop SVG editors usually expose an "embed images" toggle, or a per-image "Embed" button in the XML/properties panel.
• Commercial vector-illustration tools have an SVG save dialog where the image-location toggle is "Embed" (vs "Link").
• Browser-based design tools typically inline raster references automatically when exporting SVG.

Or do it manually:

base64 -w 0 logo.png | sed 's/^/data:image\/png;base64,/' > data-uri.txt
# Then paste into the SVG, replacing the href value.

Format considerations for embedded rasters

The format of the embedded raster carries through to the PDF:

• Embedded JPEG: passes through as /DCTDecode. No recompression. Best for photographic raster regions inside SVGs.
• Embedded PNG: passes through as /FlateDecode with PNG predictor. No recompression. Best for screenshots, logos with transparency.
• Embedded GIF: the renderer decodes and re-encodes (PDF doesn't have a native GIF filter). Slight overhead but quality preserved.
• Embedded WebP / AVIF / HEIC: the renderer decodes and re-encodes. PDF compatibility means these become PNG-style FlateDecode streams.

Size implications

Embedded rasters dominate file size. A 5 KB SVG with a 50 KB embedded JPEG produces a ~55 KB PDF. Multiple embedded rasters compound.

Common pattern: a chart SVG (small vector) with a 1 MB embedded logo image somewhere in the corner produces a 1+ MB PDF. The chart vector content is small; the logo dominates.

If size matters, optimize the embedded raster before embedding (resize to display dimensions, pick JPEG at appropriate quality, etc.).

Rasters and SVG transformations

An SVG can transform an embedded raster: scale it, rotate it, place it inside a clipPath, apply opacity. PDF supports transformation matrices on Image XObjects natively, so all these survive into the PDF. The raster bytes don't change — only the placement matrix in the page content stream.

Example: an SVG with <image transform="rotate(45) scale(0.5)" href="data:..."/> produces a PDF page where the raster is drawn at a 45° angle, half its native size. The pixel data passes through unchanged; the rotation matrix in the content stream handles the placement.

Embedded rasters with alpha

An embedded PNG with alpha (RGBA) gets the same SMask treatment as a directly-uploaded PNG: the RGB channels become the main Image XObject, the alpha becomes a separate /SMask Image XObject, both attached to the same drawing operation in the content stream.

The result is a vector-with-raster-with-soft-edges PDF page that composites correctly against the page background.

Aspect ratio of embedded images

The <image> tag has width and height attributes that may not match the raster's native pixel aspect ratio. SVG's preserveAspectRatio on the image element controls fitting (default: meet, with center alignment).

SVGtoPDF preserves the fitting behavior. The raster is embedded at its native pixel dimensions; placement coordinates and any preserveAspectRatio rule become part of the PDF content stream's transformation matrix.