Guide
# Images and SVG
JPEG, PNG and lossless WebP images with aspect-preserving sizing, and the SVG subset icon sets use — drawn as vectors.
## Formats
Decoded in Ruby, cached per process.
Images are **JPEG** (grey, RGB, CMYK), **PNG** (every colour type, alpha as a soft mask, palette transparency) and lossless **WebP**. The source is a file path or any IO (`StringIO`, an ActiveStorage download, …). Parsed fonts and images are cached per process, keyed by content, so the same logo on every page is embedded once.
A WebP is decoded in Ruby (the VP8L bitstream, in a plain or an extended container; colour profile and metadata chunks are skipped) and embedded like a PNG: RGB, with the alpha channel as a soft mask when a pixel is not opaque. Decoding takes 0.2 to 0.4 s per megapixel, once per process for the same bytes. Lossy and animated WebP raise `UnsupportedImage` naming which it is, as does a file that is cut short or damaged; convert those to JPEG, PNG or lossless WebP (`cwebp -lossless`).
A JPEG is embedded in a PDF byte for byte and decoded in Ruby only where pixels are needed: `to_png`, and a `monochrome` render, which dithers it. Baseline, extended and progressive JPEGs decode (every chroma subsampling, restart intervals, grey, RGB, YCbCr, CMYK and YCCK) to the pixels libjpeg-turbo gives, a photo drawn small at a half, a quarter or an eighth of its size. A lossless, arithmetic-coded, hierarchical or 12-bit JPEG, or one of more than 33 megapixels, is not decoded: `to_png` draws a crossed box (`SkippedImage`) and monochrome embeds it as it is (`NotMonochrome`). The EXIF orientation is not applied, in a picture as in the PDF.
## Sizing and fit
`image(source, width: nil, height: nil, fit: nil, align: nil, opacity: nil, radius: 0, rotate: 0, max_ppi: 300, downscale: false, float: nil, margin: nil)`
| Given | Result |
| --- | --- |
| nothing | one pixel is one point |
| `width:` or `height:` | the other side follows the aspect ratio |
| both | exactly that size |
| `fit: [w, h]` | scaled to fit inside the box, aspect preserved |
| `fit: :cover` with `width:` and `height:` | scaled to fill the box, aspect preserved, the excess cropped around the centre (CSS `object-fit: cover`) |
| `radius:` | corners rounded by that many points (the image is clipped) |
| `rotate:` | turned that many degrees clockwise around its centre; the space it takes up does not change (CSS `transform: rotate`) |
| `float: :left` or `:right` | taken to that side of the flow; the text and the lists that follow wrap beside it, `margin:` away (CSS `float`) |
An image is never wider than the space it is given; it scales down to the column. `align:` (`:left`, `:center`, `:right`) positions a narrower image and is not read on a floated one. `margin:` is a number (kept on the sides that face the text) or names the sides as `padding:` does; the rules for what wraps and what moves below are on [Elements](https://stationery.zoolutions.llc/docs/elements#floats).
```ruby
image "logo.png", height: 34, align: :right
image StringIO.new(product.photo.download), fit: [120, 80]
# text wraps beside the photo and continues below it
image photo, float: :left, width: 0.4, margin: { right: 14, bottom: 8 }, alt: "The bay at dawn"
# a tilted, rounded snapshot cropped to 4:3
image photo, width: 160, height: 120, fit: :cover, radius: 8, rotate: -3
```
A rotated image paints outside its rectangle at the corners, so leave room around it (a `box(padding:)`).
## Resolution
Bitmaps keep their pixels.
A JPEG is embedded byte for byte and a PNG or WebP re-encoded losslessly, so a 1600 px photo drawn 160 pt wide ships all 1600 px at 720 ppi. Print needs about 300 ppi (`width_in_points / 72 * 300` pixels: a 160 pt photo wants about 670 px) and screen PDFs half that.
Every image is checked when it is painted: drawn at more than twice `max_ppi:` it is reported as a [`Warnings::OversizedImage`](https://stationery.zoolutions.llc/docs/warnings) naming the file, its pixel width and the resolution it lands at, so `strict` catches it.
```ruby
class Flyer < Stationery::Document
images max_ppi: 300, downscale: true # document defaults; nil switches the check off
end
image "photo.png", width: 160 # a 1600 px PNG is resampled to 667 px
image "photo.jpg", width: 160, max_ppi: nil # this one is fine as it is
```
`downscale: true` resamples a **PNG** or a **WebP** to `max_ppi` at its drawn size with a box filter (alpha and palette transparency included) and embeds that; the layout, the tagged `Figure` and the text around it do not change. A **JPEG** is never re-encoded, so it only warns: size JPEGs before you embed them. With ActiveStorage, make a JPEG variant per drawn size (`resize_to_limit`, quality 75) and preprocess it, so a render only downloads. A 10-page flyer with 18 photos went from 3.3 MB to under 1 MB that way with no visible difference.
## SVG
Icons and simple drawings as vectors.
`svg(source_or_path, width: nil, height: nil, color: "#000000", align: nil)` takes SVG markup or a path to a `.svg` file. `currentColor` takes `color:`, so one icon file serves every theme colour.
```ruby
CHECK = <<~SVG
SVG
row { column(width: 16) { svg CHECK, width: 14, color: "#0F766E" }; column { text "Shipped" } }
```
**Supported:** `path` (every command, including arcs), `rect` (with `rx`/`ry`), `circle`, `ellipse`, `line`, `polyline`, `polygon` and `g`, with fill, stroke, line caps and joins, `fill-rule`, opacity, inline `style` attributes, `