Page export: images and SVG

PageExporter writes the pages of a document, workbook or presentation as PNG, JPEG, TIFF, WebP or SVG. Pages are laid out once (the layout of each kind is described in layout.md, spreadsheet-rendering.md and presentation-rendering.md), painted into a OneRender display list, and then either drawn by OneRender's image backend and encoded by OneImage, or written as SVG by RecursiveAI.OneDocument.Rendering.Svg.SvgWriter.

One-liners

document.SaveAs("page.webp");               // the first page; the format comes from the extension
document.SaveAs("all-pages.tif");           // a TIFF holds every page
Office.Convert("deck.pptx", "slide1.svg");  // the first slide

The registered writers take the first page, and every page for a TIFF. Extensions: .png, .jpg/.jpeg, .tif/.tiff, .webp, .svg.

Choosing pages, size and encoder settings

var options = new PageExportOptions
{
    Pages = PageSelection.Parse("2-4,9"),   // 1-based; "all", "7-", "-3" also parse
    WidthPixels = 1600,                      // or Dpi = 200; both Width and Height fit the page inside the box
    Quality = 85,                            // JPEG and lossy WebP
};
 
PageExporter.Export(document, stream, PageImageFormat.Tiff, options);                    // one multi-page TIFF
PageExporter.ExportPages(document, PageImageFormat.Png, page => Save(page.Number, page.Data), options);   // one file per page

Limits: a page is at most 100 million pixels (PageExporter.MaxPixels), dpi 1 to 2400, quality 1 to 100. A range ends at the last page when it runs past it (1-99 is every page of a short document); a range that starts past the last page throws ArgumentOutOfRangeException; a single-page format given several pages in one stream throws ArgumentException (use ExportPages). A page that cannot be drawn or encoded throws OfficeFormatException with code render.failed. The report lists font substitutions and layout and SVG notes as code: message lines. JPEG uses 4:4:4 sampling because 4:2:0 fringes glyph edges.

A workbook with nothing to print exports one blank Letter page. A presentation exports its visible slides in order (the pages PresentationRenderer writes to PDF).

Multi-page TIFF

OneImage encodes one image per call, so each page is encoded as a TIFF of its own and the files are joined by chaining their directories (TiffPages): the bytes after the header are copied unchanged and the offsets inside them are moved. Only the plain tags OneImage's encoder writes are accepted; anything holding further offsets (sub-directories, JPEG-in-TIFF) raises render.failed instead of writing a corrupt file. A page range gives a TIFF of just those pages. The decoded pixels of each joined page are tested equal to the single-page file for all four compressions.

SVG

SvgWriter turns a finished DisplayList into an SVG 1.1 document (xlink:href, plus the CSS mix-blend-mode, isolation and mask-type properties browsers add). The namespace depends only on OneRender's display-list types and OneFont's face type, so OneRender can lift it. Output is deterministic: ids come from a counter, numbers are invariant-culture with at most Precision (3) decimals, and nothing reads a clock or a random source.

What SVG cannot express (conic gradients, rounded borders, inset shadows, masks of several layers or with subtract/intersect/exclude, 3D transforms) is drawn by the ISvgRasterizer the caller gives and embedded as an image where it belongs, at the resolution RasterScale (2) times the enclosing transforms' scale, at most 16 million pixels per region. PageExporter supplies one that uses OneRender's image backend. Without a rasterizer the content is written without the effect. Backdrop filters are left out. Each case is a note: svg.conic-gradient, svg.rounded-border, svg.inset-shadow, svg.mask-layers, svg.transform-3d, svg.backdrop-filter, svg.image-missing, svg.inline-svg-ids, svg.outlines-refused, svg.text-approximated.

Glyph runs

SvgGlyphMode.Auto (default) writes <text> where the SVG text model reproduces the run exactly: one glyph per BMP character, left to right, each character at its own x. That keeps text searchable and small. Ligatures, marks, right-to-left and joined scripts are written as glyph outlines (one path per run), because a viewer shapes text its own way. Text always writes text (clusters that are not one glyph per character become a tspan per cluster, noted as svg.text-approximated); Outlines always writes outlines. Characters a face does not have draw nothing, as in the image and PDF backends. Colour bitmap fonts (CBDT, sbix) are always text.

Font licences. No font is embedded. Outlines are glyph shapes, so they are refused for a font whose OS/2 fsType has the restricted-licence bit (0x0002) set: the run is written as text and the note svg.outlines-refused says so. The substituted open fonts (Liberation, Carlito, Caladea, Noto) are SIL OFL and have no such bit.

Checks

• Round trip against the image backend (PageExporterTests.SvgDrawnBackMatchesTheRasterOfTheSamePage): every page of the rendering test documents is exported as PNG at 1200 pixels wide and as SVG with outlines, the SVG is drawn back by OneImage.Svg, and the two are compared after averaging 4 x 4 blocks (two rasterizers cover glyph edges differently; averaging keeps misplaced lines, glyphs and shapes and drops the anti-aliasing noise). Tolerance: mean absolute difference per channel at most 1.0 of 255, and at most 1.5% of blocks differing by more than 32. Over 202 pages (151 word-processing, 29 workbook, 13 slide, and the drawing fixtures) the mean of the means is 0.04 and the largest 0.85. The one page near the limit is drawing-docx/fills (0.85, 1.07% over): its 24 pattern fills are tiles a few pixels wide, and the two rasterizers sample them in a different phase (the gradients and solid fills in the same page agree).
• A browser (information): the same fixture (drawing-effects-groups) opened in headless Chrome for Testing 157 draws it; against our PNG at 96 dpi the mean difference is 0.30 with outlines and 0.65 with text (Chrome used its own substitute font).
• AOT and browser-WASM smoke each write one page as SVG and one as WebP (smoke/shared/RenderSmoke.cs).

Command line

onedocument render in.docx -o out.png|jpg|tif|webp|svg [--pages 1-3,5|all] [--dpi n] [--width px] [--height px]
                 [--quality n] [--svg-glyphs auto|text|outlines] [--transparent] [--no-tags]

A TIFF holds every page asked for (all by default). Other formats write page 1, or the one page --pages/--page names; several pages give out-1.png, out-2.png, and so on. convert writes the first page (every page for TIFF).