# 出力と結果の処理

一部成功の結果も含め、Argus の出力マニフェスト、深度マップ、結合した点群、カメラ姿勢を読み取ります。

Canonical: https://developer.realsee.ai/ja/docs/argus/outputs
Source: https://developer.realsee.ai/ja/docs/argus/outputs.md
Language: ja

# 出力と結果の処理

`GET /open/v1/argus/task/info` がゲートウェイの `code: 0` とタスクの `data.status: 2` を返したら、`data.expiration_timestamp` より前に `data.output_url` から `output.zip` をダウンロードします。URL は一時的です。ファイルは管理されたストレージに保存し、取得後は URL を破棄してください。

<span id="files-in-the-result" class="docs-anchor-alias" aria-hidden="true"></span>

## 結果に含まれるファイル

```text
output.zip
├── output.json
├── depth/
│   ├── 000000_depth.exr
│   └── 000001_depth.exr
├── pointcloud/
│   └── merged.glb
├── pose/
│   ├── 000000_pose.json
│   └── 000001_pose.json
└── intrinsics/                 # optional
    ├── 000000_intrinsics.json
    └── 000001_intrinsics.json
```

| ファイル | 意味 |
| --- | --- |
| `output.json` | 必須のアルゴリズム結果マニフェスト。ほかのファイルより先に確認します。 |
| `depth/*_depth.exr` | 画像ごとの 32 ビット浮動小数点 EXR 深度マップ。単位はメートルです。 |
| `pointcloud/merged.glb` | 右手系・Y 軸上方向の結合点群。 |
| `pose/*_pose.json` | 対応する成功画像のカメラ姿勢。 |
| `intrinsics/*_intrinsics.json` | 任意のカメラ内部パラメーター。成功画像の一部または全部で存在しない場合があります。 |

マニフェストには各成果物の相対 `path` と関連メタデータがあります。これを使って ZIP 内のファイルを特定します。

<span id="task-status-and-manifest-status" class="docs-anchor-alias" aria-hidden="true"></span>

## タスク状態とマニフェスト状態

ゲートウェイの数値状態は実行の進捗、`output.json.status` はアルゴリズムの結果を表します。両方を確認してください。

| マニフェストの状態 | 意味と処理 |
| --- | --- |
| `success` | 全入力画像が成功しました。各画像 ID に深度マップと姿勢があります。 |
| `partial` | 一部が成功しました。重複のない ID を持つ空でない `missing_ids` が必要です。成功 ID は深度と姿勢の両方に存在し、失敗 ID はどちらにも存在しません。両者で `name_mapping` の全 ID を網羅します。 |
| `error` | アルゴリズムが失敗しました。マニフェストの `version`、`status`、`error` を確認し、`error.code` と `error.message` を読み取ります。存在しない成果物を使わないでください。 |

<span id="match-outputs-to-the-original-images" class="docs-anchor-alias" aria-hidden="true"></span>

## 出力と元画像を対応させる

画像 ID と入力ファイル名の対応は `name_mapping` を正とします。深度と姿勢を元画像に対応させる際に使い、ローカルディレクトリの並びから ID を推測しないでください。

例：

```json
{
  "name_mapping": {
    "000000": "living-room.jpg",
    "000001": "kitchen.jpg"
  }
}
```

これはマニフェストの抜粋です。成功・一部成功の場合は `version`、`status`、成果物のメタデータ、必要な欠落画像の項目も含まれます。

<span id="depth-maps-and-point-cloud" class="docs-anchor-alias" aria-hidden="true"></span>

## 深度マップと点群

各 `depth_maps` 項目には `image_id`、相対 `path`、`format`、`resolution`、`unit` があります。深度の単位はメートルです。処理ツールへ渡す前に EXR ヘッダーを確認してください。

`point_cloud` には結合 GLB と `vertex_count`、`has_color`、`has_normals`、`coordinate_system` などがあります。返されたメタデータに従って処理し、右手系・Y 軸上方向の座標規約を保持してください。

<span id="camera-poses" class="docs-anchor-alias" aria-hidden="true"></span>

## カメラ姿勢

成功画像ごとに `image_id`、`rotation`、`translation`、`coordinate_system` を持つ姿勢 JSON があります。

- `rotation` はワールド座標をカメラ座標に変換する 3 × 3 行列です。
- `translation` はカメラ座標で表したワールド原点の位置です。
- `coordinate_system` は `right-handed, Y-up` です。

別の座標系へ統合する場合もこの定義に従います。translation はワールド座標でのカメラ位置ではありません。

<span id="optional-camera-intrinsics" class="docs-anchor-alias" aria-hidden="true"></span>

## 任意のカメラ内部パラメーター

マニフェストに `intrinsics` がある場合は、`image_id` と相対 `path` でファイルを特定します。成功画像だけを参照し、一部の画像にしかない場合もあります。

各ファイルの実際のカメラ `model` と項目を解釈してください。正距円筒パノラマとピンホール画像は投影モデルが異なります。パノラマのモデルを流用せず、各画像のモデルに従います。

<span id="validate-before-use" class="docs-anchor-alias" aria-hidden="true"></span>

## 使用前の検証

1. パストラバーサル、重複パス、展開先外への書き出しがなく ZIP 全体を展開できることを確認します。
2. マニフェスト状態と必須のエラー・欠落画像項目を含め `output.json` を検証します。
3. 参照する全ファイルが存在し、画像 ID がマッピングと姿勢・深度の項目に一致することを確認します。
4. GLB と EXR のヘッダーが指定形式と一致することを確認します。
5. 再構成データを使う前に `partial` と `error` を明示的に処理します。

送信コードとダウンロードは [クイックスタート](https://developer.realsee.ai/ja/docs/argus/quickstart)、照会項目は [API の説明](https://developer.realsee.ai/ja/docs/argus/reference) を参照してください。