OfficeIMO.Epub.Image 3.5.3

OfficeIMO.Epub.Image

OfficeIMO.Epub.Image is the thin visual adapter between the bounded EPUB package model and the existing OfficeIMO HTML/Drawing renderer. It adds no image encoder or layout engine.

Retained application/xhtml+xml chapters are parsed as XML. Empty non-void elements remain siblings, and CSS text and SVG/MathML namespaces retain their XML meaning. Malformed XML, noncanonical XHTML names, processing instructions, and DTD-defined entity references are rejected instead of being recovered as HTML. text/html chapters and the extracted-text fallback keep HTML parsing.

Load raw chapter HTML and resource payloads when visual fidelity matters:

EpubDocument book = EpubDocument.Load(path, new EpubReadOptions {
    IncludeRawHtml = true,
    IncludeResourceData = true
});

IReadOnlyList<OfficeImageExportResult> pages = await book
    .ToImages()
    .Paged()
    .AsPng()
    .ExportAsync();

When raw HTML or resource bytes were not retained, export remains available through a diagnosed plain-text or missing-resource fallback.

Package resources use case-sensitive container paths. Chapter count, text-budget, invalid-encoding, and unsupported-spine omissions propagate into image diagnostics and the RequireNoOmissions policy.

An HTML base element resolves relative URLs from the chapter's container path. External URLs never select retained package bytes. Use asynchronous export with ResourceResolver to supply policy-approved external resources; synchronous export reports external images that still need resolution.

Fixed-layout canvas inspection

Inspect one retained XHTML chapter declared pre-paginated before exporting it:

EpubFixedLayoutInspection inspection = book.InspectFixedLayoutPage(0);
foreach (OfficeDrawingQualityIssue issue in inspection.CanvasQuality.Issues) {
    Console.WriteLine(issue.Message);
}

The chapter must declare one viewport with positive numeric width and height. Inspection renders at that viewport with zero margins, using the existing package resource resolver and caller-supplied font/resource limits. It compares rendered element rectangles with the declared page canvas, including content extending beyond the automatic output clip. Explicit authored clips remain in effect. Negative and transformed coordinates are included. Affine effect groups are checked through their contents; empty space in intermediate rendering buffers does not count as overflow. Excessive inspection surfaces fail instead of returning incomplete results. No output image is encoded.

Inspect HasCanvasOverflow, HasTextInkOverflow, TextInkDiagnostics, ClippingDiagnostics, Rendering.Diagnostics, PackageDiagnostics and PreparationDiagnostics together. HasRenderingWarnings summarizes diagnosed rendering loss and package/preparation/inspection warnings. Suppressing package diagnostics for image export does not suppress them in this inspection. Missing raw XHTML, a reflowable chapter, an unsupported viewport or encrypted content rejects inspection; text fallback cannot establish fixed geometry.

Inspect identified layout regions in the same render pass when a page contains positioned text or image containers:

EpubFixedLayoutInspection inspection = book.InspectFixedLayoutRegions(
    0, new[] { "caption", "illustration" });
foreach (EpubFixedLayoutRegionInspection region in inspection.Regions) {
    Console.WriteLine($"{region.ElementId}: box={region.HasOverflow}, ink={region.HasTextInkOverflow}");
}

Region findings compare rendered element rectangles with the region's local border box. Moving or rotating the entire region does not change this local containment; descendant transforms do. Authored clips inside the region remain in effect, while ancestor clips do not redefine its local box. The page-level canvas findings still include the whole scene's transforms and clips. Supply up to 1024 distinct IDs of positioned, floating, flex or grid containers. Missing or duplicate source IDs and targets without one rendered region, including hidden or unsupported targets, reject inspection rather than produce an empty successful result. Region selection does not modify the retained XHTML or the rendered painting.

Each region also exposes TextInkDiagnostics and HasTextInkOverflow for positioned XHTML text in that same local space. A glyph can extend outside its container while both the layout box and the page-level ink check still fit. Descendant transforms are included; region and ancestor transforms do not change local containment. Rectangular and filled path clips on the region and its descendants constrain the measured contours. Ancestor clips do not suppress local ink findings. Regional ink warnings contribute to the enclosing report's HasRenderingWarnings.

HasClippedElementBounds identifies rendered element rectangles that extend outside rectangular scene clips. ClippingDiagnostics gives the source, clip rectangle, clipped axes and finding count. These informational findings include intentional image and background crops; they do not automatically mean the design is wrong. Descendant transforms and clips are included, and an unclipped axis is not treated as a boundary. The automatic output clip is excluded. Inspection rejects pages with more than 1024 scene clips instead of silently truncating the checks.

Path-shaped clips, including rounded overflow boxes, produce HtmlRenderClipGeometryNotInspected warnings. Their precise clipping geometry is not covered by the rectangular element check. Text-ink inspection below can still measure supported filled paths; these are separate evidence scopes.

TextInkDiagnostics separately compares positioned XHTML and embedded vector text glyph outlines with the page canvas, using the shared drawing engine's font fallback, shaping, color-glyph layers, synthetic styles and affine transforms. Decorations use conservative stroke bounds. The measurement uses nominal CSS-pixel geometry at scale 1; it is not a pixel scan. Empty space in a text frame is excluded. Transparent text is ignored. Glyph contours use non-zero winding after supported clipping, so holes and cancelled overlaps do not count as filled ink. Complex outlines that exceed the bounded filled-geometry analysis produce an unmeasured warning. Rectangular clips and filled path clips constrain the measured contours before their bounds are compared with the page or region. Nested, transformed and single-axis clips are supported. Concave, self-intersecting and multi-contour paths retain their even-odd or non-zero fill rule. Rounded rectangles, ellipses and polygons use the shared Drawing renderer's curve flattening at nominal scale 1, including affine transforms. HtmlRenderClippedTextInkBounds informational findings identify text outline or conservative decoration bounds cropped by a supported clip or embedded drawing viewport; review whether the crop is intentional. Automatic page output clipping is excluded; embedded drawing viewports are included because those drawings paint into separate surfaces. Unsupported open paths, non-finite or over-budget geometry and unavailable text outlines produce HtmlRenderTextInkNotInspected warnings rather than an apparently clean result. Supported paths are limited to 512 commands and 512 flattened vertices. Embedded vector inspection follows positioned, baseline, wrapped, rich and shaped vertical text through affine effect groups and supported filled drawing clips, with each drawing surface's fonts and viewport. Baseline, wrapped and rich text reuse the renderer's layout and glyph placement, including mixed sizes, synthetic styles, rotation, alignment and font fallback. Ink inspection measures the retained render output, including ellipsis; it does not establish that every source character remains visible after layout. Vertical text uses the selected shaping provider's vertical advances, the painter's text-box clip and frame transform, color layers and conservative decoration bounds. Missing or unusable vertical shaping remains unmeasured; inspection does not infer geometry from the fallback layout. Shape-only drawings do not produce text warnings, including masked groups, singular transforms and repeated vector patterns. A bounded content check retains unmeasured warnings when those containers contain text, text-bearing masks, outline metadata or embedded images; it does not infer pixel visibility. Text represented by outline metadata, masks, vector patterns and embedded image resources remain explicitly unmeasured; the inspection does not recover text from arbitrary paths or raster pixels. Each vector traversal is limited to 4096 elements and line runs and 64 nested groups/clips. Baseline, wrapped, rich and vertical text input is additionally limited to 65,536 UTF-16 code units across the traversal. Repeated ellipsis measurements have a separate one-million character-work limit per text block and share the traversal work limit. Inspection rejects more than 4096 text runs, 64 nested clips, or excessive contour-clipping work instead of returning a partial report.

This is managed layout evidence. Filled geometry uses a 1e-9 CSS-pixel tolerance for coincident crossings and degenerate vertical intervals; it does not establish pixel coverage, shadows/filters, or pixel visibility within clipped contours or element rectangles. SVG spine inspection, native-reader presentation and accessible reading order require separate qualification. A clean report does not certify a publication.

Generated capability summary

This table is generated from the package-neutral OfficeIMO operation catalog. The detailed source contracts remain authoritative for feature-level behavior and limitations.

The complete rows for OfficeIMO.Epub.Image are published in the generated operation contract.