Community图像github.com

照片场景重建

将参考照片重建为 Blender 场景,从同一相机视角呈现为照片,使用多智能体框架、渲染与比较循环、固定保真度顺序以及从照片中测量的光照和材质。

照片场景重建 是什么?

该技能提供了一套系统化的多智能体协作方法,用于从单张参考照片重建逼真的 3D Blender 场景。其核心流程包括:首先由主线程进行相机校准、锚点测量和对象清单整理,然后将场景划分为 4-6 个独立领域(如光照、街道、建筑等),每个领域由专属智能体负责,通过严格的合约和布局文件共享数据。重建过程遵循固定的保真度顺序(从轮廓、比例、颜色到细节和磨损),每次迭代后通过渲染与照片进行并排比较,并使用“CG 感检查”清单确保真实感。该方法特别强调复杂对象必须使用真实网格模型(禁止基本几何体占位),并提供了从自身库、Poly Haven 到付费生成模型的分级获取策略。技能支持 Blender 5.1、Python 及多种工具,适用于建筑、街景、室内等场景的照片级重建需求。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/liangjunglj-cpu/ginkgo-skills/tree/main/skills/photo-scene-reconstruction

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

在你喜欢的 AI 中提问

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

文档

照片场景重建 是做什么的?

此方法于 2026 年 11 月在三个项目上开发:一张有轨电车的街景照片(弗莱堡)、一个有哥特式喷泉的广场(Fischbrunnen,弗莱堡)以及三个代码生成的城市场景、商店和海港立体模型。下面的示例来自这些项目。通用框架(相机、编排器、渲染和比较工具)位于本文件旁边的 harness/ 目录中:将 harness/blender 和 harness/tools 复制到新的运行文件夹中。下面列出的、不在 harness/ 中的工具名称(例如 facade_solve.py)是每个运行自行编写的特定领域探测脚本;其用途会在出现它们的地方进行描述。

要求:Blender(基于 5.1 版本编写,Cycles 渲染器)、带有 numpy、opencv 和 pillow 的 Python(供 2D 工具使用,tools/py.sh 使用 uv 运行它们),以及能够启动子智能体的运行时环境。

用户通过与照片并排比较来目视判断保真度。以下所有内容都是为了使得这种比较廉价、频繁且诚实。

0. 主线程在任何智能体开始前进行设置

主线程(主会话)独立完成这些操作。智能体只有在所有设置完成后才能启动。

  1. 运行文件夹。 <runs>/<scene>/,包含 ref/photo.jpg、blender/、tools/、layout/、gen/、renders/、work/、final/。从 harness/ 复制 lib.py、arch.py、assets.py、render.py、build_scene.py 以及通用工具(cam.py、vp.py、solve_cam.py、iterate.sh、overlay.py、edges.py、pair.py、crop.py、stats.py、py.sh、fetch_polyhaven.py、fetch_ph_model.py)。

  2. 解算相机,使用 tools/vp.py。找到垂直消隐点和主立面方向的一个水平消隐点。然后 tools/solve_cam.py 获取以下参数:

    • 焦距,根据两个方向(主立面方向和与其垂直的水平方向)正交得出(不要假设镜头参数);
    • 俯仰角,根据垂直消隐点得出;
    • 偏航角,选择使得主立面与世界坐标 +X 轴方向一致。

    将结果写入 layout/camera.json。此后相机在整个运行过程中冻结。

  3. 测量锚点,使用 tools/cam.py:

    • on_z 用于水平平面上的点,on_y 用于垂直平面上的点,project 返回像素坐标,ray 返回视角射线。
    • 测量地面线、立面平面以及每个地标的距离。
    • 将主线程的初步估计值作为起始值写入规则书。
    • 在接近平行视角时,地面线的一个像素可能对应半米的深度。优先使用已知物体的高度和宽度(门 2.1 米,眼睛高度 1.6 米,路缘石 0.12 米),而不是单个地面点。
  4. 对象清单。 列出照片中可见的每个对象,并将其标记为 脚本化(scripted) 或 网格(mesh)(第 3 节)。此清单决定了领域划分和资源获取。

  5. 编写 AGENTS.md 用于本次运行:目标、世界坐标系、锚点、领域表格、硬性规则、循环、工作顺序、完成规则。

1. 领域使用权(智能体如何共享一个场景)

划分场景

  • 一个领域 = 一个带有 build(L, ctx) 的模块 + 一个 layout/<domain>.json 文件 + 所有新内容的文件前缀(tools/<domain>_*.py、tex/<domain>_*、gen/<domain>_*)。
  • 根据屏幕区域和工作类型进行划分,而不是按对象数量。一个好的划分能让每个智能体独立裁剪和判断其区域。弗莱堡项目使用了五个领域:光照、街道、左侧建筑、主立面、道具。
  • 光照始终是独立的领域,拥有天空、曝光、色彩管理和色调处理。其他领域不得为了使其材质看起来正确而修改曝光。
  • 主体元素(视线焦点所在的物体)拥有独立的领域。
  • 四到六个领域。领域太少会导致智能体在同一文件中产生冲突;领域太多则主线程无法审阅。

约定

  • build_scene.py 仅负责编排:合并 layout/*.json 到 L 中、创建相机、按固定顺序调用每个模块、保存。其中不包含任何几何体。
  • 每个智能体可以读取任意布局键,但只能写入自己的布局文件和模块。
  • 共享辅助工具(lib.py、arch.py、assets.py、cam.py、iterate.sh)是冻结的。需要修改辅助工具的智能体应将其复制到自己的模块中,并赋予新名称。assets.py包含网格适配步骤,以便每个领域以相同方式适配网格:
    • import_gltf 导入并设置 XYZ 旋转;
    • world_bounds 从顶点计算边界;
    • fit 缩放至测量高度或宽度,设置偏航角,并将最低顶点放置到其支撑表面。
  • 测量锚点的领域拥有该锚点。 主线程的锚点只是起始值。拥有该锚点的领域会优化它,并将结果发布到其布局文件中,例如 L['facade']['plane_y'] 或 L['fountain']['centre']。其他所有领域从 L 中读取该值,且绝不将数值复制到自己的代码中,因此一次优化会在下一次构建时惠及所有人。
  • 将像素测量值与其衍生的世界坐标值一起存储(例如 facade.px 旁边同时有 facade.sec)。一个解算脚本(tools/facade_solve.py)将像素转换为世界坐标并写入布局。这样,重新测量只需编辑像素值并重新运行解算器,而不是手动编辑坐标。
  • 其他模块导入的名称在规则书中列出,并附有规则“只能添加新函数,绝不能修改这些”。跨领域的值通过 ctx 传递(例如 ctx['track_x']),而不是通过直接编辑。
  • build(L, ctx) 必须始终可用。每个智能体都会重建整个场景,因此一个模块出错会阻塞所有人。在保存有风险修改前请检查语法。

运行智能体

  • 每个智能体构建到自己的 work/<domain>.blend 文件中;渲染通过 work/.gpu_lock(超过 6 分钟的锁视为过期)进行序列化。使用 only= 参数可跳过其他领域以加快速度;在判断颜色时请使用完整场景,因为相邻物体的光线会相互影响。
  • 同时渲染的智能体不超过两到三个。 多个 Blender 进程曾导致 Windows 页面文件超过 50 GB 并撑满 C 盘。一旦智能体完成工作,立即删除其 work/<domain>.blend 文件。等待时应基于特定进程 ID,而非“没有 Blender 在运行”。
  • 分波次运行。 第一波是构建几何体的领域(例如地面、立面和主体),最多同时运行三个。第二波是光照以及有机体或家具领域,它们需要几何体来进行光照、阴影和生长。在未完成的几何体上进行光照判断是徒劳的。
  • 在任一流程开始前保持机器唤醒(使用 request_keep_awake)。当 PC 因空闲而休眠时,渲染会冻结长达九小时。
  • 轮次。 每个波次或轮次后,主线程构建 main,目视将渲染结果与照片进行比较,并将最显著的差异作为下一轮的简报。用户在发送的比较表上的注释,例如“纹理更粗糙”或“光照看起来不自然”,会单独成为一个轮次。
  • 每个智能体在 renders/ 目录中保留其最近三组预览,并删除其前缀下更早的预览。
  • 智能体绝不花费付费额度。他们应报告生成的资产能修复什么问题,并附上要使用的照片裁剪区域;主线程将其连同成本信息一起提供给用户。
  • 智能体不提交、不接触 git,也不在运行文件夹外写入任何内容。

智能体简报(主线程发送的内容)

保持简短;其余信息由规则书承载。

  • “首先阅读 AGENTS.md。” 然后:你的领域、你的模块和布局文件、你的照片区域(像素坐标)。
  • 已经存在什么以及有什么问题(指出与照片最显著的三个差异)。
  • 该领域的网格列表(来自清单),已获取至 gen/。
  • 完成规则和报告格式(如下)。

完成与集成

  • 当智能体的区域在 960 像素裁剪图与照片并排对比中表现良好,或在大约 12 次迭代后,智能体停止工作。
  • 最终报告,250 字以内:改变了什么、与照片仍然存在的差异、生成资产在何处会有帮助、最后一张渲染图的标签。
  • 然后主线程从所有模块构建 work/main.blend,渲染完整画面,并在不阅读智能体报告的情况下与照片进行对比。报告描述意图,而图像是证据。差异成为下一轮的简报。
  • 光照氛围和效果随后作为非破坏性叠加层应用于 main.blend 之上,这样外观更改永远不会干扰已批准的保真度。有轨电车运行在 main.blend 之上使用了 blender/mood.py。Fischbrunnen 项目则在设置 FB_MOOD 环境变量时,将 mood/<variant>.json(由 tools/mood_make.py 写入)深度合并到布局之上;它接受一个逗号分隔的列表,例如 warm_a,film。推荐使用 Fischbrunnen 的形式:氛围通过相同的模块重建,无需第二个场景文件。

2. 保真度顺序与循环

每次更改后的循环

tools/iterate.sh <domain> <n> [width=480] [spp=24] [only=a,b] [x0 y0 x1 y1]

该脚本构建、渲染,并写入 ovl_*(照片 | 渲染 | 50% 混合)和 edg_*(照片边缘以红色叠加在渲染图上,并带有像素网格)。如果提供了照片像素坐标框,则仅渲染该区域并写入 crop_*(照片裁剪 | 渲染裁剪,放大显示);在宽度为 960 像素时大约需要 25 秒。打开图像查看。在查看对比之前,切勿将任何更改报告为改进。

按此顺序工作,不要跳过

每个阶段都有一个关卡。在之前的关卡通过之前添加细节是徒劳的,因为当早期错误被修复时,这些细节会移动。

阶段做什么继续前进前的关卡
1. 阅读放大你所在区域的照片裁剪图。写下实际存在的内容:数量、材质、接触关系。存在一份书面清单;每个项目都在清单中。
2. 轮廓使用 cam.py 的测量结果放置大体轮廓。在 960 像素宽的 edg_* 文件中,轮廓与红色边缘对齐,误差在几个像素内。
3. 比例开口、楼层线、开间、重复次数。窗和门的边缘与照片边缘对齐;数量一致。
4. 颜色与照片对比测量材质基色,构建完整场景,光照领域的曝光保持不变。作为反照率(第 4.2 节)比较材质版本。tools/stats.py 和领域区域检查结果与照片接近,且 50% 混合图像未显示色块。
5. 小部件装饰条、固定件、线缆、标牌、排水沟、灯具、街道杂物。网格依据第 3 节。该区域的每个清单项目都存在于裁剪图中。
6. 变化与磨损倒角、颜色变化、窗台下的污渍、条纹、地面磨损、玻璃波纹和反射。裁剪图通过下面的 CG 感检查,且纹理能量检查(第 4.3 节)结果与照片接近。

适用于每个阶段的规则:

  • 真实世界尺寸,图案使用毫米。使用 cam.py 测量;不要猜测。
  • 没有悬空或穿插的物体。物体要么立在地面上,要么固定在墙上。
  • 每次迭代只做一个更改来追查差异,以便比较显示更改的效果。

CG 感检查(每次渲染后:“还有什么告诉我这是 CG?”)

CG 感来源通常的修复方法
完美锐利的边缘对建筑部件添加 2 到 10 毫米的倒角或斜边
平坦单一颜色的表面添加测量到的颜色变化、污渍、条纹,应用真实比例的纹理
可见的重复图案为每个实例添加色调、旋转、磨损的变化
缺少接触阴影检查物体是否接触地面;检查光照和降噪设置
玻璃背后或反射中无内容添加内部平面或色调,真实反射,轻微波纹
纹理比例错误重新从照片测量图案的毫米尺寸
原始几何体形状的对象替换为真实网格(第 3 节)
地面过于干净添加磨损、湿迹、树叶、接缝

用户批准保真度之后

只有在此之后,才能按顺序进行以下操作:

  1. 真实感处理: 倒角、玻璃和地面磨损。有轨电车运行将其作为一个模块(weather 模块)处理;Fischbrunnen 项目则是在每个领域内部完成。两种方式均可,但每个表面必须由一个领域拥有。
  2. 渲染质量: 2160 像素超采样和高精度降噪。
  3. 传感器处理(第 4.1 节)。
  4. 其他视角的验证视图(一个 proof.py 脚本,渲染额外相机视角)。
  5. 光照氛围。
  6. 影像处理(第 5 节)。

在每个检查点发送照片与渲染的对比图,并等待用户反馈。

3. 网格:复杂对象不使用基本几何体

规则:复杂对象绝不使用简单的基本几何体构建。应使用现有的真实网格。

适用范围

  • 脚本化几何体允许用于建筑和基础设施: 墙壁、楼板、屋顶、窗框和门框、檐口和装饰线条、路缘石、铺装、护栏、杆子、电线、平面标牌。
  • 需要真实网格用于所有有机或对象状物体: 树木、灌木、盆栽植物、人物、车辆、自行车、椅子、桌子、长凳、花盆、遮阳伞、具有造型体的灯具、雕塑装饰品、雕像、带褶皱的布料。
  • 测试:如果有人会将你的构建描述为“棍子上的球体”、“带四条腿的盒子”或“圆柱体”,那么它就是不允许的基本几何体占位符,即使是作为发送给用户的渲染图中的占位符也不行。

获取渠道(按符合的第一项采用)

  1. 你自己的网格库。 维护一个索引(类别、尺寸、三角形数量、路径、许可证),包含所有先前项目生成或下载的道具网格,并首先搜索它。重复使用优于购买。
  2. Poly Haven CC0,免费:使用 tools/fetch_ph_model.py <id>(glTF 2k 下载到 gen/ph/<id>/),材质和天空使用 tools/fetch_polyhaven.py <id>。每个智能体的下载量保持在约 150 MB 以内。
  3. 生成的网格, 付费,仅通过主线程,并且仅在用户看到成本之后:对于柔软或有机的道具和装饰品使用 Meshy,对于硬表面主体使用 Tripo H3.1 detailed。分三步准备和适配网格:
    • 清理裁剪图。 从照片中裁剪出对象(gen/meshy_refs/<name>_crop.jpg)。对其执行一次简单的图像编辑处理,以移除遮挡物、补全裁剪部分,并赋予纯色背景,保存为 <name>_clean.png。然后才能调用图像到 3D 的转换。在喷泉运行时,这使得所有四个雕像和顶篷都能在第一次尝试时就可用。
    • 离线减面一次, 输出到 gen/<domain>_meshes.blend,附带一个...

相关技能