简介这份PDF面向使用Metashape Professional进行摄影测量与三维重建的Python开发者系统梳理了Agisoft官方1.8.2版Python API参考文档帮助读者在脚本层面调用软件核心处理能力。资源包共1个PDF文件约1.16MB内容涵盖API概述、应用模块说明、变更日志与Python模块索引并给出从打开项目、添加照片、对齐相机到构建深度图、密集云、模型、UV与纹理的完整示例代码便于对照查阅各类与函数用法。已有311人学习下载适合需要将照片对齐、建模、导出DEM与正射影像等流程自动化的中高级用户可作为编写批处理脚本、搭建网络处理任务时的案头速查手册。1. 脚本化摄影测量为什么一个chunk对象能顶半支建模团队很多人第一次看到 Metashape 的 Python 脚本会觉得它不过是把界面上的按钮换成了函数调用——点一下“对齐照片”变成alignCameras()仅此而已。真正反直觉的地方在于这个 API 暴露的不是“操作”而是项目的数据模型本身。一个Document里挂着若干Chunk每个Chunk又持有相机、标记、点云、网格、纹理、坐标系、校准参数你拿到的是整条摄影测量流水线的中间状态而不是黑匣子式的“一键处理”。这意味着你可以读出一个相机的畸变系数、改掉它的主点坐标、把某个 chunk 的投影换成另一套 CRS再让后续步骤基于你改过的状态继续跑。对做 python 开发语言的人来说这套设计的价值不在于省几次点击而在于把“重建”从一次性操作变成了可检查、可干预、可复现的数据流。搞懂它为什么这样组织比记住几个函数名重要得多。2. Document 与 Chunk项目状态为什么必须显式持有2.1 从Metashape.app.document说起单例入口与多文档并存API 的入口设计很有意思。Metashape.app是一个全局Application实例它的document属性指向当前界面里打开的那个项目但文档同时明确Document类可以被多次实例化多个项目对象能并存于同一进程。这两句话放在一起其实是在告诉你一个关键事实app.document只是“当前 UI 绑定”的快捷方式不是唯一真相。import Metashape # 入口一拿界面当前打开的项目 doc Metashape.app.document # 入口二自己新建一个独立文档对象与 UI 无关 doc2 Metashape.Document() doc2.open(project.psz) # 两者互不干扰doc2 的操作不会反映到界面 print(doc.path, doc2.path)这段代码里Metashape.app.document返回的是应用层持有的引用Metashape.Document()则是脚本自己创建的对象。为什么要区分因为批处理场景下你往往不想让脚本的中间状态污染用户正在编辑的界面项目。常见的实现思路是Application持有一个指向 GUI 文档的弱引用或直接引用而Document构造函数走的是独立的加载路径两者共享同一套底层项目解析逻辑但生命周期解耦。这也解释了为什么文档里强调“可以同时创建多个 Document 实例”——它不是随口一提而是在为无人值守的批量重建留出设计空间。doc.open()接受.psz路径doc.save()写回doc.saveAs()另存。注意save()不带参数时写回原路径如果文档从未保存过行为取决于实现——稳妥做法是永远显式给路径别赌默认值。2.2 Chunk 是处理单元不是“图层”doc.chunk返回当前激活的 chunkdoc.chunks是列表。很多人把 chunk 理解成“图层”或“分组”这是踩坑的起点。Chunk 在摄影测量语义里是一个独立的对齐与重建上下文它有自己的相机集合、自己的稀疏点云、自己的坐标系、自己的处理参数。两个 chunk 之间默认不共享对齐结果除非你显式做对齐合并。chunk doc.chunk print(chunk.cameras) # 该 chunk 下的相机列表 print(chunk.markers) # 控制点/标记 print(chunk.crs) # 该 chunk 的坐标参考系 print(chunk.dense_cloud) # 密集点云对象若已生成chunk.crs这个属性值得单独说。它不是一个字符串而是一个CoordinateSystem对象赋值时会触发投影解析。文档示例里doc.chunk.crs crs看似简单但背后是脚本通过app.getCoordinateSystem()弹出选择框拿到对象再赋给 chunk后续所有导出DEM、正射、模型都会按这个 CRS 解释坐标。如果你在批处理里硬编码一个 EPSG 字符串得确认底层解析器认这个写法——不同版本对 CRS 字符串的宽容度不一样这是血泪经验里最常见的一类翻车。2.3 处理流水线的顺序约束从哪来文档给的示例流水线是matchPhotos→alignCameras→buildDepthMaps→buildDenseCloud→buildModel→buildUV→buildTexture。这个顺序不是随便排的它对应摄影测量的物理依赖链先有特征匹配才能估计相机位姿有位姿才能做多视立体生成深度图有深度图才能融合成密集点云有点云才能建网格有网格才能展 UV 和贴纹理。chunk.matchPhotos( downscale1, # 匹配时的降采样倍率1 表示全分辨率 generic_preselectionTrue, # 通用预筛选先粗筛候选像对 reference_preselectionFalse # 是否用参考坐标预筛选 ) chunk.alignCameras() chunk.buildDepthMaps( downscale4, # 深度图降采样4 是速度/质量折中 filter_modeMetashape.AggressiveFiltering # 激进滤波压噪声 ) chunk.buildDenseCloud()downscale参数在matchPhotos和buildDepthMaps里含义不同前者影响特征提取的图像分辨率后者影响深度图计算的分辨率。把两者混为一谈是新手常犯的错——匹配阶段降太多会导致弱纹理区域匹配失败深度图阶段降太多会让点云边缘发糊。filter_mode用枚举而不是整数这是 API 的一贯风格Metashape.AggressiveFiltering、Metashape.ModerateFiltering这类常量把底层整型编码藏起来脚本可读性更好但也意味着你得查模块索引确认枚举名别凭记忆拼。3. Calibration 与坐标相机内参为什么是可变对象3.1 内参不是只读快照Calibration类暴露了f焦距、cx/cy主点、k1~k4径向畸变、p1~p4偏心畸变、b1/b2仿射与非正交。关键在于这些是可写属性不是对齐后锁死的只读结果。你可以load()一个外部校准文件也可以直接改字段再save()。calib chunk.sensors[0].calibration calib.f 3200.0 # 直接改焦距 calib.cx 2048.0 # 改主点 X calib.k1 -0.12 # 改径向畸变 calib.save(calib.xml, formatMetashape.CalibrationFormatXML)为什么允许改因为实际工程里相机内参可能来自标定板、来自厂商出厂值、来自另一批数据的估计值脚本需要把这些先验灌进去再对齐。project(point)和error(point, proj)两个方法则提供了正向验证手段给一个三维点算出它投到像素平面的位置再和实测像素坐标比得到重投影误差。这套“可写内参 可算投影误差”的组合是把标定质量纳入自动化质检的基础。3.2project与error的机制含义project(point)内部走的是针孔模型加畸变多项式先把三维点变换到相机坐标系除以深度得到归一化坐标套用k1~k4、p1~p4、b1/b2的畸变公式再乘焦距加主点。error(point, proj)则是project的结果与给定像素坐标的差。文档没写公式细节但按这个领域的通行做法畸变模型就是 Brown-Conrady 那一套的扩展。理解这一点你才知道为什么改k1会同时影响画面中心和边缘的投影——它不是线性缩放而是径向多项式。提示改完内参后不要立刻信任对齐结果先用几个已知控制点跑error()看残差量级残差突然变大说明参数灌错了。3.3 坐标系与 GCP 的耦合chunk.crs决定坐标解释方式而Marker标记/控制点携带参考坐标。文档提到可以“添加/修改地面控制数据、指定地理投影和坐标”。机制上GCP 的作用是在对齐后做一次带约束的平差把标记的像素观测和已知地面坐标联立修正相机位姿和场景尺度。脚本里如果先设 CRS 再导 GCP和先导 GCP 再设 CRS中间状态可能不一致——稳妥顺序是先定 CRS再灌标记坐标最后触发带参考的对齐或优化。这个顺序在文档示例里没明说但从数据依赖能推出来。4. Application 与视图捕获脚本怎么和界面共存4.1 全局属性与 GPU 掩码Application暴露了version、activated、cpu_enable、gpu_mask、settings等。gpu_mask是位掩码值 5 表示二进制101启用 0 号和 2 号设备。这种位掩码设计在需要精细控制多卡时很常见但也容易算错——想启用 1 号和 3 号就是1010即 10别写成 3。devices Metashape.app.enumGPUDevices() for i, d in enumerate(devices): print(i, d) # 只启用第 0 和第 2 块 GPU Metashape.app.gpu_mask 0b101 Metashape.app.cpu_enable False # GPU 可用时是否仍用 CPUenumGPUDevices()返回设备列表配合gpu_mask做设备选择。cpu_enable的语义是“GPU 激活时是否仍参与计算”关掉它能避免 CPU 拖慢某些 GPU 密集步骤但也可能让显存不足时直接失败——这是取舍不是绝对优化。4.2captureView与视图模式枚举ModelView、OrthoView提供captureView(width, height, transparent, hide_items)返回一个Image对象。视图模式用枚举控制ModelViewMode有ModelViewShaded、ModelViewSolid、ModelViewWireframe、ModelViewConfidence、ModelViewTexturedDenseCloudViewMode有颜色/分类/置信度几种。这套设计的动机是让脚本能生成“和界面看到的一样的截图”用于报告或质检留档。view Metashape.app.model_view view.model_view_mode Metashape.ModelViewTextured img view.captureView(width1920, height1080, transparentFalse, hide_itemsTrue) img.save(preview.png)hide_itemsTrue会隐藏坐标轴、网格等辅助元素只留模型本体。注意captureView依赖当前视图状态批处理里如果界面没初始化好可能拿到空图——这是无头环境下的经典坑。4.3 交互式对话框在自动化里的位置getOpenFileName、getSaveFileName、getCoordinateSystem、getInt、getFloat、getString、messageBox这些是阻塞式 UI 调用。它们在人工辅助脚本里很好用但在无人值守批处理里是毒药——没人点确定脚本就挂在那里。设计上它们属于Application而不是Document就是在提示你这些是“界面交互”不是“数据处理”。写批处理时应该用参数文件或环境变量替代把交互调用隔离到单独的入口脚本里。5. 避坑与排查脚本跑不通时先看这几处5.1 现象alignCameras()后相机数为零原因通常是matchPhotos的预筛选把候选像对筛没了或者照片路径在项目里是相对路径而脚本换了工作目录导致读不到图。解决先检查chunk.cameras的photo.path是否可解析再把generic_preselection关掉试一次确认是筛选问题还是数据问题。5.2 现象buildDepthMaps报显存不足downscale1在全分辨率下深度图非常吃显存。原因不是代码错是参数太激进。解决把downscale调到 2 或 4或者用gpu_mask只留大显存卡必要时开cpu_enable兜底。别一上来就怀疑驱动。5.3 现象导出的模型坐标全错多半是chunk.crs没设或设错导致导出时按局部坐标解释。解决在处理前显式赋chunk.crs导出前再读一次确认没被后续步骤覆盖。CRS 对象赋值失败有时不抛异常只是静默不生效所以赋值后要回读校验。5.4 现象save()抛RuntimeError文档示例里用try/except RuntimeError包住doc.save(path)并弹messageBox说明保存失败是以运行时异常形式冒出来的。常见原因是路径不可写、磁盘满、或项目里有失效的外部引用。解决先确保目标目录存在且可写再检查项目是否引用了已移动的照片。5.5 现象脚本在控制台能跑命令行-r跑就崩控制台里Metashape.app.document指向已打开项目命令行启动时可能没有活动文档。原因是对app.document的隐式依赖。解决脚本里显式Document()并open()不要假设有现成文档。6. 设计取舍为什么这套 API 选择“暴露状态”而不是“封装流程”把 Metashape 的 Python API 和那些“一行代码出模型”的高层封装对比会发现它刻意选择了更笨拙的路线不给你reconstruct(photos)这种一站式函数而是把matchPhotos、alignCameras、buildDepthMaps、buildDenseCloud、buildModel、buildUV、buildTexture一步步摊开每步的参数、每步的中间产物都可访问。这个取舍的代价是脚本更长、学习曲线更陡收益是可干预性和可复现性。设计维度高层封装路线Metashape 这种状态暴露路线上手成本低高需理解流水线依赖中间状态可查通常不可相机、点云、校准全可读失败可定位难黑匣子可按步骤二分排查参数精细控制有限每步独立参数批处理可复现依赖封装内部默认值参数显式易固化这种路线适合什么场景适合你需要把摄影测量嵌进更大自动化管线的时候——比如先用自己的代码筛一遍照片、按 EXIF 分组、给不同组灌不同校准再让 Metashape 只做重建或者重建完不直接出图而是把点云读出来做自定义分析。反过来如果你只是偶尔把一堆照片变成模型这套 API 的粒度确实偏细。验证这套 API 是否用对了我一般会做三件事一是对齐后打印相机数和平均重投影误差确认几何合理二是导出前回读chunk.crs和几个 GCP 的残差三是把整条流水线的参数写进一个配置字典换数据集时只改配置不改代码。这三步能挡住大部分“跑完了但结果是错的”这类最难受的故障。从那以后我每次写这类脚本都强制先把Document的打开方式和chunk.crs的赋值单独抽成一个初始化函数跑通再往下接处理步骤——因为翻车最多的从来不是算法本身而是入口状态没对齐。希望帮到你。本文还有配套的精品资源点击获取