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

> Segment image with SAM-2 given point/box prompts

Segment image with SAM-2 given point/box prompts.

## Parameters

<ParamField body="image_input" type="Union[str, Image.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 per prompt.
</ParamField>

<ParamField body="multimask_output" type="bool" default="False">
  If *True* returns multiple masks.
</ParamField>

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

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

## Returns

np.ndarray: Binary segmentation mask as numpy array (H, W) with dtype uint8.
Foreground pixels are 255, background pixels are 0.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
mask = client.run(
    ModelType.SAM2,
    image_input=image,
    prompts=[[320, 240]],
    labels=[1],
)
print(mask.shape)  # (480, 640)
```

## 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" />

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


## Related topics

- [sam2](/models/cortex/sam2.md)