python-hwpx-automation 6.0.3__py3-none-any.whl

hwpx_automation/office/rendering/_render_hwpx_mac.applescript

@@ -0,0 +1,249 @@
+-- SPDX-License-Identifier: Apache-2.0
+-- Mac Hancom (한컴오피스 한글) render backend for the VisualComplete oracle.
+--
+-- This build of Hancom Office HWP (com.hancom.office.hwp12.mac.general) ships
+-- NO AppleScript dictionary (sdef) and NO headless convert CLI, so PDF export is
+-- GUI-only. This script drives that GUI deterministically through System Events
+-- (UI scripting), the Mac analogue of the Windows COM backend (_render_hwpx.ps1).
+--
+-- Flow, anchored on STABLE MENU-ITEM NAMES (prefix match), not pixels:
+--   open <input>  ->  파일 (File) > "PDF로 저장하기..."  ->  NSSavePanel
+--   -> Return (= the default 저장 button)  ->  파일 > "문서 닫기"
+--
+-- Why no typing is needed: the save panel is document-relative — it pre-fills
+--   위치 (location) = the input file's directory and the name field = the input
+--   stem. The Python caller therefore STAGES the input as <out_dir>/<out_stem>.hwpx,
+--   so pressing 저장 writes exactly <out_dir>/<out_stem>.pdf. The caller also
+--   pre-deletes the target, so the "대치(replace)?" sheet never appears in normal
+--   operation; it is still dismissed defensively here. A "문서 닫기" save-changes
+--   prompt is likewise discarded (we only exported; the doc is unmodified).
+--
+-- Usage:  osascript _render_hwpx_mac.applescript <input.hwpx> <out.pdf> [timeoutSecs]
+-- Output: prints "OK" on success; prints "ERR: <reason>" and exits 1 otherwise.
+
+property procName : "Hancom Office HWP"
+property appName : "Hancom Office HWP"
+property pdfDialogTitle : "PDF로 저장하기"
+property fileMenuName : "파일"
+property savePdfPrefix : "PDF로 저장하기"
+property closeDocPrefix : "문서 닫기"
+
+on run argv
+	if (count of argv) < 2 then return "ERR: usage: <input.hwpx> <out.pdf> [timeoutSecs]"
+	set inputPath to item 1 of argv
+	set outPdf to item 2 of argv
+	set timeoutSecs to 90
+	if (count of argv) ≥ 3 then
+		try
+			set timeoutSecs to (item 3 of argv) as integer
+		end try
+	end if
+
+	set inputBase to do shell script "basename " & quoted form of inputPath
+
+	try
+		-- 1) Open the staged input. LaunchServices focuses Hancom (launching it
+		--    if needed) and opens the document.
+		do shell script "open -a " & quoted form of appName & " " & quoted form of inputPath
+
+		-- 2) Wait for the document window to exist.
+		if not (waitForWindowNamed(inputBase, timeoutSecs)) then
+			return "ERR: document window did not open: " & inputBase
+		end if
+		-- A prior timed-out render can leave a same-named window behind, and
+		-- LaunchServices does not guarantee that the newly opened document is
+		-- frontmost. Raise the exact staged document before using its File menu.
+		raiseWindowNamed(inputBase)
+		delay 0.3
+
+		-- 3) 파일 > "PDF로 저장하기..."  (open the export save panel)
+		clickFileMenuItemByPrefix(savePdfPrefix)
+
+		-- 4) Wait for the export dialog.
+		if not (waitForWindowNamed(pdfDialogTitle, 30)) then
+			return "ERR: PDF save dialog did not appear"
+		end if
+		delay 1.0
+
+		-- 5) Press Return = the default 저장 button (no typing: panel is
+		--    pre-filled with 위치=out_dir, name=out_stem from the staged input).
+		tell application "System Events" to tell process procName
+			set frontmost to true
+			delay 0.3
+			key code 36 -- Return
+		end tell
+		-- Some Hancom builds expose the dialog before its default button is
+		-- ready. Retry Return once only while the same dialog is still present.
+		delay 1.0
+		if listContains(windowNames(), pdfDialogTitle) then
+			tell application "System Events" to tell process procName
+				set frontmost to true
+				key code 36
+			end tell
+		end if
+
+		-- 6) Defensive: a "대치(replace)?" sheet only appears if the target still
+		--    exists. Dismiss it (대치) if present, then wait for the file.
+		dismissOverwriteSheetIfPresent()
+
+		-- 7) The render is asynchronous — wait until the PDF lands at out_pdf and
+		--    the dialog has closed.
+		set wrote to waitForFile(outPdf, timeoutSecs)
+		waitForWindowGone(pdfDialogTitle, 15)
+
+		-- 8) Always close the document so the next render starts from a clean
+		--    session, even if the wait above was noisy. Discard any save-changes
+		--    prompt (we only exported; the doc content is unmodified).
+		try
+			clickFileMenuItemByPrefix(closeDocPrefix)
+			dismissCloseSheetIfPresent()
+		end try
+
+		if not wrote then return "ERR: PDF not written to " & outPdf
+		return "OK"
+	on error errMsg number errNum
+		-- Best-effort cleanup so a mid-flow error doesn't leak an open document.
+		try
+			clickFileMenuItemByPrefix(closeDocPrefix)
+			dismissCloseSheetIfPresent()
+		end try
+		return "ERR: " & errMsg & " (" & errNum & ")"
+	end try
+end run
+
+-- Find the 파일 menu by name, then click the first menu item whose name starts
+-- with `prefix`. Name-based so it survives index drift across Hancom versions.
+on clickFileMenuItemByPrefix(prefix)
+	tell application "System Events" to tell process procName
+		set frontmost to true
+		delay 0.2
+		set fileMenu to missing value
+		repeat with mbi in menu bar items of menu bar 1
+			if (name of mbi as string) is fileMenuName then
+				set fileMenu to menu 1 of mbi
+				exit repeat
+			end if
+		end repeat
+		if fileMenu is missing value then error "menu '" & fileMenuName & "' not found"
+		repeat with mi in menu items of fileMenu
+			try
+				if (name of mi as string) starts with prefix then
+					click mi
+					return
+				end if
+			end try
+		end repeat
+		error "menu item not found: " & prefix
+	end tell
+end clickFileMenuItemByPrefix
+
+on raiseWindowNamed(winName)
+	tell application "System Events" to tell process procName
+		set frontmost to true
+		try
+			perform action "AXRaise" of (first window whose name is winName)
+		end try
+	end tell
+end raiseWindowNamed
+
+-- Window polling uses the ATOMIC ``name of windows`` string list (never a held
+-- ``repeat with w in windows`` element reference): the save dialog appears and
+-- disappears mid-flow, so a lazily-resolved ``item N of every window`` can become
+-- an invalid index (-1719). Snapshotting names and guarding with ``try`` is
+-- race-safe.
+on windowNames()
+	try
+		tell application "System Events" to tell process procName
+			return (name of windows) as list
+		end tell
+	on error
+		return {}
+	end try
+end windowNames
+
+on listContains(theList, theValue)
+	repeat with x in theList
+		if (x as string) is theValue then return true
+	end repeat
+	return false
+end listContains
+
+on waitForWindowNamed(winName, secs)
+	repeat (secs * 2) times
+		if listContains(windowNames(), winName) then return true
+		delay 0.5
+	end repeat
+	return false
+end waitForWindowNamed
+
+on waitForWindowGone(winName, secs)
+	repeat (secs * 2) times
+		if not (listContains(windowNames(), winName)) then return true
+		delay 0.5
+	end repeat
+	return false
+end waitForWindowGone
+
+on waitForFile(p, secs)
+	-- size>0 alone is NOT completion: Hancom streams the PDF asynchronously and
+	-- closing the document mid-write truncates it (measured: a TOC-regenerating
+	-- document produced a deterministic %%EOF-less torso). Require the PDF
+	-- trailer marker so the export has actually finished before we move on.
+	repeat (secs * 2) times
+		if (do shell script "test -s " & quoted form of p & " && tail -c 64 " & quoted form of p & " | grep -q '%%EOF' && echo 1 || echo 0") is "1" then
+			return true
+		end if
+		delay 0.5
+	end repeat
+	return false
+end waitForFile
+
+-- The overwrite confirmation is a SHEET of the PDF dialog window; its buttons are
+-- directly accessible (unlike the save panel's own nested buttons). Re-fetch the
+-- window by name each pass and guard, since it is being torn down concurrently.
+on dismissOverwriteSheetIfPresent()
+	repeat 6 times
+		try
+			tell application "System Events" to tell process procName
+				set dlg to (first window whose name is pdfDialogTitle)
+				if (count of sheets of dlg) > 0 then
+					tell sheet 1 of dlg
+						if (exists button "대치") then
+							click button "대치"
+							return true
+						end if
+					end tell
+				end if
+			end tell
+		end try
+		delay 0.3
+	end repeat
+	return false
+end dismissOverwriteSheetIfPresent
+
+-- If closing surfaces a save-changes sheet, discard (저장 안 함 / 안 함). We only
+-- exported a PDF, so the document content is unchanged.
+on dismissCloseSheetIfPresent()
+	repeat 6 times
+		set handled to false
+		try
+			tell application "System Events" to tell process procName
+				repeat with wn in windowNames()
+					set w to (first window whose name is (wn as string))
+					if (count of sheets of w) > 0 then
+						repeat with b in buttons of (sheet 1 of w)
+							set bn to (name of b as string)
+							if bn contains "안 함" or bn contains "안함" then
+								click b
+								set handled to true
+							end if
+						end repeat
+					end if
+				end repeat
+			end tell
+		end try
+		if handled then return true
+		delay 0.3
+	end repeat
+	return false
+end dismissCloseSheetIfPresent

hwpx_automation/office/rendering/block_splits.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Renderer-neutral block split geometry.
+
+This module deliberately knows nothing about Hancom discovery, subprocesses,
+GUI automation, MCP, or form-fill policy.  Callers provide glyph-like objects
+with ``page``, ``x0`` and ``x1`` attributes and explicit column boundaries.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class PositionedGlyph(Protocol):
+    """Minimum geometry consumed by :func:`detect_block_splits`."""
+
+    page: int
+    x0: float
+    x1: float
+
+
+@dataclass
+class Block:
+    """One logical render block and its positioned glyphs."""
+
+    id: str
+    glyphs: list
+
+
+@dataclass
+class BlockSplit:
+    """A block that straddles a column or page boundary."""
+
+    block_id: str
+    kind: str
+
+
+def _column_index(x_center: float, column_x_bounds: list[tuple[float, float]]) -> int:
+    for index, (x0, x1) in enumerate(column_x_bounds):
+        if x0 <= x_center <= x1:
+            return index
+    return -1
+
+
+def detect_block_splits(
+    blocks: list,
+    column_x_bounds: list,
+    page_height: float,
+) -> list:
+    """Return blocks whose glyphs span more than one page or column.
+
+    ``page_height`` remains accepted for compatibility with the established
+    contract.  Page membership comes from each glyph's explicit ``page`` field.
+    """
+
+    del page_height
+    splits: list[BlockSplit] = []
+    for block in blocks:
+        if not block.glyphs:
+            continue
+        pages = {glyph.page for glyph in block.glyphs}
+        if len(pages) > 1:
+            splits.append(BlockSplit(block_id=block.id, kind="page"))
+            continue
+        columns = {
+            _column_index((glyph.x0 + glyph.x1) / 2.0, column_x_bounds)
+            for glyph in block.glyphs
+        }
+        columns.discard(-1)
+        if len(columns) > 1:
+            splits.append(BlockSplit(block_id=block.id, kind="column"))
+    return splits
+
+
+__all__ = ["Block", "BlockSplit", "PositionedGlyph", "detect_block_splits"]

hwpx_automation/office/rendering/detectors.py

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pixel-level visual detectors (ported from the baseline measurement harness).
+
+``diff_ratio`` and ``overlap_score`` are byte-for-byte the same heuristics the
+one-off ``scripts/visualcomplete-baseline/overlap_detect.py`` used, so the gate
+reproduces the harness verdicts on the measured corpus. Added here:
+
+* mask-aware variants (diff / new-ink restricted to outside the edit mask),
+* a diff-image generator for report artifacts.
+
+``numpy`` and ``Pillow`` are imported lazily so importing this module (and the
+whole :mod:`hwpx.visual` package) never requires the imaging stack; callers must
+gate on :func:`imaging_available` and degrade otherwise.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from PIL import Image
+
+# Pixels darker than this (0-255 grayscale) count as "ink".
+_INK_THRESHOLD = 160
+# Row is "inked" when at least this fraction of its pixels are ink.
+_ROW_INK_FRACTION = 0.01
+
+
+def imaging_available() -> bool:
+    """True when numpy + Pillow can be imported (required by every detector)."""
+
+    try:  # pragma: no cover - trivial import probe
+        import numpy  # noqa: F401
+        from PIL import Image  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def _ink_mask(img: "Image.Image", threshold: int = _INK_THRESHOLD):
+    import numpy as np
+
+    gray = np.asarray(img.convert("L"))
+    return gray < threshold
+
+
+def _match_size(a: "Image.Image", b: "Image.Image"):
+    if a.size != b.size:
+        width = min(a.size[0], b.size[0])
+        height = min(a.size[1], b.size[1])
+        a = a.crop((0, 0, width, height))
+        b = b.crop((0, 0, width, height))
+    return a, b
+
+
+def _zero_rects(mask, rects) -> None:
+    """In-place: clear the given pixel rectangles in a boolean ink/diff mask."""
+
+    for x0, y0, x1, y1 in rects:
+        mask[y0:y1, x0:x1] = False
+
+
+def diff_ratio(a: "Image.Image", b: "Image.Image") -> float:
+    """Fraction of pixels whose ink/no-ink state differs between ``a`` and ``b``."""
+
+    import numpy as np
+
+    a, b = _match_size(a, b)
+    diff = np.logical_xor(_ink_mask(a), _ink_mask(b))
+    return float(diff.sum()) / float(diff.size or 1)
+
+
+def diff_ratio_outside_mask(a: "Image.Image", b: "Image.Image", rects) -> float:
+    """Like :func:`diff_ratio` but ignoring pixels inside ``rects`` (allowed region)."""
+
+    import numpy as np
+
+    a, b = _match_size(a, b)
+    diff = np.logical_xor(_ink_mask(a), _ink_mask(b))
+    if rects:
+        _zero_rects(diff, rects)
+    return float(diff.sum()) / float(diff.size or 1)
+
+
+def new_ink_ratio_outside_mask(before: "Image.Image", after: "Image.Image", rects) -> float:
+    """Fraction of pixels that gained ink in ``after`` *outside* the mask.
+
+    This is the "the fill spilled out of its slot" signal: ink present in the
+    output but not the original, in a region the edit was not allowed to paint.
+    """
+
+
+    before, after = _match_size(before, after)
+    new_ink = _ink_mask(after) & ~_ink_mask(before)
+    if rects:
+        _zero_rects(new_ink, rects)
+    return float(new_ink.sum()) / float(new_ink.size or 1)
+
+
+def overlap_score(img: "Image.Image") -> dict[str, float]:
+    """Row-band analysis. A band far taller than the median line suggests
+    collapsed / overlapping lines (글자 겹침)."""
+
+    import numpy as np
+
+    mask = _ink_mask(img)
+    row_density = mask.mean(axis=1)
+    inked_rows = row_density > _ROW_INK_FRACTION
+
+    bands: list[tuple[int, int]] = []
+    start: int | None = None
+    for i, inked in enumerate(inked_rows):
+        if inked and start is None:
+            start = i
+        elif not inked and start is not None:
+            bands.append((start, i))
+            start = None
+    if start is not None:
+        bands.append((start, len(inked_rows)))
+
+    heights = [end - begin for begin, end in bands]
+    median_h = float(np.median(heights)) if heights else 0.0
+    max_h = float(max(heights)) if heights else 0.0
+    return {
+        "ink_ratio": float(mask.mean()),
+        "num_bands": float(len(bands)),
+        "median_band_height": median_h,
+        "max_band_height": max_h,
+        "tall_band_ratio": (max_h / median_h) if median_h else 0.0,
+    }
+
+
+def make_diff_image(a: "Image.Image", b: "Image.Image") -> "Image.Image":
+    """Render the ink XOR of two pages as a black-on-white diff image."""
+
+    import numpy as np
+    from PIL import Image
+
+    a, b = _match_size(a, b)
+    diff = np.logical_xor(_ink_mask(a), _ink_mask(b))
+    out = np.where(diff, 0, 255).astype("uint8")
+    return Image.fromarray(out)  # 2-D uint8 -> mode "L" inferred
+
+
+__all__ = [
+    "imaging_available",
+    "diff_ratio",
+    "diff_ratio_outside_mask",
+    "new_ink_ratio_outside_mask",
+    "overlap_score",
+    "make_diff_image",
+]

hwpx_automation/office/rendering/diff.py

@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Rasterize Hancom-exported PDFs and turn page pairs into visual signals.
+
+This is the scoring half of the gate: render PDF pages to images (``pymupdf``,
+imported lazily) and run the :mod:`.detectors` over them. The
+before/after comparison reproduces the baseline harness's verdict logic
+(``diff_ratio`` ≥ eps, relative tall-band overlap, page-count change), extended
+with edit-mask awareness for FormFit.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import hwpx_automation.office.rendering.detectors as detectors
+from hwpx.quality.rendering import EditMask
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from PIL import Image
+
+# A page whose tallest ink band is this many times the median line height is a
+# collapse signature; only flagged when the *after* page is meaningfully worse
+# than the *before* page (relative, like the baseline harness).
+_TALL_BAND_ABS = 3.0
+_TALL_BAND_REL = 1.0
+
+
+def pymupdf_available() -> bool:
+    try:  # pragma: no cover - trivial import probe
+        import fitz  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def render_pdf_to_images(pdf_path: str | Path, dpi: int = 150) -> list["Image.Image"]:
+    """Rasterize every page of ``pdf_path`` to a list of RGB ``PIL.Image``."""
+
+    import fitz  # pymupdf
+    from PIL import Image
+
+    pages: list[Image.Image] = []
+    with fitz.open(str(pdf_path)) as doc:
+        for page in doc:
+            pix = page.get_pixmap(dpi=dpi)
+            pages.append(Image.frombytes("RGB", (pix.width, pix.height), pix.samples))
+    return pages
+
+
+def _page_overlap(before_ov: dict[str, float], after_ov: dict[str, float]) -> bool:
+    return (
+        after_ov["tall_band_ratio"] >= _TALL_BAND_ABS
+        and after_ov["tall_band_ratio"] > before_ov["tall_band_ratio"] + _TALL_BAND_REL
+    )
+
+
+def compare_renders(
+    before_pdf: str | Path,
+    after_pdf: str | Path,
+    *,
+    edit_mask: EditMask | None = None,
+    diff_eps: float = 0.005,
+    dpi: int = 150,
+    diff_image_path: str | Path | None = None,
+) -> dict[str, Any]:
+    """Compare two rendered PDFs and return the visual signal dictionary."""
+
+    before_pages = render_pdf_to_images(before_pdf, dpi)
+    after_pages = render_pdf_to_images(after_pdf, dpi)
+    page_count = min(len(before_pages), len(after_pages))
+
+    max_full_diff = 0.0
+    max_outside_diff = 0.0
+    max_new_ink_outside = 0.0
+    overlap_flag = False
+    worst_page = 0
+
+    for i in range(page_count):
+        before_img, after_img = before_pages[i], after_pages[i]
+        full = detectors.diff_ratio(before_img, after_img)
+        if full > max_full_diff:
+            max_full_diff = full
+            worst_page = i
+
+        if edit_mask is not None and not edit_mask.is_empty:
+            rects = edit_mask.rects_for(i, before_img.size[0], before_img.size[1])
+            max_outside_diff = max(
+                max_outside_diff, detectors.diff_ratio_outside_mask(before_img, after_img, rects)
+            )
+            max_new_ink_outside = max(
+                max_new_ink_outside,
+                detectors.new_ink_ratio_outside_mask(before_img, after_img, rects),
+            )
+
+        if _page_overlap(detectors.overlap_score(before_img), detectors.overlap_score(after_img)):
+            overlap_flag = True
+
+    page_count_changed = len(before_pages) != len(after_pages)
+    has_mask = edit_mask is not None and not edit_mask.is_empty
+
+    effective_diff = max_outside_diff if has_mask else max_full_diff
+    unexpected_diff_outside_mask = effective_diff >= diff_eps
+    # Overflow: the fill painted ink outside its slot, or content spilled onto
+    # extra pages. Without a mask, the page-growth proxy is the available signal.
+    overflow_detected = len(after_pages) > len(before_pages)
+    if has_mask:
+        overflow_detected = overflow_detected or (max_new_ink_outside >= diff_eps)
+
+    diff_image_out: str | None = None
+    if diff_image_path is not None and page_count > 0:
+        image = detectors.make_diff_image(before_pages[worst_page], after_pages[worst_page])
+        image.save(str(diff_image_path))
+        diff_image_out = str(diff_image_path)
+
+    return {
+        "render_checked": True,
+        "page_count": page_count,
+        "before_page_count": len(before_pages),
+        "after_page_count": len(after_pages),
+        "page_count_changed": page_count_changed,
+        "max_diff_ratio": round(max_full_diff, 6),
+        "max_diff_outside_mask": round(max_outside_diff, 6),
+        "max_new_ink_outside_mask": round(max_new_ink_outside, 6),
+        "unexpected_diff_outside_mask": unexpected_diff_outside_mask,
+        "overlap_detected": overlap_flag,
+        "overflow_detected": overflow_detected,
+        "diff_image": diff_image_out,
+    }
+
+
+def analyze_single(after_pdf: str | Path, *, dpi: int = 150) -> dict[str, Any]:
+    """Single-render structural-visual pass (new-doc generation, no before).
+
+    Without a reference there is no faithful overlap baseline, so this only
+    confirms the doc rasterizes and reports its page count. Overlap/overflow
+    judgement for new docs is a Phase-E concern; here it stays conservative.
+    """
+
+    after_pages = render_pdf_to_images(after_pdf, dpi)
+    return {
+        "render_checked": True,
+        "before_page_count": None,
+        "after_page_count": len(after_pages),
+        "page_count_changed": None,
+        "max_diff_ratio": None,
+        "unexpected_diff_outside_mask": False,
+        "overlap_detected": False,
+        "overflow_detected": False,
+        "diff_image": None,
+    }
+
+
+__all__ = ["pymupdf_available", "render_pdf_to_images", "compare_renders", "analyze_single"]