Appearance
API 仕様とクライアント連携
API 仕様
AM3D Cloud API は、概念上は以下のエンドポイントで構成されます。公開版では実 URL は記載しません。
| 用途 | メソッド | パス |
|---|---|---|
| 深度推定・変換 | POST | /infer |
| モデル予熱 | POST | /warm |
| 死活監視 | GET | /health |
/infer パラメータ
/infer は動画ファイルを受け取り、RGBD SBS 形式の MP4 を返すエンドポイントです。実装で利用する主なパラメータは以下です。
| パラメータ | 必須 | 内容 |
|---|---|---|
file | 必須 | 入力動画ファイル |
encoder | 任意 | 使用するモデルサイズ |
depth_type | 任意 | 深度表現の種類 |
input_size | 任意 | 推論時の入力解像度 |
max_res | 任意 | 出力動画の最大解像度 |
target_fps | 任意 | 処理対象 FPS。元動画より低くすると処理時間を短縮できる |
p_low | 任意 | 深度正規化に使う下側パーセンタイル |
p_high | 任意 | 深度正規化に使う上側パーセンタイル |
white_near | 任意 | 近い物体を白として扱うかどうか |
対応拡張子、デフォルト値、レスポンスヘッダー、音声の扱いは実装バージョンに依存します。利用前に対象バージョンの API 仕様を確認してください。
レスポンス
| 項目 | 内容 |
|---|---|
| Content-Type | video/mp4 |
| 出力形式 | RGBD SBS MP4 |
| 左側 | カラー映像 |
| 右側 | 深度マップ |
| 深度表現 | 設定に応じて白黒方向を制御 |
| 音声 | 入力動画・処理設定・エンコード設定に依存 |
Unity / iPad クライアント連携
Unity iPad クライアントでは、動画バイナリと任意パラメータをフォームデータとして追加し、/infer に送信する構成が想定されています。処理時間が長くなるため、通常の短い HTTP タイムアウトではなく、動画長に応じた十分なタイムアウト設定が必要です。
利用者の操作フロー
| 操作 | 内容 |
|---|---|
| 1 | アプリで 2D 動画を選択 |
| 2 | 変換ボタンでクラウドに送信 |
| 3 | クラウド GPU が深度推定を実行 |
| 4 | RGBD SBS MP4 を受信 |
| 5 | アプリ上で Looking Glass に表示 |
利用者は推論環境を自分で構築する必要はありません。アプリ側は、動画選択、アップロード、進捗表示、結果保存、再生を担当します。
長尺動画と target_fps の考え方
クラウド深度推定では、処理対象フレーム数が増えるほど処理時間が長くなります。長尺動画をそのまま高 FPS で処理すると、API タイムアウトやコスト上限に達しやすくなります。
現在設定での考え方
| 条件 | 実用性 |
|---|---|
| 短尺動画 | 1 リクエストで処理しやすい |
| 1 分前後の動画 | FPS や解像度を調整すれば実用可能 |
| 数分以上の動画 | タイムアウト延長または分割処理を検討 |
| 長尺動画 | 分割送信を基本に設計する |
実用上の判断基準
| 動画長 | 推奨対応 |
|---|---|
| 〜30秒 | そのまま送信しやすい |
| 1〜3分 | target_fps を下げて処理量を抑える |
| 3〜10分 | 分割処理またはタイムアウト延長を検討 |
| 10分超 | 分割処理を前提にする |
| 1時間超 | 一定時間ごとに分割し、ジョブ管理する |
現場用途の推奨設定
現場記録や確認用途では、滑らかさよりも奥行きの把握を優先し、解像度と FPS を抑える設定が有効です。
| パラメータ | 考え方 |
|---|---|
max_res | 表示品質と処理時間のバランスで設定 |
target_fps | 10〜15fps 程度を目安に検討 |
| 分割長 | タイムアウトに収まる長さに調整 |
タイムアウト延長
タイムアウトを延長すれば、長い動画を 1 リクエストで処理できる可能性はあります。ただし、失敗時の再実行コストやユーザー待ち時間が増えるため、長尺動画では分割処理とジョブ管理を優先して検討します。