6.SDK二次開發(fā)指南（ccmasterkernel’s documentation）
本用戶手冊(cè)與ContextCapture MasterKernel SDK有關(guān)
作為ContextCapture MasterKernel SDK的一部分坐求，ccMasterKernel是一個(gè)以編程方式訪問ContextCapture Master所有功能的python模塊。此模塊代替用戶界面，用于完整的項(xiàng)目創(chuàng)建擦耀、編輯和監(jiān)控贼邓。
提醒：本文件中的信息如有更改亡问，恕不另行通知机断，并按“原樣”提供畸颅。Bentley對(duì)本材料不作任何形式的保證盟猖，包括但不限于對(duì)適銷性和特定用途適用性的暗示保證讨衣。Bentley不對(duì)本文所包含的錯(cuò)誤或與使用本材料有關(guān)的任何直接、間接式镐、特殊反镇、附帶或后果性損害負(fù)責(zé)。
版權(quán)：Bentley Systems
6.1概述（Overview）
作為ContextCapture MasterKernel SDK的一部分娘汞，ccMasterKernel是一個(gè)以編程方式訪問ContextCapture Master所有功能的python模塊歹茶。此模塊代替用戶界面，用于完整的項(xiàng)目創(chuàng)建、編輯和監(jiān)控惊豺。
ccmasterkernel模塊允許在一個(gè)簡(jiǎn)單的方式燎孟，通過Python腳本開發(fā)定制的基于ContextCapture的應(yīng)用程序，自定義和/或自動(dòng)3D重建過程尸昧。
API模塊（應(yīng)用程序編程接口）允許控制ContextCapture主項(xiàng)目（CCM文件）中使用的所有項(xiàng)：
項(xiàng)目（Project）：創(chuàng)建缤弦、保存、編輯彻磁、選項(xiàng)設(shè)置碍沐、樹結(jié)構(gòu)管理。
塊（Block）：（Excel衷蜓，XML導(dǎo)入以及導(dǎo)出（KML）累提，XML，非約束的照片）磁浇，分割斋陪，提取，照片/?照片組（PhotoGroup）創(chuàng)建和編輯包括相機(jī)的三維屬性和位置/旋轉(zhuǎn)置吓，控制點(diǎn)（三維位置无虚、照片測(cè)量），連接點(diǎn)的創(chuàng)建和編輯衍锚。
AT（空中三角測(cè)量/?Aerotriangulation）：組件儿咱，定位模式,設(shè)置，任務(wù)提交浴骂，監(jiān)測(cè)/控制式撼，導(dǎo)出空三報(bào)告。
重建（Reconstruction）：空間框架（SRS告匠，興趣區(qū)域戈抄，瓦片分塊），重建約束后专，參考三維模型划鸽，（導(dǎo)入導(dǎo)出retouches，勻色戚哎，處理設(shè)置裸诽，導(dǎo)出瓦片分割為kml。
生產(chǎn)（Production）：控制所有參數(shù)（用途建瘫，格式崭捍，選項(xiàng)，范圍和定義）啰脚，任務(wù)提交殷蛇，監(jiān)測(cè)/控制实夹。
工作隊(duì)列監(jiān)測(cè)。
應(yīng)用設(shè)置（Application?Settings）：許可檢查粒梦，軟件的版本控制亮航，在線更新。
二次開發(fā)API包括各種工具和數(shù)據(jù)交換（屬性樹匀们，幾何）測(cè)量運(yùn)算缴淋。
6.2?安裝（Installation）
從更新9（update?9）開始，?python將被打包為一個(gè)wheel包泄朴。您可以在sdk/dist安裝目錄下找到*.whl文件重抖。需要python 3.6 x64版本支持。
烈建議使用virtualenv和pip安裝此軟件包祖灰。
但是钟沛，仍然有一個(gè)ContextCapture SDK命令提示快捷方式，您可以使用它來創(chuàng)建virtualenv并在其中安裝ccmasterkernel局扶。
6.3?升級(jí)指南（Migration?guide）
從更新9（update9）開始恨统，包名不再是ccmasterkernelpy，而是*ccmasterkernel三妈。您需要更新腳本畜埋，才能是你老的腳步可以在新版本下運(yùn)行。如果不想全部更改畴蒲，可以做如下替換：
把老命令
importCCMasterKernelPy
替換為：
importccmasterkernelasCCMasterKernelPy
作為一個(gè)小技巧
6.4教程
此簡(jiǎn)單腳本創(chuàng)建新的CCM項(xiàng)目悠鞍，導(dǎo)入XML塊定義，并保存項(xiàng)目：
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()
幾個(gè)完整的示例將與包一起安裝在python安裝示例/目錄中饿凛。
automaster.py
此腳本讀取照片目錄創(chuàng)建一個(gè)完整的重建（Reconstruction）狞玛，它遵循整個(gè)工作流程（航空三角測(cè)量、重建和生產(chǎn)）涧窒，并介紹了任務(wù)監(jiān)控。
module_info.py
此腳本演示如何通過Python模塊General面板的信息：許可證和功能锭亏、支持的生產(chǎn)（production）格式和選項(xiàng)等纠吴。
dump_project.py
此腳本從現(xiàn)有CCM項(xiàng)目中提取各種數(shù)據(jù)信息。
import_and_extract.py
此腳本演示了Aerial塊導(dǎo)入慧瘤、塊提取和塊導(dǎo)出的示例戴已。
import_and_split.py
此腳本演示了Aerial塊導(dǎo)入、塊分割和塊導(dǎo)出的示例锅减。
import_txt.py
此腳本根據(jù)自定義文本塊格式創(chuàng)建塊
reconstruction_settings.py
此腳本在現(xiàn)有CCM項(xiàng)目中使用自定義設(shè)置創(chuàng)建新的重建糖儡。
6.5 API參考手冊(cè)
6.5.1模塊信息
獲取模塊的基本信息，無許可也可以訪問怔匣。
version()?→?str
Returns?軟件版本.
edition()?→?str
Returns?軟件規(guī)格?(eg. Expert, Ultimate).
isLicenseValid()?→?bool
Returns True?許可有效.
如果許可無效握联，可以通過lastLicenseErrorMsg()獲取許可詳細(xì)信息
lastLicenseErrorMsg()?→?str
Returns?許可錯(cuò)誤的信息.
6.5.2?項(xiàng)目（Project）
Project選項(xiàng)管理與ContextCapture處理的場(chǎng)景相關(guān)的所有數(shù)據(jù)。
創(chuàng)建空項(xiàng)目的示例：
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）
一個(gè)Block區(qū)塊項(xiàng)目包含了一系列影像和屬性，包括傳感器尺寸金闽、焦距纯露、主點(diǎn)、透鏡畸變以及位置和旋轉(zhuǎn)?等姿態(tài)信息代芜，基于這些信息埠褪，可以建立一個(gè)或多個(gè)重建項(xiàng)目。
Block的定義如下：
照片（Photos）：導(dǎo)入或添加的照片及其相關(guān)的照片組屬性和照片姿態(tài)（通過航空三角測(cè)量或?qū)胗?jì)算）挤庇。通過塊的照片組（photogroup）訪問照片
點(diǎn)云（PointClouds）：導(dǎo)入的點(diǎn)云及其關(guān)聯(lián)屬性
控制點(diǎn)（Control?points）：手工輸入或?qū)氤佟？刂泣c(diǎn)是可選的嫡秕。參見類：'ccmasterkernel.controlpoint'
連接點(diǎn)（Tie?points）：由ContextCapture自動(dòng)提取或?qū)肟视铩＿€可以輸入用戶連接點(diǎn)以幫助進(jìn)行航空三角測(cè)量。
塊類型（BlockType）：例如“Aerial”淘菩，可選選項(xiàng)
Reconstruction列表（List?of reconstructions）：基于Block
創(chuàng)建Block的示例：
block?=?ccmasterkernel.Block(project)
project.addBlock(block)
forinputFile?in?inputFiles:
????????block.getPhotogroups().addPhotoInAutoMode(inputFile)
為了管理塊的空三遵班，可以創(chuàng)建專門用于調(diào)整的特殊塊。對(duì)于這些塊潮改，附加一個(gè)AT對(duì)象來管理航空三角測(cè)量設(shè)置狭郑、處理和報(bào)告。
示例：
blockAT?=?ccmasterkernel.Block(project)
project.addBlock(blockAT)
blockAT.setBlockTemplate(ccmasterkernel.BlockTemplate.Template_adjusted, inputBlock)
坐標(biāo)系：對(duì)于地理參考項(xiàng)目汇在，在塊級(jí)別翰萨，三維位置使用ECEF參考（EPSG:4978）。
6.5.4?照片（Photos）
管理照片集和關(guān)聯(lián)的屬性糕殉。通過照片組訪問塊的照片亩鬼。
照片被分為一組或多組照片。均勻的一組照片阿蝶，所有照片都是用同一個(gè)具有相同內(nèi)部方向（圖像尺寸雳锋、傳感器尺寸、焦距等）的物理相機(jī)拍攝的羡洁。
如果照片是根據(jù)拍攝時(shí)使用的相機(jī)按子目錄組織的玷过，則ContextCapture可以自動(dòng)確定相關(guān)的照片組。
6.5.5?空三（Aerotriangulation）
航空三角測(cè)量從輸入塊（Block）開始筑煮，生成具有計(jì)算或調(diào)整屬性的新塊辛蚊。
航空三角測(cè)量可考慮當(dāng)前攝像機(jī)位置（例如，從GPS初始化）或地理參考控制點(diǎn)真仲。
示例：
blockAT?=?ccmasterkernel.Block(project)
project.addBlock(blockAT)
blockAT.setBlockTemplate(ccmasterkernel.BlockTemplate.Template_adjusted, block)
# submit aerotriangulation processing
blockAT.getAT().submitProcessing()
6.5.6?連接點(diǎn)（TiePoints）
一個(gè)連接點(diǎn)對(duì)應(yīng)于兩張或多張不同照片中的像素袋马，其中這些像素表示場(chǎng)景中同一物理點(diǎn)的投影。ContextCapture可以在航空三角測(cè)量過程中自動(dòng)生成大量的連接點(diǎn)秸应。但是虑凛，用戶連接點(diǎn)也可以預(yù)先輸入碑宴，以幫助進(jìn)行航空三角測(cè)量。
6.5.7?點(diǎn)云（PointClouds）
管理點(diǎn)云集和關(guān)聯(lián)屬性
6.5.8?重建（Reconstruction）
一個(gè)重建項(xiàng)目(Reconstruction)管理著一個(gè)三維重建框架（包含空間坐標(biāo)系卧檐，建模區(qū)域墓懂，瓦片設(shè)置，處理設(shè)定等）霉囚，?基于一個(gè)重建項(xiàng)目可以建立一或多個(gè)生產(chǎn)任務(wù)捕仔。
Reconstruction的定義包含以下屬性：
空間參考（Spatial?framework）：定義空間參考系統(tǒng)（SRS）、感興趣區(qū)域（ROI）和瓦片切割方式盈罐。
重建約束（Reconstruction?constraints）：允許使用現(xiàn)有的三維數(shù)據(jù)來控制重建并避免重建錯(cuò)誤
參考三維模型（Reference?3D model）：是重建沙盒榜跌，它以本機(jī)格式存儲(chǔ)一個(gè)三維模型，隨著生產(chǎn)進(jìn)度逐步完成盅粪。該參考三維模型是應(yīng)用了修飾和重建約束的模型钓葫，并從中派生出需要完成的生成。通過InternalTile對(duì)象訪問參考三維模型
重建設(shè)置（Reconstruction?settings）：處理選項(xiàng)設(shè)置票顾，設(shè)置幾何精度級(jí)別（高或最高）和其他重建設(shè)置础浮。
Production列表（List?of productions）
示例：
reconstruction?=?ccmasterkernel.Reconstruction(block)
block.addReconstruction(reconstruction)
6.5.9生產(chǎn)（Production）
生產(chǎn)項(xiàng)管理三維模型的生成，包括錯(cuò)誤反饋奠骄、進(jìn)度監(jiān)控和有關(guān)底層重建更新的通知（例如豆同，修飾）。
6.5.10?幾何對(duì)象（Geometry）
MasterKernel中使用的基本幾何類型的定義
6.5.11?大地測(cè)量（Geodesy）
通過Geodesy來實(shí)現(xiàn)在不同坐標(biāo)系統(tǒng)下的轉(zhuǎn)換
6.6?編碼指引（API programming guid）
6.7?空間參考系統(tǒng)（Spatial?Reference System）
地理參考項(xiàng)目需要通過選擇空間參考系統(tǒng)（SRS）來定義制圖系統(tǒng)含鳞∮靶猓可以為管道中的各個(gè)步驟定義不同的SRS。例如蝉绷，重構(gòu)（空間框架）級(jí)別和生產(chǎn)級(jí)別都接受SRS的定義鸭廷。
可以使用任何已知的SRS定義，包括epsg定義熔吗、proj.4聲明或包含已知文本（wkt）的.prj文件名辆床。
尋找空間參考系，請(qǐng)?jiān)L問：www.spatialreference.org
EPSG編碼：
支持大多數(shù)EPSG定義桅狠，包括EPSG投影制圖系統(tǒng)和EPSG地理系統(tǒng)佛吓。使用語法“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聲明允許定義自定義投影系統(tǒng)（例如“+proj=utm+zone=11+datum=wgs84”）。另見項(xiàng)目4一般參數(shù)垂攘。
WKT規(guī)范支持（Well?known text）
OpenGIS坐標(biāo)系的眾所周知的文本格式（WKT）可以在一個(gè)附加的.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瓦片系統(tǒng)（Bing?Maps Tile System）：Bing地圖坐標(biāo)系統(tǒng)可用于重建空間框架（例如“Bing地圖：15”）陨仅。另請(qǐng)參閱msdn.microsoft.com津滞。
6.8?生產(chǎn)格式和選項(xiàng)（Production?formats and options）
建議的輸出格式和選項(xiàng)取決于重建特性和生產(chǎn)目的。
輸出格式通過ProductionDriver對(duì)象進(jìn)行管理灼伤，并在ProductionDriverManager中注冊(cè)触徐。
獲取支持的Production格式驅(qū)動(dòng)：
fori?inrange?(0, ccmasterkernel.ProductionDriverManager.getNumDrivers()):
print( ccmasterkernel.ProductionDriverManager.getDriver(i)getShortName() )
ProductionDriver對(duì)象是在具有短名稱的生產(chǎn)對(duì)象（如obj、osgb）上指定的狐赡。
每個(gè)ProductionDriver都有自己的實(shí)現(xiàn)并接受自己的選項(xiàng)撞鹉。ProductionDriver對(duì)象可以返回受支持選項(xiàng)的元描述。
獲取obj驅(qū)動(dòng)程序的選項(xiàng)元描述：
objDriver?=?ccmasterkernel.ProductionDriverManager.getDriverByName('OBJ')
ptOptionsDesc?=?ccmasterkernel.PropertyTree()
objDriver.getOptionsMetaDescription(ptOptionsDesc)
ptOptionsDesc.dump()
每個(gè)選項(xiàng)由ID字符串颖侄、類型（bool鸟雏、double、int览祖、string）孝鹊、可顯示名稱name和默認(rèn)值標(biāo)識(shí)。
選項(xiàng)元描述示例：
Id:?"TextureEnabled"
Type:?bool
Name:?"Include texture maps"
Default:?True
還可以在帶有名稱/值對(duì)的元描述的子項(xiàng)屬性中提供可選的預(yù)定義值展蒂。
6.9?任務(wù)隊(duì)列監(jiān)測(cè)（Job?queue monitoring）
以下示例顯示如何提交航空三角測(cè)量作業(yè)又活，以及如何監(jiān)視作業(yè)進(jìn)度：
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.')
