diff --git a/README.md b/README.md index 4529bfe..aaf7eb8 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,45 @@ its matrix and the transform that drew it both count. Nearly every figure a plotting tool writes is a form, so a pattern that stayed at the page's origin would miss the shape it was asked to fill by the width of a page. +## Thumbnails, and a strip of them + +A page strip wants a hundred small pictures of somebody else's file, quickly +and without being able to be made to allocate. That is `Page` with three +options and nothing else: + +```go +img, err := render.Page(doc, i, render.Options{ + Scale: 0.2, // device pixels per point: a 612pt page → 122px + MaxPixels: 4 << 20, // what the file may ask to allocate + MaxDuration: 2 * time.Second, // what it may ask to spend +}) +rgba := img.ToNRGBA() // for a toolkit that wants image.RGBA +``` + +`Scale` is the thumbnail control — device pixels per point, so 0.2 is a fifth +of the page's own size. `MaxPixels` and `MaxDuration` are the two bounds a +caller drawing an untrusted file needs: one caps what comes out, the other +caps the work of making it. ⛔ On a timeout the page comes back **as far as it +got**, with `ErrTimedOut` — deliberately not a blank, because half a page is +worth more than nothing to somebody scrolling, and the error says plainly that +it is half. + +**Measured** on a 68-page scanned book, at load average 25 so the figures are +pessimistic: + +| scale | per thumbnail | worst page | pixels in the strip | +|---|---|---|---| +| 0.15 | 21.9 ms | 54 ms | 25 394 | +| 0.25 | 21.7 ms | 93 ms | 69 989 | +| 0.50 | 20.3 ms | 31 ms | 271 545 | + +⛔ **The scale barely moves it, and that is the useful part.** Ten times the +pixels cost the same, because on a scanned page the time goes into decoding +the embedded image, not into rasterising it — so for scans, asking for a +larger thumbnail is nearly free, and asking for a smaller one saves nothing. +A strip of a hundred is about two seconds; a *virtualised* strip that draws +only what is on screen is a tenth of that. + ## How it is checked By writing a PDF whose geometry is known and looking at the pixels that