從 Mobile Vision 遷移至 Android 上的 ML Kit

本文件說明如何將專案從 Google Mobile Vision (GMV) 遷移至 Android 上的 ML Kit。

整體 API 變更

這些異動適用於所有 API：

  • GMV API 會同步傳回 SparseArray<T> 結果。ML Kit API 會使用 Google Play 服務 Task API，以非同步方式傳回結果。
  • GMV 會使用 API 介面中的 isOperational() 呼叫，指出模組是否已成功下載並可供使用。ML Kit 沒有這類方法。如果尚未下載模組，ML Kit 會擲回 MlKitException.UNAVAILABLE 例外狀況。您可以擷取這個例外狀況並處理下一個影格，或設定逾時並使用目前的影格重試。
  • GMV 方法使用 Frame 做為輸入。ML Kit 使用 InputImage。
  • GMV 提供 MultiDetector、MultiProcessor 和 FocusingProcessor 框架，可執行多項偵測和結果篩選。ML Kit 不提供這類機制，但開發人員可視需要自行實作相同功能。

更新 Gradle 匯入項目

在模組 (應用程式層級) Gradle 檔案 (通常是 app/build.gradle) 中，根據下表更新 ML Kit Android 程式庫的依附元件：

API GMV 構件 ML Kit 構件
FaceDetector com.google.android.gms:play-services-vision:x.x.x com.google.android.gms:play-services-mlkit-face-detection:17.1.0
BarcodeDetector com.google.android.gms:play-services-vision:x.x.x com.google.android.gms:play-services-mlkit-barcode-scanning:18.3.1
TextRecognition com.google.android.gms:play-services-vision:x.x.x com.google.android.gms:play-services-mlkit-text-recognition:19.0.2
CameraSource com.google.android.gms:play-services-vision:x.x.x com.google.mlkit:camera:16.0.0-beta3

API 變更

本節說明各個 Vision API 對應的 GMV 和 ML Kit 類別和方法，並說明如何初始化 API。

FaceDetector

請按照以下範例重新編寫初始化程式碼：

GMV

detector = new FaceDetector.Builder(context)
    .setMode(FaceDetector.ACCURATE_MODE)
    .setLandmarkType(FaceDetector.ALL_LANDMARKS)
    .setClassificationType(FaceDetector.ALL_CLASSIFICATIONS)
    .build();

ML Kit

FaceDetectorOptions options = new FaceDetectorOptions.Builder()
    .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_ACCURATE)
    .setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_ALL)
    .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
    .build();

detector = FaceDetection.getClient(options);

變更下列類別和方法名稱：

android.gms.vision.face mlkit.vision.face
FaceDetector FaceDetector
SparseArray<Face> detect(Frame frame) Task<List<Face>> process(@NonNull InputImage image)
FaceDetector.Builder.setClassificationType(int classificationType) FaceDetectorOptions.Builder.setClassificationMode(int classificationMode)
NO_CLASSIFICATIONS, ALL_CLASSIFICATIONS CLASSIFICATION_MODE_NONE, CLASSIFICATION_MODE_ALL
FaceDetector.Builder.setLandmarkType(int landmarkType) FaceDetectorOptions.Builder.setLandmarkMode(int landmarkMode)
NO_LANDMARKS, ALL_LANDMARKS, CONTOUR_LANDMARKS LANDMARK_MODE_NONE, LANDMARK_MODE_ALL

使用 #setContourMode 取代 GMV CONTOUR_LANDMARKS)

FaceDetector.Builder.setTrackingEnabled(boolean trackingEnabled) FaceDetectorOptions.Builder.enableTracking()
FaceDetector.Builder.setMinFaceSize(float proportionalMinFaceSize) FaceDetectorOptions.Builder.setMinFaceSize(float minFaceSize)
FaceDetector.Builder.setMode(int mode) FaceDetectorOptions.Builder.setPerformanceMode(int performanceMode)
FAST_MODE, ACCURATE_MODE PERFORMANCE_MODE_FAST, PERFORMANCE_MODE_ACCURATE
FaceDetector.Builder.setProminentFaceOnly(boolean prominentFaceOnly) 這項功能包含在臉部輪廓模式中。
Face Face
Contour FaceContour
Landmark FaceLandmark
Face.getContours() Face.getAllContours()
Face.getEulerY() Face.getHeadEulerAngleY()
Face.getEulerZ() Face.getHeadEulerAngleZ()
Face.getId() Face.getTrackingId()
Face.getIsLeftEyeOpenProbability() Face.getLeftEyeOpenProbability()
Face.getIsRightEyeOpenProbability() Face.getRightEyeOpenProbability()
Face.getIsSmilingProbability() Face.getSmilingProbability()
Face.getLandmarks() Face.getLandmark(int landmarkType)
Face.getPosition()
Face.getHeight()
Face.getWidth() 		Face.getBoundingBox()

BarcodeDetector

請按照以下範例重新編寫初始化程式碼：

GMV

barcodeDetector = new BarcodeDetector.Builder(context).build());

ML Kit

barcodeScanner = BarcodeScanning.getClient();

變更下列類別和方法名稱：

android.gms.vision.barcode mlkit.vision.barcode
BarcodeDetector BarcodeScanner
SparseArray<Barcode> detect(Frame frame) Task<List<Barcode>> process(@NonNull InputImage image)
Barcode Barcode

TextRecognition

請按照以下範例重新編寫初始化程式碼：

GMV

textRecognizer = new TextRecognizer.Builder(context).build();

ML Kit

textRecognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS);

變更下列類別和方法名稱：

android.gms.vision.text mlkit.vision.text
TextRecognizer TextRecognizer
SparseArray<TextBlock> detect(Frame frame) Task<Text> process(@NonNull InputImage image)
SparseArray<TextBlock> Text
Line Line
TextBlock TextBlock
Element Element
getLanguage() getRecognizedLanguage()
getBoundingBox() getBoundingBox()
getCornerPoints() getCornerPoints()
TextBlock.getComponents() TextBlock.getLines()
TextBlock.getValue() TextBlock.getText()
Element.getValue() Element.getText()

CameraSource

如果您使用 Google Mobile Vision 提供的 CameraSource 程式庫，只要應用程式在 SDK 最低版本 >= 21 的環境中執行，就能輕鬆遷移至 ML Kit 的 CameraXSource 程式庫。

變更下列類別和方法名稱：

android.gms.vision mlkit.vision.camera
CameraSource CameraSourceConfig
CameraSource.Builder CameraSourceConfig.Builder
CameraSource.Builder.setAutoFocusEnabled 使用 CameraX 時，系統預設會提供自動對焦功能。
CameraSource.Builder.setFacing CameraSourceConfig.Builder.setCameraFacing
CameraSource.Builder.setFocusMode 使用 CameraX 時，系統預設會提供自動對焦功能。
CameraSource.Builder.setRequestedFps 已淘汰。
CameraSource.Builder.setRequestedPreviewSize CameraSourceConfig.Builder.setRequestedPreviewSize
CameraSource CameraXSource
new CameraSource.Builder(mContext, detector)....build(); CameraXSource(CameraSourceConfig, PreviewView)
getCameraFacing() getCameraFacing()
getPreviewSize() getPreviewSize()
release() close()
start(SurfaceHolder surfaceHolder) start() // The previewview is set in the CameraSourceConfig
start() start()
stop() stop()
Detector.Processor DetectionTaskCallback
receiveDetections(Detections<T> detections) void onDetectionTaskReceived(@NonNull Task<ResultT> detectionTask);
release() 內部處理
CameraSource.PictureCallback 已淘汰
CameraSource.ShutterCallback 已淘汰

取得說明

如果遇到任何問題，請前往社群頁面，查看與我們聯絡的管道。