简介这份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 rD:\projects\site_a.psz output_dir rD:\projects\out doc Metashape.Document() doc.open(project_path) chunk doc.chunk # 1. 照片对齐downscale1 表示不降采样精度最高但最慢 chunk.matchPhotos(downscale1, generic_preselectionTrue, reference_preselectionFalse) chunk.alignCameras() # 2. 构建深度图downscale4 是速度与质量的折中 chunk.buildDepthMaps(downscale4, filter_modeMetashape.AggressiveFiltering) # 3. 稠密云 chunk.buildDenseCloud() # 4. 网格Arbitrary 适合非平面物体地形类可换 HeightField chunk.buildModel(surface_typeMetashape.Arbitrary, interpolationMetashape.EnabledInterpolation) # 5. UV 和纹理 chunk.buildUV(mapping_modeMetashape.GenericMapping) chunk.buildTexture(blending_modeMetashape.MosaicBlending, texture_size4096) 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_maskMetashape 可能默认只用一张卡或者把计算分到一张弱卡上拖慢整体。我一般会在脚本开头根据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_preselectiondownscale设太大比如 8会导致特征点太少先降到 2 试实在不行在界面里手动对齐几张看质量再回脚本调参数。4.3 稠密云阶段显存爆掉现象是buildDepthMaps跑到一半报内存或显存错误进程直接退出。原因是downscale设太小比如 1加上照片分辨率高深度图数量一多就撑爆。解决深度图阶段downscale至少设 2照片特别多时设 4用gpu_mask把计算集中到显存最大的卡上分块处理把一个大 chunk 拆成几个子区域分别跑再合并。4.4 纹理烘焙出来是黑的或者错位现象是buildTexture完成后模型贴图全黑或者 UV 明显错乱。原因通常是buildUV的mapping_mode和模型类型不匹配或者网格有非流形结构。解决GenericMapping是通用选项但复杂模型可以试AdaptiveMapping烘焙前先chunk.buildModel时开interpolationEnabledInterpolation补洞纹理尺寸别超过显卡支持的上限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做成字典列表外层循环参数组合内层循环项目输出目录按参数组合命名跑完直接对比。这里有个血泪经验批处理脚本一定要加“断点续跑”逻辑每个项目处理完写一个标记文件重跑时跳过已完成的不然跑到一半崩了从头再来一晚上白干。验证方法上我习惯先拿一个小项目十几张照片把整条链路跑通确认每个输出文件都能正常打开、纹理没黑、点云密度合理再放大项目。参数改动一次只动一个改完对比前后结果别一次调三个参数然后不知道是哪个起了作用。从那以后我每次写新脚本都强制先用小数据集跑一遍全流程再上生产这个习惯帮我省掉过好几次整批重跑。希望帮到你。本文还有配套的精品资源点击获取
简介这份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 rD:\projects\site_a.psz output_dir rD:\projects\out doc Metashape.Document() doc.open(project_path) chunk doc.chunk # 1. 照片对齐downscale1 表示不降采样精度最高但最慢 chunk.matchPhotos(downscale1, generic_preselectionTrue, reference_preselectionFalse) chunk.alignCameras() # 2. 构建深度图downscale4 是速度与质量的折中 chunk.buildDepthMaps(downscale4, filter_modeMetashape.AggressiveFiltering) # 3. 稠密云 chunk.buildDenseCloud() # 4. 网格Arbitrary 适合非平面物体地形类可换 HeightField chunk.buildModel(surface_typeMetashape.Arbitrary, interpolationMetashape.EnabledInterpolation) # 5. UV 和纹理 chunk.buildUV(mapping_modeMetashape.GenericMapping) chunk.buildTexture(blending_modeMetashape.MosaicBlending, texture_size4096) 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_maskMetashape 可能默认只用一张卡或者把计算分到一张弱卡上拖慢整体。我一般会在脚本开头根据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_preselectiondownscale设太大比如 8会导致特征点太少先降到 2 试实在不行在界面里手动对齐几张看质量再回脚本调参数。4.3 稠密云阶段显存爆掉现象是buildDepthMaps跑到一半报内存或显存错误进程直接退出。原因是downscale设太小比如 1加上照片分辨率高深度图数量一多就撑爆。解决深度图阶段downscale至少设 2照片特别多时设 4用gpu_mask把计算集中到显存最大的卡上分块处理把一个大 chunk 拆成几个子区域分别跑再合并。4.4 纹理烘焙出来是黑的或者错位现象是buildTexture完成后模型贴图全黑或者 UV 明显错乱。原因通常是buildUV的mapping_mode和模型类型不匹配或者网格有非流形结构。解决GenericMapping是通用选项但复杂模型可以试AdaptiveMapping烘焙前先chunk.buildModel时开interpolationEnabledInterpolation补洞纹理尺寸别超过显卡支持的上限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做成字典列表外层循环参数组合内层循环项目输出目录按参数组合命名跑完直接对比。这里有个血泪经验批处理脚本一定要加“断点续跑”逻辑每个项目处理完写一个标记文件重跑时跳过已完成的不然跑到一半崩了从头再来一晚上白干。验证方法上我习惯先拿一个小项目十几张照片把整条链路跑通确认每个输出文件都能正常打开、纹理没黑、点云密度合理再放大项目。参数改动一次只动一个改完对比前后结果别一次调三个参数然后不知道是哪个起了作用。从那以后我每次写新脚本都强制先用小数据集跑一遍全流程再上生产这个习惯帮我省掉过好几次整批重跑。希望帮到你。本文还有配套的精品资源点击获取
