基本概念

文檔校正提供了文檔翻拍過程的輔助增強(qiáng)功能，包含兩個(gè)子功能：

• 文檔檢測(cè)：能夠自動(dòng)識(shí)別圖片中的文檔，返回文檔在原圖中的位置信息。這里的文檔泛指外形方正的事物，比如書本、相片、畫框等。
• 文檔校正：能根據(jù)文檔在原始圖片中的位置信息校正文檔的拍攝角度，自動(dòng)將拍攝視角調(diào)整到正對(duì)文檔的角度上。

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

• 文檔檢測(cè)

  調(diào)用文檔檢測(cè)接口，識(shí)別圖片中的文檔，返回文檔在原圖中的位置信息。

  圖1?含有文檔的圖片

?如上圖中的紅點(diǎn)所示，文檔檢測(cè)接口返回了圖中相片文檔四個(gè)頂點(diǎn)相對(duì)圖像左上角的坐標(biāo)信息。文檔檢測(cè)結(jié)果如下：

{
  "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}
    }"
}

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

• 文檔校正

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

  圖2?圖片中的校正區(qū)域

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

圖3?校正完成的文檔圖片

約束與限制

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

文檔檢測(cè)校正開發(fā)

場(chǎng)景介紹

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

接口說明

文檔校正提供了setVisionConfiguration()、docDetect()和docRefine()三個(gè)函數(shù)接口。

• setVisionConfiguration是IDocRefine接口的成員。通過傳入的DocRefineConfiguration，選擇需要調(diào)用的文檔校正類型。

void setVisionConfiguration(DocRefineConfiguration docRefineConfiguration);

• 下表列出了DocRefineConfiguration的常用設(shè)置：

  接口	參數(shù)名	類型	參數(shù)說明
  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);

其中：

image為待文檔檢測(cè)的輸入圖片。

如果visionCallback為null，執(zhí)行同步調(diào)用，結(jié)果碼由方法返回，檢測(cè)結(jié)果由result返回。

如果visionCallback為有效的回調(diào)函數(shù)，則該函數(shù)為異步調(diào)用，函數(shù)返回時(shí)result中的值無效，實(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);

其中：

image為待文檔校正的輸入圖片。

如果visionCallback為null，執(zhí)行同步調(diào)用，結(jié)果碼由方法返回，校正結(jié)果由result中返回。

如果visionCallback為有效的回調(diào)函數(shù)，則該函數(shù)為異步調(diào)用，函數(shù)返回時(shí)result中的值無效，實(shí)際識(shí)別結(jié)果由回調(diào)函數(shù)返回。

同步模式調(diào)用成功時(shí)，該函數(shù)返回結(jié)果碼0。異步模式調(diào)用請(qǐng)求發(fā)送成功時(shí)，該函數(shù)返回結(jié)果碼700。

開發(fā)步驟

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

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() {
    @Override
    public void onServiceConnect() {
        // 定義連接能力引擎成功后的操作。
    }

    @Override
    public void onServiceDisconnect() {
        // 定義連接能力引擎失敗后的操作。
    }
};

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

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

在收到onServiceConnect回調(diào)連接服務(wù)成功后，實(shí)例化IDocRefine接口，將此工程的context作為入?yún)?，context應(yīng)為ohos.aafwk.ability.Ability或ohos.aafwk.ability.AbilitySlice的實(shí)例或子類實(shí)例。

IDocRefine docRefine = VisionManager.getDocRefine(context);

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

VisionImage image = VisionImage.fromPixelMap(pixelMap);

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

DocCoordinates docCoordinates = new DocCoordinates();

說明

該類在同步模式下用于存放檢測(cè)接口docDetect()傳出的文檔位置結(jié)果。

（可選）定義VisionCallback<DocCoordinates>回調(diào)。

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

說明

在異步模式下，該類的onResult()方法用于獲得檢測(cè)的結(jié)果docCoordinates（內(nèi)含檢測(cè)到的文檔坐標(biāo)）；onError()方法用于處理錯(cuò)誤返回碼；onProcessing()方法用于返回處理進(jìn)度，目前沒有實(shí)現(xiàn)此接口的功能。

同步與異步模式區(qū)別在于docDetect()的最后一個(gè)參數(shù)visionCallback是否為空。若非空則為異步模式，此時(shí)會(huì)忽略自定義的DocCoordinates輸入docCoordinates，接口調(diào)用結(jié)果一律從回調(diào)函數(shù)visionCallback獲得。

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

ImageResult imageResult = new ImageResult();

說明

該類在同步模式下用于存放校正docRefine()方法傳出的圖片結(jié)果。

（可選）定義VisionCallback<ImageResult>回調(diào)。

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

說明

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

通過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)用方通過反射的方式調(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();

說明
如果返回的result不為0，說明當(dāng)前文檔校正能力準(zhǔn)備失敗，需要處理錯(cuò)誤，不再執(zhí)行以后的動(dòng)作。在docDetect()和docRefine()方法中會(huì)首先調(diào)用prepare()啟動(dòng)引擎，如果引擎已經(jīng)啟動(dòng)則不會(huì)再次啟動(dòng)。

調(diào)用IDocRefine的docDetect()方法：

result = docRefine.docDetect(image, docCoordinates, null); // 同步

或者

result = docRefine.docDetect(image, null, callback); // 異步

說明

• 同步模式調(diào)用完成時(shí)，該函數(shù)立即返回結(jié)果碼。
• 異步模式調(diào)用請(qǐng)求發(fā)送成功時(shí)，該函數(shù)返回結(jié)果碼700。如果返回其他的值，說明異步調(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)用，說明檢測(cè)成功，相當(dāng)于同步模式結(jié)果碼為0的情況。
  • 如果onError()方法被調(diào)用，說明檢測(cè)發(fā)生了錯(cuò)誤，具體的調(diào)用結(jié)果碼將由onError()的參數(shù)接收。

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

調(diào)用IDocRefine的docRefine()方法：

result = docRefine.docRefine(image, docCoordinates, imageResult, null); // 同步

或者

result = docRefine.docRefine(image, docCoordinates, null, callback); // 異步

說明

• 同步模式調(diào)用完成時(shí)，該函數(shù)立即返回結(jié)果碼。
• 異步模式調(diào)用請(qǐng)求發(fā)送成功時(shí)，該函數(shù)返回結(jié)果碼700。如果返回其他的值，說明異步調(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)用，說明校正成功，相當(dāng)于同步模式結(jié)果碼為0的情況。
  • 如果onError()方法被調(diào)用，說明校正發(fā)生了錯(cuò)誤，具體的調(diào)用結(jié)果碼將由onError()的參數(shù)接收。

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

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

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

說明

不再使用文檔校正能力時(shí)，調(diào)用release()方法釋放資源。

調(diào)用VisionManager.destroy()方法，斷開與能力引擎的連接。文章來源地址http://www.zghlxwxcb.cn/news/detail-502554.html

VisionManager.destroy();

到了這里，關(guān)于HarmonyOS學(xué)習(xí)路之開發(fā)篇—AI功能開發(fā)（文檔檢測(cè)校正）的文章就介紹完了。如果您還想了解更多內(nèi)容，請(qǐng)?jiān)谟疑辖撬阉鱐OY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！