core/patterns.py

"""Build a resolution-independent :class:`Drawing` for each of the four patterns.

Geometry is derived from OpenCV itself (``getObjPoints``) wherever a board is
involved, so the rendered layout always matches what the OpenCV detector
expects -- including the ChArUco chessboard square parity, which is read from
real marker centres and never hardcoded (spec 8.3).

Each ``build_*`` function returns a :class:`PatternResult` whose ``drawing`` is
the *core* layout (pattern body + margin only). Format-specific decorations
(caption band, centre marks) are added later by :func:`compose_single_canvas`
(PNG/SVG) or by ``render_pdf`` (A4), because their placement depends on the
final canvas.
"""

from __future__ import annotations

from dataclasses import dataclass, field

import cv2
import numpy as np

from .aruco_utils import get_marker_module_matrix
from .drawing import Drawing, Line, Rect, Text

# --- Layout constants (mm) ---------------------------------------------------
DEFAULT_MARK_LEN_MM = 5.0       # fallback centre-tick length (used if no margin)
# Centre-alignment ticks default to this fraction of the quiet zone (margin), so
# they always stay well inside the margin and scale with it.
CENTER_MARK_QUIET_FRACTION = 0.3
DEFAULT_MARK_WIDTH_MM = 0.2     # stroke width of centre-alignment ticks
DEFAULT_CUT_LINE_WIDTH_MM = 0.25  # stroke width of the outer cut/trim rectangle
DEFAULT_CAPTION_FONT_MM = 2.6   # caption text em-size
CAPTION_LINE_SPACING = 1.35     # caption line pitch as a multiple of font size
CAPTION_PAD_MM = 2.5            # padding around the caption band
ID_FONT_MAX_MM = 6.0            # upper clamp for ID-label font size
ID_FONT_MIN_MM = 0.8           # below this an ID label is omitted (illegible)
INFO_LABEL_FONT_MAX_MM = 4.0    # max font for the bottom-right OpenCV-input label
INFO_LABEL_FONT_MIN_MM = 1.2    # below this the bottom-right label is omitted
# U+00D7 multiplication sign. Present in DejaVu (PNG), browser fonts (SVG) and
# the PDF base-14 fonts via WinAnsi/Latin-1, so it is safe in all three
# renderers -- unlike CJK glyphs, which only the PNG font carries.
MULT_SIGN = "×"


@dataclass
class PatternResult:
    """Everything needed to render a pattern and describe it.

    ``drawing`` is the core (body + margin) layout. ``summary`` carries computed
    values for the UI and caption. ``yaml_fields`` / ``yaml_mats`` feed the
    FileStorage YAML writer. ``warnings`` holds user-facing notes (in Japanese).
    """

    drawing: Drawing
    body_w_mm: float
    body_h_mm: float
    margin_mm: float
    yaml_fields: dict
    yaml_mats: dict
    summary: dict
    warnings: list[str] = field(default_factory=list)


def _obj_xy(marker_obj_points: np.ndarray) -> np.ndarray:
    """Return a marker's 4 corner ``(x, y)`` coordinates as a ``(4, 2)`` array."""
    return np.asarray(marker_obj_points, dtype=float).reshape(-1, 3)[:, :2]


def _marker_black_rects(
    dictionary: "cv2.aruco.Dictionary",
    marker_id: int,
    x0_mm: float,
    y0_mm: float,
    side_mm: float,
) -> list[Rect]:
    """Lay a marker's module matrix into the square box ``[x0, x0+side]^2``.

    Adjacent black modules in a row are merged into a single ``Rect`` so that
    output files stay small and vector edges stay crisp. Row 0 / column 0 of the
    matrix map to the top / left of the box (no flip; see ``aruco_utils``).
    """
    if side_mm <= 0:  # degenerate box -> nothing to draw
        return []
    mat = get_marker_module_matrix(dictionary, marker_id)
    n = mat.shape[0]
    ms = side_mm / n  # module size in mm
    rects: list[Rect] = []
    for r in range(n):
        c = 0
        while c < n:
            if mat[r, c]:
                run_start = c
                while c < n and mat[r, c]:
                    c += 1
                rects.append(
                    Rect(
                        x0_mm + run_start * ms,
                        y0_mm + r * ms,
                        (c - run_start) * ms,
                        ms,
                        "black",
                    )
                )
            else:
                c += 1
    return rects


def _id_label(
    text: str,
    cx_mm: float,
    top_mm: float,
    band_h_mm: float,
    max_font_mm: float,
) -> Text | None:
    """Build a centred, top-anchored monospace ID label inside a safe band.

    ``top_mm`` / ``band_h_mm`` describe a horizontal strip known to be free of
    any marker quiet zone. Returns ``None`` if the strip is too thin to hold a
    legible label, so callers can record that the label was skipped.
    """
    font = min(band_h_mm * 0.85, max_font_mm)
    if font < ID_FONT_MIN_MM:
        return None
    return Text(
        cx_mm,
        top_mm + (band_h_mm - font) * 0.5,
        text,
        font,
        h_anchor="middle",
        v_anchor="top",
        monospace=True,
    )


def _bottom_right_label(
    draw: Drawing, body_w: float, body_h: float, margin_mm: float, text: str
) -> bool:
    """Place a right-aligned info label in the bottom margin, below the board.

    Used by the chessboard and ChArUco builders to print the values an OpenCV
    detector needs (inner-corner count plus the relevant lengths). It lives in
    the bottom quiet margin so it never overlaps the board. The font scales with
    the margin but is also shrunk to fit the canvas width; the label is omitted
    only when that would make it illegible. Returns whether a label was added.
    """
    inset = margin_mm * 0.2
    avail_w = body_w + 2 * margin_mm - 2 * inset
    # ~0.6 em average glyph advance keeps the right-anchored text on-canvas.
    fit_w = avail_w / max(1.0, len(text) * 0.6)
    font = min(margin_mm * 0.5, fit_w, INFO_LABEL_FONT_MAX_MM)
    if font < INFO_LABEL_FONT_MIN_MM:
        return False
    draw.add(
        Text(
            body_w + 2 * margin_mm - inset,
            margin_mm + body_h + margin_mm / 2.0,
            text,
            font,
            h_anchor="end",
            v_anchor="middle",
        )
    )
    return True


# --- ArUco single marker -----------------------------------------------------
def build_aruco_single(
    dictionary: "cv2.aruco.Dictionary",
    dict_name: str,
    marker_id: int,
    marker_length_mm: float,
    margin_mm: float,
    show_id: bool,
    add_quiet_zone: bool,
) -> PatternResult:
    """ArUco single marker. Input is ``marker_length_mm`` (the marker itself, not
    including margin). The canvas is ``marker_length_mm + 2*margin_mm`` square."""
    if marker_length_mm <= 0:
        raise ValueError(f"markerLength ({marker_length_mm} mm) は正の値にしてください。")

    total_mm = marker_length_mm + 2.0 * margin_mm
    warnings: list[str] = []
    n = int(dictionary.markerSize) + 2
    module_mm = marker_length_mm / n
    if add_quiet_zone and margin_mm < module_mm:
        warnings.append(
            f"余白 {margin_mm:.2f}mm が 1 モジュール幅 {module_mm:.2f}mm 未満です。"
            "検出用の quiet zone を確保するため余白を広げることを推奨します。"
        )

    draw = Drawing(total_mm, total_mm)
    draw.extend(_marker_black_rects(dictionary, marker_id, margin_mm, margin_mm, marker_length_mm))

    if show_id:
        label = _id_label(
            f"id={marker_id}",
            cx_mm=total_mm / 2.0,
            top_mm=margin_mm + marker_length_mm,
            band_h_mm=margin_mm,
            max_font_mm=ID_FONT_MAX_MM,
        )
        if label is not None:
            draw.add(label)
        else:
            warnings.append("余白が狭いため ID ラベルを省略しました。")

    summary = {
        "pattern": "aruco_single",
        "dictionary": dict_name,
        "id": marker_id,
        "markerLength": marker_length_mm,
        "total": total_mm,
        "margin": margin_mm,
    }
    yaml_fields = {
        "pattern_type": "aruco_single",
        "unit": "mm",
        "dictionary": dict_name,
        "id": int(marker_id),
        "markerLength": float(marker_length_mm),
        "margin": float(margin_mm),
    }
    return PatternResult(draw, marker_length_mm, marker_length_mm, margin_mm, yaml_fields, {}, summary, warnings)


# --- ArUco GridBoard ---------------------------------------------------------
def build_gridboard(
    dictionary: "cv2.aruco.Dictionary",
    dict_name: str,
    markers_x: int,
    markers_y: int,
    marker_length: float,
    marker_separation: float,
    first_marker: int,
    margin_mm: float,
    show_ids: bool,
    add_quiet_zone: bool,
    marker_ids: list[int] | None = None,
) -> PatternResult:
    """ArUco GridBoard. Marker ids are passed to OpenCV as an explicit ids array
    (4.13's ``GridBoard`` constructor dropped the ``firstMarker`` parameter; its
    5th positional arg is now the ids Mat).

    If ``marker_ids`` is given it is used verbatim (arbitrary, possibly
    non-consecutive ids); otherwise ids are consecutive from ``first_marker``."""
    n_markers = markers_x * markers_y
    if marker_ids is not None:
        ids = np.asarray(marker_ids, dtype=np.int32).reshape(-1, 1)
        if ids.size != n_markers:
            raise ValueError(
                f"GridBoard には {n_markers} 個の ID が必要ですが {ids.size} 個指定されました。"
            )
    else:
        ids = np.arange(first_marker, first_marker + n_markers, dtype=np.int32).reshape(-1, 1)
    board = cv2.aruco.GridBoard(
        (markers_x, markers_y), float(marker_length), float(marker_separation), dictionary, ids
    )
    obj_points = board.getObjPoints()
    board_ids = np.asarray(board.getIds(), dtype=np.int32).ravel()

    body_w = markers_x * marker_length + (markers_x - 1) * marker_separation
    body_h = markers_y * marker_length + (markers_y - 1) * marker_separation
    draw = Drawing(body_w + 2 * margin_mm, body_h + 2 * margin_mm)

    warnings: list[str] = []
    module_mm = marker_length / (int(dictionary.markerSize) + 2)
    if add_quiet_zone and marker_separation < module_mm:
        warnings.append(
            f"マーカー間隔 {marker_separation:.2f}mm が 1 モジュール幅 "
            f"{module_mm:.2f}mm 未満です。検出が不安定になる恐れがあります。"
        )

    skipped_label = False
    for mk, mid in zip(obj_points, board_ids):
        xy = _obj_xy(mk)
        min_x, min_y = xy.min(axis=0)
        max_x, max_y = xy.max(axis=0)
        side = max_x - min_x
        x0 = margin_mm + min_x
        y0 = margin_mm + min_y
        draw.extend(_marker_black_rects(dictionary, int(mid), x0, y0, side))

        if show_ids:
            # The label sits below the marker. Keep one module of clearance from
            # this marker (bottom) and from the next marker (top) so we never
            # touch either marker's quiet zone (spec 4-4 / 8.2).
            is_bottom_row = (max_y + marker_separation) > body_h
            gap_below = margin_mm if is_bottom_row else marker_separation
            clearance_top = module_mm  # clear this marker's quiet zone
            clearance_bottom = 0.0 if is_bottom_row else module_mm  # clear next marker
            band_top = y0 + side + clearance_top
            band_h = max(0.0, gap_below - clearance_top - clearance_bottom)
            label = _id_label(str(int(mid)), x0 + side / 2.0, band_top, band_h, max_font_mm=side * 0.25)
            if label is not None:
                draw.add(label)
            else:
                skipped_label = True
    if show_ids and skipped_label:
        warnings.append("一部のマーカーは間隔が狭いため ID ラベルを省略しました。")

    summary = {
        "pattern": "gridboard",
        "dictionary": dict_name,
        "markersX": markers_x,
        "markersY": markers_y,
        "markerLength": marker_length,
        "markerSeparation": marker_separation,
        "firstMarker": int(board_ids[0]),
        "ids": board_ids.tolist(),
        "margin": margin_mm,
        "bodyW": body_w,
        "bodyH": body_h,
    }
    yaml_fields = {
        "pattern_type": "gridboard",
        "unit": "mm",
        "dictionary": dict_name,
        "markersX": int(markers_x),
        "markersY": int(markers_y),
        "markerLength": float(marker_length),
        "markerSeparation": float(marker_separation),
        "firstMarker": int(board_ids[0]),
        "margin": float(margin_mm),
    }
    yaml_mats = {"ids": board_ids.reshape(1, -1)}
    return PatternResult(draw, body_w, body_h, margin_mm, yaml_fields, yaml_mats, summary, warnings)


# --- ChArUco board -----------------------------------------------------------
def build_charuco(
    dictionary: "cv2.aruco.Dictionary",
    dict_name: str,
    squares_x: int,
    squares_y: int,
    square_length: float,
    marker_length: float,
    margin_mm: float,
    show_ids: bool,
    add_quiet_zone: bool,
    first_marker: int = 0,
    marker_ids: list[int] | None = None,
) -> PatternResult:
    """ChArUco board. Marker placement and chessboard parity are both derived
    from ``getObjPoints``. The board always uses OpenCV's modern (post-4.6)
    pattern -- the legacy pattern is intentionally not supported.

    Marker ids: if ``marker_ids`` is given it is used verbatim (arbitrary,
    possibly non-consecutive); otherwise ids are consecutive from
    ``first_marker``. Both go through an explicit ids array -- the same
    mechanism used for GridBoard."""
    if square_length <= 0:
        raise ValueError(f"squareLength ({square_length}mm) は正の値にしてください。")
    if marker_length >= square_length:
        raise ValueError(
            f"markerLength ({marker_length}mm) は squareLength "
            f"({square_length}mm) より小さくしてください。"
        )
    board = cv2.aruco.CharucoBoard(
        (squares_x, squares_y), float(square_length), float(marker_length), dictionary
    )
    # Read the marker count from this board before choosing the ids.
    count = len(board.getObjPoints())
    ids: np.ndarray | None = None
    if marker_ids is not None:
        ids = np.asarray(marker_ids, dtype=np.int32).reshape(-1, 1)
        if ids.size != count:
            raise ValueError(
                f"この ChArUco ボードには {count} 個の ID が必要ですが {ids.size} 個指定されました。"
            )
    elif first_marker != 0:
        ids = np.arange(first_marker, first_marker + count, dtype=np.int32).reshape(-1, 1)
    if ids is not None:
        board = cv2.aruco.CharucoBoard(
            (squares_x, squares_y), float(square_length), float(marker_length), dictionary, ids
        )
    obj_points = board.getObjPoints()
    board_ids = np.asarray(board.getIds(), dtype=np.int32).ravel()

    body_w = squares_x * square_length
    body_h = squares_y * square_length
    draw = Drawing(body_w + 2 * margin_mm, body_h + 2 * margin_mm)

    # Derive the parity of marker-bearing (white) squares from a real marker
    # centre, then paint every black square. Never hardcode the parity.
    centres = [(_obj_xy(mk).mean(axis=0)) for mk in obj_points]
    gx0, gy0 = int(centres[0][0] // square_length), int(centres[0][1] // square_length)
    white_parity = (gx0 + gy0) % 2
    for j in range(squares_y):
        for i in range(squares_x):
            if (i + j) % 2 != white_parity:  # black square
                draw.add(
                    Rect(
                        margin_mm + i * square_length,
                        margin_mm + j * square_length,
                        square_length,
                        square_length,
                        "black",
                    )
                )

    for mk, mid in zip(obj_points, board_ids):
        xy = _obj_xy(mk)
        min_x, min_y = xy.min(axis=0)
        max_x, max_y = xy.max(axis=0)
        side = max_x - min_x
        draw.extend(
            _marker_black_rects(dictionary, int(mid), margin_mm + min_x, margin_mm + min_y, side)
        )

    warnings: list[str] = []
    ring = (square_length - marker_length) / 2.0  # white quiet ring inside each square
    if add_quiet_zone and ring < marker_length / (int(dictionary.markerSize) + 2):
        warnings.append(
            f"白マス内の quiet zone (リング幅 {ring:.2f}mm) が狭いため、"
            "markerLength を小さくすると検出が安定します。"
        )
    if show_ids:
        # Any in-square placement would intrude on the marker's quiet ring, so
        # per-marker ID labels are intentionally omitted (spec 4-4 / 8.3, safety
        # first). The YAML carries the full ids array instead.
        warnings.append("ChArUco の ID 併記は quiet zone 保護のため省略しています（ID は YAML に出力されます）。")

    inner_x, inner_y = squares_x - 1, squares_y - 1

    # Bottom-right label with the values an OpenCV CharucoBoard needs: the
    # inner-corner count plus the square and marker lengths. Same placement as
    # the chessboard label so the two read consistently.
    _bottom_right_label(
        draw, body_w, body_h, margin_mm,
        f"inner {inner_x}{MULT_SIGN}{inner_y} | square {square_length:g} mm | marker {marker_length:g} mm",
    )

    summary = {
        "pattern": "charuco",
        "dictionary": dict_name,
        "squaresX": squares_x,
        "squaresY": squares_y,
        "squareLength": square_length,
        "markerLength": marker_length,
        "firstMarker": int(board_ids[0]),
        "ids": board_ids.tolist(),
        "margin": margin_mm,
        "bodyW": body_w,
        "bodyH": body_h,
        "innerCornersX": inner_x,
        "innerCornersY": inner_y,
    }
    yaml_fields = {
        "pattern_type": "charuco",
        "unit": "mm",
        "dictionary": dict_name,
        "squaresX": int(squares_x),
        "squaresY": int(squares_y),
        "squareLength": float(square_length),
        "markerLength": float(marker_length),
        "firstMarker": int(board_ids[0]),
        "margin": float(margin_mm),
    }
    yaml_mats = {"ids": board_ids.reshape(1, -1)}
    return PatternResult(draw, body_w, body_h, margin_mm, yaml_fields, yaml_mats, summary, warnings)


def charuco_marker_count(
    dictionary: "cv2.aruco.Dictionary", squares_x: int, squares_y: int
) -> int:
    """Number of ArUco markers a ChArUco board of this size carries.

    Independent of the marker/square lengths, so dummy valid lengths are used.
    Lets the UI validate an explicit id list up front.
    """
    board = cv2.aruco.CharucoBoard((squares_x, squares_y), 10.0, 7.0, dictionary)
    return len(board.getObjPoints())


# --- Chessboard --------------------------------------------------------------
def build_chessboard(
    squares_x: int,
    squares_y: int,
    square_length: float,
    margin_mm: float,
) -> PatternResult:
    """Plain checkerboard. The top-left square is white; ``(i+j)`` odd is black.

    Reports both square count and inner-corner count to avoid the classic
    ``findChessboardCorners`` mix-up (spec 8.4).
    """
    body_w = squares_x * square_length
    body_h = squares_y * square_length
    draw = Drawing(body_w + 2 * margin_mm, body_h + 2 * margin_mm)
    for j in range(squares_y):
        for i in range(squares_x):
            if (i + j) % 2 == 1:  # black square (top-left is white)
                draw.add(
                    Rect(
                        margin_mm + i * square_length,
                        margin_mm + j * square_length,
                        square_length,
                        square_length,
                        "black",
                    )
                )

    inner_x, inner_y = squares_x - 1, squares_y - 1

    # Bottom-right label carrying exactly what OpenCV's findChessboardCorners
    # needs: the inner-corner count (patternSize) and the square length (spec 8.4).
    _bottom_right_label(
        draw, body_w, body_h, margin_mm,
        f"inner {inner_x}{MULT_SIGN}{inner_y} | square {square_length:g} mm",
    )

    summary = {
        "pattern": "chessboard",
        "squaresX": squares_x,
        "squaresY": squares_y,
        "squareLength": square_length,
        "innerCornersX": inner_x,
        "innerCornersY": inner_y,
        "margin": margin_mm,
        "bodyW": body_w,
        "bodyH": body_h,
    }
    yaml_fields = {
        "pattern_type": "chessboard",
        "unit": "mm",
        "squaresX": int(squares_x),
        "squaresY": int(squares_y),
        "innerCornersX": int(inner_x),
        "innerCornersY": int(inner_y),
        "squareLength": float(square_length),
        "margin": float(margin_mm),
    }
    return PatternResult(draw, body_w, body_h, margin_mm, yaml_fields, {}, summary, [])


# --- Caption text ------------------------------------------------------------
def _format_ids(ids: list[int]) -> str:
    """Compact description of a marker-id set: a range if consecutive, else a
    (possibly truncated) list, always with the total count."""
    consecutive = all(ids[i + 1] - ids[i] == 1 for i in range(len(ids) - 1))
    if consecutive:
        return f"{ids[0]}..{ids[-1]} (consecutive, {len(ids)} total)"
    shown = ", ".join(str(x) for x in ids)
    if len(shown) > 60:
        shown = ", ".join(str(x) for x in ids[:10]) + ", ..."
    return f"{shown} (custom, {len(ids)} total)"


def build_caption_lines(
    result: PatternResult,
    opencv_version: str,
    timestamp: str,
    dpi: int | None = None,
) -> list[str]:
    """Compose the footer caption lines (spec 11). Only present fields appear.

    All caption text is English (ASCII) so it renders correctly in every output
    format: the PNG font (DejaVu) and the PDF base-14 fonts have no CJK glyphs,
    which would otherwise turn Japanese text into tofu boxes."""
    s = result.summary
    pt = s["pattern"]
    label = {
        "aruco_single": "ArUco single marker",
        "gridboard": "ArUco GridBoard",
        "charuco": "ChArUco board",
        "chessboard": "Chessboard",
    }[pt]

    lines: list[str] = [f"Type: {label}"]
    if pt == "aruco_single":
        lines.append(f"Dictionary: {s['dictionary']}  /  id: {s['id']}")
        lines.append(f"markerLength: {s['markerLength']:.3g} mm  /  total: {s['total']:.3g} mm")
    elif pt == "gridboard":
        lines.append(f"Dictionary: {s['dictionary']}  /  {s['markersX']}x{s['markersY']} markers")
        lines.append(
            f"markerLength: {s['markerLength']:.3g} mm  /  separation: {s['markerSeparation']:.3g} mm"
        )
        lines.append(f"id: {_format_ids(s['ids'])}")
    elif pt == "charuco":
        lines.append(f"Dictionary: {s['dictionary']}  /  {s['squaresX']}x{s['squaresY']} squares")
        lines.append(
            f"squareLength: {s['squareLength']:.3g} mm  /  markerLength: {s['markerLength']:.3g} mm"
        )
        lines.append(f"inner corners: {s['innerCornersX']}x{s['innerCornersY']}")
        lines.append(f"id: {_format_ids(s['ids'])}")
    elif pt == "chessboard":
        lines.append(f"{s['squaresX']}x{s['squaresY']} squares  /  squareLength: {s['squareLength']:.3g} mm")
        lines.append(f"inner corners: {s['innerCornersX']}x{s['innerCornersY']}")

    tail = f"margin: {s['margin']:.3g} mm"
    if dpi is not None:
        tail += f"  /  DPI: {dpi}"
    tail += f"  /  OpenCV {opencv_version}  /  {timestamp}"
    lines.append(tail)
    return lines


# --- Single-canvas composition (PNG / SVG) -----------------------------------
def compose_single_canvas(
    result: PatternResult,
    center_marks: bool,
    caption_lines: list[str] | None,
    cut_lines: bool = False,
    mark_len_mm: float | None = None,
    mark_width_mm: float = DEFAULT_MARK_WIDTH_MM,
    caption_font_mm: float = DEFAULT_CAPTION_FONT_MM,
    cut_width_mm: float = DEFAULT_CUT_LINE_WIDTH_MM,
) -> Drawing:
    """Wrap the core drawing into a tight single canvas with optional caption
    band, centre-alignment ticks, and an outer cut/trim rectangle (used by the
    PNG and SVG renderers).

    ``mark_len_mm`` defaults to ``CENTER_MARK_QUIET_FRACTION`` of the margin
    (quiet zone) so the ticks always stay inside the margin. ``cut_lines`` draws
    a solid rectangle along the pattern+margin edge (never the caption band)."""
    core = result.drawing
    pattern_w, pattern_h = core.width_mm, core.height_mm  # pattern + margin extent

    band_h = 0.0
    if caption_lines:
        line_pitch = caption_font_mm * CAPTION_LINE_SPACING
        band_h = 2 * CAPTION_PAD_MM + len(caption_lines) * line_pitch

    out = Drawing(pattern_w, pattern_h + band_h, list(core.items))

    # Cut rectangle hugs the pattern+margin edge (above any caption band).
    if cut_lines:
        out.extend(_cut_rect_lines(pattern_w, pattern_h, cut_width_mm))

    # Centre marks sit on the edges of the pattern+margin rectangle so they mark
    # the true pattern centre even when a caption band is appended below.
    if center_marks:
        length = mark_len_mm if mark_len_mm is not None else CENTER_MARK_QUIET_FRACTION * result.margin_mm
        out.extend(_center_marks(pattern_w, pattern_h, length, mark_width_mm))

    if caption_lines:
        out.add(Line(0, pattern_h, pattern_w, pattern_h, 0.15, "black"))
        line_pitch = caption_font_mm * CAPTION_LINE_SPACING
        y = pattern_h + CAPTION_PAD_MM
        for ln in caption_lines:
            out.add(Text(CAPTION_PAD_MM, y, ln, caption_font_mm, "start", "top"))
            y += line_pitch
    return out


def _center_marks(w: float, h: float, length: float, width: float) -> list[Line]:
    """Four inward ticks at the midpoints of the rectangle ``[0,w] x [0,h]``."""
    cx, cy = w / 2.0, h / 2.0
    return [
        Line(cx, 0, cx, length, width),          # top
        Line(cx, h - length, cx, h, width),      # bottom
        Line(0, cy, length, cy, width),          # left
        Line(w - length, cy, w, cy, width),      # right
    ]


def _cut_rect_lines(w: float, h: float, width: float) -> list[Line]:
    """Solid rectangle outline along the outer edge of ``[0,w] x [0,h]``.

    The stroke is inset by half its width so the whole line stays inside the
    canvas. It marks where to trim the printout; sitting on the pattern+margin
    boundary, it never enters the quiet zone (which is the margin itself)."""
    half = width / 2.0
    x0, y0, x1, y1 = half, half, w - half, h - half
    return [
        Line(x0, y0, x1, y0, width),  # top
        Line(x0, y1, x1, y1, width),  # bottom
        Line(x0, y0, x0, y1, width),  # left
        Line(x1, y0, x1, y1, width),  # right
    ]