Shape Detection API：一張圖片勝過千言萬語、臉孔和條碼

Shape Detection API 會偵測圖片中的臉孔、條碼和文字。

湯瑪斯.史坦納 (Thomas Steiner)

什麼是 Shape Detection API？

有了 navigator.mediaDevices.getUserMedia 和 Chrome for Android 相片挑選工具等 API，您就可以輕鬆從裝置相機擷取圖片或即時影像資料，或是上傳本機圖片。到目前為止，即使圖片實際上可能包含許多有趣的功能，例如臉孔、條碼和文字，但程式碼並無法存取這些動態圖片資料和網頁上的靜態圖片。

例如，過去如果開發人員想要在用戶端擷取這類功能，以建構 QR 程式碼讀取器，就必須依賴外部 JavaScript 程式庫。因此，實際做法可能相當高昂，價格看似高昂，而且能增加網頁的整體權重。另一方面，包括 Android、iOS 和 macOS 等作業系統，以及相機模組中的硬體晶片，通常都具備效能卓越且經過最佳化的功能偵測工具，例如 Android FaceDetector 或 iOS 一般功能偵測工具 CIDetector。

Shape Detection API 會透過一組 JavaScript 介面公開這些實作內容。目前支援的功能包括透過 FaceDetector 介面進行臉部偵測、透過 BarcodeDetector 介面偵測條碼，以及透過 TextDetector 介面進行文字偵測 (光學字元辨識，OCR)。

建議用途

如上所述，Shape Detection API 目前支援偵測臉孔、條碼和文字。以下條列式清單提供這三項功能的用途範例。

臉部偵測

  • 線上社群網路或相片分享網站通常可讓使用者在圖片中加註人物。只要醒目顯示偵測到的臉孔邊界，就可以加快這項工作
  • 內容網站可根據偵測到的臉孔動態裁剪圖片，而非仰賴其他經驗法則；或使用類似 Ken Burns 的平移和縮放效果，以類似故事的格式呈現偵測到的臉孔。
  • 使用者可透過多媒體訊息網站，在偵測到的臉部地標上疊加「太陽眼鏡或鬍子」等有趣物體。

條碼偵測

  • 讀取 QR code 的網頁應用程式可解鎖有趣的用途，例如線上付款或網頁導航，或使用條碼在訊息應用程式上建立社交連結。
  • 購物應用程式可讓使用者掃描實體商店中的 EAN 或 UPC 條碼，比較線上價格。
  • 機場可提供網路資訊站，讓乘客掃描登機證的 Aztec 代碼，顯示與航班相關的個人化資訊。

文字偵測

  • 線上社群網站可以藉由在未提供其他說明的情況下，將偵測到的文字新增為 <img> 標記的 alt 屬性，藉此提升使用者產生圖片內容的無障礙功能。
  • 內容網站可以使用文字偵測功能，避免將標題置於含有文字的主頁橫幅上方。
  • 網頁應用程式可使用文字偵測功能翻譯文字，例如餐廳菜單。

目前狀態

步驟 狀態
1. 建立說明 完成
2. 建立規格的初始草稿 完成
3.收集意見回饋並改進設計 進行中
4. 來源試用 完成
5.啟動 條碼偵測完成
進行臉部偵測
文字偵測進行中

如何使用 Shape Detection API

如要在本機測試 Shape Detection API，請在 about://flags 中啟用 #enable-experimental-web-platform-features 標記。

FaceDetector、BarcodeDetector 和 TextDetector 這三個偵測工具的介面都相似。這些方法都提供名為 detect() 的單一非同步方法，此方法採用 ImageBitmapSource 做為輸入 (即 CanvasImageSource、Blob 或 ImageData)。

如果是 FaceDetector 和 BarcodeDetector，您可以將選用參數傳遞至偵測工具的建構函式，以提供提示給基礎偵測工具。

請詳閱說明中的支援矩陣，瞭解不同平台的概要說明。

使用 BarcodeDetector

BarcodeDetector 會傳回在 ImageBitmapSource 和定界框中找到的條碼原始值，以及其他資訊，例如偵測到的條碼格式。

const barcodeDetector = new BarcodeDetector({
  // (Optional) A series of barcode formats to search for.
  // Not all formats may be supported on all platforms
  formats: [
    'aztec',
    'code_128',
    'code_39',
    'code_93',
    'codabar',
    'data_matrix',
    'ean_13',
    'ean_8',
    'itf',
    'pdf417',
    'qr_code',
    'upc_a',
    'upc_e'
  ]
});
try {
  const barcodes = await barcodeDetector.detect(image);
  barcodes.forEach(barcode => searchProductDatabase(barcode));
} catch (e) {
  console.error('Barcode detection failed:', e);
}

使用 FaceDetector

FaceDetector 一律會在 ImageBitmapSource 中傳回偵測到的臉孔定界框。視平台而定，或許能取得有關眼睛、鼻子或嘴巴等臉孔地標的更多資訊。請注意，這個 API 只會偵測臉孔。 無法識別臉孔屬於誰的。

const faceDetector = new FaceDetector({
  // (Optional) Hint to try and limit the amount of detected faces
  // on the scene to this maximum number.
  maxDetectedFaces: 5,
  // (Optional) Hint to try and prioritize speed over accuracy
  // by, e.g., operating on a reduced scale or looking for large features.
  fastMode: false
});
try {
  const faces = await faceDetector.detect(image);
  faces.forEach(face => drawMustache(face));
} catch (e) {
  console.error('Face detection failed:', e);
}

使用 TextDetector

TextDetector 一律會回傳偵測到的文字的定界框，並在某些平台上傳回可辨識的字元。

const textDetector = new TextDetector();
try {
  const texts = await textDetector.detect(image);
  texts.forEach(text => textToSpeech(text));
} catch (e) {
  console.error('Text detection failed:', e);
}

功能偵測

單純檢查建構函式是否存在，來功能偵測 Shape Detection API 並不足夠。即使出現介面，也不會指出基礎平台是否支援該項功能。這可按預期方式運作。因此我們建議採用防禦程式設計方法進行下列功能偵測：

const supported = await (async () => 'FaceDetector' in window &&
    await new FaceDetector().detect(document.createElement('canvas'))
    .then(_ => true)
    .catch(e => e.name === 'NotSupportedError' ? false : true))();

BarcodeDetector 介面已更新，加入 getSupportedFormats() 方法和類似介面的建議 FaceDetector 和 TextDetector 適用。

await BarcodeDetector.getSupportedFormats();
/* On a macOS computer logs
  [
    "aztec",
    "code_128",
    "code_39",
    "code_93",
    "data_matrix",
    "ean_13",
    "ean_8",
    "itf",
    "pdf417",
    "qr_code",
    "upc_e"
  ]
*/

藉此偵測所需的特定功能，例如掃描 QR code：

if (('BarcodeDetector' in window) &&
    ((await BarcodeDetector.getSupportedFormats()).includes('qr_code'))) {
  console.log('QR code scanning is supported.');
}

這比隱藏介面更好，因為即使是不同平台，功能也可能不同，因此應建議開發人員檢查其所需的精確功能 (例如特定條碼格式或臉部地標)。

作業系統支援

條碼偵測功能適用於 macOS、ChromeOS 和 Android。Android 必須啟用 Google Play 服務。

最佳做法

所有偵測工具皆以非同步方式運作，也就是不會封鎖主執行緒。因此，請不要依賴即時偵測，而是讓偵測工具有時間處理。

如果您喜歡網路工作站，您會很高興得知偵測工具也存在。偵測結果可以序列化，因此可以透過 postMessage() 從工作站傳送至主要應用程式。您可以透過示範瞭解實際運作情形。

並非所有平台實作都支援所有功能，因此請務必仔細查看支援情況，並使用此 API 做為漸進式強化。例如，某些平台可能支援臉部偵測 (眼睛、鼻子、嘴巴等) 的功能，或者是存在和位置和文字位置，但無法辨識文字內容。

意見回饋：

Chrome 團隊和網路標準社群希望瞭解您對 Shape Detection API 的想法。

告訴我們 API 設計

該 API 有什麼功能不如預期嗎？或是您需要實作提案的方法或屬性嗎？如果您對安全性模型有任何疑問或意見，

實作時遇到問題嗎？

您在執行 Chrome 時發現錯誤了嗎？還是實作與規格不同？

  • 前往 https://new.crbug.com 回報錯誤。請務必附上大量詳細資料、簡單的重現指示，並將「元件」設為 Blink>ImageCapture。Glitch 適合用來快速分享簡單快速的作品。

打算使用 API 嗎？

打算在網站上使用 Shape Detection API 嗎？您的公開支持可協助我們決定各項功能的優先順序，以及向其他瀏覽器廠商瞭解這項功能有多重要。

實用連結