> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# foundationstereo

> Estimate depth from stereo pair using FoundationStereo

Estimate depth from stereo pair using FoundationStereo.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField body="left_image" type="Union[str, Image.Image, np.ndarray]">
  Left stereo image.
</ParamField>

<ParamField body="right_image" type="Union[str, Image.Image, np.ndarray]">
  Right stereo image.
</ParamField>

<ParamField body="stereo_image" type="ImageInput | None">
  Rectified \[left | right] frame, with equal-width views and at most 720x1280 pixels per eye. Supply this instead of left\_image and right\_image.
</ParamField>

<ParamField body="return_left_image" type="bool" default="False">
  If true, return a dictionary containing "depth" (float32 HxW) and "left\_image" (uint8 RGB HxWx3). The left image can be passed to any segmentation model.
</ParamField>

<ParamField body="aux_args" type="Dict[str, Any]">
  Camera parameters: - "K": 3x3 intrinsics for the rectified left view at input resolution - "baseline": Stereo baseline in meters - "hiera": Hierarchy level (0-2) - "valid\_iters": Number of valid iterations
</ParamField>

<ParamField body="timeout" type="float | None">
  Optional HTTP timeout.
</ParamField>

## Returns

np.ndarray | dict\[str, np.ndarray]: Depends on return\_left\_image:

* False (default): The depth array.
* True: A dictionary with "depth" and "left\_image" arrays.

Depth is float32 with shape (H, W), in meters. The optional left
image is uint8 RGB with shape (H, W, 3), aligned with depth.
Both use the input per-eye resolution; the server performs no
resizing or rectification.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
K = np.array([[525, 0, 320], [0, 525, 240], [0, 0, 1]], dtype=np.float32)
aux = {"K": K, "baseline": 0.1, "hiera": 0, "valid_iters": 32}
left_image = np.array(Image.open("left.jpg"))
right_image = np.array(Image.open("right.jpg"))
depth = client.run(ModelType.FOUNDATIONSTEREO, left_image=left_image, right_image=right_image, aux_args=aux)
print(depth.shape)  # (480, 640)
```