# 海丝宝匣：四款文物自动试戴

## 本次升级

- 戒指识别手部关键点，可选食指、中指、无名指或小指；金镯跟随手腕。
- 两款项链根据双肩关键点估计颈肩位置、大小与倾斜角度。
- 照片自动定位；摄像头持续跟随、平滑移动。目标离开画面后隐藏饰品，重新出现后恢复定位。可关闭自动模式，继续手动调整。
- 骨环已从网站目录、素材和资料包移除，保留四款文物。
- 双面1080×1680“海丝旅票”：正面是真人合影、署名、地点、寄语、日期印章和探索印记；背面是文物原图、实物参数、三个知识细节和来源。答对问答会获得知识印记。
- 每面可单独保存PNG或调用浏览器打印。结束体验清除本次照片、署名、寄语、纪念卡和探索记录。

## 四款文物

|资料期数|正式名称|定位部位|核心信息|
|---|---|---|---|
|104|花卉纹带插销金镯|手腕|周长18.5厘米，重36.71克；金片锤鍱、花卉纹、插销固定|
|102|金项饰|颈肩|南宋；长172厘米；四股八条金线；带钩和五个调节圆环|
|99|金双重顶链犀角形牌饰项链|颈肩|两条金链、对称牌饰、三条流苏；两个石榴与一个桃心坠饰；191.87克|
|81|镶金饼金戒指|所选手指|太阳纹样；外径2.64厘米、内径1.94厘米；16.72克|

“犀角形”描述金牌饰的形状，不代表犀角材质。戒指资料未单独标明年代，页面不自行补入。

## 运行方式

Mac双击“启动海丝宝匣.command”，保持终端窗口打开；结束时按Ctrl+C。启动器优先使用本机已有Python运行时，自动打开本机网页。也可在本文件夹运行：

```sh
python3 launch.py
```

模型、WASM、照片、PDF均随包提供，不需要API密钥，也不调用云端识别接口。浏览器首次识别仍需加载本地模型，速度取决于设备。不要直接双击index.html：浏览器的本地文件限制会阻止模块和Worker正常运行。公网部署使用HTTPS，完整上传本目录并保留相对路径。服务器须正确提供JS/MJS、WASM文件。

## 已有体验

四款文物筛选、真人示例、本地照片上传、镜像摄像头、三秒倒计时拍照、手动移动/缩放/旋转、明暗阴影、遮挡画笔、原图对照、文物热点、原始PDF、知识问答、双面纪念卡和结束清除。游客图片与关键点只在浏览器本机处理，无后台存储。

## 实际边界

这是二维关键点跟随试戴，尚非TikTok完整三维特效系统。没有皮肤/衣物/头发自动遮挡分割，也没有真实尺寸适配或历史佩戴复原。手挡住项链时可用遮挡画笔修正；大角度转身和手背翻转仍需更完善的3D或分割方案。金项饰的悬垂试戴层是视觉整理，不能代表172厘米文物的确切历史佩戴方式。

已用真实MediaPipe模型完成真人样例识别、VIDEO位移回放、目标丢失与重捕获测试；尚未在用户实体摄像头、低端手机、多人体现场及实际打印机上验收。网页尚未发布公网，也不是已审核的微信小程序。下载行为受浏览器支持影响，移动端可长按纪念图保存。

## 上线前工作

馆方审定四款内容与图像、替换高清试戴素材；在目标设备检查光线、镜像、遮挡、快速移动、多人体和权限拒绝；落实HTTPS托管。跨设备二维码领取、云相册和打印派单需要另建后台。

## 文件结构

index.html / style.css：界面；catalog.js：四款内容；app.js：体验流程；tracking-client.mjs / tracking-worker.js：模型通信和推理；tracking-geometry.mjs：关键点定位和平滑；souvenir.mjs：双面纪念卡；vendor与models：本地模型依赖；tests：真实模型浏览器验收与几何单元测试。

## 素材来源

文物：用户提供的《南海I号船说》104、102、99、81期，来源为南海I号博物馆（广东海上丝绸之路博物馆）等原文署名机构。各原始PDF附于assets。

真人手部：Ruts Vakulenko / Pexels，https://www.pexels.com/photo/woman-hand-on-white-background-20140706/

真人颈肩：RDNE Stock project / Pexels，https://www.pexels.com/photo/a-woman-in-white-off-shoulder-top-with-her-hands-on-her-shoulders-8182356/

Pexels许可：https://www.pexels.com/license/ 。示例不表示模特代言。模型与第三方代码见THIRD_PARTY.md。

## 2026-09-13 视觉升级

首页与新增“穿戴灵感”区使用四张gpt-image-2写实佩戴图，两张现代、两张历史氛围。支持风格筛选、大图预览和对应文物试戴入口。AI画面为创意示意，不是文物实拍或历史复原；原始文物资料仍在知识区保留。详见IMAGE2-NOTES.md。