企业官网建设流程全解析

简介：这份PDF面向使用 Metashape Professional 进行摄影测量与三维重建的开发者，系统讲解其 Python API 1.82 的调用方式与核心模块，适合已具备 Python 基础、希望将建模流程自动化的中高级用户。文档围绕 Metashape 模块展开，涵盖 Document 类与项目数据的检查操作，并说明通过控制台、运行脚本命令及命令行参数执行脚本的三种途径，同时给出照片对齐、密集云构建、建模、纹理化、模型简化与成果导出等处理步骤的接口说明，附有完整示例代码演示从加载项目到保存结果的流程。资源包仅含 1 个 PDF 文件，大小约 1.16MB，便于随身查阅与检索。目前已有 311 人学习，可作为脚本开发时的常备参考手册，帮助读者快速定位类与函数用法、理解 API 变更脉络，减少在自动化处理流程中的试错成本。

1. 拿到这份 1.82 参考手册，先搞清楚它能替你省掉哪些手工活

如果你正在用 Metashape Professional 做航测或近景建模，手上有一批项目要按同一套参数跑完对齐、稠密、网格、纹理，那这份 1.82 版 Python API 参考手册就是给你准备的。它不是教程，是一本把Metashape模块里每个类、每个方法、每个枚举值摊开给你看的工具书，配合 Python 3.8 脚本引擎，能把软件里点鼠标的流程改成一行命令跑完。我见过太多人把项目文件一个个打开、手动点对齐、等进度条、再点保存，一天下来跑不了几个区块。这份文档的价值在于：它把Document、Chunk、Camera、Calibration这些对象的属性和方法列清楚，你照着写脚本，批处理、参数扫描、结果导出都能自动化。适合已经会用 Metashape 界面、想往脚本化走的人，也适合刚接手一批历史项目、需要统一重跑流程的从业者。下面我按“先跑通一条链路、再拆模块、最后避坑”的顺序，把这份手册里真正用得上的部分拆开讲。

2. 从 Document 到 Chunk：把一条完整处理链路写成脚本

2.1 为什么先啃 Document 和 Chunk 这两个对象

整份 API 的入口就两个东西：Metashape.app.document拿到当前打开的项目，或者自己Metashape.Document()新建一个。手册里明确写了，Document代表一个 Metashape 项目，可以同时存在多个实例，这意味着你可以在一个脚本里开多个项目做对比处理。Document下面挂的是chunk，一个项目可以有多个 chunk，每个 chunk 独立保存照片、对齐结果、稠密云、网格。实际写批处理时，最常见的结构就是：遍历目录下的.psz文件，逐个doc.open()，取doc.chunk，跑处理链，doc.save()。这里有个容易忽略的点：doc.chunk返回的是当前激活的 chunk，如果你的项目里有多个 chunk，得用doc.chunks列表按索引或标签取，不然脚本会一直只处理第一个。手册里Document类还提供了addChunk()、remove()这些方法，做多区块管理时用得上。

2.2 一条可复现的处理链：对齐、稠密、网格、纹理

手册第 2 章开头给了一段示例，基本就是标准处理链的骨架。我把它补成能直接跑的版本，加了路径参数和异常处理：

import Metashape import os # 项目路径和输出路径按实际改 project_path = r"D:\projects\site_a.psz" output_dir = r"D:\projects\out" doc = Metashape.Document() doc.open(project_path) chunk = doc.chunk # 1. 照片对齐：downscale=1 表示不降采样，精度最高但最慢 chunk.matchPhotos(downscale=1, generic_preselection=True, reference_preselection=False) chunk.alignCameras() # 2. 构建深度图：downscale=4 是速度与质量的折中 chunk.buildDepthMaps(downscale=4, filter_mode=Metashape.AggressiveFiltering) # 3. 稠密云 chunk.buildDenseCloud() # 4. 网格：Arbitrary 适合非平面物体，地形类可换 HeightField chunk.buildModel(surface_type=Metashape.Arbitrary, interpolation=Metashape.EnabledInterpolation) # 5. UV 和纹理 chunk.buildUV(mapping_mode=Metashape.GenericMapping) chunk.buildTexture(blending_mode=Metashape.MosaicBlending, texture_size=4096) doc.save()

这段代码的逻辑很直白：matchPhotos做特征提取和匹配，alignCameras解算相机位姿，buildDepthMaps为每个相机生成深度图，buildDenseCloud融合成稠密点云，buildModel重建网格，buildUV展开纹理坐标，buildTexture烘焙纹理。参数上，downscale是最影响耗时的一个，对齐阶段设 1 意味着用原图分辨率，照片多的时候会非常慢，常见做法是先设 2 或 4 跑一遍看对齐质量，确认没问题再设 1 重跑。filter_mode选AggressiveFiltering会滤掉更多噪点，但薄结构（比如栏杆、树枝）容易丢，做建筑立面时我一般用MildFiltering。surface_type选Arbitrary是通用重建，选HeightField适合地形，后者内存占用小很多。texture_size设 4096 是常规选择，要出高清正射或近景细节可以上 8192，但显存和磁盘要跟上。

2.3 相机校准和地面控制点：脚本里怎么改

手册里Calibration类列了f、cx、cy、k1到k4、p1到p4、b1、b2这些参数，对应焦距、主点、径向畸变、切向畸变、仿射和非正交。实际项目里如果相机是固定型号、已经做过标定，可以在脚本里直接给chunk.sensors下的传感器赋校准值，省掉每次从文件导入。地面控制点这块，chunk.markers可以添加标记，配合Marker.projections把像素坐标和地面坐标关联起来，再调chunk.optimizeCameras()做平差。手册里Application类还提供了getCoordinateSystem()弹窗让用户选坐标系，做交互式脚本时可以用，但批处理场景下更稳的做法是直接给chunk.crs赋一个已知的CoordinateSystem对象，避免脚本卡在弹窗上等人点。

3. Application 与 Settings：把交互和全局配置管起来

3.1 Application 类不只是弹窗工具

很多人翻手册时把Application当成一堆getOpenFileName、messageBox的集合，其实它管的是全局状态。Metashape.app.version能拿到当前版本号，写兼容脚本时先判断版本再决定调哪个方法，比事后报错强。Metashape.app.gpu_mask是 GPU 设备位掩码，手册里写得很清楚：值 5 表示启用 0 号和 2 号设备。多卡机器上跑批处理，如果不显式设gpu_mask，Metashape 可能默认只用一张卡，或者把计算分到一张弱卡上拖慢整体。我一般会在脚本开头根据enumGPUDevices()返回的设备列表，按显存排序后设掩码，把弱卡排除掉。Metashape.app.cpu_enable控制 GPU 活跃时是否还用 CPU，默认是开的，某些深度图阶段关掉 CPU 反而更快，这个得按机器实测。

3.2 Settings 的读写和持久化

Settings类对应应用设置，load()和save()从磁盘读写，setValue(key, value)和value(key)按 key 存取。手册里列了几个关键项：project_absolute_paths控制项目文件里存绝对路径还是相对路径，做项目迁移时这个很关键，设成False用相对路径，整个项目文件夹拷到别的机器上不会因为盘符变了而丢图；project_compression是压缩级别，数值越大文件越小但保存越慢；log_enable和log_path控制日志写文件，批处理跑一晚上，第二天靠日志定位哪个项目在哪一步失败。这些设置在脚本里改完记得调save()，不然只对当前会话生效。有个细节：Settings的 key 是字符串，手册里没给完整 key 列表，实际用的时候可以先load()再遍历已知 key，或者直接查应用界面里对应选项的名称，别硬猜。

3.3 菜单项和界面更新：脚本也能挂到工具栏

addMenuItem(label, func, shortcut, icon)能在 Metashape 菜单里加自定义入口，把常用脚本挂上去，点一下就跑。addMenuSeparator加分隔线，removeMenuItem移除。做团队内部工具时，把批处理脚本挂成菜单项，比让每个人记命令行参数靠谱。Metashape.app.update()在长循环里要主动调，否则界面会假死，用户以为程序卡了就去强杀。手册里ConsolePane的clear()和contents可以用来清屏和读输出，调试脚本时把中间结果打到控制台，比写文件快。

4. 避坑与排查：脚本跑不通时先看这几条

4.1 报RuntimeError说项目打不开

现象是doc.open()直接抛异常，或者打开后doc.chunk是None。原因通常是路径里有中文或空格没转义，或者项目文件正被另一个 Metashape 实例占用。解决：路径统一用原始字符串r"..."，批处理前先确认没有别的进程锁着.psz；如果项目是从旧版本存的，先用界面打开另存一次再跑脚本，版本迁移的兼容问题让软件自己处理掉。

4.2 对齐结果为空或相机大量未对齐

现象是alignCameras()跑完，chunk.cameras里一堆transform是单位矩阵。原因多半是matchPhotos的generic_preselection和reference_preselection组合不对，或者照片本身重叠度不够。解决：先确认照片有 EXIF 坐标再开reference_preselection，没有坐标就只开generic_preselection；downscale设太大（比如 8）会导致特征点太少，先降到 2 试；实在不行在界面里手动对齐几张看质量，再回脚本调参数。

4.3 稠密云阶段显存爆掉

现象是buildDepthMaps跑到一半报内存或显存错误，进程直接退出。原因是downscale设太小（比如 1）加上照片分辨率高，深度图数量一多就撑爆。解决：深度图阶段downscale至少设 2，照片特别多时设 4；用gpu_mask把计算集中到显存最大的卡上；分块处理，把一个大 chunk 拆成几个子区域分别跑再合并。

4.4 纹理烘焙出来是黑的或者错位

现象是buildTexture完成后模型贴图全黑，或者 UV 明显错乱。原因通常是buildUV的mapping_mode和模型类型不匹配，或者网格有非流形结构。解决：GenericMapping是通用选项，但复杂模型可以试AdaptiveMapping；烘焙前先chunk.buildModel时开interpolation=EnabledInterpolation补洞；纹理尺寸别超过显卡支持的上限，4096 跑不通就先降到 2048 验证流程。

4.5 脚本在命令行-r模式下行为和界面里不一致

现象是同样的脚本，界面里跑正常，命令行-r跑就报错或结果不同。原因是命令行模式下没有界面上下文，Metashape.app.document可能是空的，弹窗类方法（getOpenFileName等）会直接返回空或阻塞。解决：命令行脚本一律用Metashape.Document()自己建实例，不依赖app.document；所有交互式取值改成从命令行参数或配置文件读；跑之前确认Metashape.app在无界面模式下可用，必要时用try/except包住界面相关调用。

5. 进阶用法：用 captureView 和批处理模板把出图也自动化

手册里ModelView和OrthoView的captureView(width, height, transparent, hide_items)是个容易被忽略的功能：它能把当前模型视图或正射视图直接截成Image对象，配合save()就能批量出预览图、出报告配图，不用再手动截图。实际用法是先设model_view_mode或ortho_view_mode选好显示模式（着色、线框、纹理），调captureView拿图，再存盘。做项目交付时，每个区块自动出一张纹理预览和一张线框预览，省掉大量重复劳动。

批处理模板我一般这么组织：一个config.py放路径、参数、GPU 掩码；一个run_batch.py遍历项目列表，每个项目跑完整链路，用try/except包住每一步，失败就记日志跳到下一个；日志里记项目名、步骤名、耗时、异常信息。参数扫描时把downscale、filter_mode、texture_size做成字典列表，外层循环参数组合，内层循环项目，输出目录按参数组合命名，跑完直接对比。这里有个血泪经验：批处理脚本一定要加“断点续跑”逻辑，每个项目处理完写一个标记文件，重跑时跳过已完成的，不然跑到一半崩了从头再来，一晚上白干。

验证方法上，我习惯先拿一个小项目（十几张照片）把整条链路跑通，确认每个输出文件都能正常打开、纹理没黑、点云密度合理，再放大项目。参数改动一次只动一个，改完对比前后结果，别一次调三个参数然后不知道是哪个起了作用。从那以后我每次写新脚本，都强制先用小数据集跑一遍全流程再上生产，这个习惯帮我省掉过好几次整批重跑。希望帮到你。

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