Metadata-Version: 2.4
Name: sam3-mlx
Version: 0.2.0
Summary: MLX port of Meta's Segment Anything 3 (SAM 3) for Apple Silicon.
Author: Alfredo Sandoval
License-Expression: LicenseRef-SAM AND MIT
Keywords: sam3,segment-anything,segmentation,mlx,apple-silicon,computer-vision
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: ftfy>=6.3.1
Requires-Dist: huggingface-hub>=1.1.6
Requires-Dist: medmlx-core==0.2.5
Requires-Dist: mlx<0.33,>=0.32.4
Requires-Dist: numpy>=2.3.5
Requires-Dist: pillow<14,>=13
Requires-Dist: regex>=2025.11.3
Provides-Extra: viz
Requires-Dist: matplotlib>=3.10.8; extra == "viz"
Provides-Extra: video
Requires-Dist: opencv-python-headless>=4.10.0; extra == "video"
Dynamic: license-file

# sam3-mlx

Segment images from text and geometric prompts with an unofficial native MLX port of SAM 3.

| Input | Output |
| :--- | :--- |
| Image + text, boxes or points | Masks, boxes and confidence scores |

**Apple Silicon · Metal · Python 3.13+** · [uv](https://docs.astral.sh/uv/)

## Quick start

```bash
uv venv --python 3.13
source .venv/bin/activate
export MLX_ENABLE_TF32=0

uv pip install "sam3-mlx==0.2.0"
```

Set `MLX_ENABLE_TF32=0` before starting Python to use full FP32 matrix and
attention operations; MLX otherwise may use reduced precision on supported GPUs.
The builders also default an unset `MLX_ENABLE_TF32` to `0` and check for
an incompatible already-initialized MLX process.

Pass a local native MLX `.safetensors` image checkpoint file through
`checkpoint_path` in the lower-level builder. Omitting that argument downloads
preconverted image weights from a pinned
[`mlx-community/sam3-image` revision](https://huggingface.co/mlx-community/sam3-image/tree/b72a14d8127e17e6f2a3d2e075bbbf4307ba146e)
on Hugging Face. Official PyTorch `.pt`/`.pth` checkpoints require conversion
before loading.

```python
from sam3_mlx import build_sam3_image_model
from sam3_mlx.model.sam3_image_processor import Sam3Processor

model = build_sam3_image_model(checkpoint_path="weights/model.safetensors")
processor = Sam3Processor(model, resolution=1008)

state = processor.set_image("image.jpg")
state = processor.set_text_prompt("shoe", state)

masks, boxes, scores = state["masks"], state["boxes"], state["scores"]
```

Use a resolution divisible by 14. Selected-frame video runs each frame independently.

## MedMLX runner

The registered runner uses the common optional weights-folder interface:

```python
from sam3_mlx.medmlx import run

result = run(image_path="image.png", text_prompt="lesion", output_dir="outputs")
```

Omitting `weights_path` downloads the pinned `mlx-community/sam3-image` snapshot
through the MedMLX cache. For offline use, pass a `weights_path` folder
containing `model.safetensors`. The loader checks the actual tensors; no conversion
manifest is required. `details.weights_revision` records the downloaded Hub revision,
or `null` for a supplied folder without a revision record. The lower-level
builder's explicit checkpoint-file API above remains available.

## License

The SAM License and third-party notices are included in the distribution. This
unofficial port is not affiliated with Meta. Checkpoints have separate access terms.

For research and education. Outputs require human review.
