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

# gsam2

> Segment objects in image using text prompt

Segment objects in image using text prompt.

## Parameters

<ParamField body="image_input" type="ImageInput" required>
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField body="prompt" type="str" required>
  Text description of objects to segment.
</ParamField>

<ParamField body="box_threshold" type="float | None">
  Optional confidence threshold (0.0-1.0) for filtering detections.
</ParamField>

<ParamField body="text_threshold" type="float | None">
  Optional text confidence threshold (0.0-1.0).
</ParamField>

<ParamField body="nms_threshold" type="float | None">
  Optional Non-Maximum-Suppression threshold (0.0-1.0).
</ParamField>

<ParamField body="timeout" type="float | None">
  Optional timeout in seconds for the HTTP request.
</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.GSAM2, image_input=image, prompt="a cat")
print(mask.shape)  # (480, 640)
```

Combines Grounding DINO with SAM 2.

## Example Output

<img src="https://mintcdn.com/scaledfoundations/lgZgGQWKvUIw0C7n/assets/images/cortex/gsam2-output.jpg?fit=max&auto=format&n=lgZgGQWKvUIw0C7n&q=85&s=99dcf4265e0428fcfedc420540a52dd8" alt="GSAM2 text-prompted segmentation output" width="1056" height="552" data-path="assets/images/cortex/gsam2-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="gsam2", image_input=img, prompt="street")

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

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


## Related topics

- [gsam2](/models/cortex/gsam2.md)
- [GRID Cortex Client](/models/cortex.md)
- [AsyncCortexClient](/python-api/grid-cortex-client/asynccortexclient.md)
- [CortexClient](/python-api/grid-cortex-client/cortexclient.md)
- [CortexHubClient](/python-api/grid-cortex-client/cortexhubclient.md)