---
title: Sam3 Annotation Tool
emoji: 💻
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.0.2
app_file: app.py
pinned: false
license: apache-2.0
short_description: generate segmentation image datasets using sam3
---

# SAM3 Annotation Tool

GP's interactive Gradio app to generate train datasets with annotations for one or multiple images using SAM3.

Latest code lives on github
https://github.com/G-Paris/sam3-annotation-tool

This was a big exploration of how to vibe-code my way through such a project. So give the tool some slack if you're trying to make some changes to it :)

## Features

*   **Generate masks using prompts, input boxes or a combination**
*   **Discard masks that are not relevant**
*   **Finetune masks using point refinement**
*   **Export dataset zipped or unzipped, zipped uploads directly to cvat**

## Extra
*   **Zoom and move around higher res images**
*   **Define cropped area to increase SAM3 inference resolution**
*   **Append masks from multiple SAM inference calls per image**
*   **Save&load progress when working with larger amount of images**

## Quickstart

### Prerequisites

1.  **Install `uv`**
    This project uses `uv` for fast Python package management.
    
    **Linux/macOS:**
    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
    
    **Windows:**
    ```powershell
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    ```

2.  **Hugging Face Token**
    The SAM3 model (`facebook/sam3`) is hosted on Hugging Face and may be gated. You need an access token to download it.
    1.  Create a Hugging Face account if you don't have one.
    2.  **Request Access**: Visit the [facebook/sam3 model card](https://huggingface.co/facebook/sam3) and accept the license terms to request access. You must do this before the model can be downloaded.
    3.  Go to [Settings > Access Tokens](https://huggingface.co/settings/tokens).
    4.  Create a new token with **Read** permissions. You only need read access to the SAM3 repository.

### Installation & Running

1.  **Clone the repository**
    ```bash
    git clone https://github.com/G-Paris/sam3-annotation-tool.git
    cd sam3-annotation-tool
    ```

2.  **Install dependencies**
    Use `uv` to sync the project environment:
    ```bash
    # Create virtual environment and install dependencies from uv.lock
    uv sync
    ```

3.  **Run the Application**
    Use `uv run` to start the app.

    You must provide your Hugging Face token (with access to `facebook/sam3`).
    
    **Linux/macOS:**
    ```bash
    export HF_TOKEN="hf_..." 
    uv run app.py
    ```

    **Windows (PowerShell):**
    ```powershell
    $env:HF_TOKEN="hf_..."
    uv run app.py
    ```

    *Tip: You can also create a `.env` file (not committed) to store your token.*

4.  **Access the Interface**
    Once the application starts, open your browser and navigate to the local URL provided in the terminal (typically `http://127.0.0.1:7860`).

## License & Legal Disclaimer

**This Tool (The Code): Apache License 2.0**
The source code of this annotation tool (UI, wrapper logic, data management) is licensed under the [Apache License 2.0](LICENSE). You are free to use, modify, and distribute this software for commercial and non-commercial purposes, provided you include the original license.

**The Model (SAM 3): Meta Custom License**
This tool uses the **Segment Anything Model 3 (SAM 3)** by Meta. The model weights and core SAM 3 definitions are subject to **Meta's Custom License**, which may have different restrictions (especially regarding commercial use or redistributing the weights).

*   **We do NOT bundle SAM 3 weights** in this repository.
*   The model is downloaded automatically from Hugging Face (`facebook/sam3`) using your access token.
*   By using this tool, you agree to comply with Meta's license terms for SAM 3.

**Please review the separate license terms for SAM 3 explicitly on their [Hugging Face Model Card](https://huggingface.co/facebook/sam3).**

## Project Structure

- `app.py`: Main Gradio application entry point and UI definition.
- `src/sam3_annotation_tool/`: Source code for the application logic.
  - `controller.py`: Manages application state and business logic.
  - `inference.py`: Handles model loading and inference (SAM3).
  - `schemas.py`: Pydantic data models for type safety.
  - `view_helpers.py`: UI-specific helper functions and event handlers.
  - `dataset_manager.py`: YOLO dataset export and management.
  - `theme.py`: Custom UI theme.
  - `utils.py`: General helper functions for image processing.
- `scripts/`: Utility scripts for dataset operations (cleanup, verification, analysis).
- `tests/`: Unit and integration tests.
- `pyproject.toml`: Project configuration and dependencies.
- `uv.lock`: Locked dependency versions for reproducibility.