Images

Adding an image

doc.Image(File.ReadAllBytes("logo.png"), ImageFit.Width);

Papyra accepts every format its image library can decode: JPEG, PNG, GIF, BMP, TIFF, WebP, TGA, PBM, and QOI - transparency included. JPEG and PNG embed as-is; everything else is converted losslessly to PNG when you call Image(...), so all four output formats behave identically. For animated or multi-page sources (GIF, WebP, TIFF) only the first frame is kept. Unrecognized data fails immediately at compose time with a clear error. SVG is a vector format with its own Svg(...) method, provided by the optional Papyra.Svg package - see the SVG guide.

Sizing

Without explicit dimensions, ImageFit controls sizing:

• WIDTH - scale to the full content width, keeping the aspect ratio
• ORIGINAL - natural size, based on the image’s pixel dimensions (one source pixel = one point; capped at the content width)

Explicit dimensions override the fit mode - always preserving the aspect ratio, never stretching:

doc.Image(logo, width: 120f);                 // fixed width, height follows
doc.Image(logo, height: 40f);                 // fixed height, width follows
doc.Image(logo, width: 120f, height: 80f);    // contain-in-box: largest size inside 120×80

Units are points, and unlike ORIGINAL, explicit dimensions may upscale; the content width still caps the result so an oversized request cannot overflow the page.

Alignment

doc.Image(logo, ImageFit.Original, alignment: TextAlignment.Center);

LEFT (default), CENTER, and RIGHT work everywhere an image can appear - top level, header/footer bands, paragraphs, lists, rows, and table cells (where the image’s own alignment wins over the cell alignment). In DOCX the alignment becomes the drawing paragraph’s justification; in XLSX the anchor carries an exact column offset instead of snapping to the column boundary.

Per-format behavior

• PDF - RGB and grayscale JPEG embed as-is; opaque PNG embeds losslessly (grayscale, RGB, and palette images pass their compressed data straight through). PNGs with transparency or interlacing are decoded, and an alpha channel becomes a real soft mask, so transparency composites correctly - conformant under PDF/A-2 and later. CMYK JPEGs are transcoded to RGB during rendering (pixel-lossless from the decoded image, but the original JPEG bytes are not preserved).
• DOCX - PNG and JPEG as inline drawings.
• XLSX - images float over the grid as anchored drawings (oneCellAnchor) at the position where they appear in the composition; the anchor row keeps the image’s height so following rows don’t overlap.

Images also work inside table cells, row items, list items (via ParagraphBuilder.Image - there they behave as blocks in the text flow, see tables) and in page header/footer bands (HeaderFooterBuilder.Image).

See also

• Feature support matrix
• Roadmap