照片深度:让图片像真实场景一样呈现
0. 设置 创建一个含MoGe-2的Python环境(一次性;下载前会询问) scripts/setup.sh
1. 深度 图片 → 近密度图(+ 16位距离、相机参数、原始npz) scripts/depth.py
2a. 窗口 将图片作为three.js场景中的窗 examples/portal.js
2b. 放置 在图片自身的3D空间中拟合平面和点 scripts/fit_plane.py
3. 检查 从最终使用时的极端视角来审视效果
scripts/ 和 examples/ 指的是此技能自身目录中的文件夹(无论是插件还是复制的技能,均为 ${CLAUDE_SKILL_DIR}),而非用户的工程项目目录。请设置 S 指向该 scripts/ 文件夹,并通过完整路径执行 "$S/depth.py" 及其他脚本。
0. 设置(一次性)
首先检查:如果已有能正常 import moge 的环境,可直接复用(询问用户其环境位置)。否则,在下载前须征得用户同意,明确说明将下载的内容:PyTorch及PyPI上的辅助库(安装后约1 GB)、MoGe源码及两个小型GitHub库(固定提交版本,几MB),以及后续的模型权重(约1.3 GB,来自Hugging Face的 Ruicheng/moge-2-vitl)。然后运行:
"$S/setup.sh" <环境文件夹> --yes
详细信息、GPU注意事项及其他模型:请参阅 references/setup.md。
1. 深度
<环境>/.venv/bin/python "$S/depth.py" picture.jpg --out public/depth/ [--dist16] [--npz]
- 始终生成
<stem>-near.webp:近密度图(视差),0表示天空,1表示最近物体,物体边缘向外扩展2像素确保边缘随物体移动。对于1-2K图片,文件大小约10-25 KB。 --dist16:生成<stem>-dist16.webp(16位对数距离,R通道高位、G通道低位,无损压缩)和<stem>-camera.json(估算的内参),用于重建图片为3D表面。--npz:生成原始度量深度,供fit_plane.py使用。- 除非传入
--allow-download,否则拒绝下载权重:请先询问用户。 - 脚本会输出有效区域比例、深度百分位数和估算的视场角。请留意这些信息:“有效20%”或150°视场角意味着模型未能理解该图片。
每次图片更改时必须重新运行:使用旧版图片的深度图会导致所有边缘位置错误。
2a. 窗口效果
examples/portal.js 是一个自包含的three.js材质(请将其复制到项目中)。图片是从休息点(即默认相机位置)看到的场景。从其他任何位置观察,玻璃上的每个像素都显示沿着该视线方向穿透玻璃后看到的景物,通过16步遍历近密度图实现:近处物体覆盖远处物体,边缘不撕裂。详细信息、调优方法及失败模式:请参阅 references/portal.md。
import { makePortal } from "./portal.js";
const portal = makePortal({ map, near, width: 4, height: 2.5 });
scene.add(portal.mesh); portal.setRest(defaultCameraPosition);
// 每帧:portal.update(camera);
examples/portal.html 是一个单文件演示:提供一个包含图片、其近密度图、portal.js 和页面的文件夹,打开 portal.html?pic=<文件>&near=<文件>,然后移动鼠标指针即可体验。
按照最终展示方式进行测试: 将相机移动到网站实际会使用的最左、最右、最高、最低位置(对于自动化检查,演示支持 window.__view = [x, y] 设置视角),然后检查:
- 看不出深度?真实场景中该效果的初次实现可能弱到难以察觉:调低
uQ.y(从0.6降至0.4)。 - 近处物体相对框架移动过大,或者天空在漂移?深度反了(将距离误用作近密度)。
- 大幅度移动时出现拖影或物体重影?单张图片的近处物体背后没有内容。保持相机小幅度移动,或启用缓和效果(
uEase),或绘制一个背景层(参见 references/placing.md)。
2b. 在图片中放置物体
<环境>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260
<环境>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260 --corners 415,128 515,124 516,250 414,255
<环境>/.venv/bin/python "$S/fit_plane.py" point out/city-depth.npz 640,700
像素坐标基于图片自身(使用 --norm 可归一化到0..1)。输出为JSON格式,位于three.js相机空间(相机位于原点,沿-Z方向观察,单位为米)。flatness_rms_m 指示该区域的实际平坦程度:例如,在40米远处的一堵墙上,几厘米的均方根值即为平坦。请在面板自身的边缘内部选取角点(而非其外接框),这样广告牌会跟随面板的真实形状,避免看起来歪斜。将整个图片重建为3D表面、处理撕裂边缘以及背景层:请参阅 references/placing.md。
规则
- 许可证: MoGe-2的代码和权重为MIT许可证。多种流行的深度模型未获商业使用授权(参见 references/setup.md):在为客户或出售作品的作品集切换模型前请务必检查。
- 图片自身的许可证仍适用于由它生成的所有内容。
- Alpha通道中的遮罩: 如果图片的Alpha通道中带有遮罩(如水、天空),请使用无损方式保存WebP并保留精确RGB值(
cwebp -lossless -exact,Pillow 库exact=True)。有损压缩的Alpha通道会将透明像素下的颜色清零并造成颜色扩散。 - 下载任何内容前必须询问用户(包括包、权重),明确说明内容名称、来源及大小。