Skip to content

v0.7.9 — rotated and vertical text geometry

Choose a tag to compare

@Detective-XH Detective-XH released this 13 Jun 14:39
· 146 commits to master since this release
v0.7.9
057036a

Added

  • Text.H and Text.Rotation complete the per-glyph geometry on the Text struct
    (returned by Page.Texts(), Page.Content(), and Reader.GetStyledTexts).
    Text.H is the nominal font-box height in points — the magnitude of the text
    rendering matrix's up-vector, so it equals the font size for ordinary horizontal
    text and stays positive and rotation-invariant for rotated runs, where
    FontSize (taken from the matrix x-scale) collapses toward zero: on a 90°-rotated
    run whose FontSize reads 0, H still reports the true 12 pt. Text.Rotation is
    the baseline's angle in degrees, counter-clockwise-positive from horizontal
    (0 for upright text) — the rendering matrix's baseline angle, distinct from and
    opposite-signed to the page /Rotate attribute (clockwise), which is not applied
    here. Both fields are additive (Text stays Stable-tier); no existing field value,
    golden, or DebugJSON output changes. Word.H/Line.H are unchanged (still the
    first-glyph font size); unifying them with the rotation-aware Text.H is left to a
    later vertical-layout change. Carrying the two new float64 fields widens Text
    from 64 to 80 bytes, so the structured-extraction paths
    (Texts/GetStyledTexts/Content/DebugJSON) allocate +8–13 % more bytes and
    run +2–3.5 % slower, with the allocation count unchanged; GetPlainText is a
    separate path and is unaffected (measured same-machine A/B, Apple M4 Pro). A
    fast-path that skips the per-glyph trigonometry on horizontal text was measured and
    gave no benefit, confirming the cost is the wider struct rather than the
    computation — so the simpler unconditional form ships. See EXAMPLES.md.

  • Vertical writing-mode text (a -V predefined CMap) now advances down the page
    instead of horizontally. Previously such text decoded correctly but every glyph
    advanced along the x-axis (or, for composite fonts, did not advance at all), so a
    multi-glyph vertical run overprinted at a single point. The per-glyph advance and the
    TJ kerning adjustment now translate along the vertical axis using the PDF default
    one-em displacement, and text following a TJ array in the same text block is no
    longer pushed an extra line down. The vertical_writing_mode warning message now
    states that the advance is applied with a default-metrics approximation rather than
    ignored. Per-glyph vertical metrics (/W2), the glyph position vector, and vertical
    word/line grouping are not yet modelled; horizontal text, GetPlainText, and all
    existing field values and goldens are unchanged.

  • Page /Rotate (the clockwise display-rotation attribute) is now honored, so
    extracted text and image coordinates land in the page's upright display space instead
    of the raw content space that previously ignored the rotation. A page authored sideways
    with /Rotate set to display upright now extracts with a horizontal baseline — the font
    size comes back, the rotated_text warning stops, and reading-order grouping works. A
    new Page.Rotate() int accessor returns the applied clockwise rotation
    (0/90/180/270); /Rotate is inheritable and normalized (a non-multiple of 90,
    an absent, or a non-integer value reads as 0). Text.Rotation now reflects the combined
    text-matrix and page rotation in display space. The change is additive and
    golden-neutral: an unrotated page (/Rotate 0) is bit-for-bit unchanged,
    GetPlainText is unaffected, and every corpus, DebugJSON, and signal golden is
    unchanged; the per-page cost is within measurement noise. See EXAMPLES.md.

Changed

  • Content().Rect (the re path-construction rectangles from Page.Content()) now
    honors the CTM: each rectangle's four corners are mapped through the current
    transformation matrix and returned as their axis-aligned display-space bounding box, so
    it agrees with the /Rotate-honored text and image geometry on a rotated or
    cm-transformed page — the last mixed-frame surface after the page-/Rotate work. An
    unrotated page with no cm transform is bit-for-bit unchanged; the returned bbox is now
    always normalized (Min <= Max), which additionally corrects un-normalized output for a
    negative-dimension re. DebugJSON does not emit content rectangles, so its goldens are
    unaffected.

  • Word.H and Line.H (and the Block and DebugJSON boxes derived from them) are
    now the rotation-aware nominal font height — the same basis as Text.H — finishing
    the unification noted when Text.H shipped. Previously they came from the text
    matrix's x-scale (FontSize), which collapses toward 0 on a 90°-rotated run, doubles
    under horizontal text scaling, and goes negative under a horizontal flip; they now
    report the text up-vector magnitude, which is rotation-invariant and always
    non-negative
    , so a word, line, or block reports the same nominal height as the glyphs
    in it. For ordinary horizontal text this value equals the font size exactly, so all
    existing extraction output — every corpus golden, DebugJSON, and Page.Words()/
    Page.Lines() result — is byte-for-byte unchanged; only rotated, flipped, or scaled
    runs (none of which were previously locked by a test) take the new value. One
    consequence on the Experimental Page.Blocks() API: because the corrected line height
    also feeds block grouping, the way non-horizontal lines group into blocks can
    change — in particular a 90°-rotated column, which used to collapse into a single block
    because its old height read 0, can now split into separate blocks.

Performance

  • The text-extraction paths that group glyphs into lines — Page.Words,
    Page.Lines, Page.Blocks, Reader.DebugJSON, and Page.ExtractionSummary —
    now allocate substantially less memory. The internal y-band grouping step used to
    copy the page's glyph slice twice per page (a defensive copy plus per-band
    value copies); it now sorts a lightweight index permutation and references the
    original glyphs in place, leaving the page's content untouched. Output is
    byte-for-byte identical. On a 22-page Traditional-Chinese document,
    Reader.DebugJSON drops −21.6 % bytes allocated (and ~1 % fewer allocations),
    and the word/line path drops −29–31 % bytes. Time per operation is flat to
    slightly lower — the workload is dominated by garbage-collection pressure, so
    fewer bytes chiefly relieve GC. This more than offsets the +8–13 % bytes the new
    Text.H/Text.Rotation fields added (above).

Verify this release

This is a signed git tag (ED25519-SK / FIDO2 hardware key). This release was
signed with:

256 SHA256:BlsTid0viIuF2db9zc/gY1JerD7mK47KH19brGGFKWM (ED25519-SK)

The maintainer's trusted signing keys are published on the GitHub account, so
nothing needs to be copied from these notes:

curl -s https://api.github.com/users/Detective-XH/ssh_signing_keys \
  | python3 -c "import json,sys; [print('*', k['key']) for k in json.load(sys.stdin)]" > allowed_signers
git -c gpg.ssh.allowedSignersFile=./allowed_signers tag -v v0.7.9
# expect: Good "git" signature for * with ED25519-SK key SHA256:BlsTid0...

Module integrity is independently guaranteed by the Go checksum database:

go mod download github.com/Detective-XH/gopdf@v0.7.9 && go mod verify