6.SDK二次開發(fā)指南（ccmasterkernel’s documentation）

本用戶手冊與ContextCapture MasterKernel SDK有關(guān)

作為ContextCapture MasterKernel SDK的一部分，ccMasterKernel是一個以編程方式訪問ContextCapture Master所有功能的python模塊。此模塊代替用戶界面，用于完整的項目創(chuàng)建、編輯和監(jiān)控。

提醒：本文件中的信息如有更改，恕不另行通知，并按“原樣”提供。Bentley對本材料不作任何形式的保證，包括但不限于對適銷性和特定用途適用性的暗示保證。Bentley不對本文所包含的錯誤或與使用本材料有關(guān)的任何直接、間接、特殊、附帶或后果性損害負(fù)責(zé)。

版權(quán)：Bentley Systems

6.1概述（Overview）

作為ContextCapture MasterKernel SDK的一部分，ccMasterKernel是一個以編程方式訪問ContextCapture Master所有功能的python模塊。此模塊代替用戶界面，用于完整的項目創(chuàng)建、編輯和監(jiān)控。

ccmasterkernel模塊允許在一個簡單的方式，通過Python腳本開發(fā)定制的基于ContextCapture的應(yīng)用程序，自定義和/或自動3D重建過程。

API模塊（應(yīng)用程序編程接口）允許控制ContextCapture主項目（CCM文件）中使用的所有項：

項目（Project）：創(chuàng)建、保存、編輯、選項設(shè)置、樹結(jié)構(gòu)管理。

塊（Block）：（Excel，XML導(dǎo)入以及導(dǎo)出（KML），XML，非約束的照片），分割，提取，照片/?照片組（PhotoGroup）創(chuàng)建和編輯包括相機(jī)的三維屬性和位置/旋轉(zhuǎn)，控制點(diǎn)（三維位置、照片測量），連接點(diǎn)的創(chuàng)建和編輯。

AT（空中三角測量/?Aerotriangulation）：組件，定位模式,設(shè)置，任務(wù)提交，監(jiān)測/控制，導(dǎo)出空三報告。

重建（Reconstruction）：空間框架（SRS，興趣區(qū)域，瓦片分塊），重建約束，參考三維模型，（導(dǎo)入導(dǎo)出retouches，勻色，處理設(shè)置，導(dǎo)出瓦片分割為kml。

生產(chǎn)（Production）：控制所有參數(shù)（用途，格式，選項，范圍和定義），任務(wù)提交，監(jiān)測/控制。

工作隊列監(jiān)測。

應(yīng)用設(shè)置（Application?Settings）：許可檢查，軟件的版本控制，在線更新。

二次開發(fā)API包括各種工具和數(shù)據(jù)交換（屬性樹，幾何）測量運(yùn)算。

6.2?安裝（Installation）

從更新9（update?9）開始，?python將被打包為一個wheel包。您可以在sdk/dist安裝目錄下找到*.whl文件。需要python 3.6 x64版本支持。

烈建議使用virtualenv和pip安裝此軟件包。

但是，仍然有一個ContextCapture SDK命令提示快捷方式，您可以使用它來創(chuàng)建virtualenv并在其中安裝ccmasterkernel。

6.3?升級指南（Migration?guide）

從更新9（update9）開始，包名不再是ccmasterkernelpy，而是*ccmasterkernel。您需要更新腳本，才能是你老的腳步可以在新版本下運(yùn)行。如果不想全部更改，可以做如下替換：

把老命令

importCCMasterKernelPy

替換為：

importccmasterkernelasCCMasterKernelPy

作為一個小技巧

6.4教程

此簡單腳本創(chuàng)建新的CCM項目，導(dǎo)入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

此腳本讀取照片目錄創(chuàng)建一個完整的重建（Reconstruction），它遵循整個工作流程（航空三角測量、重建和生產(chǎn)），并介紹了任務(wù)監(jiān)控。

module_info.py

此腳本演示如何通過Python模塊General面板的信息：許可證和功能、支持的生產(chǎn)（production）格式和選項等。

dump_project.py

此腳本從現(xiàn)有CCM項目中提取各種數(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項目中使用自定義設(shè)置創(chuàng)建新的重建。

6.5 API參考手冊

6.5.1模塊信息

獲取模塊的基本信息，無許可也可以訪問。

version()?→?str

Returns?軟件版本.

edition()?→?str

Returns?軟件規(guī)格?(eg. Expert, Ultimate).

isLicenseValid()?→?bool

Returns True?許可有效.

如果許可無效，可以通過lastLicenseErrorMsg()獲取許可詳細(xì)信息

lastLicenseErrorMsg()?→?str

Returns?許可錯誤的信息.

6.5.2?項目（Project）

Project選項管理與ContextCapture處理的場景相關(guān)的所有數(shù)據(jù)。

創(chuà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）

一個Block區(qū)塊項目包含了一系列影像和屬性，包括傳感器尺寸、焦距、主點(diǎn)、透鏡畸變以及位置和旋轉(zhuǎn)?等姿態(tài)信息，基于這些信息，可以建立一個或多個重建項目。

Block的定義如下：

照片（Photos）：導(dǎo)入或添加的照片及其相關(guān)的照片組屬性和照片姿態(tài)（通過航空三角測量或?qū)胗嬎悖?。通過塊的照片組（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自動提取或?qū)搿＿€可以輸入用戶連接點(diǎn)以幫助進(jìn)行航空三角測量。

塊類型（BlockType）：例如“Aerial”，可選選項

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)整的特殊塊。對于這些塊，附加一個AT對象來管理航空三角測量設(shè)置、處理和報告。

示例：

blockAT?=?ccmasterkernel.Block(project)

project.addBlock(blockAT)

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

坐標(biāo)系：對于地理參考項目，在塊級別，三維位置使用ECEF參考（EPSG:4978）。

6.5.4?照片（Photos）

管理照片集和關(guān)聯(lián)的屬性。通過照片組訪問塊的照片。

照片被分為一組或多組照片。均勻的一組照片，所有照片都是用同一個具有相同內(nèi)部方向（圖像尺寸、傳感器尺寸、焦距等）的物理相機(jī)拍攝的。

如果照片是根據(jù)拍攝時使用的相機(jī)按子目錄組織的，則ContextCapture可以自動確定相關(guān)的照片組。

6.5.5?空三（Aerotriangulation）

航空三角測量從輸入塊（Block）開始，生成具有計算或調(diào)整屬性的新塊。

航空三角測量可考慮當(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）

一個連接點(diǎn)對應(yīng)于兩張或多張不同照片中的像素，其中這些像素表示場景中同一物理點(diǎn)的投影。ContextCapture可以在航空三角測量過程中自動生成大量的連接點(diǎn)。但是，用戶連接點(diǎn)也可以預(yù)先輸入，以幫助進(jìn)行航空三角測量。

6.5.7?點(diǎn)云（PointClouds）

管理點(diǎn)云集和關(guān)聯(lián)屬性

6.5.8?重建（Reconstruction）

一個重建項目(Reconstruction)管理著一個三維重建框架（包含空間坐標(biāo)系，建模區(qū)域，瓦片設(shè)置，處理設(shè)定等），?基于一個重建項目可以建立一或多個生產(chǎn)任務(wù)。

Reconstruction的定義包含以下屬性：

空間參考（Spatial?framework）：定義空間參考系統(tǒng)（SRS）、感興趣區(qū)域（ROI）和瓦片切割方式。

重建約束（Reconstruction?constraints）：允許使用現(xiàn)有的三維數(shù)據(jù)來控制重建并避免重建錯誤

參考三維模型（Reference?3D model）：是重建沙盒，它以本機(jī)格式存儲一個三維模型，隨著生產(chǎn)進(jìn)度逐步完成。該參考三維模型是應(yīng)用了修飾和重建約束的模型，并從中派生出需要完成的生成。通過InternalTile對象訪問參考三維模型

重建設(shè)置（Reconstruction?settings）：處理選項設(shè)置，設(shè)置幾何精度級別（高或最高）和其他重建設(shè)置。

Production列表（List?of productions）

示例：

reconstruction?=?ccmasterkernel.Reconstruction(block)

block.addReconstruction(reconstruction)

6.5.9生產(chǎn)（Production）

生產(chǎn)項管理三維模型的生成，包括錯誤反饋、進(jìn)度監(jiān)控和有關(guān)底層重建更新的通知（例如，修飾）。

6.5.10?幾何對象（Geometry）

MasterKernel中使用的基本幾何類型的定義

6.5.11?大地測量（Geodesy）

通過Geodesy來實(shí)現(xiàn)在不同坐標(biāo)系統(tǒng)下的轉(zhuǎn)換

6.6?編碼指引（API programming guid）

6.7?空間參考系統(tǒng)（Spatial?Reference System）

地理參考項目需要通過選擇空間參考系統(tǒng)（SRS）來定義制圖系統(tǒng)。可以為管道中的各個步驟定義不同的SRS。例如，重構(gòu)（空間框架）級別和生產(chǎn)級別都接受SRS的定義。

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

尋找空間參考系，請訪問：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”）。另見項目4一般參數(shù)。

WKT規(guī)范支持（Well?known text）

OpenGIS坐標(biāo)系的眾所周知的文本格式（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瓦片系統(tǒng)（Bing?Maps Tile System）：Bing地圖坐標(biāo)系統(tǒng)可用于重建空間框架（例如“Bing地圖：15”）。另請參閱msdn.microsoft.com。

6.8?生產(chǎn)格式和選項（Production?formats and options）

建議的輸出格式和選項取決于重建特性和生產(chǎn)目的。

輸出格式通過ProductionDriver對象進(jìn)行管理，并在ProductionDriverManager中注冊。

獲取支持的Production格式驅(qū)動：

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

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

ProductionDriver對象是在具有短名稱的生產(chǎn)對象（如obj、osgb）上指定的。

每個ProductionDriver都有自己的實(shí)現(xiàn)并接受自己的選項。ProductionDriver對象可以返回受支持選項的元描述。

獲取obj驅(qū)動程序的選項元描述：

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

ptOptionsDesc?=?ccmasterkernel.PropertyTree()

objDriver.getOptionsMetaDescription(ptOptionsDesc)

ptOptionsDesc.dump()

每個選項由ID字符串、類型（bool、double、int、string）、可顯示名稱name和默認(rèn)值標(biāo)識。

選項元描述示例：

Id:?"TextureEnabled"

Type:?bool

Name:?"Include texture maps"

Default:?True

還可以在帶有名稱/值對的元描述的子項屬性中提供可選的預(yù)定義值。

6.9?任務(wù)隊列監(jiān)測（Job?queue monitoring）

以下示例顯示如何提交航空三角測量作業(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.')