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.noneignores it; an angle (90deg, rounded to quarter turns) andflipset them by hand.image-rendering: autolets the PDF viewer smooth enlarged images;pixelatedandcrisp-edgeskeep 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,pathwith arcs),g,use,symbol, nestedsvg,viewBoxandpreserveAspectRatio,transform; - fill and stroke with colours, linear and radial gradients and patterns, dashes, line caps and joins,
fill-rule, opacity; marker,clip-pathandmask(on shapes);textandtspanwith the document's fonts, including@font-facefonts,text-anchorandtextLength;image, raster or SVG;- CSS in
<style>elements andstyleattributes of the SVG, with@font-faceand@import.
What is not drawn:
- filters other than
feOffsetandfeBlend: the element is drawn without the effect (no blur, no shadow); - animation and scripting: the initial state is drawn;
textPathtext does not follow its path, it is drawn as ordinary text at its position;switchdraws all its children, without evaluating conditions;- HTML content of
foreignObject, and@mediarules inside an SVG.
An SVG error never stops the document: an SVG that cannot be parsed gives a diagnostic and draws nothing.