企业官网建设流程全解析

简介：面向 Metashape Professional 用户的 Python API 参考手册，适合需要以脚本自动化摄影测量流程、批量管理项目数据或进行二次开发的初中级开发者。包内共 1 个 PDF 文件，约 1.16MB，按概览、应用模块、API 变更日志和 Python 模块索引编排，便于按类名与函数检索。内容围绕核心 Document 类展开，说明项目打开保存、chunk 与相机/标记增删、相机校准和地理投影设置，并覆盖照片对齐、密集云、网格、UV、纹理、模型简化及模型/DEM/正射影像导出等处理接口，也涉及网络处理任务的启动与控制。已有 304 人学习，可作为查阅型资料配合实际脚本调试和流程封装使用。

1. 从一堆重复点击里脱身：MetaShape Python API 1.8.2 能接管什么

接手一个三千张航片的建模项目，真正消耗时间的往往不是显卡跑得慢，而是同一套对齐、深度图、纹理参数在界面上重复点二十遍。MetaShape Python API 1.8.2 解决的就是这件事——它是 Metashape Professional 内嵌的 python 脚本接口，把工程读写、相机与标记管理、空三对齐、稠密重建、建模、纹理、正射与 DEM 导出全都暴露成可调用的类和方法。反直觉的一点是，它不是一套装在系统里的独立第三方库，脚本必须跑在 Metashape 进程内部，官方指定 Python 3.8 作为脚本引擎，而且只在 Professional 版生效。这份参考手册就是它的完整方法索引，适合每天要重复跑同类测区的作业人员，也适合想把重建流程接进自动化管线的开发者。读它的正确姿势不是从头背到尾，而是先弄清对象模型，再拿一条流水线跑通，最后把参数表和踩坑点贴在手边。

2. 三层对象模型拆开看：Document、Chunk、Camera 与三个脚本入口

拿到手册先别急着翻方法列表，最容易翻车的地方反而在最前面：很多人默认Metashape.app.document永远有值，脚本一上命令行就报NoneType。先把对象模型捋顺，后面的参数调试才有落脚点。整个 API 的结构其实很朴素，Document 是工程，Chunk 是工程里的测区，Camera 和 Marker 是测区里的基本单元，剩下的 Model、DenseCloud、TiledModel、Orthomosaic 都挂在 Chunk 下面，靠 Chunk 的方法生成。

2.1 三个执行入口的适用边界

手册概览里列了三种跑脚本的方式，它们不是随便挑一个都行，各自的失效场景差别很大。

第一种是界面的 Console 面板，把它当标准 Python 交互环境用。这是调参阶段最有效的手段，改一行跑一行，随时能print(chunk.cameras[0].transform)看中间状态。缺点是进程一关全都清零，而且交互环境下Metashape.app.document天然指向当前打开的工程，容易养成依赖，等切到命令行才发现代码里到处是隐式假设。

第二种是 Tools 菜单里的 Run script，选一个.py文件执行。适合把调好的脚本交给不熟悉命令行的同事，点两下就能跑。缺点是执行完变量全丢，出错只弹一个 messageBox，没有堆栈细节，排查全靠事先写日志。

第三种是命令行-r参数，适合批处理和无人值守。这是唯一能接进定时任务或外部调度系统的方式，但也是最容易出问题的：

# 用安装目录下的可执行程序启动，-r 后面跟脚本路径 # 路径里带空格时一定要加引号，否则会被拆成多个参数 "C:/Program Files/Metashape Pro/metashape.exe" -r "D:/scripts/batch_build.py" # 跑批之前建议先手动执行一次，确认脚本里没有依赖界面的弹窗函数 # 需要完全不显示主窗口时，用哪个启动参数以本机安装目录下的命令行帮助为准

这段命令的关键在于后两点。-r是同步执行的，脚本里每一条指令都会按顺序跑完，中途出错进程直接退出，不会有交互提示。所以批处理脚本里绝不能出现getOpenFileName、getSaveFileName、getCoordinateSystem这类会弹窗的函数，它们在无界面环境下要么返回空字符串，要么把进程挂在那里等一个永远不会有人点的按钮，这是黑匣子式卡死最常见的来源。

提示：调参用 Console，交付给同事用 Run script，接自动化用命令行-r。不要试图用一套代码同时满足三个场景，代价是到处写兼容分支。

2.2 Document 与 Chunk 的引用关系

Metashape.app.document指向界面里当前打开的那个工程，它是一个属性而不是方法，没有括号。在 Console 里它几乎总是可用的，但在独立脚本里，尤其是启动瞬间就执行的那种，它可能是空的。稳妥的写法是自己创建 Document 实例再打开文件：

import Metashape doc = Metashape.Document() doc.open(r"D:/projects/survey_01.psz") # 传工程文件，不要传图片目录 # 一个工程里可以有多个 chunk，界面上叫"块"，通常按测区或按批次分 for chunk in doc.chunks: print(chunk.label, len(chunk.cameras), len(chunk.markers)) # doc.chunk 只是 doc.chunks[0] 的简写 # 多测区工程里把它当全局用，是很多"为什么参数改了没生效"的来源 chunk = doc.chunks[0]

doc.open接受的是.psz或.psx工程文件，前者是打包压缩格式，后者是带外部数据目录的格式。如果一个工程是从别的机器上拷过来的，.psx更容易出现相对路径找不到素材的情况，手册里 Settings 类的project_absolute_paths就是控制这个行为的开关。Chunk 上能拿到的东西很杂，cameras、markers、crs、meta、transform，以及各个重建结果的引用，绝大多数处理逻辑都是在 Chunk 这一层展开的。

2.3 相机对象与对齐状态的自检

Camera 这一层最值得先掌握的是两个属性：transform和reference。前者是 4x4 变换矩阵，空三没对齐时它是None；后者是外业给的参考坐标，包含location、accuracy，有 GPS 或 IMU 数据时才有意义。判断一条流水线是否健康，第一步永远是数对齐率：

import Metashape doc = Metashape.Document() doc.open(r"D:/projects/survey_01.psz") chunk = doc.chunks[0] # 对齐成功的相机 transform 是矩阵，失败的是 None aligned = [c for c in chunk.cameras if c.transform is not None] print("total=%d aligned=%d rate=%.1f%%" % (len(chunk.cameras), len(aligned), 100.0 * len(aligned) / max(len(chunk.cameras), 1))) # 相机内参挂在 calibration 上，后面校正畸变要用 cam = chunk.cameras[0] print("f=%.3f cx=%.3f cy=%.3f" % (cam.calibration.f, cam.calibration.cx, cam.calibration.cy)) # 保存时给一个新路径，避免覆盖原始工程 doc.save(r"D:/projects/survey_01_check.psz")

doc.save()不带参数会覆盖当前工程路径，doc.save(path)是另存。手册里 Calibration 的f、cx、cy单位都是像素而不是毫米，这一点从外业标定文件导进来时经常被搞混，后面第 4 章会专门说。这段脚本的价值在于它是所有批处理的地基——先能稳定打开工程、数清对齐率、另存副本，再往上加处理步骤才不会一错全错。

3. 对齐到纹理的八步流水线：downscale、filter_mode、texture_size 怎么给值

手册 Application Modules 开头的示例给了一条完整的处理链，从matchPhotos一路到buildTexture，看起来是照着抄就行，实际上每个参数背后都对应一次时间和质量的取舍。这套流水线在 1.8.2 里的顺序是固定的：特征匹配、空三、深度图、稠密点云、网格、UV、纹理，中间任何一步失败，后面的结果都是垃圾。参数给的保守，跑一晚上出不来；给激进了，显存打爆或者模型糊成一片。

3.1 matchPhotos 与 alignCameras：先粗后细的两轮策略

matchPhotos的参数里最重要的是downscale。它控制特征提取时的降采样倍数，手册里的示例写的是 1，配合generic_preselection=True和reference_preselection=False。这几个取值的含义是：

我的习惯是先跑一轮downscale=4看对齐率，一千张影像大概十几分钟就能出结果。如果对齐率低于八成，问题多半出在重叠度不够或者弱纹理区域，这时候应该回去补拍或者加地面标记点，而不是把 downscale 降到 0 硬算——降下去只会让本来匹配不上的地方算得更久，结果不会变好。

alignCameras()本身没有多少可调参数，它依赖上一步产生的连接点做光束法平差。这一步失败几乎总是匹配点不够，报错信息通常很含糊，所以一定要在它之后立刻统计transform is not None的比例，别等到建完深度图才发现一半相机是空的。

import Metashape doc = Metashape.Document() doc.open(r"D:/projects/survey_01.psz") chunk = doc.chunks[0] # 有参考坐标才开 reference_preselection，没有就是 False has_reference = any(c.reference.location is not None for c in chunk.cameras) # 第一轮用 4 快速评估，reset_alignment 保证不会混入旧连接点 chunk.matchPhotos(downscale=4, generic_preselection=True, reference_preselection=has_reference, reset_alignment=True) chunk.alignCameras() aligned = sum(1 for c in chunk.cameras if c.transform is not None) print("align rate: %.1f%%" % (100.0 * aligned / len(chunk.cameras)))

reset_alignment=True这个参数值得单独说一句。不加它的时候，重跑matchPhotos会在原有连接点上继续叠加，跑第二轮、第三轮之后连接点数量虚高，平差结果反而更差，这种玄学问题查起来非常费劲。

3.2 buildDepthMaps 与稠密点云：显存和质量的平衡点

深度图这一步是整个流程里显存消耗最大的，downscale直接决定峰值占用。手册示例用的是downscale=4配Metashape.AggressiveFiltering。filter_mode的四个取值对应不同的深度图平滑策略：

• NoFiltering：保留原始深度，噪声最多，适合后续要自己做滤波的场景
• MildFiltering：轻度平滑，弱纹理区域会出现明显的块状伪影
• ModerateFiltering：日常默认，大多数航拍场景够用
• AggressiveFiltering：强平滑，适合大面积水体以外的规则场景，代价是细节边缘被磨掉

我一般的取值是 8G 显存用downscale=4配ModerateFiltering，16G 以上才敢放到 2。这个数字不是绝对的，跟影像分辨率和重叠度都有关，但有一条经验可靠：显存不够时程序会直接抛错退出，不会自动降级，所以宁可先按 4 跑一遍确认能过，再逐级往下试。

buildDepthMaps之后是buildDenseCloud，参数主要是point_colors和point_confidence：

# 深度图，reuse_depth=False 时强制重算；改纹理参数重跑时设 True 能省一半时间 chunk.buildDepthMaps(downscale=4, filter_mode=Metashape.ModerateFiltering, reuse_depth=False) # 稠密点云，point_confidence 会额外生成一列置信度，代价是文件变大 chunk.buildDenseCloud(point_colors=True, point_confidence=True)

如果在新版本里执行到buildDenseCloud提示方法不存在，常见做法是换成buildPointCloud，两者的参数名基本对得上，只是返回的点云对象类型有差异。这一步产出的点云可以直接导出，也可以继续往下建网格。

3.3 buildModel、buildUV 与 buildTexture：三类参数的耦合

建网格这一步参数最少但影响最大。surface_type选Metashape.Arbitrary是任意曲面，适合建筑物、雕塑这类有垂直面的对象；选HeightField是高度场，速度快很多，但只适合地形类数据。interpolation控制孔洞填充策略，EnabledInterpolation会把小洞补上，DisabledInterpolation保持原样，Extrapolated会向外延伸，后者在数据边缘容易造出不存在的地形。

buildUV的mapping_mode决定了纹理怎么铺。GenericMapping是通用映射，质量最好也最慢；OrthophotoMapping和AdaptiveOrthophotoMapping适合近似平面的地形数据，速度快；SphericalMapping用于球面或圆柱状对象。

buildTexture的blending_mode和texture_size需要一起看：

手册示例用的是 4096 配MosaicBlending，这个组合在 1.8.2 上是最稳的起点。8192 在多数独显上没问题，16384 基本只能配合大显存卡，而且导出文件会大到不方便传输。

3.4 把八步串成一份可重跑的批处理

把所有参数落成一个脚本，关键是把可变量抽到文件头部，改参数不用翻代码中间。下面这份脚本的每一步都对应上面讨论的取舍：

import Metashape PROJECT_IN = r"D:/projects/survey_01.psz" PROJECT_OUT = r"D:/projects/survey_01_built.psz" ALIGN_DOWNSCALE = 4 # 先粗后细，第一轮用 4 DEPTH_DOWNSCALE = 4 # 显存 8G 的安全值 TEXTURE_SIZE = 8192 # 4096 保稳，8192 需要 6G 以上显存 doc = Metashape.Document() doc.open(PROJECT_IN) chunk = doc.chunks[0] # 1) 特征匹配 + 2) 空三 chunk.matchPhotos(downscale=ALIGN_DOWNSCALE, generic_preselection=True, reference_preselection=False, reset_alignment=True) chunk.alignCameras() # 对齐率不达标就别往下跑了，后面的结果没有意义 aligned = [c for c in chunk.cameras if c.transform is not None] if len(aligned) < 0.8 * len(chunk.cameras): raise RuntimeError("对齐率过低: %d/%d" % (len(aligned), len(chunk.cameras))) # 3) 深度图 4) 稠密点云 chunk.buildDepthMaps(downscale=DEPTH_DOWNSCALE, filter_mode=Metashape.ModerateFiltering, reuse_depth=False) chunk.buildDenseCloud(point_colors=True, point_confidence=False) # 5) 网格 6) UV 7) 纹理 chunk.buildModel(surface_type=Metashape.Arbitrary, interpolation=Metashape.EnabledInterpolation, face_count=Metashape.HighFaceCount) chunk.buildUV(mapping_mode=Metashape.GenericMapping) chunk.buildTexture(blending_mode=Metashape.MosaicBlending, texture_size=TEXTURE_SIZE) # 8) 另存，不覆盖原始工程 doc.save(PROJECT_OUT)

这份脚本里加了一个对齐率闸门，低于 80% 直接抛异常终止。这条判断省下的时间比任何参数优化都多——一条跑三小时的流水线，如果在第二步就该停，多跑的两小时五十分钟全是浪费。face_count用HighFaceCount是在模型精度和体积之间取了偏精度的值，如果只需要做正射影像，用MediumFaceCount能省不少时间。

4. GPU 位掩码与坐标系：脚本里最容易被忽略的两个隐性故障源

流水线跑通之后，剩下的问题往往不是参数，而是环境。手册里 Application 类的篇幅不大，但 GPU 配置和坐标系设置踩坑的概率远高于处理步骤本身，因为它们的表现通常是"结果看起来没问题，但对不上"，比直接报错难查得多。

4.1 gpu_mask 的位运算与 CPU 回退

gpu_mask是一个整数，手册里明确写了按位解释：值为 1 时启用设备 0，值为 5 时启用设备 0 和设备 2。这个设计在多卡机器上很容易配错，因为 5 不是"第五张卡"，而是1 | 4的二进制组合。

import Metashape # 枚举可用设备，返回顺序就是从 0 开始的编号 devices = Metashape.app.enumGPUDevices() for i, dev in enumerate(devices): print(i, dev) # 设备 0 -> 1，设备 1 -> 2，设备 2 -> 4 # 只用编号 0 和 2，掩码是 1 | 4 = 5 Metashape.app.gpu_mask = 1 | 4 # 关掉 CPU 参与计算；显存不足时不会自动回退，会直接抛错 Metashape.app.cpu_enable = False

把cpu_enable设成False是一把双刃剑。好处是避免深度图阶段 CPU 和 GPU 抢内存带宽，速度更稳定；坏处是显存一旦不够就直接失败，没有降级路径。我的做法是批处理固定关 CPU，因为失败能立刻发现，比跑到一半速度莫名变慢好排查得多。如果一批任务要跑通宵没人盯，那就保持cpu_enable = True，牺牲一点速度换成功率。

gpu_mask是应用级设置，改一次对之后所有 chunk 都生效。但在同一个进程里切换掩码时要注意，已经提交的后台任务不会重新分配，必须等它结束或者task.cancel()之后再改。

4.2 chunk.crs 的赋值顺序

坐标系这一块最典型的翻车是赋值顺序。手册里 Application 类提供了getCoordinateSystem(label, value)弹窗选坐标系，示例代码把它直接赋给doc.chunk.crs然后保存。这个写法在交互环境里没问题，但不能进批处理。脚本里应该直接构造：

import Metashape doc = Metashape.Document() doc.open(r"D:/projects/survey_01.psz") chunk = doc.chunks[0] # 直接构造，避免弹窗；EPSG 编码写死，脚本才能无人值守 chunk.crs = Metashape.CoordinateSystem("EPSG::32650") # 坐标系必须在写相机参考坐标之前定好 # 顺序反了，参考坐标会被当成工程局部坐标处理，成图位置整体偏移 for cam in chunk.cameras: ref = cam.reference if ref is not None and ref.location is None: ref.location = Metashape.Vector([500000.0, 3000000.0, 120.0])

chunk.crs赋值之后，工程内的所有坐标解释方式都跟着变，包括地面控制点、相机参考坐标、导出的 DEM 和正射影像。顺序搞反的后果不是报错，而是成果整体平移几十公里，而且从界面上看不出任何异常。这种问题只能靠导入前后比对一个已知点的坐标来发现。

4.3 Calibration 对象的读写与投影校验

相机内参在手册里是独立的一节，因为畸变模型的参数不少。常用的字段整理如下：

project和error这两个方法是校验外参的利器。拿一个已知地面控制点，用它的物方坐标反投到某张影像，再跟图上实际像素位置比，误差超过几个像素就说明这一带的外参有问题：

import Metashape chunk = Metashape.app.document.chunk cam = chunk.cameras[0] calib = cam.calibration # 覆盖内参前先读一遍原值，方便对比 print("before f=%.3f cx=%.3f cy=%.3f" % (calib.f, calib.cx, calib.cy)) # 从外业标定文件重新导入，format 省略时默认按 XML 解析 calib.load(r"D:/calib/camera_01.xml", Metashape.CalibrationFormatXML) cam.calibration = calib # 反投影校验：物方点 -> 像素，和人工量测的像素坐标比对 proj = calib.project(Metashape.Vector([500123.4, 3000456.7, 88.2])) print("projected pixel: %.2f, %.2f" % (proj.x, proj.y))

内参导入之后必须重新做一次空三，否则已有的连接点还是按旧内参解出来的，两者对不上。这条经验吃过一次亏：只换内参不重跑对齐，模型精度反而比换之前更差。

5. 翻车现场复盘：五个必须提前知道的报错与处置

手册是参考文档不是故障手册，它告诉你每个方法有什么参数，但不告诉你参数配错时程序会以什么姿势倒下。下面这几条都是实际跑批过程中反复遇到的，按现象、原因、解决三段写，遇到时可以直接对照。这些问题的共同点是报错信息都很含糊，光看日志基本定位不到，必须知道往哪看。

5.1 命令行跑脚本秒退，日志只有一行 import 报错

现象：用-r启动脚本，进程一闪而过，日志里只有ModuleNotFoundError: No module named 'Metashape'，但在界面 Console 里同样的import Metashape完全正常。

原因：脚本被系统的 Python 解释器执行了，而不是被 Metashape 内嵌的 3.8 引擎执行。手册概览里写得很清楚，脚本引擎是应用内置的，不存在一个可以pip install的 Metashape 包。

解决：确认启动命令用的是 Metashape 自己的可执行文件加-r，脚本路径作为它的参数，而不是python script.py。如果是在 IDE 里调试，把解释器指向应用安装目录下的运行时，或者干脆退回 Console 面板调试，调好再交给命令行。

5.2 Console 里逐行敲没问题，整段跑就卡住不动

现象：把调试好的十几行代码存成文件执行，界面失去响应，进度条不动，任务管理器里进程还在但 CPU 占用接近零。

原因：脚本里混进了弹窗类函数。getSaveFileName、getOpenFileName、getCoordinateSystem、getInt这些在交互环境里会弹出对话框等人点，在批处理或非前台执行时没人点，进程就一直等。另一种可能是长循环里没有调用Metashape.app.update()，界面不刷新，看起来像卡死其实还在算。

解决：把所有弹窗函数抽到独立的交互分支里，用命令行参数或配置文件控制；纯批处理路径上只留硬编码路径。长循环里每隔若干次迭代插一次Metashape.app.update()，只是刷新界面，不影响计算逻辑。

5.3 buildDepthMaps 跑到一半进程消失，内存见底

现象：深度图阶段跑到 60% 左右进程直接消失，没有任何异常堆栈，系统日志里能看到内存耗尽记录。

原因：downscale给得太小，单张深度图的显存和内存占用随影像分辨率平方增长；或者一个进程里同时处理多个 chunk，每个 chunk 的中间结果都留在内存里。

解决：先按downscale=4跑通一轮，再往下试 2。多 chunk 批处理时用循环逐个处理，每处理完一个就把中间结果导出并释放引用，不要一股脑塞在同一个进程里。Linux 下可以调用Metashape.app.releaseFreeMemory()主动回收，Windows 上这个调用没有效果，只能靠控制单个任务的数据量。

5.4 对齐率只有三成，剩下的相机 transform 全是 None

现象：matchPhotos和alignCameras都正常返回，没有报错，但统计下来只有三成相机对齐成功。

原因：downscale给得太大导致特征点太少；generic_preselection在重复纹理场景（比如大面积水面、成排的同类建筑）会匹配出大量错误连接；或者reference_preselection开着但参考坐标精度太差，预选阶段就把正确的匹配对排除了。

解决：把downscale降到 1 或 0 重跑一轮，同时确认reset_alignment=True清掉上一轮的脏数据。重复纹理场景不要指望自动匹配，加人工标记点（markers）并给定坐标，然后开reference_preselection让位置信息参与约束。参考坐标精度差的时候必须把reference_preselection关掉，宁可慢也不能错。

5.5 同样的代码换一个版本就报方法不存在

现象：脚本在一个旧版本工程上跑得好好的，换到 1.8.2 之后某个build*方法报AttributeError。

原因：手册末尾有一节专门记录 API 变更，处理类的方法在不同版本间会重命名或合并，旧的调用方式不会一直保留。这类变更不会在运行前提示，只在调用到那一刻才炸。

解决：升级前先把手册的变更记录当 diff 清单过一遍，用脚本里出现过的方法名去对照搜索，把被重命名的方法提前替换掉。拿不准新方法叫什么的时候，在 Console 里用dir(chunk)直接看当前版本暴露了哪些名字，比翻文档快。

注意：这五条里有三条的根因都不在 API 本身，而在运行环境。所以拿到一份新脚本，先确认执行入口、再确认内存预算、最后才调参数，顺序反了会白折腾很久。

6. 收尾自检：用 captureView 和变更记录给脚本上最后一道锁

流水线跑通不代表成果可信，尤其是无人值守跑了一整晚的那批任务，第二天早上看到一堆输出文件，第一个问题永远是"它到底算成什么样了"。手册里 ModelView 和 OrthoView 的captureView提供了一个成本极低的自检手段：在脚本末尾截一张模型视图存档，跟上一批次的截图并排一比，模型坍缩、纹理大面积缺失、位置整体偏移这几类问题一眼就能看出来。

import Metashape # captureView 只能在带界面的进程里用，纯命令行批次里拿不到有效图像 # 所以它适合放在每日构建的最后一步，而不是生产批处理的中途 view = Metashape.app.model_view img = view.captureView(width=1600, height=900, transparent=False, hide_items=False) if img is not None: img.save(r"D:/reports/model_preview.png")

四个参数里hide_items值得注意，设成False时截图会带上坐标轴、相机视锥这些辅助元素，做交付物要设True保持干净。transparent只在需要贴图到别处时开。这个方法返回的是 Image 对象，不是直接落盘，所以要自己调save。OrthoView 的用法完全一致，只是换成了正射视图，做 DEM 和正射成果的批次可以用它留档。

另一个自检动作是维护一张迁移检查表。手册末尾的变更记录按版本罗列了新增、重命名、废弃的接口，把它当成升级前的必查项：

那张表我一般贴在脚本文件头部当注释，改一次版本就打一次勾。有一回换了版本之后filter_mode的枚举名没变但可选值少了一个，脚本里写死的常量跑到那一行才抛异常，前面已经烧了两个多小时。从那以后我每次升级版本，都强制走一遍「小测区跑通全链路 + 变更记录逐条对照 + 截图比对」，三步加起来不到二十分钟，但能把整晚的返工挡在门外。希望帮到你。

本文还有配套的精品资源，点击获取