Metashape Python API 1.82：摄影测量流水线自动化与批处理实战

简介这份资源是面向 Metashape Professional 用户的 Python 脚本开发参考手册对应 1.82 版本适合已具备一定 Python 基础、希望在三维重建流程中实现自动化的测绘、摄影测量与视觉工程从业者。内容围绕 Metashape 模块展开涵盖 Document 类与项目数据操作、相机与标记管理、照片对齐、密集云构建、建模与纹理化等处理步骤以及模型、正射影像、DEM 的导出和网络任务控制并附有模块索引与变更日志便于查阅。资源包共 1 个 PDF 文件约 1.16MB为官方英文 API 参考文档结构按概述、应用模块、变更记录与索引组织适合作为案头速查与脚本编写依据。目前已有 311 人学习下载可帮助读者快速定位类与函数用法减少试错成本。1. 从一条命令行脚本说起这个 API 到底能替你省下多少重复劳动如果你手头有一批无人机航拍照片要在 Metashape Professional 里跑完对齐、稠密点云、建模、纹理、导出正射影像这一整套流程点鼠标点到手酸是常态。更麻烦的是同样的参数要在几十个项目上重复设置稍有偏差结果就不一致。MetaShape Python API 1.82 就是来解决这个问题的——它把 Metashape Professional 的核心处理能力暴露成 Python 接口让你用脚本把整条摄影测量流水线串起来。这个 API 基于 Python 3.8仅 Professional 版支持覆盖项目管理、相机与标记操作、处理步骤调用、结果导出等环节。适合谁做批量航测建模的开发者、需要把三维重建嵌进自有系统的团队以及想把重复操作自动化的测绘从业者。需要先明确一点这不是一个独立安装的库而是 Metashape Professional 内置的脚本引擎。你写的脚本要么在软件的控制台面板里跑要么通过「工具 → 运行脚本」执行要么在命令行用-r参数传入脚本路径。理解这个前提后面所有的代码才有落脚点。2. 核心对象模型拆解Document、Chunk 与 Application 三层结构2.1 Document 与 Chunk项目数据的容器整个 API 的骨架非常清晰Document代表一个 Metashape 项目文件.psz一个 Document 下可以挂多个Chunk每个 Chunk 是一套独立的处理单元——包含照片、相机、标记、点云、模型等。你几乎所有的处理操作都落在 Chunk 上。import Metashape # 获取当前界面打开的项目也可以 Document() 新建 doc Metashape.app.document doc.open(project.psz) # chunk 是处理的基本单位一个项目可以有多个 chunk chunk doc.chunk # 当前激活的 chunk print(len(doc.chunks)) # chunk 总数doc.chunk返回当前激活的 chunkdoc.chunks是列表可以按索引取。参数上没什么玄学但要注意doc.open()会替换当前文档内容如果界面上有未保存的修改脚本里最好先判断再操作。常见做法是在脚本开头加一层保护避免把用户正在编辑的项目冲掉。2.2 Application全局入口与交互能力Metashape.app是Application类的单例提供版本信息、GPU 配置、文件对话框、坐标系统选择等全局能力。它最有价值的地方是把「需要用户输入」的环节也脚本化了——你可以弹一个坐标系选择框把用户选的结果直接赋给 chunk。import Metashape doc Metashape.app.document # 弹出坐标系选择对话框默认值为当前 chunk 的 crs crs Metashape.app.getCoordinateSystem(选择坐标系, doc.chunk.crs) doc.chunk.crs crs # 弹出保存文件对话框 path Metashape.app.getSaveFileName(项目另存为) try: doc.save(path) except RuntimeError: Metashape.app.messageBox(保存失败)getCoordinateSystem(label, value)的value是默认选中项返回CoordinateSystem对象取消则返回None。getSaveFileName返回字符串路径取消返回空串。这里有个血泪经验doc.save()在路径不可写时会抛RuntimeError不捕获的话脚本直接中断批量任务里一个失败会拖垮整批。2.3 处理流水线一次脚本跑完对齐到纹理API 最实用的部分是把处理步骤串成链。下面这段是官方示例的整理版也是我一般用来做批处理模板的骨架import Metashape doc Metashape.app.document doc.open(project.psz) chunk doc.chunk # 照片对齐downscale1 表示不降采样精度最高但最慢 chunk.matchPhotos(downscale1, generic_preselectionTrue, reference_preselectionFalse) chunk.alignCameras() # 深度图与稠密点云 chunk.buildDepthMaps(downscale4, filter_modeMetashape.AggressiveFiltering) chunk.buildDenseCloud() # 网格与纹理 chunk.buildModel(surface_typeMetashape.Arbitrary, interpolationMetashape.EnabledInterpolation) chunk.buildUV(mapping_modeMetashape.GenericMapping) chunk.buildTexture(blending_modeMetashape.MosaicBlending, texture_size4096) doc.save()逐段说参数matchPhotos的downscale控制特征提取的图像缩放级别1 是原图、2 是半分辨率数值越大越快但特征点越少generic_preselection开启通用预选能显著减少匹配对数。buildDepthMaps的downscale4是稠密化的常用折中filter_mode选AggressiveFiltering对噪声多的数据集更稳。buildModel的surface_type用Arbitrary适合非平面物体interpolation用EnabledInterpolation会补洞。buildTexture的texture_size4096是纹理图集边长太大吃显存太小糊。提示buildDenseCloud()在 1.8.x 里已被深度图流程取代如果你的脚本是从老版本迁移过来的直接调它可能报错或行为不一致建议改成buildDepthMapsbuildDenseCloud的组合。3. 相机、校准与几何对象数据层的读写细节3.1 Calibration相机内参的读写与投影计算Calibration类封装了焦距、主点、畸变系数等内参还带project()和error()两个几何方法做精度检查时很顺手。import Metashape calib Metashape.Calibration() calib.load(camera_calib.xml, Metashape.CalibrationFormatXML) # 查看内参 print(calib.f, calib.cx, calib.cy) print(calib.k1, calib.k2, calib.p1, calib.p2) # 把三维点投影到像素坐标并计算与实测像素的误差 point_3d Metashape.Vector((1.0, 2.0, 3.0)) proj calib.project(point_3d) err calib.error(point_3d, Metashape.Vector((512, 384)))load(path, format)支持 XML 等格式save()反向导出。project(point)返回二维像素坐标Vectorerror(point, proj)返回投影误差。参数里point是相机坐标系下的三维点不是世界坐标——这点容易翻车传错坐标系算出来的误差毫无意义。3.2 AttachedGeometry 与 BBox空间数据的组织方式AttachedGeometry提供了一套几何构造器用来给项目附加矢量数据比如 GCP 连线、边界线。BBox则是轴对齐包围盒min/max/size三个属性直接读。import Metashape # 构造一个多边形几何 ring [1, 2, 3, 4] # 顶点 key 列表 poly Metashape.AttachedGeometry.Polygon(ring) # 包围盒 bbox Metashape.BBox() bbox.min Metashape.Vector((0, 0, 0)) bbox.max Metashape.Vector((10, 10, 10)) print(bbox.size)Polygon(exterior_ring, interior_rings)的 ring 是顶点 key 的整数列表不是坐标值——这是它和普通几何库最大的区别key 对应的是 chunk 里 marker 或顶点的索引。BBox.size返回的是Vector类型的尺寸不是标量。3.3 Settings 与视图捕获把界面状态也纳入脚本Settings类读写应用配置ModelView/OrthoView的captureView()能把当前视图截成图像做报告配图很方便。import Metashape settings Metashape.app.settings settings.setValue(project_compression, 6) settings.save() # 捕获模型视图宽 1920 高 1080透明背景 img Metashape.app.model_view.captureView(1920, 1080, True, False) img.save(preview.png)setValue(key, value)的 key 是字符串比如project_compression、log_enable。captureView(width, height, transparent, hide_items)四个参数都可选hide_itemsTrue会隐藏坐标轴等辅助元素出图更干净。注意captureView依赖界面渲染在无头模式下跑会失败。4. 避坑与排查脚本跑不通时先看这几条4.1 报 ModuleNotFoundError: No module named Metashape现象在系统 Python 里import Metashape直接失败。原因这个模块只存在于 Metashape Professional 的内置解释器里不是 pip 包。解决脚本必须在软件内运行控制台或「运行脚本」或用命令行metashape -r script.py调用别指望在外部 venv 里装。4.2 处理步骤报「Empty chunk」或结果为空现象alignCameras()跑完 chunk 里没相机。原因照片没加进 chunk或者加到了错误的 chunk。解决先确认chunk.cameras数量加照片用chunk.addPhotos([...])多 chunk 项目里明确指定目标 chunk别依赖doc.chunk的默认激活状态。4.3 保存项目抛 RuntimeError现象doc.save(path)报错。原因路径含中文或特殊字符、目录无写权限、文件被占用。解决用os.path拼绝对路径保存前os.makedirs确保目录存在并用 try/except 包住失败时走messageBox提示而不是让脚本崩掉。4.4 纹理尺寸设太大导致显存溢出现象buildTexture(texture_size8192)中途失败或软件卡死。原因纹理图集边长翻倍显存占用是四倍增长。解决先用 4096 跑通流程确认模型面数合理后再往上调批量任务里根据 GPU 显存动态设texture_size别一刀切。4.5 坐标系赋值后导出位置偏移现象设了chunk.crs但导出的模型坐标不对。原因只改了 crs 没做投影转换或者 GCP 的参考坐标系与 chunk 不一致。解决赋值前用Metashape.app.getCoordinateSystem拿到目标 crs确认 marker 的reference已按同一 crs 填写必要时调chunk.updateTransform()重算。5. 二次开发改造把脚本变成可复用的批处理工具真正让这套 API 产生价值的不是跑通一次示例而是把它封装成能反复用的批处理工具。我一般的做法是抽一个process_project(path, params)函数把处理参数外置成字典主循环遍历项目列表每个项目独立 try/except失败记录到日志而不是中断整批。import Metashape import os import logging logging.basicConfig(filenamebatch.log, levellogging.INFO) def process_project(psz_path, out_dir, params): doc Metashape.Document() doc.open(psz_path) chunk doc.chunk try: chunk.matchPhotos(downscaleparams[downscale], generic_preselectionTrue) chunk.alignCameras() chunk.buildDepthMaps(downscaleparams[depth_downscale], filter_modeMetashape.AggressiveFiltering) chunk.buildDenseCloud() chunk.buildModel(surface_typeMetashape.Arbitrary, interpolationMetashape.EnabledInterpolation) chunk.buildUV(mapping_modeMetashape.GenericMapping) chunk.buildTexture(blending_modeMetashape.MosaicBlending, texture_sizeparams[texture_size]) out os.path.join(out_dir, os.path.basename(psz_path)) doc.save(out) logging.info(OK: %s, psz_path) except Exception as e: logging.error(FAIL: %s - %s, psz_path, e) params {downscale: 1, depth_downscale: 4, texture_size: 4096} for p in [a.psz, b.psz]: process_project(p, ./out, params)改造要点有三个。第一用Metashape.Document()新建实例而不是复用app.document这样批处理时不会互相污染界面状态。第二参数全部走字典方便从 JSON 或命令行读入换数据集只改配置不改代码。第三异常粒度控制在单个项目日志里带项目名和错误信息事后排查有据可依。验证方法上我习惯先拿两三个小项目跑通全流程对比手动操作的结果——重点看相机对齐数量和纹理清晰度是否一致再放大到全量。如果结果偏差大优先查downscale和filter_mode这两个参数它们对精度影响最直接。还有一个技巧把常用操作封装成带默认参数的辅助函数比如safe_save(doc, path)内部做目录检查和异常捕获所有脚本统一调用。这样以后换机器、换路径改一处就够。说个教训。早期我做批量脚本时图省事直接复用app.document循环打开项目结果某个项目处理到一半报错界面状态卡在中间态后面所有项目全跟着错。从那以后我每次批处理都强制走独立Document实例加单项目异常隔离再没出现过连锁翻车。希望帮到你。本文还有配套的精品资源点击获取