Community图像github.com

照片深度

为单张照片、绘画或AI生成图片在网页上赋予真实深度。通过MoGe-2(MIT许可证)估算深度图,然后在three.js场景中让图片像窗户一样表现(随相机移动产生视差且边缘无撕裂),或定位图片中的物体位置(为墙面或标志拟合平面以放置广告牌、角色脚下的地面、像素下的3D点)。

照片深度 是什么?

Photo Depth 是一个面向开发者和AI代理用户的技能,用于将任何单张图片(照片、绘画或AI生成图)转化为具有真实3D深度的交互式网页体验。它基于MoGe-2模型(MIT许可证)估算深度图(近密度图),提供两种核心应用:一是“窗口模式”,在three.js场景中将图片呈现为一个3D窗口,相机移动时产生真实视差,近处物体遮挡远处物体且边缘不撕裂;二是“放置模式”,允许在图片的3D空间中拟合平面或点,从而将3D物体(如广告牌、角色)精确融入原图。该技能支持Python环境设置(自动询问下载权限),输出多种深度格式(WebP、16位距离、原始npz),并附带独立演示HTML文件。它适用于背景、传送门、天空盒或景画效果,要求运行前获得用户许可,并提醒注意MoGe-2的MIT许可证以及图片本身的版权要求。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/skyeyesec333/photo-depth/tree/main/skills/photo-depth

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

照片深度:让图片像真实场景一样呈现

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通道会将透明像素下的颜色清零并造成颜色扩散。
  • 下载任何内容前必须询问用户(包括包、权重),明确说明内容名称、来源及大小。

相关技能