From 66a2c8416816c0be7a8d1d39fe28ea15a21073f5 Mon Sep 17 00:00:00 2001 From: xiangsilian Date: Sun, 14 Jun 2026 00:23:10 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E9=A2=84=E4=B8=8B=E8=BD=BD=E7=A6=BB?= =?UTF-8?q?=E7=BA=BF=E6=A8=A1=E5=9E=8B=E6=9D=83=E9=87=8D+=E5=AD=97?= =?UTF-8?q?=E4=BD=93=EF=BC=8C=E8=A1=A5=E5=85=85=E5=86=85=E7=BD=91=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 下载 BiSeNet(79999_iter.pth 53MB) + resnet18骨干(45MB) + Noto Sans CJK SC字体(16MB) 到 face_analysis/weights 与 fonts（大文件 .gitignore 不入库，靠文件拷贝带入内网） - 新增 OFFLINE_ASSETS.md：文件清单+sha256校验+resnet18骨干离线放置说明+来源URL - 字体由 SourceHanSansSC 改为 NotoSansCJKsc(同一套字体)，同步更新两份文档引用 - 文档补充内网/离线注意事项(resnet18联网下载坑、权重已预置) --- .gitignore | 9 ++++ OFFLINE_ASSETS.md | 66 +++++++++++++++++++++++++ docs/接口1-四庭七眼测量-开发任务书.md | 13 +++-- docs/接口1-四庭七眼测量-技术实现方案.md | 15 ++++-- 4 files changed, 94 insertions(+), 9 deletions(-) create mode 100644 OFFLINE_ASSETS.md diff --git a/.gitignore b/.gitignore index 2b91c72..b2b9b95 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,12 @@ venv/ __pycache__/ *.pyc .env + +# 离线资产（大文件，手动拷贝到内网机，不入 git；清单见 OFFLINE_ASSETS.md） +face_analysis/weights/*.pth +face_analysis/fonts/*.otf + +# 生成的标注图、测试输出 +static/annotations/* +!static/annotations/.gitkeep +tests/output/ diff --git a/OFFLINE_ASSETS.md b/OFFLINE_ASSETS.md new file mode 100644 index 0000000..dad1c03 --- /dev/null +++ b/OFFLINE_ASSETS.md @@ -0,0 +1,66 @@ +# 离线资产清单（内网部署用） + +开发/部署机在内网无法联网，以下模型权重与字体**已预先下载**放在仓库对应目录。 +这些文件**不进 git**（见 `.gitignore`），通过文件拷贝（U盘/内网共享）随项目一起带到内网机即可。 + +> 拷贝到内网机后，用本文件末尾的 sha256 校验完整性，确认未损坏。 + +## 文件清单 + +| 文件 | 路径 | 大小 | 用途 | +|------|------|------|------| +| BiSeNet 主权重 | `face_analysis/weights/79999_iter.pth` | 53,289,463 B (~53MB) | 人脸解析分割（方案 B，取真实发际线/头顶） | +| resnet18 骨干 | `face_analysis/weights/resnet18-5c106cde.pth` | 46,827,520 B (~45MB) | BiSeNet 的骨干网络，**内网必需**（见下） | +| 中文字体 | `face_analysis/fonts/NotoSansCJKsc-Regular.otf` | 16,437,364 B (~16MB) | 标注图中文渲染（= 思源黑体，同一套字体） | + +## sha256 校验 + +``` +468e13ca13a9b43cc0881a9f99083a430e9c0a38abd935431d1c28ee94b26567 face_analysis/weights/79999_iter.pth +5c106cde386e87d4033832f2996f5493238eda96ccf559d1d62760c4de0613f8 face_analysis/weights/resnet18-5c106cde.pth +2c76254f6fc379fddfce0a7e84fb5385bb135d3e399294f6eeb6680d0365b74b face_analysis/fonts/NotoSansCJKsc-Regular.otf +``` + +校验命令： +```bash +# Linux/macOS +sha256sum -c <<'EOF' +468e13ca13a9b43cc0881a9f99083a430e9c0a38abd935431d1c28ee94b26567 face_analysis/weights/79999_iter.pth +5c106cde386e87d4033832f2996f5493238eda96ccf559d1d62760c4de0613f8 face_analysis/weights/resnet18-5c106cde.pth +2c76254f6fc379fddfce0a7e84fb5385bb135d3e399294f6eeb6680d0365b74b face_analysis/fonts/NotoSansCJKsc-Regular.otf +EOF +``` +```powershell +# Windows PowerShell +Get-FileHash face_analysis\weights\79999_iter.pth -Algorithm SHA256 +``` + +> resnet18 文件名内嵌的 `5c106cde` 即其官方 sha256 前 8 位（torchvision 命名惯例），与上表一致 = 官方权重无误。 + +## ⚠️ resnet18 骨干的离线处理（重要） + +BiSeNet 初始化时会调用 `torch.utils.model_zoo` / `torchvision` **联网下载** resnet18 骨干，内网会失败报错。两种解法任选其一： + +1. **放进 torch 缓存目录**（推荐，零改代码）： + ```bash + mkdir -p ~/.cache/torch/hub/checkpoints/ + cp face_analysis/weights/resnet18-5c106cde.pth ~/.cache/torch/hub/checkpoints/ + ``` + （Windows 路径：`%USERPROFILE%\.cache\torch\hub\checkpoints\`） +2. **改 BiSeNet 代码**，把骨干加载改成从 `face_analysis/weights/resnet18-5c106cde.pth` 本地读取（`load_state_dict(torch.load(本地路径))`，并去掉联网下载分支）。 + +## 下载来源（联网环境重建用） + +``` +79999_iter.pth https://huggingface.co/ManyOtherFunctions/face-parse-bisent/resolve/main/79999_iter.pth +resnet18-5c106cde.pth https://download.pytorch.org/models/resnet18-5c106cde.pth +NotoSansCJKsc-Regular.otf https://github.com/notofonts/noto-cjk/raw/main/Sans/OTF/SimplifiedChinese/NotoSansCJKsc-Regular.otf +``` + +## 还差什么（pip 依赖） + +模型已就位，但**内网机还需要 Python 依赖的离线 wheel 包**（`mediapipe`/`opencv-python`/`torch` CPU 版等），否则 `pip install` 在内网无法联网安装。这部分**与目标机的操作系统和 Python 版本强相关**，需确认后单独打包：见仓库提交说明或联系下载方补充 `wheels/` 目录。 + +--- + +> 创建日期：2026-06-14 ｜ 配套：技术方案 v2.0 / 任务书 v1.3 diff --git a/docs/接口1-四庭七眼测量-开发任务书.md b/docs/接口1-四庭七眼测量-开发任务书.md index bb09896..95b2f91 100644 --- a/docs/接口1-四庭七眼测量-开发任务书.md +++ b/docs/接口1-四庭七眼测量-开发任务书.md @@ -27,7 +27,7 @@ 2. **新增逻辑全部放在 `face_analysis/` 包内**，`app.py` 只做编排（读图→校验→调用→返回），保持单文件 app 的薄控制器风格。 3. **依赖锁版本**：`numpy<2`（用 1.26.4）。torch 用 CPU 版。安装走 `pip.conf` 里的腾讯云镜像（torch 需用官方 CPU index）。 4. **模型权重不入 git**：`face_analysis/weights/*.pth` 写进 `.gitignore`，由 §2 的下载脚本拉取。 -5. **中文字体入 git**：`face_analysis/fonts/SourceHanSansSC-Regular.otf`。 +5. **中文字体**：`face_analysis/fonts/NotoSansCJKsc-Regular.otf`（= 思源黑体，已预下载，见 `OFFLINE_ASSETS.md`）。 6. **每个模块都要能单独 import 且有 `if __name__ == "__main__"` 自测入口**，方便分阶段验证。 7. 代码风格、注释密度与 `app.py` 保持一致；注释用中文。 8. **不要 mock 兜底**：算法失败时返回对应错误码，**不得**回退成硬编码示例数据。 @@ -42,7 +42,12 @@ `./venv/bin/pip install torch==2.2.2 torchvision==0.17.2 --index-url https://download.pytorch.org/whl/cpu` 其余走现有 `pip.conf` 镜像。 3. 创建目录骨架：`face_analysis/{__init__.py,fonts/,weights/}`、`static/annotations/`。 -4. 写 `scripts/download_weights.sh`：下载 BiSeNet face-parsing 权重 `79999_iter.pth`（来源：face-parsing.PyTorch 仓库 release）到 `face_analysis/weights/`，下载思源黑体到 `face_analysis/fonts/`（若已手动放置则跳过）。 +4. **权重/字体已预下载到位**（内网无需联网，见根目录 `OFFLINE_ASSETS.md` 的 sha256 清单）： + - `face_analysis/weights/79999_iter.pth`（BiSeNet 主权重 ~53MB） + - `face_analysis/weights/resnet18-5c106cde.pth`（骨干 ~45MB） + - `face_analysis/fonts/NotoSansCJKsc-Regular.otf`（中文字体 ~16MB） + 仍需写 `scripts/download_weights.sh`（供联网环境/生产机重建），但内网执行时跳过此步、直接用已有文件。 + ⚠️ **resnet18 骨干**：BiSeNet 初始化会尝试联网下载骨干，内网会失败——需把 `resnet18-5c106cde.pth` 拷到 `~/.cache/torch/hub/checkpoints/` 或改 BiSeNet 代码从 `weights/` 本地加载。 5. 更新 `.gitignore`：忽略 `face_analysis/weights/*.pth`、`static/annotations/*`（保留 `.gitkeep`）。 **交付物** @@ -56,8 +61,8 @@ print('numpy', numpy.__version__); print('mediapipe', mediapipe.__version__)" ``` - 必须无 import 错误；`numpy.__version__` 以 `1.26` 开头。 -- `ls face_analysis/weights/79999_iter.pth` 存在且 >40MB。 -- `ls face_analysis/fonts/SourceHanSansSC-Regular.otf` 存在。 +- `ls face_analysis/weights/79999_iter.pth` 存在且 >40MB；`resnet18-5c106cde.pth` 存在。 +- `ls face_analysis/fonts/NotoSansCJKsc-Regular.otf` 存在。 **完成标准**：上述命令全部通过，无报错。 diff --git a/docs/接口1-四庭七眼测量-技术实现方案.md b/docs/接口1-四庭七眼测量-技术实现方案.md index 5cc2897..4034e21 100644 --- a/docs/接口1-四庭七眼测量-技术实现方案.md +++ b/docs/接口1-四庭七眼测量-技术实现方案.md @@ -60,7 +60,11 @@ pip install mediapipe opencv-python pillow numpy -i https://pypi.tuna.tsinghua.e - **真实发际线** = 沿面部中轴线（用 §4 的 `brow_center_x` 作为 x），从上往下扫描，**头发区域 → 皮肤区域**的第一个交界 y 坐标。 - **头顶** = 头发 mask 的**最高点**（最小 y）。 -> 权重需单独下载（`79999_iter.pth`，~50 MB），放入 `face_analysis/weights/`，不入 git（写进 `.gitignore`），由部署脚本拉取。 +> 权重需单独下载，放入 `face_analysis/weights/`，不入 git（写进 `.gitignore`）： +> - `79999_iter.pth`（~53 MB）— BiSeNet 主权重。 +> - `resnet18-5c106cde.pth`（~45 MB）— BiSeNet 用的 resnet18 骨干。**离线/内网环境必须预放**：BiSeNet 初始化时会尝试用 `torch.utils.model_zoo` 联网下载该骨干，内网会失败。需把它放进 torch hub 缓存（`~/.cache/torch/hub/checkpoints/`）或改代码从本地路径加载。 +> +> **本仓库已预先下载好上述权重 + 字体**（见根目录 `OFFLINE_ASSETS.md` 的 sha256 清单），内网机器无需联网，直接使用。 --- @@ -432,8 +436,8 @@ def create_annotated_image(input_image_path, vertical_result, eye_result, px_per # ⚠️ 字体：PingFangSC 是 macOS 字体，Linux 服务器没有；且 ImageFont.load_default() # 不渲染中文（会出现方块/空白）。必须随仓库打包一个中文 TTF 并用绝对路径加载。 - # 建议放 face_analysis/fonts/SourceHanSansSC-Regular.otf（思源黑体）或 Noto Sans CJK。 - FONT_PATH = os.path.join(os.path.dirname(__file__), "fonts", "SourceHanSansSC-Regular.otf") + # 已打包 Noto Sans CJK SC（= 思源黑体，同一套字体）：face_analysis/fonts/NotoSansCJKsc-Regular.otf + FONT_PATH = os.path.join(os.path.dirname(__file__), "fonts", "NotoSansCJKsc-Regular.otf") font = ImageFont.truetype(FONT_PATH, 10) # 字体缺失时直接抛错，避免静默降级成乱码 line_color = (255, 255, 255, 255) # #FFFFFF 100% @@ -624,9 +628,10 @@ hair/ │ ├── annotation.py # 标注图片生成（numpy 渐变线 + 中文字体） │ ├── face_mesh_landmarks.py # 关键点索引常量 │ ├── fonts/ -│ │ └── SourceHanSansSC-Regular.otf # 打包的中文字体（入 git） +│ │ └── NotoSansCJKsc-Regular.otf # 打包的中文字体（= 思源黑体） │ └── weights/ # 模型权重（不入 git，部署脚本拉取） -│ └── 79999_iter.pth # BiSeNet face-parsing 权重 ~50MB +│ ├── 79999_iter.pth # BiSeNet face-parsing 权重 ~53MB +│ └── resnet18-5c106cde.pth # BiSeNet 骨干权重 ~45MB（离线必需，见下） ├── static/ │ └── annotations/ # 生成的标注 PNG 存放目录 ├── .gitignore # 忽略 face_analysis/weights/*.pth