README.md

---
pipeline_tag: mask-generation
license: apache-2.0
base_model: facebook/sam2.1-hiera-small
library_name: kerasformers
tags:
- keras
- kerasformers
- sam2
- mask-generation
- image-segmentation
- arxiv:2408.00714
- pytorch
- jax
- tf
---

## ***See [our collection](https://huggingface.co/collections/kerasformers/sam-v1-v2-v3-6a6a8c261dabbc2996e1b4a2) for all versions of SAM.***

# Run SAM2 with Keras 3: JAX, PyTorch, or TensorFlow

[![GitHub](https://img.shields.io/badge/GitHub-KerasFormers-black?logo=github)](https://github.com/IMvision12/KerasFormers) [![Docs](https://img.shields.io/badge/Docs-SAM2-blue)](https://imvision12.github.io/KerasFormers/sam2/) [![Collection](https://img.shields.io/badge/HF-SAM%20collection-yellow)](https://huggingface.co/collections/kerasformers/sam-v1-v2-v3-6a6a8c261dabbc2996e1b4a2)

# kerasformers/sam2_hiera_small

Paper: [SAM 2: Segment Anything in Images and Videos (arXiv:2408.00714)](https://arxiv.org/abs/2408.00714) · [HF Papers](https://huggingface.co/papers/2408.00714)

SAM2 keeps SAM's promptable formulation and replaces the plain ViT with a Hiera backbone plus FPN neck. This Keras port covers the image path only: point or box prompts on a single image (no video memory / frame propagation).

For more details on the model, please go to Meta's original [model card](https://huggingface.co/facebook/sam2.1-hiera-small).

Pure-**Keras 3** conversion of [`facebook/sam2.1-hiera-small`](https://huggingface.co/facebook/sam2.1-hiera-small) for [kerasformers](https://github.com/IMvision12/KerasFormers). One implementation runs unmodified on **TensorFlow / Torch / JAX**.

This is a **promptable segmentation** checkpoint (`SAM2PromptableSegment`): point (and optional box) prompts, backbone Hiera-S.

## ✨ Quick start

```python
import os
os.environ["KERAS_BACKEND"] = "torch"  # or "jax" / "tensorflow"

import numpy as np
from PIL import Image
from kerasformers.models.sam2 import (
    SAM2PromptableSegment,
    SAM2Processor,
)

model = SAM2PromptableSegment.from_weights("kerasformers/sam2_hiera_small")
processor = SAM2Processor.from_weights("kerasformers/sam2_hiera_small")

image = Image.open("your_image.jpg").convert("RGB")
inputs = processor(
    image,
    input_points=np.array([[[[450, 200]]]], dtype="float32"),
    input_labels=np.array([[[1]]], dtype="int32"),
)
META = ("original_size", "reshaped_size")
output = model({k: v for k, v in inputs.items() if k not in META})
masks = processor.post_process_masks(
    output["pred_masks"], original_size=inputs["original_size"]
)
print(output["iou_scores"].shape, masks.shape)
```

Load any SAM / SAM2 / SAM3 variant the same way with `from_weights("kerasformers/<variant>")` (use `SAM2PromptableSegment` for this repo):

| Variant | Hub | Family |
|---|---|---|
| `sam_vit_base` | [`kerasformers/sam_vit_base`](https://huggingface.co/kerasformers/sam_vit_base) | SAM |
| `sam_vit_large` | [`kerasformers/sam_vit_large`](https://huggingface.co/kerasformers/sam_vit_large) | SAM |
| `sam_vit_huge` | [`kerasformers/sam_vit_huge`](https://huggingface.co/kerasformers/sam_vit_huge) | SAM |
| `sam2_hiera_small` | [`kerasformers/sam2_hiera_small`](https://huggingface.co/kerasformers/sam2_hiera_small) | SAM2 |
| `sam2_hiera_base_plus` | [`kerasformers/sam2_hiera_base_plus`](https://huggingface.co/kerasformers/sam2_hiera_base_plus) | SAM2 |
| `sam2_hiera_large` | [`kerasformers/sam2_hiera_large`](https://huggingface.co/kerasformers/sam2_hiera_large) | SAM2 |
| `sam3` | [`kerasformers/sam3`](https://huggingface.co/kerasformers/sam3) | SAM3 |

## Tips

- Set `KERAS_BACKEND` **before** importing Keras / kerasformers.
- SAM / SAM2: point coordinates are in original pixel space; box prompts need `enable_boxes=True` / `include_box_input=True` when building the graph.
- SAM2 in this port is image-only (no video memory bank).
- SAM3: prefer `SAM3InstanceSegment.predict(...)` for text prompts; upstream `facebook/sam3` is gated.
- See [SAM2 docs](https://imvision12.github.io/KerasFormers/sam2/) and [Loading Weights](https://imvision12.github.io/KerasFormers/loading_weights/).
- Community / upstream safetensors still work via the `hf:` prefix, e.g. `SAM2PromptableSegment.from_weights("hf:facebook/sam2.1-hiera-small")`.

## Special Thanks

A huge thank you to the Meta SAM 2 authors for creating and releasing these models.

License: Apache 2.0.