SAM3Inference

SAM3Inference#

class rapidtools.models.SAM3Inference(model_id: str = 'facebook/sam3', device: str = 'auto', load_in_4bit: bool = False, temperature: float | None = None, max_tokens: int | None = None)[source]#

Bases: BaseLocalInferenceModel

Text-prompted instance segmentation with SAM 3.

Instantiate once and call run_inference() repeatedly to avoid reloading the ~3.4 GB of weights.

Example

>>> from rapidtools.models import SAM3Inference
>>> SAM3Inference.list_available_models()
['facebook/sam3']
>>> sam = SAM3Inference(device='cuda')
>>> out = sam.run_inference(['a.jpg', 'b.jpg'], 'swimming pool')
>>> len(out.masks), len(out.bounding_boxes)
(2, 2)

Methods

list_available_models

Return the SAM 3 checkpoints supported through Transformers.

run_batch

Process assets sequentially to avoid GPU out-of-memory crashes.

run_inference

Segment every instance of prompt in one or more images.
classmethod list_available_models(auth_key: str | None = None) → list[str][source]#

Return the SAM 3 checkpoints supported through Transformers.

Parameters:

auth_key – Unused; present for signature parity with API wrappers.

Returns:

list[str] – Repository IDs.

Example

>>> from rapidtools.models import SAM3Inference
>>> SAM3Inference.list_available_models()
['facebook/sam3']
run_inference(image_inputs: str | Path | Sequence[str | Path], prompt: str | Path | None = None, threshold: float | None = None, mask_threshold: float | None = None, config: SegmentationConfig | None = None, **kwargs: Any) → ModelOutput | None[source]#

Segment every instance of prompt in one or more images.

Parameters:

  • image_inputs – One path/URL or a list of them (processed as a batch).

  • prompt – Concept to segment (e.g. 'building') or a prompt file. None runs the model without a text prompt.

  • threshold – Detection confidence threshold (default 0.5).

  • mask_threshold – Threshold for binarising mask logits (default 0.5).

  • config – A SegmentationConfig; explicit keyword arguments take precedence over it.

  • **kwargs – Ignored; accepted for interface compatibility.

Returns:

ModelOutput | None – masks holds one (n, H, W) array per image, bounding_boxes one [[x0, y0, x1, y1], ...] list per image, and raw_response['scores'] the confidences. All three lists have exactly one entry per input image, in input order; an image that could not be loaded (or a result without boxes/scores) is represented by None, and raw_response['failed_indices'] lists the positions that failed. None when no image loads or inference fails.

Example

>>> from rapidtools.models import SAM3Inference
>>> sam = SAM3Inference()
>>> out = sam.run_inference('tile.jpg', 'tree', threshold=0.4)
>>> out.has_masks, out.raw_response['status']
(True, 'success')