Smart3D(ContextCapture)操作手册中文翻译7.SDK二次开发指南（ccmasterkernel’s documentation）

6.SDK二次开发指南（ccmasterkernel’s documentation）

本用户手册与ContextCapture MasterKernel SDK有关

作为ContextCapture MasterKernel SDK的一部分，ccMasterKernel是一个以编程方式访问ContextCapture Master所有功能的python模块。此模块代替用户界面，用于完整的项目创建、编辑和监控。

提醒：本文件中的信息如有更改，恕不另行通知，并按“原样”提供。Bentley对本材料不作任何形式的保证，包括但不限于对适销性和特定用途适用性的暗示保证。Bentley不对本文所包含的错误或与使用本材料有关的任何直接、间接、特殊、附带或后果性损害负责。

版权：Bentley Systems

6.1概述（Overview）

ccmasterkernel模块允许在一个简单的方式，通过Python脚本开发定制的基于ContextCapture的应用程序，自定义和/或自动3D重建过程。

API模块（应用程序编程接口）允许控制ContextCapture主项目（CCM文件）中使用的所有项：

项目（Project）：创建、保存、编辑、选项设置、树结构管理。

块（Block）：（Excel，XML导入以及导出（KML），XML，非约束的照片），分割，提取，照片/ 照片组（PhotoGroup）创建和编辑包括相机的三维属性和位置/旋转，控制点（三维位置、照片测量），连接点的创建和编辑。

AT（空中三角测量/ Aerotriangulation）：组件，定位模式,设置，任务提交，监测/控制，导出空三报告。

重建（Reconstruction）：空间框架（SRS，兴趣区域，瓦片分块），重建约束，参考三维模型，（导入导出retouches，匀色，处理设置，导出瓦片分割为kml。

生产（Production）：控制所有参数（用途，格式，选项，范围和定义），任务提交，监测/控制。

工作队列监测。

应用设置（Application Settings）：许可检查，软件的版本控制，在线更新。

二次开发API包括各种工具和数据交换（属性树，几何）测量运算。

6.2 安装（Installation）

从更新9（update 9）开始， python将被打包为一个wheel包。您可以在sdk/dist安装目录下找到*.whl文件。需要python 3.6 x64版本支持。

烈建议使用virtualenv和pip安装此软件包。

但是，仍然有一个ContextCapture SDK命令提示快捷方式，您可以使用它来创建virtualenv并在其中安装ccmasterkernel。

6.3 升级指南（Migration guide）

从更新9（update9）开始，包名不再是ccmasterkernelpy，而是*ccmasterkernel。您需要更新脚本，才能是你老的脚步可以在新版本下运行。如果不想全部更改，可以做如下替换：

把老命令

importCCMasterKernelPy

替换为：

importccmasterkernelasCCMasterKernelPy

作为一个小技巧

6.4教程

此简单脚本创建新的CCM项目，导入XML块定义，并保存项目：

importccmasterkernel

project=ccmasterkernel.Project()

project.setName('my project')

project.setProjectFilePath('D:/DATA/my project/my project.ccm')

project.importBlocks("'D:/DATA/block.xml")

project.writeToFile()

几个完整的示例将与包一起安装在python安装示例/目录中。

automaster.py

此脚本读取照片目录创建一个完整的重建（Reconstruction），它遵循整个工作流程（航空三角测量、重建和生产），并介绍了任务监控。

module_info.py

此脚本演示如何通过Python模块General面板的信息：许可证和功能、支持的生产（production）格式和选项等。

dump_project.py

此脚本从现有CCM项目中提取各种数据信息。

import_and_extract.py

此脚本演示了Aerial块导入、块提取和块导出的示例。

import_and_split.py

此脚本演示了Aerial块导入、块分割和块导出的示例。

import_txt.py

此脚本根据自定义文本块格式创建块

reconstruction_settings.py

此脚本在现有CCM项目中使用自定义设置创建新的重建。

6.5 API参考手册

6.5.1模块信息

获取模块的基本信息，无许可也可以访问。

version() → str

Returns 软件版本.

edition() → str

Returns 软件规格 (eg. Expert, Ultimate).

isLicenseValid() → bool

Returns True 许可有效.

如果许可无效，可以通过lastLicenseErrorMsg()获取许可详细信息

lastLicenseErrorMsg() → str

Returns 许可错误的信息.

6.5.2 项目（Project）

Project选项管理与ContextCapture处理的场景相关的所有数据。

创建空项目的示例：

project=ccmasterkernel.Project()

project.setName('my project')

project.setProjectFilePath('D:/DATA/my project/my project.ccm')

project.writeToFile()

类 MasterItem

类ProjectSRS

类ProjectSRSManager

类 Project

6.5.3块（block）

一个Block区块项目包含了一系列影像和属性，包括传感器尺寸、焦距、主点、透镜畸变以及位置和旋转等姿态信息，基于这些信息，可以建立一个或多个重建项目。

Block的定义如下：

照片（Photos）：导入或添加的照片及其相关的照片组属性和照片姿态（通过航空三角测量或导入计算）。通过块的照片组（photogroup）访问照片

点云（PointClouds）：导入的点云及其关联属性

控制点（Control points）：手工输入或导入。控制点是可选的。参见类：'ccmasterkernel.controlpoint'

连接点（Tie points）：由ContextCapture自动提取或导入。还可以输入用户连接点以帮助进行航空三角测量。

块类型（BlockType）：例如“Aerial”，可选选项

Reconstruction列表（List of reconstructions）：基于Block

创建Block的示例：

block = ccmasterkernel.Block(project)

project.addBlock(block)

forinputFile in inputFiles:

block.getPhotogroups().addPhotoInAutoMode(inputFile)

为了管理块的空三，可以创建专门用于调整的特殊块。对于这些块，附加一个AT对象来管理航空三角测量设置、处理和报告。

示例：

blockAT = ccmasterkernel.Block(project)

project.addBlock(blockAT)

blockAT.setBlockTemplate(ccmasterkernel.BlockTemplate.Template_adjusted, inputBlock)

坐标系：对于地理参考项目，在块级别，三维位置使用ECEF参考（EPSG:4978）。

6.5.4 照片（Photos）

管理照片集和关联的属性。通过照片组访问块的照片。

照片被分为一组或多组照片。均匀的一组照片，所有照片都是用同一个具有相同内部方向（图像尺寸、传感器尺寸、焦距等）的物理相机拍摄的。

如果照片是根据拍摄时使用的相机按子目录组织的，则ContextCapture可以自动确定相关的照片组。

6.5.5 空三（Aerotriangulation）

航空三角测量从输入块（Block）开始，生成具有计算或调整属性的新块。

航空三角测量可考虑当前摄像机位置（例如，从GPS初始化）或地理参考控制点。

示例：

blockAT = ccmasterkernel.Block(project)

project.addBlock(blockAT)

blockAT.setBlockTemplate(ccmasterkernel.BlockTemplate.Template_adjusted, block)

# submit aerotriangulation processing

blockAT.getAT().submitProcessing()

6.5.6 连接点（TiePoints）

一个连接点对应于两张或多张不同照片中的像素，其中这些像素表示场景中同一物理点的投影。ContextCapture可以在航空三角测量过程中自动生成大量的连接点。但是，用户连接点也可以预先输入，以帮助进行航空三角测量。

6.5.7 点云（PointClouds）

管理点云集和关联属性

6.5.8 重建（Reconstruction）

一个重建项目(Reconstruction)管理着一个三维重建框架（包含空间坐标系，建模区域，瓦片设置，处理设定等），基于一个重建项目可以建立一或多个生产任务。

Reconstruction的定义包含以下属性：

空间参考（Spatial framework）：定义空间参考系统（SRS）、感兴趣区域（ROI）和瓦片切割方式。

重建约束（Reconstruction constraints）：允许使用现有的三维数据来控制重建并避免重建错误

参考三维模型（Reference 3D model）：是重建沙盒，它以本机格式存储一个三维模型，随着生产进度逐步完成。该参考三维模型是应用了修饰和重建约束的模型，并从中派生出需要完成的生成。通过InternalTile对象访问参考三维模型

重建设置（Reconstruction settings）：处理选项设置，设置几何精度级别（高或最高）和其他重建设置。

Production列表（List of productions）

示例：

reconstruction = ccmasterkernel.Reconstruction(block)

block.addReconstruction(reconstruction)

6.5.9生产（Production）

生产项管理三维模型的生成，包括错误反馈、进度监控和有关底层重建更新的通知（例如，修饰）。

6.5.10 几何对象（Geometry）

MasterKernel中使用的基本几何类型的定义

6.5.11 大地测量（Geodesy）

通过Geodesy来实现在不同坐标系统下的转换

6.6 编码指引（API programming guid）

6.7 空间参考系统（Spatial Reference System）

地理参考项目需要通过选择空间参考系统（SRS）来定义制图系统。可以为管道中的各个步骤定义不同的SRS。例如，重构（空间框架）级别和生产级别都接受SRS的定义。

可以使用任何已知的SRS定义，包括epsg定义、proj.4声明或包含已知文本（wkt）的.prj文件名。

寻找空间参考系，请访问：www.spatialreference.org

EPSG编码：

支持大多数EPSG定义，包括EPSG投影制图系统和EPSG地理系统。使用语法“epsg:code”输入epsg代码（例如“epsg:32651”）

示例：

ProjectionCode

ECEF (Earth-Centered, Earth-Fixed)EPSG:4978

WGS84 (World Geodetic System 1984)EPSG:4326

WGS84 / UTM Zone 31NEPSG:32631

PROJ4

Proj4声明允许定义自定义投影系统（例如“+proj=utm+zone=11+datum=wgs84”）。另见项目4一般参数。

WKT规范支持（Well known text）

OpenGIS坐标系的众所周知的文本格式（WKT）可以在一个附加的.prj文件中提供。在这种情况下，输入投影文件路径作为SRS定义（例如“c:/projects/myprojection.prj”）。

示例：

GEOGCS["WGS 84",

DATUM["WGS_1984",

SPHEROID["WGS 84",6378137,298.257223563,

AUTHORITY["EPSG",7030]],

TOWGS84[0,0,0,0,0,0,0],

AUTHORITY["EPSG",6326]],

PRIMEM["Greenwich",0,AUTHORITY["EPSG",8901]],

UNIT["DMSH",0.0174532925199433,AUTHORITY["EPSG",9108]],

AXIS["Lat",NORTH],

AXIS["Long",EAST],

AUTHORITY["EPSG",4326]]

其他定义（Other definitions）：

ContextCapture在工作流的某些步骤中支持其他类型的SRS定义

ENU（East-North-Up）：可以使用语法“ENU:lat，lon”（例如“ENU:41.57231,2.26157”）输入本地ENU定义。

Bing Maps瓦片系统（Bing Maps Tile System）：Bing地图坐标系统可用于重建空间框架（例如“Bing地图：15”）。另请参阅msdn.microsoft.com。

6.8 生产格式和选项（Production formats and options）

建议的输出格式和选项取决于重建特性和生产目的。

输出格式通过ProductionDriver对象进行管理，并在ProductionDriverManager中注册。

获取支持的Production格式驱动：

fori inrange (0, ccmasterkernel.ProductionDriverManager.getNumDrivers()):

print( ccmasterkernel.ProductionDriverManager.getDriver(i)getShortName() )

ProductionDriver对象是在具有短名称的生产对象（如obj、osgb）上指定的。

每个ProductionDriver都有自己的实现并接受自己的选项。ProductionDriver对象可以返回受支持选项的元描述。

获取obj驱动程序的选项元描述：

objDriver = ccmasterkernel.ProductionDriverManager.getDriverByName('OBJ')

ptOptionsDesc = ccmasterkernel.PropertyTree()

objDriver.getOptionsMetaDescription(ptOptionsDesc)

ptOptionsDesc.dump()

每个选项由ID字符串、类型（bool、double、int、string）、可显示名称name和默认值标识。

选项元描述示例：

Id: "TextureEnabled"

Type: bool

Name: "Include texture maps"

Default: True

还可以在带有名称/值对的元描述的子项属性中提供可选的预定义值。

6.9 任务队列监测（Job queue monitoring）

以下示例显示如何提交航空三角测量作业，以及如何监视作业进度：

The following example shows how to submit an aerotriangulation job, and how to monitor the job progress:

# job submission

atSubmitError = blockAT.getAT().submitProcessing()

ifnot atSubmitError.isNone():

print('Error: Failed to submit aerotriangulation.')

print(atSubmitError.message)

      sys.exit(0)

print('The aerotriangulation job has been submitted and is waiting to be processed...')

# job monitoring

iPreviousProgress =0

iProgress =0

previousJobStatus = ccmasterkernel.JobStatus.Job_unknown

jobStatus = ccmasterkernel.JobStatus.Job_unknown

while1:

jobStatus = blockAT.getAT().getJobStatus()

ifjobStatus != previousJobStatus:

print(ccmasterkernel.jobStatusAsString(jobStatus))

ifjobStatus == ccmasterkernel.JobStatus.Job_failed orjobStatus == ccmasterkernel.JobStatus.Job_cancelled orjobStatus == ccmasterkernel.JobStatus.Job_completed:

break

ifiProgress != iPreviousProgress:

print('%s%%- %s'% (iProgress,blockAT.getAT().getJobMessage()))

iPreviousProgress = iProgress

iProgress = blockAT.getAT().getJobProgress()

      time.sleep(1)

      blockAT.getAT().updateJobStatus()

previousJobStatus = jobStatus

# job result

ifjobStatus != ccmasterkernel.JobStatus.Job_completed:

print('"Error: Incomplete aerotriangulation.')

if blockAT.getAT().getJobMessage() !='':

print( blockAT.getAT().getJobMessage() )

print('Aerotriangulation completed.')