一、基本概念

• 文檔校正提供了文檔翻拍過(guò)程的輔助增強(qiáng)功能，包含兩個(gè)子功能：文檔檢測(cè)和文檔校驗(yàn)。
• 文檔檢測(cè)：能夠自動(dòng)識(shí)別圖片中的文檔，返回文檔在原圖中的位置信息。這里的文檔泛指外形方正的事物，比如書(shū)本、相片、畫(huà)框等。
• 文檔校正：能根據(jù)文檔在原始圖片中的位置信息校正文檔的拍攝角度，自動(dòng)將拍攝視角調(diào)整到正對(duì)文檔的角度上。

二、運(yùn)作機(jī)制

① 文檔檢測(cè)

• 調(diào)用文檔檢測(cè)接口，識(shí)別圖片中的文檔，返回文檔在原圖中的位置信息；
• 如下圖中的紅點(diǎn)所示，文檔檢測(cè)接口返回了圖中相片文檔四個(gè)頂點(diǎn)相對(duì)圖像左上角的坐標(biāo)信息：

• 文檔檢測(cè)結(jié)果如下，該 JSON 保存了原圖中相片文檔四個(gè)角相對(duì)原圖左上頂點(diǎn)的坐標(biāo)信息（單位：像素），其中 resultCode 為返回碼：

{"resultCode":0,"doc":"{\"bottom_left\":{\"x\":17,\"y\":440},\"bottom_right\":{\"x\":589,\"y\":760},\"top_left\":{\"x\":256,\"y\":13},\"top_right\":{\"x\":829,\"y\":332}}"}

② 文檔校正

• 根據(jù)文檔在原始圖片中的位置信息校正文檔的拍攝角度（可自定義校正的區(qū)域）。
• 圖片中的校正區(qū)域：

• 校正上圖中深藍(lán)色矩形（文檔檢測(cè)接口返回的文檔區(qū)域）區(qū)域，校正后的效果如下圖：

③ 使用限制

• 支持處理的圖片格式包括 JPEG、JPG、PNG，最終輸出的圖片僅支持 JPEG 格式。
• 拍攝時(shí)盡量將文檔放置在與文檔背景色有一定色差的平面上，并盡量讓文檔充滿畫(huà)面，保持文檔邊界入鏡，以獲得最佳效果。
• 輸入圖片高和寬最小為 100 像素，最大為 10000 像素。

三、應(yīng)用場(chǎng)景

• 將紙質(zhì)信件等舊文檔翻拍成電子版，幫助改善舊文檔的翻拍效果。
• 記錄書(shū)畫(huà)展覽中的精彩作品，幫助將作品拍攝得更加端正。

四、API 說(shuō)明

• 文檔校正提供了 setVisionConfiguration()、docDetect() 和 docRefine() 三個(gè)函數(shù)接口。
• setVisionConfiguration 是 IDocRefine 接口的成員，通過(guò)傳入的 DocRefineConfiguration，選擇需要調(diào)用的文檔校正類(lèi)型：

void setVisionConfiguration(DocRefineConfiguration docRefineConfiguration);

• DocRefineConfiguration 的常用設(shè)置：

接口參數(shù)名類(lèi)型參數(shù)說(shuō)明

setProcessMode()	mode	int	進(jìn)程模式定義： VisionConfiguration.MODE_IN（同進(jìn)程調(diào)用） VisionConfiguration.MODE_OUT（跨進(jìn)程調(diào)用） 默認(rèn)值為VisionConfiguration.MODE_OUT

• 調(diào)用 IDocRefine的docDetect() 方法，獲取檢測(cè)結(jié)果：

int docDetect(VisionImage image, DocCoordinates result, VisionCallback<DocCoordinates> visionCallBack);

• 說(shuō)明：
• • image 為待文檔檢測(cè)的輸入圖片。
• • 如果 visionCallback 為 null，執(zhí)行同步調(diào)用，結(jié)果碼由方法返回，檢測(cè)結(jié)果由 result 中返回。
• • 如果 visionCallback 為有效的回調(diào)函數(shù)，則該函數(shù)為異步調(diào)用，函數(shù)返回時(shí) result 中的值無(wú)效，實(shí)際識(shí)別結(jié)果由回調(diào)函數(shù)返回。
• • 同步模式調(diào)用成功時(shí)，該函數(shù)返回結(jié)果碼 0。異步模式調(diào)用請(qǐng)求發(fā)送成功時(shí)，該函數(shù)返回結(jié)果碼 700。
• 調(diào)用 IDocRefine 的 docRefine() 方法，獲取校正結(jié)果：

int docRefine(VisionImage image, DocCoordinates coordinates, ImageResult result,VisionCallback<ImageResult> visionCallBack);

• 說(shuō)明：
• • image 為待文檔校正的輸入圖片。
• • 如果 visionCallback 為 null，執(zhí)行同步調(diào)用，結(jié)果碼由方法返回，校正結(jié)果由 result 中返回。
• • 如果 visionCallback 為有效的回調(diào)函數(shù)，則該函數(shù)為異步調(diào)用，函數(shù)返回時(shí) result 中的值無(wú)效，實(shí)際識(shí)別結(jié)果由回調(diào)函數(shù)返回。
• • 同步模式調(diào)用成功時(shí)，該函數(shù)返回結(jié)果碼 0。異步模式調(diào)用請(qǐng)求發(fā)送成功時(shí)，該函數(shù)返回結(jié)果碼 700。

五、開(kāi)發(fā)流程

• 在使用文檔校正時(shí)，先將相關(guān)的類(lèi)添加至工程：

import ohos.ai.cv.common.ConnectionCallback;import ohos.ai.cv.common.VisionCallback;import ohos.ai.cv.common.VisionImage;import ohos.ai.cv.common.VisionManager;import ohos.ai.cv.common.ImageResult;import ohos.ai.cv.docrefine.DocCoordinates;import ohos.ai.cv.docrefine.DocRefineConfiguration;import ohos.ai.cv.docrefine.IDocRefine;import ohos.app.Context;import ohos.media.image.PixelMap;

• 定義 ConnectionCallback 回調(diào)，實(shí)現(xiàn)連接能力引擎成功與否后的操作：

ConnectionCallback connectionCallback = new ConnectionCallback() {@Overridepublic void onServiceConnect() {// 定義連接能力引擎成功后的操作。}@Overridepublic void onServiceDisconnect() {// 定義連接能力引擎失敗后的操作。}};

• 調(diào)用 VisionManager.init() 方法，將此工程的 context 和已經(jīng)定義的 connectionCallback 作為入?yún)?#xff0c;建立與能力引擎的連接，context 應(yīng)為 ohos.aafwk.ability.Ability 或 ohos.aafwk.ability.AbilitySlice 的實(shí)例或子類(lèi)實(shí)例：

int result = VisionManager.init(context, connectionCallback);

• 實(shí)例化 IDocRefine 接口，將此工程的 context 作為入?yún)?#xff0c;context 應(yīng)為 ohos.aafwk.ability.Ability 或 ohos.aafwk.ability.AbilitySlice 的實(shí)例或子類(lèi)實(shí)例：

IDocRefine docRefine = VisionManager.getDocRefine(context);

• 實(shí)例化 VisionImage 對(duì)象 image，并傳入待校正圖片 pixelMap：

VisionImage image = VisionImage.fromPixelMap(pixelMap);

• 實(shí)例化 DocCoordinates 對(duì)象 docCoordinates：

DocCoordinates docCoordinates = new DocCoordinates();

• （可選）定義 VisionCallback 回調(diào)：
• • 在異步模式下，該類(lèi)的 onResult() 方法用于獲得檢測(cè)的結(jié)果 docCoordinates（內(nèi)含檢測(cè)到的文檔坐標(biāo)）；onError() 方法用于處理錯(cuò)誤返回碼；onProcessing() 方法用于返回處理進(jìn)度，目前沒(méi)有實(shí)現(xiàn)此接口的功能。
• • 同步與異步模式區(qū)別在于 docDetect() 的最后一個(gè)參數(shù) visionCallback 是否為空。若非空則為異步模式，此時(shí)會(huì)忽略自定義的 DocCoordinates 輸入 docCoordinates，接口調(diào)用結(jié)果一律從回調(diào)函數(shù)visionCallback 獲得。

VisionCallback<DocCoordinates> callback= new VisionCallback<DocCoordinates>() {@Overridepublic void onResult(DocCoordinates docCoordinates) {// 對(duì)正確獲得的結(jié)果進(jìn)行處理}@Overridepublic void onError(int i) {// 處理錯(cuò)誤返回碼}@Overridepublic void onProcessing(float v) {// 返回處理進(jìn)度}};

• 實(shí)例化 ImageResult 對(duì)象 imageResult：

ImageResult imageResult = new ImageResult();

• （可選）定義 VisionCallback 回調(diào)：
• • 在異步模式下，該類(lèi)的 onResult() 方法用于獲得校正的結(jié)果 imageResult（內(nèi)含校正后的圖片）；onError() 方法用于處理錯(cuò)誤返回碼；onProcessing() 方法用于返回處理進(jìn)度，目前沒(méi)有實(shí)現(xiàn)此接口的功能。
• • 同步與異步模式區(qū)別在于 docRefine() 的最后一個(gè)參數(shù) visionCallback 是否為空。若非空則為異步模式。此時(shí)會(huì)忽略自定義的 ImageResult 輸入 imageResult，接口調(diào)用結(jié)果一律從回調(diào)類(lèi) visionCallback 獲得。

VisionCallback<ImageResult> callback = new VisionCallback<ImageResult>() {@Overridepublic void onResult(ImageResult imageResult) {// 對(duì)正確獲得的結(jié)果進(jìn)行處理}@Overridepublic void onError(int i) {// 處理錯(cuò)誤返回碼}@Overridepublic void onProcessing(float v) {// 返回處理進(jìn)度}};

• 通過(guò) DocRefineConfiguration 配置校正參數(shù)，可選擇進(jìn)程調(diào)用模式等（推薦使用MODE_IN同進(jìn)程模式），跨進(jìn)程模式（MODE_OUT）下調(diào)用方與能力引擎處于不同進(jìn)程；同進(jìn)程模式（MODE_IN)下，能力引擎在調(diào)用方進(jìn)程中實(shí)例化，調(diào)用方通過(guò)反射的方式調(diào)用引擎里的文檔校正能力。以同進(jìn)程調(diào)用為例：

DocRefineConfiguration.Builder builder = new DocRefineConfiguration.Builder();builder.setProcessMode(VisionConfiguration.MODE_IN);DocRefineConfiguration configuration = builder.build();docRefine.setVisionConfiguration(configuration);

• （可選）調(diào)用 IDocRefine的prepare() 方法：

result = docRefine.prepare();

• 調(diào)用 IDocRefine 的 docDetect() 方法：
• • 同步模式調(diào)用完成時(shí)，該函數(shù)立即返回結(jié)果碼。
• • 異步模式調(diào)用請(qǐng)求發(fā)送成功時(shí)，該函數(shù)返回結(jié)果碼700。如果返回其他的值，說(shuō)明異步調(diào)用請(qǐng)求不成功，需要先處理錯(cuò)誤，回調(diào)函數(shù)不會(huì)被調(diào)用。
• • 如果異步模式調(diào)用請(qǐng)求發(fā)送成功，則檢測(cè)完成后，相應(yīng)的回調(diào)函數(shù)會(huì)被自動(dòng)調(diào)用。
• • • 如果 onResult() 回調(diào)被調(diào)用，說(shuō)明檢測(cè)成功，相當(dāng)于同步模式結(jié)果碼為0的情況。
• • • 如果 onError() 方法被調(diào)用，說(shuō)明檢測(cè)發(fā)生了錯(cuò)誤，具體的調(diào)用結(jié)果碼將由 onError() 的參數(shù)接收。

result = docRefine.docDetect(image, docCoordinates, null); // 同步// 或者result = docRefine.docDetect(image, null, callback); // 異步

• 調(diào)用 IDocRefine的docRefine() 方法：
• • 同步模式調(diào)用完成時(shí)，該函數(shù)立即返回結(jié)果碼。
• • 異步模式調(diào)用請(qǐng)求發(fā)送成功時(shí)，該函數(shù)返回結(jié)果碼700。如果返回其他的值，說(shuō)明異步調(diào)用請(qǐng)求不成功，需要先處理錯(cuò)誤，回調(diào)函數(shù)不會(huì)被調(diào)用。
• • 如果異步模式調(diào)用請(qǐng)求發(fā)送成功，則校正完成后，相應(yīng)的回調(diào)函數(shù)會(huì)被自動(dòng)調(diào)用。
• • • 如果 onResult() 回調(diào)被調(diào)用，說(shuō)明校正成功，相當(dāng)于同步模式結(jié)果碼為0的情況。
• • • 如果 onError() 方法被調(diào)用，說(shuō)明校正發(fā)生了錯(cuò)誤，具體的調(diào)用結(jié)果碼將由 onError() 的參數(shù)接收。

result = docRefine.docRefine(image, docCoordinates, imageResult, null); // 同步// 或者result = docRefine.docRefine(image, docCoordinates, null, callback); // 異步

• 調(diào)用 IDocRefine的release() 方法，釋放資源，調(diào)用 pixelMap 的 release() 方法，釋放圖片內(nèi)存：

result = docRefine.release();if (pixelMap != null) {pixelMap.release();pixelMap = null;}

• 調(diào)用 VisionManager.destroy() 方法，斷開(kāi)與能力引擎的連接：

VisionManager.destroy();

• 結(jié)果碼定義如下表：

結(jié)果碼說(shuō)明

0	成功
-1	未知錯(cuò)誤
-2	不支持的功能或接口
-3	內(nèi)存分配失敗或創(chuàng)建對(duì)象失敗
-4	所需庫(kù)加載失敗
-10	引擎開(kāi)關(guān)已經(jīng)關(guān)閉
101	失敗
102	超時(shí)
200	輸入?yún)?shù)不合法（圖片尺寸錯(cuò)誤）
201	輸入?yún)?shù)不合法（為空）
210	輸入?yún)?shù)合法
500	服務(wù)綁定異常
521	服務(wù)綁定異常斷開(kāi)
522	服務(wù)已連接
600	模型文件異常
601	模型文件不存在
602	模型加載失敗
700	異步調(diào)用請(qǐng)求發(fā)送成功
1001	神經(jīng)網(wǎng)絡(luò)處理單元錯(cuò)誤

總結(jié)

以上是生活随笔為你收集整理的HarmonyOS之AI能力·文档检测校正的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。