瞭解如何在自己的應用程式中使用 Scene Semantics API。
透過場景語意 API，開發人員可以提供機器學習模型的即時語意資訊，瞭解使用者周遭的場景。針對戶外場景的圖片，API 會為一系列實用的語意類別 (例如天空、建築物、樹木、道路、人行道、車輛、人形等) 傳回每個像素的標籤。除了像素標籤之外，場景語意 API 還會為每個像素標籤提供信心值，並提供簡單易用的查詢方式，可查詢特定標籤在戶外場景中的盛行率。
從左至右，分別為輸入圖片、像素標籤的語意圖片，以及對應的信心圖片：
必要條件
請務必瞭解基本 AR 概念 以及如何在繼續操作前設定 ARCore 工作階段。
啟用情境語意
在新的 ARCore 工作階段中，檢查使用者的裝置是否支援 Scene Semantics API。由於處理效能受限，並非所有 ARCore 相容裝置都支援 Scene Semantics API。
為節省資源，ARCore 預設會停用場景語意。啟用語意模式，讓應用程式使用 Scene Semantics API。
// Check whether the user's device supports the Scene Semantics API.
int32_t is_scene_semantics_supported = 0;
ArSession_isSemanticModeSupported(ar_session, AR_SEMANTIC_MODE_ENABLED, &is_scene_semantics_supported);
// Configure the session for AR_SEMANTIC_MODEL_ENABLED.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);
if (is_scene_semantics_supported) {
ArConfig_setSemanticMode(ar_session, ar_config, AR_SEMANTIC_MODE_ENABLED);
}
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);
ArConfig_destroy(ar_config);
取得語意圖片
啟用場景語意後，即可擷取語意圖像。語意圖片是 AR_IMAGE_FORMAT_Y8 圖片，每個像素都會對應至 ArSemanticLabel 定義的語意標籤。
使用 ArFrame_acquireSemanticImage() 取得語意圖片：
// Retrieve the semantic image for the current frame, if available.
ArImage* semantic_image = NULL;
if (ArFrame_acquireSemanticImage(ar_session, ar_frame, &semantic_image) != AR_SUCCESS) {
// No semantic image retrieved for this frame.
// The output image may be missing for the first couple frames before the model has had a chance to run yet.
return;
}
// If a semantic image is available, use it here.
視裝置而定，輸出語意圖像的時間應在工作階段開始後的 1 到 3 個影格後。
「取得信心」圖片
除了為每個像素提供標籤的語意圖片外，API 還提供對應像素信賴值的可信度圖片。信心圖片是 AR_IMAGE_FORMAT_Y8 圖片，每個像素都會對應到 [0, 255] 範圍內的值，對應至與每個像素語意標籤相關的機率。
使用 ArFrame_acquireSemanticConfidenceImage() 取得語意信心圖像：
// Retrieve the semantic confidence image for the current frame, if available.
ArImage* semantic_confidence_image = NULL;
if (ArFrame_acquireSemanticConfidenceImage(ar_session, ar_frame, &semantic_confidence_image) != AR_SUCCESS) {
// No semantic confidence image retrieved for this frame.
// The output image may be missing for the first couple frames before the model has had a chance to run yet.
return;
}
// If a semantic confidence image is available, use it here.
輸出信心圖片的時間，應在工作階段開始後約 1 到 3 個影格後 (視裝置而定)。
查詢語意標籤的像素比例
您也可以查詢目前影格中屬於特定類別 (例如天空) 的像素比例。這項查詢比傳回語意圖像，並針對特定標籤執行逐像素搜尋更有效率。傳回的分數是 [0.0, 1.0] 範圍內的浮點值。
使用 ArFrame_getSemanticLabelFraction() 取得特定標籤的分數：
// Retrieve the fraction of pixels for the semantic label sky in the current frame.
float out_fraction = 0.0f;
if (ArFrame_getSemanticLabelFraction(ar_session, ar_frame, AR_SEMANTIC_LABEL_SKY, &out_fraction) != AR_SUCCESS) {
// No fraction of semantic labels was retrieved for this frame.
}