# Outputs and Result Handling

Read the Argus output manifest, depth maps, merged point cloud, and camera poses, including partial results.

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

After `GET /open/v1/argus/task/info` returns gateway `code: 0` and task `data.status: 2`, download the `output.zip` referenced by `data.output_url` before `data.expiration_timestamp`. The URL is temporary. Store the downloaded files in controlled storage and discard the URL after retrieval.

## Files in the result

```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
```

| File | Meaning |
| --- | --- |
| `output.json` | Required algorithm-result manifest. Read it before consuming other files. |
| `depth/*_depth.exr` | Per-image 32-bit floating-point EXR depth maps, measured in meters. |
| `pointcloud/merged.glb` | Merged point cloud in a right-handed, Y-up coordinate system. |
| `pose/*_pose.json` | Camera-pose data for the corresponding successful image. |
| `intrinsics/*_intrinsics.json` | Optional camera-intrinsics data, which may be absent for some or all successful images. |

The manifest gives each product's relative `path` and its related metadata. Use those paths to locate the files inside the downloaded ZIP.

## Task status and manifest status

The gateway's numeric task status reports execution progress. The downloaded `output.json.status` reports the algorithm result. Check both levels.

| Manifest status | Meaning and handling |
| --- | --- |
| `success` | Every input image succeeded. Each image ID has a depth map and pose. |
| `partial` | Some images succeeded. The manifest must provide a nonempty `missing_ids` list with unique IDs. Successful IDs each appear in both depth and pose entries; missing IDs appear in neither. Together, they account for all IDs in `name_mapping`. |
| `error` | The algorithm failed. The manifest contains `version`, `status`, and `error`. Read `error.code` and `error.message`; do not consume absent products. |

## Match outputs to the original images

`name_mapping` is the authoritative mapping from image IDs to input filenames. Use it to match depth maps and poses to the original images. Do not derive IDs from a local directory listing or assume its order matches the output.

For example:

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

This is a manifest excerpt. A success or partial manifest also includes its `version`, `status`, product metadata, and any required missing-image fields.

## Depth maps and point cloud

Each `depth_maps` entry identifies its `image_id`, relative `path`, `format`, `resolution`, and `unit`. Depth values use meters. Validate the EXR file header before passing the data to your depth-processing tools.

The `point_cloud` entry identifies the merged GLB and metadata such as `vertex_count`, `has_color`, `has_normals`, and `coordinate_system`. Read the returned metadata when deciding how to handle the point cloud; retain its right-handed, Y-up coordinate convention.

## Camera poses

Each successful image has a pose JSON with `image_id`, `rotation`, `translation`, and `coordinate_system`.

- `rotation` is a 3 × 3 matrix that transforms world coordinates to camera coordinates.
- `translation` is the position of the world origin in camera coordinates.
- `coordinate_system` is `right-handed, Y-up`.

Use these definitions when integrating the pose with another coordinate system. The translation field is not the camera's position in world coordinates.

## Optional camera intrinsics

When present, the manifest's `intrinsics` entries identify files by `image_id` and relative `path`. Entries refer only to successfully reconstructed images, and may cover only some of them.

Interpret each returned file using its actual camera `model` and returned fields. Equirectangular panorama calibration and pinhole-image calibration use different projection models; follow the model supplied for that image rather than copying a panorama model onto pinhole inputs.

## Validate before use

1. Check the ZIP can be fully extracted without path traversal, duplicate paths, or files escaping the extraction directory.
2. Validate `output.json`, including its manifest status and required error or missing-image fields.
3. Confirm every file referenced by the manifest exists and its image ID matches the corresponding mapping and pose/depth entry.
4. Validate GLB and EXR headers against their declared formats.
5. Handle `partial` and `error` explicitly before consuming the reconstruction.

Use [Quickstart](https://developer.realsee.ai/docs/argus/quickstart) for submission code and download guidance, and [API Reference](https://developer.realsee.ai/docs/argus/reference) for task-query fields.