画像における高速形状検出

1. はじめに

写真や画像はウェブ上で最も大きな割合を占めており、多くは人の顔やバーコード/QRコードのような認識可能な特徴を含んでいます。これらの特徴を検出する処理は計算コストが高いですが、顔のタグ付けやウェブURLへのリダイレクトなど興味深いユースケースを生みます。ハードウェアメーカーは長年これらの機能をサポートしてきましたが、Webアプリはまだこれらのハードウェア機能にアクセスできないため、計算負荷の高いライブラリを使用する必要があることが多いです。

Text Detection は興味深い分野ではありますが、本書の文脈では計算プラットフォームや文字セット全体で十分に安定しているとは見なせないため標準化の対象にしていません。参照用として姉妹の情報仕様は [TEXT-DETECTION-API] に保持されています。

1.1. 形状検出のユースケース

リポジトリの Readme/Explainer を参照してください。

2. 形状検出 API

個々のブラウザは、加速処理を提供するハードウェアの利用可能性を示す Detectors を提供してもよい（MAY）ものとします。

画像内の特徴検出は非同期で行われ、ブラウザとは独立して加速ハードウェアと通信する可能性があります。完了イベントは shape detection task source を使用します。

2.1. 検出のための画像ソース

本節は HTML Canvas 2D Context § image-sources-for-2d-rendering-contexts に触発されています。

ImageBitmapSource は、複数のインターフェイスを実装するオブジェクトを検出処理の画像ソースとして使用できるようにします。

• ImageBitmapSource オブジェクトが HTMLImageElement を表す場合、その要素の画像がソース画像として使われなければなりません。具体的には、ImageBitmapSource オブジェクトが HTMLImageElement におけるアニメーション画像を表す場合、ユーザーエージェントはアニメーションのデフォルト画像（フォーマットがアニメーションをサポートしないか無効なときに使用されると定義される画像）を使用しなければならず、もしそのような画像が存在しない場合はアニメーションの最初のフレームを使用しなければなりません。

• ImageBitmapSource オブジェクトが HTMLVideoElement を表す場合、メソッド呼び出し時点の再生位置のフレームをソース画像として使用しなければならず、ソース画像の寸法はメディアリソースの intrinsic dimensions（アスペクト比補正後）としなければなりません。

• ImageBitmapSource オブジェクトが HTMLCanvasElement を表す場合、その要素のビットマップをソース画像として使用しなければなりません。

UA が任意の検出器の detect() メソッドの入力引数として特定の型の ImageBitmapSource を使用することを要求される場合、UA は次の手順を実行しなければなりません（MUST）:

• 任意の ImageBitmapSource がドキュメントの有効スクリプトオリジンと異なる有効スクリプトオリジン（origin）を持つ場合、Promise を新しい DOMException （name が SecurityError）で拒否しなければなりません。

• ImageBitmapSource が HTMLImageElement で Broken（HTML Standard §img-error）状態にある場合、Promise を新しい DOMException （name が InvalidStateError）で拒否し、以降の手順を中止しなければなりません。

• ImageBitmapSource が完全にデコードできない HTMLImageElement である場合、Promise を新しい DOMException （name が InvalidStateError）で拒否し、以降の手順を中止しなければなりません。

• ImageBitmapSource が HTMLVideoElement であり、その readyState 属性が HAVE_NOTHING または HAVE_METADATA の場合、Promise を新しい DOMException （name が InvalidStateError）で拒否し、以降の手順を中止しなければなりません。

• ImageBitmapSource 引数が HTMLCanvasElement で、そのビットマップの origin-clean フラグ（HTML Standard §concept-canvas-origin-clean）が false の場合、Promise を新しい DOMException （name が SecurityError）で拒否し、以降の手順を中止しなければなりません。

注意: ImageBitmapSource が横または縦の寸法のいずれかがゼロのオブジェクトである場合、Promise は単に空の検出オブジェクト列で解決されます。

2.2. 顔検出 API

FaceDetector は画像中の人間の顔を検出するための、基盤となる加速プラットフォームのコンポーネントを表します。これはオプションの Dictionary FaceDetectorOptions を用いて生成できます。detect() 操作を一つ提供し、引数に ImageBitmapSource を取り、結果は Promise です。このメソッドは § 2.1 Image sources for detection に詳述された場合にはこの Promise を拒否しなければならず（MUST）、それ以外の場合は OS/プラットフォームのリソースを利用するタスクをキューして、各々が本質的に boundingBox で区切られる DetectedFace の列（Sequence）で Promise を解決することができます（MAY）。

[Exposed=(Window,Worker),
 SecureContext]
interface FaceDetector {
  constructor(optional FaceDetectorOptions faceDetectorOptions = {});
  Promise<sequence<DetectedFace>> detect(ImageBitmapSource image);
};

FaceDetector(optional FaceDetectorOptions faceDetectorOptions)

オプションの faceDetectorOptions を使って新しい FaceDetector を構築します。

検出器は多大なリソースを割り当てて保持する可能性があります。可能であれば、複数の検出に対して同じ FaceDetector を再利用してください。

detect(ImageBitmapSource image)

渡された ImageBitmapSource image に対して人間の顔を検出しようとします。検出された顔は、存在する場合 DetectedFace の列として返されます。

2.2.1. FaceDetectorOptions

dictionary FaceDetectorOptions {
  unsigned short maxDetectedFaces;
  boolean fastMode;
};

maxDetectedFaces, の型は unsigned short

UA に対して、検出シーン中の検出対象顔の数をこの最大数に制限するよう試みるヒントを与えます。

fastMode, の型は boolean

速度を精度より優先するよう UA に指示するヒントです。例えば縮小スケールで動作したり大きな特徴を優先的に探します。

2.2.2. DetectedFace

dictionary DetectedFace {
  required DOMRectReadOnly boundingBox;
  required sequence<Landmark>? landmarks;
};

boundingBox, の型は DOMRectReadOnly

検出された特徴の位置と範囲を、画像軸に沿った長方形で示します。

landmarks, の型は sequence<Landmark> nullable

検出された特徴に関連する興味ある複数のサブ特徴の列を表します。

dictionary Landmark {
  required sequence<Point2D> locations;
  LandmarkType type;
};

locations, の型は sequence<Point2D> 

検出されたランドマークの中心点、またはランドマークを囲む単純多角形の頂点を時計回りか反時計回りの順で定義する点の列です。

type, の型は LandmarkType

可能であればランドマークの種類を示します。

enum LandmarkType {
  "mouth",
  "eye",
  "nose"
};

mouth

そのランドマークは人間の口として識別されます。

eye

そのランドマークは人間の目として識別されます。

nose

そのランドマークは人間の鼻として識別されます。

[SameObject] readonly attribute unsigned long id;

2.3. バーコード検出 API

BarcodeDetector は画像中の一次元または二次元バーコードの検出のための基盤となる加速プラットフォームのコンポーネントを表します。これは引数に ImageBitmapSource を取る単一の detect() 操作を提供し、結果は Promise です。このメソッドは § 2.1 Image sources for detection に詳述されたケースではこの Promise を拒否しなければならず（MUST）、それ以外の場合は OS/プラットフォームのリソースを用いるタスクをキューして、各々が本質的に boundingBox と一連の Point2D を含み、場合によってはデコードされた rawValue （DOMString）で Promise を解決することができます（MAY）。

[Exposed=(Window,Worker),
 SecureContext]
interface BarcodeDetector {
  constructor(optional BarcodeDetectorOptions barcodeDetectorOptions = {});
  static Promise<sequence<BarcodeFormat>> getSupportedFormats();

  Promise<sequence<DetectedBarcode>> detect(ImageBitmapSource image);
};

BarcodeDetector(optional BarcodeDetectorOptions barcodeDetectorOptions)

barcodeDetectorOptions を用いて新しい BarcodeDetector を構築します。

• もし barcodeDetectorOptions.formats が存在しかつ空であれば、新しい TypeError を投げます。

• もし barcodeDetectorOptions.formats が存在し、かつ unknown を含む場合、新しい TypeError を投げます。

検出器は多大なリソースを割り当てて保持する可能性があります。可能であれば、複数の検出に対して同じ BarcodeDetector を再利用してください。

getSupportedFormats()

このメソッドは呼び出されると新しい Promise を返し、次の手順を並列で実行しなければなりません：

1. supportedFormats を新しい Array とする。
2. もし UA がバーコード検出をサポートしていないなら、グローバルタスクをキューし、関連グローバルオブジェクト 上で shape detection task source を使って resolve によって promise を supportedFormats で解決し、手順を中止します。
3. UA が画像中で検出可能だと理解する BarcodeFormat を列挙し、これらを supportedFormats に追加します。
   UA は例えば記号の配置やエンコーディングエラー等により、特定の画像上で常に認識されるかどうかを確定的に答えることはできません。ただし、もしあるシンボロジーが supportedFormats 配列にない場合、そのシンボロジーは全く検出されないべきです。
4. グローバルタスクをキューし、関連グローバルオブジェクト 上で shape detection task source を使って resolve によって promise を supportedFormats で解決します。

サポートされる BarcodeFormat の一覧はプラットフォーム依存です。例として Google Play Services や Apple の CIQRCodeFeature が挙げられます。

detect(ImageBitmapSource image)

渡された ImageBitmapSource image に対してバーコードを検出しようとします。

2.3.1. BarcodeDetectorOptions

dictionary BarcodeDetectorOptions {
  sequence<BarcodeFormat> formats;
};

formats, of type sequence<BarcodeFormat>

後続の BarcodeFormat を detect() 呼び出しで検索するためのフォーマットのリストです。未指定の場合、UAはサポートされているすべてのフォーマットを検索するべきです。

検索対象をサポートフォーマットの特定のサブセットに限定すると、より良いパフォーマンスが得られる可能性があります。

2.3.2. DetectedBarcode

dictionary DetectedBarcode {
  required DOMRectReadOnly boundingBox;
  required DOMString rawValue;
  required BarcodeFormat format;
  required sequence<Point2D> cornerPoints;
};

boundingBox, of type DOMRectReadOnly

画像に整列した検出された特徴の位置と範囲を示す長方形

rawValue, of type DOMString

バーコードからデコードされた文字列。この値は複数行の場合もあります。

format, of type BarcodeFormat

検出された BarcodeFormat を示します。

cornerPoints, of type sequence<Point2D>

検出されたバーコードの隅の座標列（時計回りで左上から）。遠近歪みの影響により必ずしも正方形とは限りません。

2.3.3. BarcodeFormat

enum BarcodeFormat {
  "aztec",
  "code_128",
  "code_39",
  "code_93",
  "codabar",
  "data_matrix",
  "ean_13",
  "ean_8",
  "itf",
  "pdf417",
  "qr_code",
  "unknown",
  "upc_a",
  "upc_e"
};

aztec

この値は、[iso24778] に準拠する正方形の2次元マトリクスであり、中央に正方形の同心模様（ブルズアイパターン）があるためアステカのピラミッドに似ています。周囲の余白ゾーンは必要ありません。

code_128

Code 128 は、[iso15417] に準拠した線形（一次元）、双方向デコード可能かつ自己チェック型のバーコードで、ASCIIの128文字すべてをエンコードできます。

code_39

この部分は Code 39 バーコードについて説明します。これは、離散型で可変長のバーコード形式です。[iso16388]

code_93

Code 93は、可変長の連続型線形バーコードで、[bc5] に従います。Code 128や見た目の似たCode 39よりも高密度に情報を保持できます。主にカナダポストで補助配送情報のエンコードに使われています。

codabar

Codabarは、1972年にPitney Bowes社によって開発された線形バーコードです。

data_matrix

Data Matrixは、[iso16022] に準拠する黒と白のモジュールで構成される正方形または長方形パターンの、方向依存性のない2次元バーコードです。

ean_13

EAN-13 は、UPC-A規格に基づく線形バーコードで、[iso15420]で定義されています。当初、欧州EAN協会により開発され、アメリカのUPCシステムの上位互換として設計されました（UPC-AコードはEAN-13の先頭に0を置いた形で表現されます）。

ean_8

EAN-8は、[iso15420] で定義されている線形バーコードで、EAN-13の派生です。

itf

ITF14バーコードは、グローバルトレードアイテムナンバーを符号化するためのInterleaved 2 of 5バーコードのGS1実装であり、常に14桁を符号化します。かつては配送業界で使われていましたが、Code 128に置き換えられました。[bc2]

pdf417

PDF417は、複数行・複数列からなる連続2次元バーコード規格で、双方向デコード可能です。標準は[iso15438] に準拠しています。

qr_code

QRコードは、テキスト・URL・その他のデータを符号化可能な2次元バーコードであり、標準規格 [iso18004] に準拠します。

unknown

この値は、どのバーコードフォーマットが検出・サポートされているかプラットフォームが不明または指定しないことを示します。

upc_a

UPC-A は、アメリカで広く使われる最も一般的な線形バーコードの一つです。[iso15420]で定義されており、各桁を異なる幅のバーとスペース2つずつの組み合わせで表現します。UPC-Aは12桁の数値を符号化でき、技術的にはEAN-13のサブセットです（UPC-AコードはEAN-13の先頭に0が付与されます）。

upc_e

UPC-Eバーコードは、UPC-Aのバリエーションで、[iso15420] に定義されています。不要なゼロを圧縮してコンパクト化されたバーコードです。

3. セキュリティおよびプライバシーに関する考慮事項

このセクションは規範的ではありません。

このインターフェイスは画像ソースの内容に関する情報を公開します。実装において、このインターフェイスが本来画像ソースの検査から保護する保護策を回避するために使われないことを確実にすることは極めて重要です。§2.1 検出対象画像ソースにて、このためのアルゴリズムを説明します。

高性能な形状検出機能を提供することで、このインターフェイスは開発者がローカルデバイス上で画像解析タスクを実行できるようにします。これは計算をリモートシステムにオフロードする場合に比べ、プライバシー上の利点となります。開発者は、このインターフェイスが返す結果を元画像と同じくらいプライバシーに敏感なものと見なすべきです。

4. 例

このセクションは規範的ではありません。

これらの例の若干修正版や拡張例（および他の例）も、例えば この Codepen コレクション で確認できます。

4.1. 特定検出器のプラットフォームサポート

if (window.FaceDetector == undefined) {
  console.error('Face Detection not supported on this platform');
}
if (window.BarcodeDetector == undefined) {
  console.error('Barcode Detection not supported on this platform');
}

4.2. 顔検出

let faceDetector = new FaceDetector({fastMode: true, maxDetectedFaces: 1});
// Assuming |theImage| is e.g. a <img> content, or a Blob.

faceDetector.detect(theImage)
.then(detectedFaces => {
  for (const face of detectedFaces) {
    console.log(
        ' Face @ (${face.boundingBox.x}, ${face.boundingBox.y}),' +
        ' size ${face.boundingBox.width}x${face.boundingBox.height}');
  }
}).catch(() => {
  console.error("Face Detection failed, boo.");
})

4.3. バーコード検出

let barcodeDetector = new BarcodeDetector();
// Assuming |theImage| is e.g. a <img> content, or a Blob.

barcodeDetector.detect(theImage)
.then(detectedCodes => {
  for (const barcode of detectedCodes) {
    console.log(' Barcode ${barcode.rawValue}' +
        ' @ (${barcode.boundingBox.x}, ${barcode.boundingBox.y}) with size' +
        ' ${barcode.boundingBox.width}x${barcode.boundingBox.height}');
  }
}).catch(() => {
  console.error("Barcode Detection failed, boo.");
})