GRID Docs | General Robotics

Estimate metric depth and/or surface normals from a single RGB image.

Parameters

ImageInput

required

RGB image as file path, URL, PIL Image, or numpy array.

float | None

Optional timeout in seconds for the HTTP request.

Optional[Union[str, Sequence[str]]]

Keyword-only. Optional selection of maps to return — "depth", "normals", or a non-empty subset of both. None (default) returns both. Requesting only what you need shrinks the response payload (normals are 3x the size of depth).

Returns

Dict with the requested subset of:

"depth": (H, W) float32 array, metric depth in metres.
"normals": (H, W, 3) float32 array, unit surface normals.

Example

from grid_cortex_client import CortexClient, ModelType
client = CortexClient()
result = client.run(ModelType.METRIC3D, ...)

Uses Metric3D ViT-Large.

Example Output

Depth

The depth map contains per-pixel metric distance in meters. Brighter regions (yellow/white) are farther from the camera; darker regions (purple/black) are closer. Values are absolute metric depth — larger values mean greater distance, and you can directly compare values across different images.

Surface Normals

Surface normals represent the direction each surface faces as a unit vector (x, y, z). In the RGB visualization, each channel maps to an axis: red = +x (right), green = +y (down), blue = +z (away from camera). Flat surfaces appear as uniform color; edges and curves show color transitions. Normals are mapped to RGB as (normal + 1) / 2 * 255 for display.

Working with the outputs

from grid_cortex_client import CortexClient
from PIL import Image

client = CortexClient()
image = Image.open("scene.jpg")  # 640x480 RGB
result = client.run(model_id="metric3d", image_input=image)

depth = result["depth"]
normals = result["normals"]

print(depth.shape, depth.dtype)
# (480, 640) float32

print(f"depth: min={depth.min():.3f}, max={depth.max():.3f}, mean={depth.mean():.3f} (meters)")
# depth: min=0.100, max=1.478, mean=0.621 (meters)

print(normals.shape, normals.dtype)
# (480, 640, 3) float32

# Visualize normals as RGB: map [-1, 1] to [0, 255]
normals_vis = ((normals + 1) / 2 * 255).clip(0, 255).astype("uint8")
Image.fromarray(normals_vis).save("normals_vis.png")

Overview

Cortex Models

metric3d

Parameters

Returns

Example

Example Output

Depth

Surface Normals

Working with the outputs

​Parameters

​Returns

​Example

​Example Output

​Depth

​Surface Normals

​Working with the outputs

Parameters

Returns

Example

Example Output

Depth

Surface Normals

Working with the outputs