简介MetaShape Python API 1.82 官方参考手册是一份面向摄影测量与三维重建开发者的技术文档适用于需要在 Metashape Professional 中通过 Python 脚本实现批量自动化处理的项目工程师与研究者。手册覆盖项目打开与保存、区块与相机管理、控制点与坐标系统设置、处理任务调度及结果导出等常用功能系统梳理了 Document、Chunk、Camera 等核心类与函数用法并给出照片对齐、密集云构建、网格生成、纹理映射等完整流程的代码示例可直接迁移到实际生产管线。包体为 1.16MB 的单个 PDF 文件适合离线查阅与快速检索。目前已有 299 人学习该资源。相比零散博客教程原版 API 参考更具权威性与完整性适合作为日常开发工具书。1. Metashape Python API 1.82让摄影测量流程脚本化、可复现的关键做摄影测量的人迟早会碰到这个场景同一个测区、同一套流程要在图形界面里反复点同样的按钮。今天处理 3000 张照片明天换一个测区还是 3000 张每一步操作都一模一样但每次都得重新盯一遍进度条。Metashape Python API 1.82 正是为打破这种重复而存在的脚本接口它把工程打开、照片对齐、密集点云构建、模型生成、正射影像导出全部暴露成可调用的 Python 对象。这篇笔记不讲软件基础功能直接围绕 1.82 版本的 Python API 拆解环境搭建、对齐与重建的完整流程、参数怎么调以及只有跑批处理才会撞上的那些坑。适合已经用 Metashape 跑过基础项目、现在想把处理管线脚本化或者纳入生产流程的从业者。2. Metashape API 的环境与核心对象两种运行形态和数据结构先盘清楚2.1 两种运行形态内置控制台与独立脚本Metashape 的 Python API 有两种跑法新手很容易在第一步就绕晕。第一种是在桌面版里打开 Python 控制台直接输入脚本这时候 API 会连到当前打开的工程通过Metashape.app.document拿到正在编辑的文档对象。这种形态适合调试小功能比如批量给照片改属性、批量加像控点标记改一行跑一行反馈很直接。第二种是独立脚本形态在命令行里执行metashape.exe -r script.py project.psxLinux 环境下对应的是metashape.sh -r script.py project.psx。这种形态不依赖图形界面脚本自己负责打开工程、处理、保存退出适合挂在服务器上批量跑多个测区。独立脚本里没有“当前打开的工程”这个概念所以需要自己创建文档对象再打开工程文件import Metashape import sys def main(): project sys.argv[1] # 命令行传入工程路径 doc Metashape.Document() doc.open(project) chunk doc.chunk print(工程:, project) print(影像数量:, len(chunk.cameras)) print(像控点数:, len(chunk.markers)) print(是否已有稀疏点云:, chunk.point_cloud is not None) if __name__ __main__: main()这段脚本只做一件事打开工程打印最基本的元信息然后退出。适合用来验证 API 环境是否正常、工程文件能否被独立进程读取。这里有一个非常容易踩坑的区别如果脚本是在 GUI 控制台里运行不要自己新建 Document否则会出现“一个进程里两个文档对象”的局面后面所有操作都会乱套只有在独立进程里运行时才需要自己创建Metashape.Document()。我见过不少同事把 GUI 里调通的脚本原封不动拿到服务器上跑结果第一行Metashape.app.document就直接报错原因就是这两种运行形态导致。2.2 核心对象与层级关系Metashape Python API 的对象层级不复杂但命名和直觉有一些出入。我习惯把整个对象模型理解成一条链Document→Chunk→Camera / Sensor / Marker / Shape / PointCloud / Model / Orthomosaic几个最常用的对象如下对象代表的实体常用属性Document一个.psx工程文件chunk、chunksChunk一个测区处理单元包含影像和成果cameras、markers、shapes、point_cloud、dense_cloud、model、orthomosaicCamera单张影像及其外方位元素sensor、transform、reference.locationSensor相机内参标定信息width、height、calibrationMarker像控点或检查点position、projectionsShape矢量对象测区边界、航线等vertices、attributes脚本里最常见的操作就是从doc.chunk出发逐层访问。chunk是关键概念一个工程里可以有多个 chunk每个 chunk 相当于一个独立的数据块有自己的影像、点云、模型和正射影像。多测区或者多架次数据我会分别放进不同 chunk用doc.chunks遍历处理这样一次脚本就能跑完整个测区的所有架次。2.3 快速列出当前版本可用的全部 API1.82 这个版本的 API 数量非常多背不全很正常。需要确认某个方法在当前版本是否存在时可以直接用dir查询import Metashape # 列出 Metashape 模块顶层所有非下划线开头的名字 names [n for n in dir(Metashape) if not n.startswith(_)] print(\n.join(names)) # 查看 Document 对象有哪些方法 print([n for n in dir(Metashape.Document)])输出量很大可以重定向到文本文件里当手册用。看名字时重点抓两类前缀一类是build*比如buildDenseCloud、buildModel、buildOrthomosaic对应重建类操作另一类是export*/import*对应数据交换。alignPhotos这类动词方法一般在 chunk 上不在 Metashape 顶层。这个查询习惯帮我省了很多翻文档的时间尤其是换版本之后不确定某个枚举是否改名时直接看dir输出比查第三方博客可靠得多。3. 对齐流程脚本化从参数设置到结果排查3.1 最小可用对齐脚本对齐是摄影测量流程的第一步也是后面所有成果的地基。对应到脚本最小可用版本是import Metashape doc Metashape.Document() doc.open(block_a.psx) chunk doc.chunk # 如果这个 chunk 已经对齐过先清空旧结果再重跑 chunk.point_cloud None # 执行对齐 chunk.alignPhotos( accuracyMetashape.HighAccuracy, pair_presetMetashape.GenericPreset, keypoint_limit40000, tiepoint_limit4000, adaptive_fittingTrue ) print(稀疏点云点数:, len(chunk.point_cloud.points)) print(参与对齐的影像数:, len([c for c in chunk.cameras if c.transform])) doc.save()这段脚本对应图形界面里的 Align Photos 按钮。逻辑说明先把旧的point_cloud置空避免旧结果干扰新解算然后调用alignPhotos完成特征提取、特征匹配、相机位姿解算最后打印两个统计量——稀疏点数量和成功参与对齐的相机数量。c.transform为 None 的相机说明解算失败可能原因是影像质量太差或重叠度不足。参数说明里accuracy控制影像金字塔层级。HighAccuracy用全分辨率影像做匹配精度高但耗时长MediumAccuracy用降采样后的影像速度快很多。无人机正射或者大范围地形的快速质检我习惯先用MediumAccuracy跑一遍确认数据没问题再上高精度。pair_preset控制影像对的匹配范围GenericPreset是通用模式适合绝大多数场景。keypoint_limit是每张照片最多提取多少特征点40000 是相对安全的数值影像纹理稀疏时可以提到 80000但盲目加大会让匹配阶段的时间成倍上升。tiepoint_limit是单张影像最多保留多少匹配连接点不建议超过 8000超过之后对精度提升非常有限反而拖慢全局优化。adaptive_fitting打开后算法会根据像控点误差自动调整相机内参没有控制点的大规模影像尤其建议打开。3.2 相机位姿精度与参考坐标系对齐质量的一个重要变量是照片自带的相机坐标的置信度通常是 GPS 或 RTK 定位。Metashape 里通过 chunk 的camera_location_accuracy和camera_rotation_accuracy控制。这个值的含义是把相机位置当作带噪声的观测点告诉算法这个位置有多可信。# 假设照片自带 RTK 定位平面误差 3cm高程误差 5cm chunk.camera_location_accuracy Metashape.Vector([0.03, 0.03, 0.05]) # 如果照片只是普通 GNSS 定位误差放大到米级 chunk.camera_location_accuracy Metashape.Vector([3.0, 3.0, 5.0])参数说明三个分量的单位是米顺序是 x、y、z。设得越小算法越信任照片自带位置像控点的纠偏作用就会相应减弱设得越大像控点权重越高。我踩过的典型翻车是无人机带了 RTK但精度向量忘了改默认值导致对齐结果被自带位置“拽偏”反过来用普通 GNSS 数据却设了 3cm 精度对齐会过度信任噪声位置产生整体漂移。坐标系设置同样不能漏。如果工程没有设置目标坐标系导出成果时很容易出现坐标信息缺失或落错带的问题。常见做法是在对齐前指定chunk.crs Metashape.CoordinateSystem(EPSG:32650)这样后续对齐、生成正射影像、导出模型都会套用同一个坐标系避免最后拿到一个没有地理参考的成果。需要注意的是这一步也会影响camera_location_accuracy的数值含义——如果用的是经纬度坐标系精度向量的单位就不是米了。所以我一般把 CRS 设在投影坐标系下精度用米表示逻辑清晰。3.3 对齐结果排查对齐完成后只靠点数判断不够我一般看三个指标对齐成功的相机比例、像控点重投影误差、以及稀疏点云覆盖情况。重投影误差的脚本如下for marker in chunk.markers: if marker.position is None: continue errors [] for camera in marker.projections: if camera.transform is None: continue err marker.projections[camera].loc - camera.project(marker.position) errors.append(err.norm()) if errors: mean_err sum(errors) / len(errors) print(marker.label, 重投影误差均值(px):, mean_err)逻辑说明marker.projections是字典键是相机对象值是手工刺点时记录下来的像素坐标camera.project(marker.position)则是把像控点的空间坐标通过当前相机位姿反投影回影像平面两者相减就是残差向量取范数得到像素误差。经验值上均值小于 1 像素说明对齐质量很好1~2 像素需要结合地面分辨率判断超过 3 像素基本要回到像控点原始坐标或刺点位置检查。这个脚本我每个测区跑完都会执行一遍把结果存成 CSV 作为交付附件比空口说“对齐完成了”有说服力得多。4. 深度重建三件套密集点云、网格和正射影像的 API 调用4.1 构建密集点云稀疏点云只是连接点的集合要得到真正可用于量测的成果得进到深度重建阶段。Metashape 会先为每张照片生成深度图再融合成密集点云。# 用中档质量、温和滤波构建密集点云 chunk.buildDenseCloud( qualityMetashape.MediumQuality, filterMetashape.MildFiltering )逻辑说明quality控制深度图的分辨率UltraHigh按影像原始分辨率重建耗时和内存占用都会非常大Low相当于对影像降采样到很低的级别速度快但点云密度明显不足。filter控制深度噪声的剔除强度AggressiveFiltering会把远距离错误点全部剔除但也会把薄弱的真实表面吃没MildFiltering是相对平衡的取舍也是我默认使用的档位。内存控制是批处理里最需要提前评估的事。密集点云构建的内存消耗远大于其他步骤而且和影像数量、质量档位强相关。建议先抽一个 40 张影像的小块用实际打算采用的质量档位跑一遍记下内存峰值再按影像数量等比估算全量任务。64GB 内存的机器跑 800 张影像的 chunk开UltraHigh很容易直接被系统杀掉这不是 Metashape 不稳定而是内存墙摆在那里。这里有一个反直觉的经验HighQuality和MediumQuality的区别不是点密度翻一倍而是深度图分辨率差四倍计算量也差四倍。地面有植被、水面这类难匹配纹理时开再高的质量档位也不一定多出细节反而可能是AggressiveFiltering把表面细节滤没了。所以当密集点云效果不理想时我优先调整 filter 而不是一味往上提 quality。4.2 网格重建有了密集点云下一步是重建表面模型。buildModel默认使用密集点云作为数据源所以这一步可以在密集点云构建完成后直接调用chunk.buildModel( surface_typeMetashape.Arbitrary, interpolationMetashape.EnabledInterpolation, face_countMetashape.MediumFaceCount )参数说明surface_type里Arbitrary适合任意形状目标比如建筑物、复杂地形HeightField适合纯地形表面生成网格更快、结构更规则但不适合有植被和建筑的场景。interpolation开启后算法会填补点云中的空洞能改善地形洞但也会在点云没有覆盖的区域“脑补”出一块错误表面。如果点云有大面积空洞我先查空洞原因是遮挡还是数据缺失再决定是否开启。face_count控制网格最大面数MediumFaceCount大约对应几十万面的预算对绝大多数 GIS 和测量用途足够只有要进游戏引擎或做精细渲染时才需要开高档否则只是白白增加文件体积和处理时间。4.3 正射影像生成与导出正射影像是最终交付里最常见的成果之一。构建正射影像前要先确认 chunk 里已经有模型或密集点云因为正射影像需要表面数据来做投影纠正。chunk.buildOrthomosaic( surface_dataMetashape.ModelData, blendingMetashape.MosaicBlending, resolution0.05, fill_holesTrue )参数说明surface_data指定用哪种表面纠正投影ModelData用网格模型DenseCloudData用密集点云。blending决定接边处融合方式MosaicBlending会自动寻找色差最小处的像元接缝过渡自然是默认推荐。resolution是输出地面分辨率单位米/像素0.05 表示 5 厘米一个像素。导出正射影像的脚本chunk.exportOrthomosaic( pathrD:\output\ortho_block_a.tif, image_formatMetashape.ImageFormatTIFF, save_alphaFalse, save_georeferencingTrue )逻辑说明save_georeferencing会把地理配准信息写入 TIFF后续在 GIS 软件里打开自动对齐坐标位置。save_alpha控制是否保留透明通道正射影像边缘区域通常没有有效像元保留 alpha 对后续镶嵌和裁切会方便很多。我一般习惯在结果验证完成后再最终导出 TIF中间过程先用低分辨率快速出一版检查覆盖范围。4.4 一个完整的批处理脚本骨架把前面对齐、密集云、模型、正射影像串起来就是一条生产流水线import Metashape, sys doc Metashape.Document() doc.open(sys.argv[1]) chunk doc.chunk chunk.crs Metashape.CoordinateSystem(EPSG:32650) chunk.camera_location_accuracy Metashape.Vector([0.03, 0.03, 0.05]) chunk.alignPhotos( accuracyMetashape.HighAccuracy, keypoint_limit40000, tiepoint_limit4000 ) doc.save() chunk.buildDenseCloud( qualityMetashape.MediumQuality, filterMetashape.MildFiltering ) doc.save() chunk.buildModel( surface_typeMetashape.Arbitrary, face_countMetashape.MediumFaceCount ) chunk.buildOrthomosaic(resolution0.05) doc.save()这个骨架把完整流程串了起来。注意我在每个阶段后都调用了doc.save()这不是多余动作——如果某一步内存溢出导致进程被杀工程文件里已经保存的阶段成果都还在重新跑只需要从断点继续不至于把前面几个小时的处理全部丢掉。独立跑批处理时这个习惯能省下大量返工时间。5. 避坑指南Metashape 批量生产里最容易翻车的五件事5.1 现象脚本在后台跑了两小时Metashape 直接闪退工程文件打不开这类崩溃多数发生在构建密集点云阶段表现形式是控制台没有任何报错进程直接被系统终止重启后打开工程提示文件损坏或无法读取。原因密集点云构建需要把每张影像的深度图常驻内存影像数量大、质量档位高时内存峰值远超预期触发操作系统 OOM。另外如果脚本只在最后保存崩溃前所有进度都回到上一次打开工程时的状态甚至可能连中间临时文件都写坏了。解决每个阶段后立即doc.save()这是最直接的后悔药。同时在构建密集点云之前打印当前可用内存提前判断会不会溢出。如果内存吃紧把quality降一档或者把大 chunk 按影像号拆成几个小 chunk 分别处理最后再合并。不要迷信“多任务并发”能提高吞吐几个大 chunk 同时跑密集云内存互相争抢翻车概率更高。5.2 现象对齐完成后地图上的相机位置乱飞整个测区杂乱无章这个现象在数据量大时尤其吓人全景视图里几十台相机散落在多个位置像四周散出去的碎片。原因最常见的根因是camera_location_accuracy设得太小算法过度信任 GNSS 位置而实际照片自带坐标误差较大导致解算时带着错误约束跑偏。另一个常见根因是影像 POS 文件里坐标系统写混了用了经纬度但工程里按投影坐标理解或者反过来。解决先把精度向量放大到米级比如[3.0, 3.0, 5.0]重新对齐看结果是否收敛。如果还飞就需要回到原始 POS 文件检查坐标格式经纬度通常以十进制度数出现投影坐标则是以米为单位的大数。还有一种情况是无人机航向角方向定义不一致导致旋转矩阵初值偏差过大这种情况只能在数据采集时避免后期很难自动修复。5.3 现象正射影像里出现大量拼接缝和色块断层运行完正射影像构建打开 TIF 看到明显的接边亮度差异局部区域甚至出现几何错位。原因不少情况下是没有选择和拼接融合方式用了默认的按视角混合导致影像边缘曝光差异直接暴露也可能是原始影像存在明显曝光不一致又没有做色彩校正。解决构建正射时明确指定blendingMetashape.MosaicBlending同时开启fill_holes。如果原始影像曝光差异显著先对照片做色彩校正这一步在脚本里对应调用 chunk 的色调均衡方法。我的习惯是原始数据一进来就统一做一次色彩校正再进对齐流程既让正射好看也提升匹配稳定性。5.4 现象GPU 利用率很低CPU 却跑满处理速度没有比纯 CPU 快多少使用独立进程在 GPU 服务器上跑重建发现显卡利用率只有二三十个百分点风扇都不怎么转。原因Metashape 的深度重建是 CPU 和 GPU 混合并行的。GPU 负责深度图估计但显存不足时大量计算会回落 CPUGPU 只能断续工作。另一个原因是脚本没有把 GPU 设备列表正确传进去尤其是多卡机器上默认配置可能根本没启用目标显卡。解决批处理前用Metashape.app.settings确认 GPU 是否被正确识别和启用把不参与计算的显卡排除掉。显存大小直接决定能扛的质量档位8GB 显存跑 24MP 影像的HighQuality密度图会比较吃力降到Medium会更稳。CPU 跑满这件事本身不一定是坏事但 GPU 利用率过低时优先怀疑显存瓶颈和数据传输瓶颈而不是 Metashape 没有调用显卡。5.5 现象独立进程运行时报 “Metashape is not licensed” 或找不到授权脚本在 GUI 里跑得好好的放到命令行独立执行就报授权错误。原因独立进程和 GUI 共享同一份 license 配置但浮动授权、环境变量、当前用户权限都会影响运行态下的许可可见性。如果服务端授权的机器绑定列表里没有当前机器独立进程自然拿不到授权。解决先在 GUI 里确认软件能正常打开并处理数据排除基础授权问题。再检查启动独立进程的用户身份和环境变量确保和 GUI 一致。最后跑一个最小脚本验证授权加载比如只打开一个空文档再退出。如果用的是浮动授权确认 license server 地址和端口在独立进程环境下也能访问。这个问题排查起来最枯燥但它一旦发生整批任务都会卡在第一步。6. 进阶技巧把脚本改造成带阶段断点和质检的批处理框架做几轮批量生产之后我逐渐把脚本从“流水账式”改成“框架式”每个处理阶段做成独立函数返回关键指标并落一份 JSON 报告。这样当一批十个测区里有三个失败时不需要逐个人工盯控制台看 JSON 就知道卡在哪一步、指标差多少。一个精简版骨架import Metashape, sys, json def stage_align(chunk): chunk.alignPhotos( accuracyMetashape.HighAccuracy, keypoint_limit60000, tiepoint_limit4000 ) ok sum(1 for c in chunk.cameras if c.transform) return {align_rate: round(ok / len(chunk.cameras), 3)} def stage_dense(chunk, quality): chunk.buildDenseCloud( qualityquality, filterMetashape.MildFiltering ) return {points: len(chunk.dense_cloud.points)} def stage_ortho(chunk, resolution): chunk.buildOrthomosaic( surface_dataMetashape.ModelData, blendingMetashape.MosaicBlending, resolutionresolution ) return {ortho_size: chunk.orthomosaic.width} def main(): doc Metashape.Document() doc.open(sys.argv[1]) chunk doc.chunk report {} report[align] stage_align(chunk) doc.save() report[dense] stage_dense(chunk, Metashape.MediumQuality) doc.save() report[ortho] stage_ortho(chunk, 0.05) doc.save() print(json.dumps(report, indent2)) if __name__ __main__: main()每个 stage 之后的doc.save()依然是核心它让你随时可以止损即使后续阶段失败前面的成果都还在重新跑只需要从失败处继续。跑完一批后把各测区的 JSON 汇总成一张表来检查对齐成功率低于 95% 的测区优先怀疑照片重叠度和影像质量密集点云点数远小于同区域平均水平的回去看滤波参数是不是设太猛正射影像尺寸和测区面积明显不匹配的检查坐标系设置是否有误。这个习惯帮我挡掉过好几次“看起来跑完了、实际数据不能用”的返工。脚本化的真正价值不是省掉那几次点击而是让每一次处理的参数和结果都有据可查、可以复现。希望帮到你。本文还有配套的精品资源点击获取