Skip to content

feat(render): render quality harness for the layout engine - #693

Merged
KnifeLemon merged 2 commits into
builtin-enginesfrom
engine/render-harness
Oct 28, 2026
Merged

KnifeLemon merged 2 commits into
builtin-enginesfrom
engine/render-harness

Conversation

@KnifeLemon

Copy link
Copy Markdown
Owner

What does this change?

The render quality harness of Project 4 ("Layout engine: render quality harness", M0). It measures a document renderer
against rhwp today, with no sample or reference file in the repository, and Filee's layout engine plugs in at one
seam (DocumentRenderers.Candidate) when its first milestone lands. Documented in docs/RENDER-QUALITY.md, linked
from docs/ENGINES.md.

  • Feature matrix written in code (RenderFeatures): line-spacing kinds × alignment, tabs, lists, tables,
    headers/footers, notes, columns, floating objects × wrap, equations, and paragraphs in Korean, Chinese, Japanese,
    Arabic, Hebrew, Devanagari, Gujarati and Thai. The documents are built as an HDocument (written by the HWPX
    writer) or with DocxBuilder (through the DOCX reader). Binary HWP twins are made with rhwp convert.
  • Read-back checks with PdfPig, each its own tested function (PdfChecks): text round trip, overlapping glyphs
    on a line (> 0.05 em), glyphs inside the page and the body inside the margins, page count, baselines ±0.5 pt, fonts
    embedded and subset.
  • Differential compare (RenderDiff): page count, line-break agreement (Myers LCS over lines), baselines, and
    per-page SSIM (own small implementation) of PDFium pictures at 100 dpi. It is proven by rhwp against itself
    (identical) and by perturbed renderings: shifted 2 pt, and re-wrapped by a wider margin.
  • Thresholds in render-thresholds.json: what rhwp reaches where it falls short of the ideal, and an allow-list
    for the layout engine's compares where rhwp is wrong. A worse value fails the test. A better one is reported, so
    the threshold can be raised.
  • The layout engine's compare is skipped with a clear reason until a renderer is registered.
  • build/render-compare.ps1 runs a private corpus outside the repository (FILEE_RENDER_CORPUS, doc.hwpx +
    the PDF 한글 printed) and writes an HTML report to %TEMP%.
  • PdfPageWriterTests now share the checks, SSIM and the HarfBuzz test shaper (TestShaper), and the feat(engines): PDF backend spike: font subsetter and Skia page writer #683 acceptance
    page passes the read-back checks too.

No new packages or programs: PdfPig, PDFtoImage/PDFium, SkiaSharp and PDFsharp only. rhwp is only the reference in
tests.

rhwp 0.8.7 today (CI matrix)

Every check meets the ideal for the line-spacing rules (lines exactly one pitch apart), tabs, lists, tables,
headers/footers, notes, columns, Korean, Chinese and Japanese. Every font is embedded and subset, and the HWP
renderings of line-spacing-percent, tables and script-ko are identical to their HWPX ones. Below the ideal
(overlaps are the share of neighbouring glyph pairs):

Feature Measured
floating overlaps 0.1265: square wrap is lost, and two paragraphs are drawn on one line
equations overlaps 0.0303: m and c of E = mc² overlap
script-ar / he / hi / gu overlaps 0.4867 / 0.6 / 0.6724 / 0.6404 (unshaped, fixed widths: #202, #185, rhwp#8143)
script-th text 0.9735 (ำ drawn as two parts), overlaps 0.214

The full run (FILEE_RENDER_FULL=1) found that rhwp's rendering of the HWP twin of Chinese and Japanese paragraphs
draws 。 and 、 half an em over the next character. No line breaks where the HWPX rendering breaks (SSIM 0.23 and
0.19), and the equations are placed differently.

Type of change

  • Bug fix
  • New feature or improvement
  • New format or engine
  • Translation
  • Documentation
  • Build, CI or dependencies

How was it tested?

  • dotnet format --verify-no-changes
  • dotnet test: tests/Filee.Engines.Tests in Release, 2004 passed. The harness class takes about 25 s (the
    matrix 15 s, the perturbed compare 6 s, the self-compare 2 s), and the building-block tests about 3 s. The full
    run takes about 70 s.
  • build/render-compare.ps1 on a scratch corpus outside the repository (rhwp PDFs standing in for 한글's).
  • Tried it in the app (what you converted or clicked, and on which OS):

Checklist

  • New UI strings are in all src/Filee.App/Assets/i18n/*.json files (none)
  • New third-party code or binaries are listed in THIRD-PARTY-NOTICES.md (none)
  • The PR does one thing (unrelated changes go in a separate PR)

🤖 Generated with Claude Code

…against rhwp

Measures a document renderer without sample files in the repository (Project 4, M0):

- Feature matrix written in code (RenderFeatures): line spacing kinds x alignment, tabs, lists, tables, headers
  and footers, notes, columns, floating objects, equations and paragraphs in eight scripts, through the HWPX
  writer or DocxBuilder and the DOCX reader; binary HWP twins made with rhwp convert.
- Read-back checks with PdfPig, one tested function each (PdfChecks): text round trip, overlapping glyphs
  (> 0.05 em), glyphs outside the page and the margins, page count, baselines (±0.5 pt), fonts embedded and subset.
- Differential compare (RenderDiff): page count, line-break agreement (Myers LCS over lines), baselines and
  per-page SSIM of PDFium pictures at 100 dpi; proven by rhwp against itself and by perturbed renderings.
- Thresholds and an allow-list for known rhwp defects in render-thresholds.json; a worse value fails the test.
- One seam for the layout engine (DocumentRenderers.Candidate); its compare is skipped until it is registered.
- build/render-compare.ps1: a private corpus (FILEE_RENDER_CORPUS, doc.hwpx + the PDF 한글 printed) to an HTML
  report in the temp folder.

PdfPageWriterTests now share the checks, SSIM and the HarfBuzz test shaper (TestShaper) with the harness.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added the feature New features label Oct 28, 2026
@KnifeLemon KnifeLemon added the built-in engines Filee: built-in engines (Project 4), on the builtin-engines branch, not released yet label Oct 28, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	tests/Filee.Engines.Tests/PdfPageWriterTests.cs
@KnifeLemon
KnifeLemon merged commit fdcb7d3 into builtin-engines Oct 28, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

built-in engines Filee: built-in engines (Project 4), on the builtin-engines branch, not released yet feature New features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant