6.SDK二次开发指南（ccmasterkernel’s documentation）
本用户手册与ContextCapture MasterKernel SDK有关
作为ContextCapture MasterKernel SDK的一部分，ccMasterKernel是一个以编程方式访问ContextCapture Master所有功能的python模块。此模块代替用户界面，用于完整的项目创建、编辑和监控。
提醒：本文件中的信息如有更改，恕不另行通知，并按“原样”提供。Bentley对本材料不作任何形式的保证，包括但不限于对适销性和特定用途适用性的暗示保证。Bentley不对本文所包含的错误或与使用本材料有关的任何直接、间接、特殊、附带或后果性损害负责。
版权：Bentley Systems
6.1概述（Overview）
作为ContextCapture MasterKernel SDK的一部分，ccMasterKernel是一个以编程方式访问ContextCapture Master所有功能的python模块。此模块代替用户界面，用于完整的项目创建、编辑和监控。
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.')