照片场景重建 是做什么的?
此方法于 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. 主线程在任何智能体开始前进行设置
主线程(主会话)独立完成这些操作。智能体只有在所有设置完成后才能启动。
-
运行文件夹。
<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)。 -
解算相机,使用
tools/vp.py。找到垂直消隐点和主立面方向的一个水平消隐点。然后tools/solve_cam.py获取以下参数:- 焦距,根据两个方向(主立面方向和与其垂直的水平方向)正交得出(不要假设镜头参数);
- 俯仰角,根据垂直消隐点得出;
- 偏航角,选择使得主立面与世界坐标 +X 轴方向一致。
将结果写入
layout/camera.json。此后相机在整个运行过程中冻结。 -
测量锚点,使用
tools/cam.py:on_z用于水平平面上的点,on_y用于垂直平面上的点,project返回像素坐标,ray返回视角射线。- 测量地面线、立面平面以及每个地标的距离。
- 将主线程的初步估计值作为起始值写入规则书。
- 在接近平行视角时,地面线的一个像素可能对应半米的深度。优先使用已知物体的高度和宽度(门 2.1 米,眼睛高度 1.6 米,路缘石 0.12 米),而不是单个地面点。
-
对象清单。 列出照片中可见的每个对象,并将其标记为 脚本化(scripted) 或 网格(mesh)(第 3 节)。此清单决定了领域划分和资源获取。
-
编写
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 节) |
| 地面过于干净 | 添加磨损、湿迹、树叶、接缝 |
用户批准保真度之后
只有在此之后,才能按顺序进行以下操作:
- 真实感处理: 倒角、玻璃和地面磨损。有轨电车运行将其作为一个模块(
weather模块)处理;Fischbrunnen 项目则是在每个领域内部完成。两种方式均可,但每个表面必须由一个领域拥有。 - 渲染质量: 2160 像素超采样和高精度降噪。
- 传感器处理(第 4.1 节)。
- 其他视角的验证视图(一个
proof.py脚本,渲染额外相机视角)。 - 光照氛围。
- 影像处理(第 5 节)。
在每个检查点发送照片与渲染的对比图,并等待用户反馈。
3. 网格:复杂对象不使用基本几何体
规则:复杂对象绝不使用简单的基本几何体构建。应使用现有的真实网格。
适用范围
- 脚本化几何体允许用于建筑和基础设施: 墙壁、楼板、屋顶、窗框和门框、檐口和装饰线条、路缘石、铺装、护栏、杆子、电线、平面标牌。
- 需要真实网格用于所有有机或对象状物体: 树木、灌木、盆栽植物、人物、车辆、自行车、椅子、桌子、长凳、花盆、遮阳伞、具有造型体的灯具、雕塑装饰品、雕像、带褶皱的布料。
- 测试:如果有人会将你的构建描述为“棍子上的球体”、“带四条腿的盒子”或“圆柱体”,那么它就是不允许的基本几何体占位符,即使是作为发送给用户的渲染图中的占位符也不行。
获取渠道(按符合的第一项采用)
- 你自己的网格库。 维护一个索引(类别、尺寸、三角形数量、路径、许可证),包含所有先前项目生成或下载的道具网格,并首先搜索它。重复使用优于购买。
- Poly Haven CC0,免费:使用
tools/fetch_ph_model.py <id>(glTF 2k 下载到gen/ph/<id>/),材质和天空使用tools/fetch_polyhaven.py <id>。每个智能体的下载量保持在约 150 MB 以内。 - 生成的网格, 付费,仅通过主线程,并且仅在用户看到成本之后:对于柔软或有机的道具和装饰品使用 Meshy,对于硬表面主体使用 Tripo H3.1 detailed。分三步准备和适配网格:
- 清理裁剪图。 从照片中裁剪出对象(
gen/meshy_refs/<name>_crop.jpg)。对其执行一次简单的图像编辑处理,以移除遮挡物、补全裁剪部分,并赋予纯色背景,保存为<name>_clean.png。然后才能调用图像到 3D 的转换。在喷泉运行时,这使得所有四个雕像和顶篷都能在第一次尝试时就可用。 - 离线减面一次, 输出到
gen/<domain>_meshes.blend,附带一个...
- 清理裁剪图。 从照片中裁剪出对象(