設定

以下のオプションはすべて FaceCaptureSession に渡されます。core では直接、Web では MeeeetUpCamProvider を通じて、React Native では useFaceCaptureSession を通じて渡されます。いずれの既定値も、SDK がこれまで取ってきた挙動そのものです。そのため、何も設定していない統合はこれまでとまったく同じように動作します。

キャプチャ条件

オプション	既定値	内容
`minDetectionScore`	`0.5`	検出がそもそもトラッキング対象になるために必要な、検出器の確信度（0–1）です。検出器がドア枠やポスターを囲ってしまうようなノイズの多い場面では、この値を上げます。
`minFaceHeight`	`0`（無効）	フレーム高さに対する顔ボックス高さの最小値（0–1）です。背景の人物を無視する最も軽い方法で、これより小さい顔はトラッキングもスコア計算も切り出しも行われません。
`minFrontalness`	`50`	あるフレームがその顔の使えるフレームとみなされるために必要な、正面度スコア（0–100）です。これを下回る顔は、トラッキングはされますがキャプチャされません。
`captureWindowMs`	`0`（無効）	顔ごとのベストショット探索ウィンドウの長さです。`0` の場合は、スコアが落ち着くのを待つ従来どおりのキャプチャになります。
`cooldownMs`	`10_000`	同じ顔をキャプチャする間隔の最小値です。ウィンドウを設定している場合は、その顔が再びキャプチャ可能になるまでの待ち時間になります。

次の2つは、変更する機会がこれより少ない設定です。

オプション	既定値	内容
`batchIntervalMs`	`10_000`	パッシブのみ。バッファされた顔を `onBatchCapture` に渡す頻度です。
`maxFacesPerRequest`	`50`	1つのバッチに含められる顔の数です。バックエンドの1リクエストあたりの上限に合わせてください。

検出確度は正面度ではない

minDetectionScore はそこに顔があるかに答え、minFrontalness はその顔がこちらを向いているかに答えます。両者を分けているのは意図的です。ML Kit は確信度を 1.0 に固定して返すのに対し、MediaPipe は 0.70–0.95 を返すため、片方をもう片方に畳み込むと、Web 側でだけ品質のしきい値が気づかないうちに厳しくなってしまいます。

ベストショットウィンドウ

captureWindowMs を指定しない場合、SDK は正面度スコアの向上が止まった時点でその顔をキャプチャします。スコアを平滑化し、ピークが10フレーム保たれるのを待って確定します。人が自分のタイミングで出入りする通路を見るカメラには、この動作が適しています。

一方、受付端末には適していません。画面の前に立っている人の映像は落ち着くことがなく、10フレームの待機と10秒のクールダウンによって、0.5秒の時点で選ばれたフレームが、1.5秒の時点のより良いフレームに差し替えられることは決してないからです。

captureWindowMs を設定すると、代わりに顔ごとに時間の区切られた探索が行われます。

ウィンドウは、その顔でキャプチャに値する最初のフレームで開きます。条件は、300ms のトラッキング継続と、minFrontalness 以上のフレームが3枚あることです。
ウィンドウが開いている間は、保持中のフレームを上回るフレームが来るたびに、その場で差し替えられ、final: false として通知されます。
ウィンドウが時間切れになると、保持中のフレームが final: true としてもう一度通知され、その顔は確定します。

const session = new FaceCaptureSession({
  sessionType: "interactive",
  captureWindowMs: 2_000,
  minFrontalness: 55,
  onSelect: (face) => {
    setPreview(face.dataUrl);        // updates live as the subject improves
    if (face.final) commit(face);    // the photo
  },
});

ウィンドウは顔ごとです。これによって1つの仕組みで両方のモードをまかなえます。インタラクティブセッションは対象が1人なのでウィンドウも1つ、パッシブセッションはその場にいるすべての顔について独立したウィンドウを動かします。

時間は顔が映っている間だけ進む

ウィンドウの時間は、その顔が実際に映っているフレームでのみ加算されます。画面外に出てから戻ってきた人はウィンドウを失いませんし、バックグラウンドで間引かれたタブも時間を消費しません。250ms を超える1回の間隔は、250ms として数えます。「2秒探索する」とは、対象が映っている状態での2秒を意味します。

再アーム

閉じたウィンドウは閉じたままです。そのため受付端末が、そこに立ち続けている人を撮り直し続けることはありません。

パッシブ: ウィンドウが閉じてから cooldownMs が経過すると、その顔は自動的に再アームされます。
インタラクティブ: 次のキャプチャを行いたい時点で session.rearm()、または useMeeeetUpCam() の cam.rearm() を呼び出します。これが「撮り直す」ボタンにあたります。

ウィンドウの途中でフレームから外れた顔は、その時点で保持していたフレームで確定します。何も残さないより、得られた中で最良のフレームを残すほうがよいためです。

しきい値の決め方

適切な値はレンズ、照明、人が立つ距離によって変わるため、推測せずに実測してください。ライブデモは4つの条件をすべてスライダーに載せ、現在の測定値を横に表示します。そこでキャプチャされるフレームは、この設定が実際に送信していたはずのフレームそのものです。

出発点として妥当な値は次のとおりです。

設置例	設定
受付。一度に1人が対象	`captureWindowMs: 2000`, `minFaceHeight: 0.2`, `minFrontalness: 55`
出入口。人が通り過ぎる	`captureWindowMs: 0`, `minFaceHeight: 0.12`, `cooldownMs: 30_000`
広い部屋。複数の顔が同時に映る	`captureWindowMs: 3000`, `minFaceHeight: 0.08`, `minFrontalness: 45`

受け取る内容

選択された顔は、すべて SelectedFace として渡されます。

フィールド	意味
`trackId`	その顔がトラッキングされている間は変わりません。
`dataUrl`	256×256 の JPEG データ URI。そのまま POST できます。
`frontalness`	選ばれたフレームの正面度スコア（0–100）です。
`final`	ウィンドウがまだこのフレームを差し替える可能性がある間は `false`、差し替えられなくなると `true` です。ウィンドウを使わない場合は常に `true` です。
`createdAt`	その顔を最初に検出した時刻です。
`lastSentAt`	この選択が通知された時刻です。

人物の同定は SDK の役割ではありません。2つの trackId は2つのトラックであって、必ずしも2人の人物ではありません。重複排除と認識は、画像を受け取る側の責務です。