需要把单张动漫角色图分解为可操控分层 PSD 时，用…

适用于从单张动漫角色插画自动分解出语义图层、补全遮挡区域、推断伪深度顺序并导出分层 PSD 的 2.5D 制作流程。

适用场景

解决思路

1. 确认目标：将单张动漫插画分解为最多 23 个完全补全、语义不同的图层，并推断绘制顺序，导出适合 2.5D 动画的分层 PSD。
2. 安装环境：`conda create -n see_through python=3.12 -y`，然后 `conda activate see_through`。
3. 安装 PyTorch CUDA 12.8：`pip install torch==2.8.0+cu128 torchvision==0.23.0+cu128 torchaudio==2.8.0+cu128 --index-url https://download.pytorch.org/whl/cu128`。
4. 安装核心依赖：`pip install -r requirements.txt`。
5. 创建资源软链接：`ln -sf common/assets assets`。
6. 按需安装可选标注器：身体解析（detectron2，用于身体属性标注）用 `pip install --no-build-isolation -r requirements-inference-annotators.txt`；SAM2 语言引导分割用 `pip install --no-build-isolation -r requirements-inference-sam2.txt`；实例分割 mmcv/mmdet（UI 推荐）用 `pip install -r requirements-inference-mmdet.txt`。
7. 始终在仓库根目录作为工作目录运行所有脚本。
8. 模型首次使用时自动从 HuggingFace 下载：LayerDiff 3D `layerdifforg/seethroughv0.0.2_layerdiff3d` 用于 SDXL 透明层生成；Marigold Depth `24yearsold/seethroughv0.0.1_marigold` 用于动漫伪深度估计；SAM Body Parsing `24yearsold/l2d_sam_iter2` 用于 19 部件语义身体分割。
9. 单图图层分解到 PSD：`python inference/scripts/inference_psd.py --srcp assets/test_image.png --save_to_psd`。
10. 整目录批量分解：`python inference/scripts/inference_psd.py --srcp path/to/image_folder/ --save_to_psd`。
11. 默认输出到 `workspace/layerdiff_output/`，每次运行生成分层 `.psd`、中间深度图、分割掩码。
12. 主流程后用启发式后处理做深度分层：`python inference/scripts/heuristic_partseg.py seg_wdepth --srcp workspace/test_samples_output/PV_0047_A0020.psd --target_tags handwear`。
13. 主流程后用启发式后处理做左右分层：`python inference/scripts/heuristic_partseg.py seg_wlr --srcp workspace/test_samples_output/PV_0047_A0020_wdepth.psd --target_tags handwear-1`。
14. 生成合成训练数据：`python inference/scripts/syn_data.py`。
15. 用 Python 子进程以编程方式运行完整流程：调用 `python inference/scripts/inference_psd.py --srcp image_path --save_to_psd`，设置 `capture_output=True, text=True, cwd=os.getcwd()`，检查 `returncode`，失败抛错；根据输入文件名推导输出 `output_dir/base_name.psd`。
16. 编程方式批量处理目录：调用 `python inference/scripts/inference_psd.py --srcp input_dir --save_to_psd`，检查 `returncode`，用 `Path(output_dir).glob('*.psd')` 收集输出并统计数量。
17. 编程方式深度分层：调用 `python inference/scripts/heuristic_partseg.py seg_wdepth --srcp psd_path --target_tags *target_tags`，检查 `returncode`，输出命名为原文件加 `_wdepth.psd`。
18. 编程方式左右分层：调用 `python inference/scripts/heuristic_partseg.py seg_wlr --srcp psd_path --target_tags *target_tags`，检查 `returncode`，输出命名为原文件加 `_wlr.psd`。
19. 完整后处理链示例：先对 PSD 做 `seg_wdepth`，再对 `_wdepth.psd` 做 `seg_wlr`。
20. 加载和检查 PSD 输出：安装 `psd-tools`（`pip install psd-tools`），然后使用 `psd_tools.PSDImage.open(psd_path)`，打印画布尺寸 `psd.width x psd.height`、总图层数 `len(list(psd.descendants()))`，遍历图层打印 `kind`、`name`、`bbox`、`is_visible()`。
21. 交互式身体部件分割：运行 `jupyter notebook inference/demo/bodypartseg_sam.ipynb`，演示使用 SAM 身体解析模型进行 19 部件分割和可视化。
22. 训练数据准备：克隆 `https://github.com/shitagaki-lab/CubismPartExtr`，按其 README 下载示例模型文件并准备 `workspace/`；按 `README_datapipeline.md` 运行数据解析脚本（脚本在 `inference/scripts/`，查看 docstring）。
23. 启动 UI：确保仓库根目录存在 `workspace/datasets/`（含示例数据）；推荐先安装 mmdet tier：`pip install -r requirements-inference-mmdet.txt`；然后 `cd ui`，按 `ui/README.md` 获取具体启动命令。
24. 端到端单图工作流：步骤1 用 `inference_psd.py` 分解；步骤2 对特定标签做深度拆分，如 `--target_tags arm sleeve`；步骤3 对结果做左右拆分，如 `--target_tags arm-1 sleeve-1`。
25. 查看可用身体标签：从 `common/live2d/scrap_model.py` 加载模块并检查标签常量/枚举，例如用 `importlib.util.spec_from_file_location` 加载后 `print(dir(mod))`。
26. ComfyUI 集成：可使用社区维护节点 `https://github.com/jtydhr88/ComfyUI-See-through`，通过 ComfyUI Manager 安装或克隆到 `ComfyUI/custom_nodes/`。
27. 故障排查：出现 detectron2/mmcv 的 `ModuleNotFoundError` 时，安装对应可选 tier，如 `pip install --no-build-isolation -r requirements-inference-annotators.txt`。
28. 故障排查：脚本路径错误时，始终从仓库根目录运行，而非子目录。
29. 故障排查：UI 启动失败时，安装 mmdet tier：`pip install -r requirements-inference-mmdet.txt`，并确保 `workspace/datasets/` 存在。
30. 故障排查：CUDA 显存不足时，使用 ≥16GB VRAM 的 GPU；SDXL 的 LayerDiff 3D 很耗显存。
31. 故障排查：Assets 找不到时，在仓库根目录重新运行 `ln -sf common/assets assets`。
32. 故障排查：SAM2 安装失败时，使用 `--no-build-isolation` 标志。
33. 故障排查：输出 PSD 为空或损坏时，检查 `workspace/layerdiff_output/` 的中间深度/掩码文件以诊断哪个阶段失败。
34. 参考目录结构定位：`inference/scripts/inference_psd.py` 主流程；`inference/scripts/heuristic_partseg.py` 深度/左右后处理；`inference/scripts/syn_data.py` 合成数据；`inference/demo/bodypartseg_sam.ipynb` 交互分割；`common/assets/` 测试图；`common/live2d/scrap_model.py` 全身标签定义；`ui/` 用户界面；`workspace/` 运行时输出（`layerdiff_output/` 默认 PSD 输出，`datasets/` UI 必需，`test_samples_output/` 示例输出）。

适用边界 · 注意事项

• 需要 See-through 框架、HuggingFace 模型和 CUDA GPU；没有对应环境或显存低于 16GB VRAM 时不适用。
• 主要面向单张动漫角色插画的语义图层分解与 2.5D/PSD 工作流；非动漫、真实照片或不需要图层分解时不适合。
• 训练数据准备依赖 Live2D/Cubism 模型文件和额外仓库；没有这类数据或不想训练时不要走训练数据准备流程。