Metashape Python API 批量航测后处理实战指南

简介这份资源是面向 Metashape Professional 用户的 Python 脚本开发参考手册对应 1.8.2 版本适合已具备一定 Python 基础、希望将摄影测量处理流程自动化的测绘、三维重建与遥感从业者。内容围绕 Metashape 模块展开涵盖 Document 类与项目读写、块与相机标记管理、相机校准与地面控制数据配置、照片对齐与密集云/网格/纹理构建、模型与 DEM 导出以及网络处理任务控制等核心接口并附有完整处理流程的示例代码与模块索引便于按类查函数、按流程搭脚本。资源包共 1 个 PDF 文件约 1.16MB为官方英文参考文档适合作为案头速查与二次开发依据。目前已有 311 人学习可帮助读者快速定位 API 用法、理解脚本执行方式与对象模型减少在自动化处理与批处理任务中的试错成本。1. 拿到这份 API 文档先想清楚它能替你省掉多少重复劳动如果你手头有一批无人机航拍照片要在 Metashape Professional 里跑完对齐、稠密点云、建模、纹理、导出正射影像这一整套流程点菜单点到手酸是常态。更麻烦的是同样的参数组合要在几十个项目上重复执行中间还得盯着进度、改参数、补导出。这份《Metashape Python Reference 1.8.2》就是干这个的它把 Metashape Professional 的核心处理能力暴露成 Python 接口让你用脚本把整条摄影测量流水线串起来。注意脚本引擎只挂在 Professional 版上标准版没有这个入口Python 版本是 3.8。适合谁做批量航测后处理、需要把建模流程嵌进自有系统、或者想给团队做半自动化工具链的开发者。下面按「能干什么 → 怎么跑 → 怎么改」拆开讲。2. 模块骨架拆解Document、Chunk 与 Application 三层结构2.1 一个 Document 就是一个 .psz 工程整个 API 的入口是Metashape模块核心类是Document它对应磁盘上的一个工程文件.psz。你可以同时开多个 Document 实例做并行批处理也可以直接拿Metashape.app.document操作当前界面上打开的那个工程。Document 下面挂的是chunk一个工程可以有多个 chunk每个 chunk 是一套独立的照片集合和处理状态。相机、标记点、校准参数、点云、网格、纹理全都挂在 chunk 上。理解这个层级很关键你写脚本时 90% 的时间是在doc.chunk上调用方法而不是在 Document 上。import Metashape # 打开已有工程拿到当前 chunk doc Metashape.app.document doc.open(/data/site_a/project.psz) chunk doc.chunk # 也可以遍历所有 chunk 做批量处理 for ch in doc.chunks: print(ch.label, len(ch.cameras), len(ch.markers))上面这段先open再取chunk是脚本的标准起手式。doc.chunks返回的是 chunk 列表ch.label是块名称ch.cameras和ch.markers分别是相机和标记点的集合长度就是数量。批量场景下我一般先遍历打印一遍确认每个块的输入是否齐全再决定跑不跑处理步骤——这一步能挡掉不少「空块跑半天」的翻车。2.2 Application 类全局状态和交互对话框都在这Metashape.app是Application类的单例管的是全局层面的东西当前文档、软件版本、GPU 设备枚举、GPU 掩码、CPU 是否参与计算以及一堆弹窗方法。做自动化脚本时弹窗方法要慎用——无人值守跑批的时候弹一个getOpenFileName出来进程就卡死了。但做交互式小工具时这些方法很好用比如让用户选坐标系、选保存路径。# 枚举 GPU 并只启用 0 号和 2 号设备 devices Metashape.app.enumGPUDevices() print(可用 GPU:, [d.name for d in devices]) # gpu_mask 是位掩码1 表示启用0 表示禁用 # 二进制 101 十进制 5即启用设备 0 和设备 2 Metashape.app.gpu_mask 5 Metashape.app.cpu_enable True # GPU 跑的时候也让 CPU 参与 # 交互式选坐标系并应用到当前 chunk crs Metashape.app.getCoordinateSystem(选择坐标系, doc.chunk.crs) if crs is not None: doc.chunk.crs crsenumGPUDevices()返回设备列表gpu_mask的位运算规则是文档里明确写的第 n 位对应第 n 个设备。cpu_enable控制 GPU 活跃时 CPU 是否也参与批量跑的时候我一般设 True让 CPU 分担一部分预处理。getCoordinateSystem第二个参数是默认值用户取消时返回None所以后面必须判空——不判空直接赋值脚本会在chunk.crs上抛异常这是新手最常见的翻车点之一。2.3 处理流水线从 matchPhotos 到 buildTexture 的调用顺序文档给的示例把主流程串得很清楚matchPhotos→alignCameras→buildDepthMaps→buildDenseCloud→buildModel→buildUV→buildTexture。这个顺序不能乱后一步依赖前一步的输出。每个方法都有枚举参数比如downscale控制降采样倍率filter_mode控制深度图滤波强度surface_type控制重建表面类型。这些参数直接决定跑出来的质量和耗时批量脚本里通常做成配置字典按项目类型切换。# 完整流水线参数集中管理 params { match_downscale: 1, # 1 全分辨率匹配最慢但最准 depth_downscale: 4, # 深度图降采样 4 倍速度优先 filter_mode: Metashape.AggressiveFiltering, surface_type: Metashape.Arbitrary, texture_size: 4096, } chunk.matchPhotos( downscaleparams[match_downscale], generic_preselectionTrue, reference_preselectionFalse, ) chunk.alignCameras() chunk.buildDepthMaps( downscaleparams[depth_downscale], filter_modeparams[filter_mode], ) chunk.buildDenseCloud() chunk.buildModel( surface_typeparams[surface_type], interpolationMetashape.EnabledInterpolation, ) chunk.buildUV(mapping_modeMetashape.GenericMapping) chunk.buildTexture( blending_modeMetashape.MosaicBlending, texture_sizeparams[texture_size], ) doc.save()逐段说matchPhotos的downscale1表示不降采样做特征匹配精度最高但最吃内存照片超过几百张时我一般会调到 2 或 4 先跑一轮看效果。generic_preselectionTrue开启通用预筛选能显著减少匹配对数。buildDepthMaps的downscale4是速度和质量之间的常用折中AggressiveFiltering对噪声多的航拍数据更稳。buildModel的Arbitrary适合非平面物体如果是地形测绘换成HeightField更合适。buildTexture的texture_size4096是纹理贴图边长再往上内存开销陡增。最后doc.save()落盘不 save 前面全白跑。3. 把脚本跑起来三种执行入口和参数调优3.1 控制台、菜单、命令行三条路文档明确给了三种执行方式。第一种是在 Metashape 的 Console 面板里当标准 Python 控制台用适合边试边调改一行跑一行。第二种是 Tools 菜单里的 Run script选一个 .py 文件执行适合已经写好的完整脚本。第三种是命令行带-r参数传脚本路径这是做批处理和定时任务的正路因为可以脱离界面跑。# 命令行方式-r 后面跟脚本路径 # 具体可执行文件名以本机安装为准这里用占位 metashape -r /data/scripts/batch_process.py命令行方式的关键是脚本里不要依赖界面交互。所有getOpenFileName、getSaveFileName、messageBox这类调用在无人值守场景下要么改成硬编码路径要么用 try/except 包住并给默认值。我一般会在脚本开头加一个HEADLESS开关交互方法和固定路径二选一同一份脚本既能手动跑也能挂到调度器上。3.2 参数怎么调downscale 和 filter_mode 的取舍downscale是出现频率最高的参数matchPhotos和buildDepthMaps都有。它的含义是图像降采样倍率值越大处理越快、精度越低。经验值照片数量少于 100 张、要求高精度时matchPhotos用 1几百张的常规航测用 2上千张的快速预览用 4。buildDepthMaps的downscale一般比匹配阶段大一档因为深度图计算量更大。filter_mode控制深度图滤波可选AggressiveFiltering、ModerateFiltering、MildFiltering、NoFiltering。航拍数据噪声多、边缘杂用 Aggressive 能压掉大部分飞点室内近景、细节丰富的物体用 Mild 或 NoFiltering 保留更多结构。这个参数调错后面建出来的模型要么坑坑洼洼要么糊成一团属于典型的「参数玄学」建议先用小样本试跑对比。3.3 相机校准和地面控制点的读写Calibration类承载相机内参焦距f、主点cx/cy、径向畸变k1~k4、偏心畸变p1~p4、仿射b1/b2。这些字段可以直接读写也可以load/save走 XML 文件。做多相机批量处理时我习惯把每台相机的校准文件统一管理脚本里按相机型号匹配加载避免每次重新标定。# 给 chunk 里所有相机批量套用同一份校准 calib Metashape.Calibration() calib.load(/data/calib/camera_a.xml) for cam in chunk.cameras: cam.sensor.calibration calib.copy()calib.copy()不能省直接赋值会让所有相机共享同一个对象引用后面改一台全跟着变。cam.sensor是相机对应的传感器对象校准挂在传感器上而不是相机上同一传感器下的多张照片共享一份内参这个层级关系理清了能少走很多弯路。4. 避坑与排查五个真实踩过的坑4.1 脚本在标准版里跑不起来现象import Metashape直接报模块找不到或者脚本在 Console 里执行无反应。原因Python 脚本引擎只在 Professional 版里提供标准版根本没有这个模块。解决确认安装的是 Professional 版且脚本引擎版本是 Python 3.8换机器部署时先跑一行import Metashape; print(Metashape.app.version)做冒烟测试。4.2 批量跑批时进程卡死不动现象挂到调度器上的脚本跑了几个小时没进展日志停在某一步。原因脚本里残留了getOpenFileName或messageBox这类交互调用无人值守时弹窗等待输入进程挂起。解决所有交互方法加开关控制无人值守分支走固定路径或者用try/except RuntimeError包住捕获后走默认逻辑。4.3 处理完没保存结果全丢现象脚本跑完没报错但重新打开工程发现处理结果不在。原因只调了处理步骤忘了doc.save()或者save之前抛了异常被吞掉。解决把doc.save()放在try/finally的 finally 里确保异常时也尝试落盘关键步骤之间加中间保存长流程不要攒到最后一次存。4.4 GPU 掩码设错计算全落到 CPU 上现象明明有独立显卡处理速度却和纯 CPU 一样慢。原因gpu_mask位掩码设错比如想启用 0 号设备却写成了 2二进制 10实际启用的是 1 号设备或者设备枚举顺序和预期不一致。解决先enumGPUDevices()打印设备列表和索引再按索引算掩码启用 0 号设备是1 0 1启用 0 和 2 是1 4 5。4.5 校准对象共享导致参数串台现象批量套用校准后改一台相机的参数其他相机跟着变。原因直接cam.sensor.calibration calib赋的是引用多个传感器指向同一个 Calibration 对象。解决每次赋值用calib.copy()生成独立副本同理BBox、Antenna这类对象跨相机复用时也要 copy。5. 二次开发改造把流水线封装成可配置的批处理工具拿到这份 API 之后最自然的改造方向是把上面那串硬编码调用封装成一个配置驱动的批处理工具。我的做法是三层配置层用 YAML 或 JSON 描述每个项目的输入路径、输出路径、参数组执行层把matchPhotos到buildTexture包成一个函数参数从配置读调度层遍历项目列表逐个开 Document、跑流水线、落盘、记日志。这样换项目只改配置不动代码。import json import Metashape def run_pipeline(project_path, cfg): doc Metashape.app.document doc.open(project_path) chunk doc.chunk chunk.matchPhotos( downscalecfg[match_downscale], generic_preselectionTrue, reference_preselectionFalse, ) chunk.alignCameras() chunk.buildDepthMaps( downscalecfg[depth_downscale], filter_modegetattr(Metashape, cfg[filter_mode]), ) chunk.buildDenseCloud() chunk.buildModel( surface_typegetattr(Metashape, cfg[surface_type]), interpolationMetashape.EnabledInterpolation, ) chunk.buildUV(mapping_modeMetashape.GenericMapping) chunk.buildTexture( blending_modeMetashape.MosaicBlending, texture_sizecfg[texture_size], ) doc.save() if __name__ __main__: with open(/data/config/batch.json) as f: jobs json.load(f) for job in jobs: run_pipeline(job[project], job[params])这段的关键在getattr(Metashape, cfg[filter_mode])配置文件里存字符串AggressiveFiltering运行时从模块里取对应枚举避免在配置里写死数值。验证方法很直接先拿一个小项目跑通全流程确认输出目录里有模型和纹理文件再把参数改一档重跑对比耗时和成果差异最后挂两个项目并行跑看日志有没有交叉污染。改造时有个细节容易忽略——doc.open打开新工程前如果当前文档有未保存改动某些版本会弹确认框无人值守场景下要先把当前文档 save 或 close 掉。从那以后我每次写批处理脚本都强制在开头加一段环境自检打印版本、枚举 GPU、确认 Professional 版、检查输出目录可写四行代码挡掉大半低级问题。希望帮到你。本文还有配套的精品资源点击获取