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

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

Thomas Steiner

什麼是 Shape Detection API？

有了 navigator.mediaDevices.getUserMedia 和 Chrome 適用於 Android 的相片挑選器等 API，您就能輕鬆透過裝置相機擷取相片或即時影像資料，或上傳本機相片。雖然圖片可能實際包含許多有趣的功能，例如臉孔、條碼和文字，但到目前為止，程式碼無法存取這類動態圖片資料，也無法存取網頁上的靜態圖片。

舉例來說，過去如果開發人員想在用戶端上擷取這類功能來建構 QR code reader，就必須仰賴外部 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);
}

特徵偵測

單純檢查建構函式是否存在，以便偵測形狀偵測 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 服務。

最佳做法

所有偵測器都以非同步方式運作，也就是不會阻斷主執行緒。因此，請不要依賴即時偵測功能，而是讓偵測器有足夠的時間執行。

如果您是 Web Workers 的愛用者，您會很高興知道偵測器也會在那裡公開。偵測結果可序列化，因此可透過 postMessage() 從 worker 傳遞至主應用程式。示範會顯示實際運作情形。

並非所有平台實作都支援所有功能，因此請務必仔細檢查支援情況，並將 API 做為漸進式增強功能使用。舉例來說，部分平台可能支援臉部偵測，但不支援臉部地標偵測 (眼睛、鼻子、嘴巴等)；或是可以辨識文字的存在和位置，但無法辨識文字內容。

意見回饋

Chrome 團隊和網路標準社群希望瞭解您使用 Shape Detection API 的體驗。

請說明 API 設計

API 是否有任何部分無法正常運作？或者，您是否缺少實作想法所需的方法或屬性？您對安全性模型有疑問或意見嗎？

導入時發生問題？

你是否發現 Chrome 實作項目有錯誤？還是實作方式與規格不同？

  • 請前往 https://new.crbug.com 提交錯誤。請務必提供盡可能多的詳細資訊、重現問題的簡單操作說明，並將「Component」設為 Blink>ImageCapture。Glitch 可讓您輕鬆快速地分享重現內容。

打算使用 API 嗎？

是否打算在網站上使用 Shape Detection API？您的公開支援內容有助於我們排定功能優先順序，並向其他瀏覽器供應商顯示支援這些功能的重要性。

實用連結