> ## 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.

# SAM2

> Point/box prompted segmentation (Segment Anything 2)

Segment objects in an image using point or box prompts with SAM 2.

## Parameters

<ParamField body="image_input" type="str | PIL.Image | np.ndarray" required>
  RGB image.
</ParamField>

<ParamField body="prompts" type="List[List[int]]" required>
  List of `[x, y]` pixel coordinates.
</ParamField>

<ParamField body="labels" type="List[int]" required>
  `1` = foreground, `0` = background, one per prompt point.
</ParamField>

<ParamField body="multimask_output" type="bool">
  If `True`, returns multiple candidate masks.
</ParamField>

<ParamField body="mode" type="str">
  Endpoint mode; only `"image"` currently supported.
</ParamField>

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

## Returns

`np.ndarray` — Binary segmentation mask of shape `(H, W)` with dtype `uint8`. Foreground pixels are `255`, background is `0`.

## Example Output

<img src="https://mintcdn.com/scaledfoundations/lgZgGQWKvUIw0C7n/assets/images/cortex/sam2-output.jpg?fit=max&auto=format&n=lgZgGQWKvUIw0C7n&q=85&s=004e506e57fba3e0484b6ada1003a2e0" alt="SAM2 point-prompted segmentation output" width="1056" height="552" data-path="assets/images/cortex/sam2-output.jpg" />

## Example

```python theme={null}
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
img = Image.open("scene.jpg")  # 640x480 RGB
mask = client.run(
    model_id="sam2",
    image_input=img,
    prompts=[[320, 350]],
    labels=[1],  # 1 = foreground
)

print(mask.shape, mask.dtype)
# (480, 640) uint8

print(np.unique(mask))
# [0, 255]

foreground = np.count_nonzero(mask)
print(f"foreground pixels: {foreground} ({foreground / mask.size * 100:.1f}%)")
# foreground pixels: 138532 (45.1%)
```