Skip to content

Images and SVG

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Images and SVG</title>
<style>
  @page { size: A5; margin: 15mm }
  body { font: 10pt/1.4 sans-serif }
  .thumb { width: 30mm; height: 20mm; object-fit: cover; border: 0.5pt solid #999 }
  .pixels { width: 20mm; image-rendering: pixelated }
  .hero { width: 100%; height: 20mm; background: url(images_logo.svg) no-repeat center / contain }
</style>
</head>
<body>
  <!-- an SVG file as an image -->
  <p><img src="images_logo.svg" alt="kolinsky logo"></p>
  <!-- a raster image, scaled to cover its box -->
  <p><img class="thumb" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAIAAAAmkwkpAAAAGElEQVR4nGPQCDjxP0ADQjLAWUCSAacMADa6Fbk2wHo4AAAAAElFTkSuQmCC" alt="Checkerboard"></p>
  <!-- the same pixels enlarged without smoothing -->
  <p><img class="pixels" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAIAAAAmkwkpAAAAGElEQVR4nGPQCDjxP0ADQjLAWUCSAacMADa6Fbk2wHo4AAAAAElFTkSuQmCC" alt="Checkerboard, pixelated"></p>
  <!-- SVG as a CSS background -->
  <div class="hero"></div>
  <!-- inline SVG: a replaced element styled from the outside, drawn from its own attributes -->
  <svg width="60" height="60" viewBox="0 0 60 60" style="margin: 2mm">
    <circle cx="30" cy="30" r="25" fill="none" stroke="#c25129" stroke-width="4"/>
    <path d="M18 30 l8 8 l16 -16" fill="none" stroke="#222" stroke-width="4"/>
  </svg>
  <!-- a missing image shows its alt text -->
  <p><img src="missing.png" alt="(image not found)"></p>
</body>
</html>
kolinsky render images_gallery.html -o images_gallery.pdf
kolinsky inspect images_gallery.html --select img

Where images come from

Images are loaded from <img src>, content: url() (on elements, pseudo-elements and margin boxes), background-image, list-style-image and border-image-source. Relative URLs resolve against the document's base URL; data: URLs work everywhere. Images load through the same resource loader as everything else, so a remote image needs network access to be allowed (see Resource loading).

The format is found from the content, not from the file name or the declared type. kolinsky decodes:

format notes
PNG all colour types and bit depths, with transparency
JPEG baseline and progressive, grayscale, RGB and CMYK
GIF the first frame; a transparent colour is kept
WebP lossy and lossless; the first frame
SVG as a vector image, see below

An image that cannot be loaded or decoded gives a resource.* diagnostic and the document is still rendered. A failed <img> shows its alt text as ordinary text; without alt text it takes no space.

Size

An image's natural size is its pixel size at 96 pixels per inch (1 image pixel = 1 CSS px), divided by image-resolution. Set the displayed size with CSS width and height; the width and height attributes of <img> are not used for layout. With only one of them set, the other follows the image's aspect ratio. min-width, max-width, min-height and max-height apply as for any replaced element.

img { max-width: 100% }                 /* never wider than the column */
img.scan { image-resolution: 300dpi }   /* a 2480 px wide scan is 210 mm wide */

image-resolution takes dppx, x, dpi or dpcm; it changes the layout size only, every pixel of the file is embedded.

Fitting into a box

object-fit places the image inside a box whose size the CSS sets:

value drawn size
fill (default) stretched to the box
contain as large as fits, aspect ratio kept
cover as small as covers the box, aspect ratio kept, the rest clipped
none the natural size
scale-down the smaller of none and contain

object-position moves the image inside the box (default 50% 50%).

Orientation and rendering

  • image-orientation: from-image (the default) applies the rotation and flip of a JPEG's EXIF data. none ignores it; an angle (90deg, rounded to quarter turns) and flip set them by hand.
  • image-rendering: auto lets the PDF viewer smooth enlarged images; pixelated and crisp-edges keep hard pixel edges, which suits charts and pixel art.

Images are not split across pages. An image taller than the page area overflows it; limit it with max-height.

SVG

SVG is drawn as vector graphics in the PDF, both as image files (<img src="../logo.svg">, url(logo.svg) in CSS) and written inline in the HTML:

<svg width="60" height="60" viewBox="0 0 60 60">
  <circle cx="30" cy="30" r="25" fill="none" stroke="#c25129" stroke-width="4"/>
</svg>

An inline <svg> is a replaced element: the document's CSS sizes and places the <svg> element itself (width, height, margins, vertical-align), while its content is styled only by its own attributes and its own <style> elements. Inside an SVG the initial font is 16 px sans-serif, whatever the HTML says; currentColor takes the color of the HTML element.

The intrinsic size comes from the width and height attributes of the root svg element, and the aspect ratio from them or from viewBox. An SVG without width and height and without a viewBox is 300 x 150 px.

What is drawn:

  • shapes (rect, circle, ellipse, line, polyline, polygon, path with arcs), g, use, symbol, nested svg, viewBox and preserveAspectRatio, transform;
  • fill and stroke with colours, linear and radial gradients and patterns, dashes, line caps and joins, fill-rule, opacity;
  • marker, clip-path and mask (on shapes);
  • text and tspan with the document's fonts, including @font-face fonts, text-anchor and textLength;
  • image, raster or SVG;
  • CSS in <style> elements and style attributes of the SVG, with @font-face and @import.

What is not drawn:

  • filters other than feOffset and feBlend: the element is drawn without the effect (no blur, no shadow);
  • animation and scripting: the initial state is drawn;
  • textPath text does not follow its path, it is drawn as ordinary text at its position;
  • switch draws all its children, without evaluating conditions;
  • HTML content of foreignObject, and @media rules inside an SVG.

An SVG error never stops the document: an SVG that cannot be parsed gives a diagnostic and draws nothing.