react-native-vision-camera-realtime

リアルタイムのVisionCameraパイプライン

これはreact-native-vision-cameraを補完する専門ガイドです。個別の段階だけでなく、Cameraバッファから最終結果までの全経路を最適化してください。正確なAPIを利用する前に、インストール済みバージョンと最新のVisionCameraドキュメント、および利用側の公式ドキュメントまたはソースを確認してください。

最終的な利用先に応じて選ぶ

最終的な利用先	推奨する経路
フレームと連動する描画、エフェクト、オーバーレイ	<SkiaCamera />またはWebGPUを使い、処理と描画を同じGPUタイムライン上に維持します
WGSLコンピュートまたはGPU推論	Frame.getNativeBuffer()からWebGPU動画フレームを経由してdevice.importExternalTexture(...)へ渡します
VisionCameraに依存するネイティブプラグイン	ホットメソッドが型付きFrameを受け取る、長寿命のNitro HybridObject
VisionCameraに依存しないネイティブライブラリ	型なしのNativeBufferポインターと明示的な解放契約
状態のみを扱うMLまたはスキャン	プラットフォームのランタイムをANEまたはNPU、GPU、CPUのバックエンド間でベンチマークし、コンパクトな状態を返します
CPUのみを使う利用先	必要十分な最小の解像度とフォーマットを使い、上限を設けた再利用可能なCPUバッファ経路を使用します

Nitro、NativeBuffer、WebGPU、Skia、Resizer、またはArrayBufferの相互運用を実装またはレビューする場合に限り、references/interop.mdを読み込んでください。

ホットパスの不変条件

1. 向きとミラーリングはメタデータとして保持します。enablePhysicalBufferRotation: falseを設定し、frame.orientationとframe.isMirroredを利用先に渡すか、拡大縮小、クロップ、描画と同じGPU変換で適用してください。Cameraバッファを物理的に回転させないでください。
2. 1つの実行ドメインとメモリドメインを維持します。GPUパイプラインでは、一度だけインポートし、前処理、推論、後処理、描画をGPU上に維持します。必要な場合に限り、コンパクトな結果を読み戻してください。
3. 検証済みのGPU専用経路ではpixelFormat: 'native'を優先します。解決されたネイティブフォーマットがYUV、RGB、RAW、またはプライベート形式のいずれかを確認するため、frame.pixelFormatとframe.hasNativeBufferをチェックしてください。
4. 通常のGPU経路では、getPixelBuffer()、getPlanes()、プレーンのピクセルバッファ、マッピング済みGPUバッファ、型付きピクセルビューを使わないでください。CPUからの参照によって同期またはダウンロードが発生する場合があります。
5. パイプライン、シェーダー、サンプラー、モデルセッション、リサイザー、大容量バッファ、ネイティブプロセッサーは一度だけ作成してウォームアップします。コンポーネントまたはセッションの存続期間中は再利用し、フレームごとに割り当てないでください。
6. フレームと連動するオーバーレイは、同じFrameからSkiaまたはWebGPUで描画します。フレームごとのジオメトリをReactの状態、通常のビュー、またはReanimatedの共有値を経由して渡さないでください。
7. すべての経路で、各Frame、NativeBuffer、ラッパー、テクスチャ、プールスロットを必ず一度だけ解放してください。ラッパーは所有権の逆順で解放し、最後にFrameを破棄してください。

同じフレーム内での処理を優先する

視覚的に一致させる必要がある場合は、検出、トラッキング、判断、描画を、対応するフレームと同期して行います。60 FPS では許容される間隔は 16.67 ms、30 FPS では 33.33 ms です。スケジューリングの余裕を確保するため、目標はそれぞれおよそ 16 ms 未満、33 ms 未満にします。

「同期」とは、同じフレーム内でデータを処理することであり、GPU の処理が終わるまで CPU をブロックすることではありません。可能であれば、依存する GPU ステージを 1 つのコマンドグラフにまとめます。フレームごとに queue.onSubmittedWorkDone()、バッファーのマッピング、読み戻し、または別の CPU／GPU フェンスを追加しないでください。

処理を非同期にする前に、コピーや読み戻しの削減、入力解像度や FPS の低減、パスの統合、モデルのテンソルの最適化、ウォームアップ済みの状態の再利用を行います。最適化しても処理がフレーム間隔に収まらず、製品が古い結果を許容する場合（多くの場合、およそ 50 ms 以上の場合）に限り、非同期処理を使用します。フレームに連動するビジュアルでは、目に見える遅延を生じさせるより、処理を簡略化することを優先します。

非同期で結果を配信する方法には、同等の選択肢が 3 つあります。

• 完了コールバックを保持するネイティブ Nitro 処理
• 完了した状態を保存し、同期的な最新状態ゲッターから取得するネイティブ Nitro 処理
• VisionCamera の useAsyncRunner() でスケジュールする同期ネイティブメソッド

非同期設計では、必ず処理中のタスク数に上限を設けます。アクティブなタスクを 1 つにするか、小規模な固定数のプールを使用し、古くなった保留中の入力は拒否または置き換え、無制限の FIFO キューは決して作成しないでください。dropFramesWhileBusy は過負荷を防ぐための仕組みであり、アーキテクチャではありません。useAsyncRunner() を使用する場合は、受け付けた Frame をタスク内で破棄し、拒否した Frame は直ちに破棄してください。

ML の計算方式はエンドツーエンドで選択する

推論結果を同じフレームの Skia または WebGPU のレンダリングに使う場合は、処理経路全体を GPU 上に維持することを優先します。ANE、NPU、または CPU に処理を移し、ジオメトリをレンダラーに戻す方法を選ぶのは、フレームの予算を守りつつ、エンドツーエンドのプロファイリングで高速化が確認できた場合に限ります。

状態のみを取得するスキャンでは、プラットフォームのランタイムで利用可能な計算ユニットをベンチマークします。ANE または NPU は GPU との競合を避け、対応モデルを高速化できる場合があります。アクセラレーターのディスパッチや転送コストが支配的な場合は、小規模なモデルでは CPU のほうが高速なことがあります。推論だけでなく、入力変換、同期、推論、結果の配信を測定してください。フレームに連動するオーバーレイのないスキャンの後であれば、通常の React の状態管理やナビゲーションを使用して問題ありません。

開発時と本番環境での確認

すべてのネイティブ依存関係が対応している場合は、サイズ変更可能な iPad 風の Mac Catalyst または iPad-on-Mac ビルドを、迅速な反復開発用のハーネスとして使用します。デスクトップのエージェントから再起動、サイズ変更、スクリーンショットの撮影を行いながら、内蔵 Mac カメラまたは useCameraDevice('external') を介した外付け UVC カメラを使用できます。Mac ターゲットまたは必要なプラグインを利用できない場合は、スマートフォンに切り替えます。

Mac での反復開発は機能の確認用であり、性能を予測するためのものではありません。本番環境のすべてのデバイスクラスと代表的な GPU でリリースビルドを検証してください。サーマルスロットリングやプールのリークを検出できるだけの時間、テストを実施します。次の項目を追跡してください。

• カメラのタイムスタンプから、対応する結果または表示までのレイテンシ（中央値、p95、p99）
• ドロップしたフレーム数と最大処理中フレーム数
• CPU と GPU の処理時間、読み戻し、マッピング、同期ポイント
• フレームあたりのアロケーション数、定常状態のメモリ使用量、持続 FPS、温度、電力

GPU の処理時間は、計測処理が同期ポイントにならないよう、非同期かつ十分に低い頻度でサンプリングします。

信頼できるリファレンス

• VisionCamera：ドキュメント一覧、パフォーマンス、非同期処理、外部カメラ
• レンダリングとコンピューティング：VisionCamera Skia、React Native WebGPU の統合
• ML コンピューティング：Apple Core ML のコンピューティングユニット、LiteRT NPU デリゲート