车票式旅行卡生成器

Overview

输入风景照 + 地点/时间等信息，输出车票式（登机牌式）图片。输出恒为 PNG。

票面结构（内部各比例按 9 张样张实测还原；票面宽高比与画幅为设计选择，见下）：

        ┌────────────────────────────────┬╌╌╌┐
        │                                │   │
     ●  │        照片区（左 68.6%W）       │   │  ●  ← 左右缘半圆冲孔（票面高度中线，左右各一）
        │                                │   │
        └────────────────────────────────┴───┘
          ● ● ● ● ●  左右两侧齿孔（半圆**内凹**，齿距 0.0558H，左右同相位）

                     ╷
                     ╵   ④ 虚线撕线 x = 71.62%W；其**上、下边缘各切一个三角形豁口**
                         （半宽 3.0%W、深 4.0%H，尖角朝票面内侧）—— 见 `references/design-spec.md` §2.1

> 两侧穿孔是"内凹半圆"、且左右同相位（见 references/design-spec.md §2.2）——这是刻意的，
> 不要"修"成外凸齿：一张纸打孔后撕成两半，两半各留一个凹半圆；按原样对接时两个半圆恰好合成
> 那个完整的圆孔（"严丝合缝拼成一张纸"）。外凸的半圆会彼此顶撞，做不到这一点。
> 同样，中央大冲孔左右两缘各有一个（不是只做右缘），保证左右对称。

信息区自上而下最多 7 行：首行编号 → 地名大写拼音（1~3 行大标题）→ 日期 → 中部编号 → 编号串 → 条形码。
默认只输出 5 项：No.<年> → 地名 → 日期 → 编号串 → 条形码（中部编号默认不画；中文小字已停用）。
各行在信息区中轴水平居中（不是左对齐 —— 样张实测结论，见 references/design-spec.md §3）。

字号自适应（硬约束）：每行字高按"内容长度 vs 可用宽度"逐行收缩；可用宽度以信息区中轴为基准取
左右对称约束（左侧不得越过照片右缘、右侧不得越过票面留白）。地名在"单行紧排 / 2 行 / 3 行"中
择字高最大者，故长地名会自动折行而非被压成小字。实测 8 组长文本（含 西双版纳→XISHUANGBANNA
这类 13 字母）与照片净距全部 > 46px，无一压到照片。

> 「堆叠两行」是预期版式，不是缺陷（使用人已确认）：QINGDAO 会渲染成 QING / DAO 两行。
> 原因是可用宽度仅 188px，单行需约 320px → 字高被迫压到约 36px（名义值的 6 折，票根会明显空）；
> 折行后字高可达约 61px，观感更饱满，也接近登机牌的地名堆叠风格。不要改成强制单行。

票面尺寸：画布默认 4:3 横版（1440×1080），票面本体 2.5:1（修长造型）、占画布面积 26.4%。
尺寸取两个上限的较小者：
TW = min(0.7854 × CW, √(面积占比 × CW × CH × 票面宽高比))。

• 只有宽度上限 → 横版画布（4:3）配修长票面会过宽、留白不足；
• 只有面积上限 → 竖版画布（3:4）在 2.5:1 下会把票面撑到画布宽的 94%、左右留白消失。

取小后，任意"画幅 × 票面比例"组合都保得住四周留白。该式在样张比例（--aspect 1.7535）下与旧公式
逐项等价：34 → 848×484、11 → 1131×645、916 → 848×484。

配色策略：背景底色由风景照主色决定（主色相锁定，仅在明度/彩度上缩放）；
票面走 tonal：与底色同色相、明度抬高、彩度微增，形成"同色系但有可见区别"的搭配
（实测 9 张样张纸面与底色的 |ΔH| 中位仅 8.2°，第 9 张即"浅绿纸 / 灰绿底"）。墨色恒为暖褐系。

何时使用

⚠️ 出图前必须完成的交互

使用人上传照片后，不得直接出图，必须先询问两项：

1. 版式：满幅出血（--fit bleed）还是 留白贴票（--fit inset）？
2. 底部编号串：--code 填什么内容？允许中文，也可回答"不要"。

其余项（画幅、色系）可给默认。完整询问话术、选项默认值、多组素材提交格式见 references/interaction.md。

前置依赖

pip install pillow numpy python-barcode

• python-barcode 缺失时不报错，条形码自动退化为规则装饰条带（compose.decorative_bars）。要"真实可扫条码"须确认已安装。
• 中文字体走系统回退：msyh.ttc（Win）→ PingFang.ttc（macOS）→ NotoSansCJK（Linux）。编号串/日期/中文地名含中文时自动切中文字体。
• 标题字体随包内置（PlayfairDisplay / ZillaSlab / Inter），以 gzip+base64 文本（assets/fonts/*.json）分发，
  首次调用由 compose.bundled_font() 自动解包到系统临时目录并缓存，无需联网、无需额外依赖。
  （以文本形式分发是为满足发布平台的文件类型白名单——平台不收 .ttf。）

快速开始

# 单张（4:3 横版、票面 2.5:1 为默认）
python scripts/gen_ticket.py \
  --photo "/path/照片1.jpg" \
  --city 青岛 --date "9月21日" \
  --code "手机摄影" --out ./out

# 同组多张（输出自动加序号 -01/-02/…）
python scripts/gen_ticket.py --photos 照片1.jpg 照片2.jpg 照片3.jpg \
  --city 青岛 --date "9月21日" \
  --code "手机摄影" --out ./out

# 多组批量（每组各自带地点/日期）
python scripts/gen_ticket.py --batch batch.json --out ./out

# 要样张比例（画幅 3:4、票面 1.7535:1）
python scripts/gen_ticket.py --photo p.jpg --city SHAO XING --date 2026-9 \
  --size 34 --aspect 1.7535 --out ./out

产出：<地名>-<日期>[-序号].png + 同名 .palette.json（底色、票面、墨色、主色相、对比度、票面坐标、paper_spec、text_avail）。

参数速查

文案类

地名 → 大写拼音的转换规则

> 折行行数由"字高最大者胜"决定：能放下就用单行，放不下才折成 2~3 行（按音节均衡）。
> ⚠️ 多音字以 pypinyin 默认读音为准（如 西安 → XIAN，与"先"同形；如需区分请直接传 XI AN）

版式类

配色类

输出类

> 输出格式恒为 PNG，不再提供 JPG 导出。

输出格式

默认票面宽高比 2.5:1（--aspect 2.5）：

票面水平居中、垂直居中。样张比例的标称基准为样张 21210825_15（约 1131×645）。
竖版与 9:16 画布在修长票面下上下会留出较多背景 —— 刻意保留（供平台顶/底 UI 遮挡与后期加字）。

票面同色系配色（tonal）

1. 取色：照片缩样 160×160 → 中位切分量化（Median-Cut），得 8 个主色及占比。
2. 定主色：取权重最高、OKLCH 彩度 ≥ 0.05 且明度在 (0.15, 0.90) 的"有彩色"。全图近黑白/低彩时退化为全图均色（80×80 缩样）的色相。
3. 派生底色：锁定主色相，明度取 --bg-lightness，彩度 = 主色彩度 × --bg-chroma-scale 并夹在 [0.008, 0.038]。
4. 派生票面（tonal）：与底色同色相，明度 = 底色基准 + --paper-lift，彩度 = 底色彩度 × --paper-chroma-gain。
   → 默认参数下渲染后实测 ΔL +0.041 / ΔH −0.0° / RGB 差 ≈ (13,15,15)，即"同色系、浅一档、看得出分界"。
5. 墨色：固定暖褐 (78,51,32) / 近黑褐 (40,34,25)，用 WCAG 校验，对比度 < 4.5:1 时逐级降明度（实测 11.2~11.3）。

如何自动 / 手动选择票面色系

> ⚠️ 已知限制：底色很浅（--bg-lightness ≈ 0.95）时，--paper-lift 超过约 0.04 会顶到 sRGB 上限——
> 票面趋于近白、且实测色相出现漂移（示例 huangshan 因该原因 ΔH = −18.5°）。
> 需要"浅色纸 / 灰底"的强对比时，应同时下调 --bg-lightness，而不是一味加大 lift。

背景与票面均叠加亚麻织纹；背景另有"左上最亮 → 右下最暗"的对角线性渐变（multiply，对角降幅约 0.05 明度）+ 极轻暗角；
票面叠纸纹与纸粒；照片做降饱和 0.86 + 微提对比 1.06 + 颗粒的统一调性。

> 背景明度已按同位置取样标定：左上/顶/左/底 四点与 8 张样张的中位偏差 MAE 0.008。

字体与匹配原则

匹配原则（四步）：先定骨架类型（衬线 / 无衬线 / 板衬线）→ 再定笔画对比度与字重 → 再定字宽与大写高 → 最后按实测大写高反算字号（font_for_cap() 用 200px 探测 getbbox("H")）。

样张字体的笔画实测（列为 p75/p10 粗细比，取自样张 15 标题带）：

• 中西文混排对齐：compose.text_font() 按内容自动选字体——含中文走中文字体、否则走西文字体；
  两条路径都按目标字高反算字号（中文经 CJK_EM_K = 0.80 补偿），故同一行的中西文高度一致。
• 不要求逐字形一致：样本为商用模板字体，无法取得；采用同骨架 + 同对比度 + 同字重的开源替代，观感接近即可。
• 更硬朗的板衬线 → --font-set slab（ZillaSlab）；有授权字体 → --title-font /path.ttf。

常见调整

文件结构

travel-ticket-card/
├── SKILL.md
├── scripts/
│   ├── gen_ticket.py    # 主入口 / CLI / 单张·同组多张·批量
│   ├── compose.py       # 票面几何（含三角豁口）、排版、字号自适应、拼音折行、字体路由、条形码
│   ├── palette.py       # 取色与 OKLCH 角色色派生（tonal / cream）
│   └── effects.py       # 亚麻/纸纹/对角渐变/暗角/投影/照片调性
├── tools/               # 复测与标定脚本（开发/复核用，生成流程不依赖）
│   ├── verify_geometry.py   # 梯度法量取票面与照片边界
│   ├── verify_edges.py      # 背景建模 + 残差图，量取上/下边缘形状（含豁口）
│   ├── fit_background.py    # 背景渐变场拟合
│   ├── peak_profile.py      # 逐行像素偏差（定位弱边界）
│   └── structure_map.py     # 结构图（无图像视觉能力时判读版式）
├── references/
│   ├── design-spec.md   # 全部实测比例、色值、算法、验证与缺口
│   └── interaction.md   # 提示词与交互规程（版式/编号串询问、批量提交格式）
├── assets/fonts/        # 内置字体数据（*.json = gzip+base64，首次使用解包到临时目录）
└── examples/
    ├── inputs/          # 示例输入照片
    ├── out/             # 示例产出（43 横版 × 2 版式 + 34/916 样张比例 + 11 cream + 同组多张）
    └── batch.example.json

溯源说明

• 设计比例取自用户提供的 9 张车票式样张（1440×1920），标称基准为样张 21210825_15
  （left=172 / top=658 / bot=1276，票面本体约 1131×645）。
• ⚠️ 9 张样张的几何并不一致：实测票面高/画布在 0.290–0.338、左边距 108–243px、照片宽 593–855px 浮动。
  本 Skill 还原的是一套标称比例，而非某张"通用模板"。逐项实测表见 references/design-spec.md §0。
• 撕线处的三角豁口（④）：在样张 20 / 15 上实测到以撕线为中心、对称 V 形的上下边缘凹陷
  （样张 20：上缘最深 +27px、下缘 −25px；样张 15：下缘深 26px、中心 u=0.716 与撕线位置重合）。
  标称取值：半宽 3.0%W、深 4.0%H、中心 = 撕线 x。其余样张因纸色与底色色差仅 2~6 个色阶（如样张 13 为 2）
  而无法判别，此项并非 9 张通用。量测方法与残差图见 references/design-spec.md §2.1。
• ⚠️ 已知缺陷（未修）：自动主色相选取不可靠 —— 中位切分按像素数切分，导致 8 个色箱权重恒等（实测均 0.1250），
  "取权重最高"与 min_weight 过滤失效；且 NEUTRAL_CHROMA = 0.050 对真实照片偏严，会触发全图均色回退。
  3 张示例输入中有 2 张的自动色相与稳健参考相差 >88°。因底色明度固定 0.955、彩度 ≤0.038，视觉上近白故不易察觉；
  需精确控制底色色系时请显式传 --bg-hue-shift。详见 references/design-spec.md §11.3 第 9 条。
• 票面同色系：9 张样张实测纸面与底色 |ΔH| 中位 8.2°、纸面明度中位 +0.017、彩度 +0.004；
  第 9 张（灰绿底）为 +0.069 的"浅绿纸 / 灰绿底"。见 references/design-spec.md §5.4。
• 样张上固定出现的字符串 2VHIXINGTU 经比对为原作者水印；现按用户要求改为「底部编号串」询问项，
  由使用人填写（可中文），--code 默认留空。
• v1.2.0 的设计变更（用户指定，非样张实测）：画布默认 4:3 横版、票面宽高比 2.5:1、
  信息区去掉「地名中文小字」与「中部编号」。这些是使用者对版式的主动选择，
  不再等同于 9 张样张的比例；要复现样张观感请显式传 --size 34 --aspect 1.7535。
  references/design-spec.md 中标注"样张实测"的数值仍以样张为准，未随之改动。
• v1.2.1 的几何修正（用户指定），三项，均已端到端量测（见 references/design-spec.md §1.3 / §2.2）：
  1. 留白贴票四边等宽：删除 pad_h / pad_v / photo_w / photo_h，改为单一 inset_pad = 0.0853H
  （＝冲孔半径），实测 43 画幅 35/35/35/35；抽出 perf_px(W) 消除 0.5px 取整误差
  （修正前右净距为 34）。
  2. 左侧补上大冲孔：中央半圆冲孔原先只做右缘 → 现左右两缘各一个，左右对称。
  3. 齿形由"外凸"改为"内凹"：原为外凸实心半圆，两张票面对接时会相互顶撞；
  现为向内挖空的半圆、左右同 y 同半径，对接缝逐行一致（仅左有纸 / 仅右有纸各 0 行），
  即两半拼合成一张完整的纸、只余规则圆孔。mask_pad(H) 随之由 ceil(bead_r·H)+1 缩为常数 2。
• v1.2.2 的发布适配（仅打包形式变更，排版与输出规格未改）：发布平台 SkillHub 只接受文本类文件
  （.ttf 等二进制被拒、单文件上限 1MB、总包上限 10MB），故做三处打包调整：
  1. 三款内置字体改为 assets/fonts/*.json（gzip+base64），运行时解包到 %TEMP%/travel-ticket-card-fonts/；
  解包字节与原 .ttf SHA256 逐字节一致，同参数复现示例图时文字区域像素零差异（差异仅出现在
  条形码区域，源于本机 python-barcode 版本不同，与字体无关）。
  2. examples/out/*.png 改为 256 色量化重新编码（每张 2.0~2.7MB → 0.39~0.47MB），分辨率与版式不变。
  3. --title-font 仍可指向使用者自备的任意 .ttf，该文件由使用者提供、不随包分发。
• 示例输入照片来自 Unsplash（Unsplash License，可自由使用及商用），仅作演示。

详细坐标、色值与算法见 references/design-spec.md；交互规程见 references/interaction.md。