Segment objects using exactly one prompt type per call: text, points, or boxes.
Parameters
image_input
str | PIL.Image | np.ndarray
required
RGB image as file path, URL, PIL Image, or numpy array.
Text prompt describing objects to segment. Exclusive with points/boxes.
List of [x, y] point coordinates. Exclusive with text/boxes. Requires labels.
List of [x0, y0, x1, y1] box coordinates. Exclusive with text/points. Requires labels.
Required for points/boxes. 1 = foreground, 0 = background.
Returns
np.ndarray — Binary segmentation mask of shape (H, W) with dtype uint8. Foreground 255, background 0.
Example Output
Example
from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image
client = CortexClient()
img = Image.open("scene.jpg") # 640x480 RGB
# Text prompt
text_mask = client.run(model_id="sam3", image_input=img, text="building")
print(text_mask.shape)
# (480, 640)
fg = np.count_nonzero(text_mask)
print(f"foreground: {fg} pixels ({fg / text_mask.size * 100:.1f}%)")
# foreground: 9013 pixels (2.9%)
# Points prompt
points_mask = client.run(
model_id="sam3",
image_input=img,
points=[[320, 350]],
labels=[1],
)
print(points_mask.shape)
# (480, 640)
fg = np.count_nonzero(points_mask)
print(f"foreground: {fg} pixels ({fg / points_mask.size * 100:.1f}%)")
# foreground: 140068 pixels (45.6%)
# Boxes prompt
boxes_mask = client.run(
model_id="sam3",
image_input=img,
boxes=[[340, 32, 609, 365]],
labels=[1],
)
print(boxes_mask.shape)
