INSTALL.md

Installation Guide

This guide will help you install all requirements for the SAM2 Image Auto Segment project.

Prerequisites

• Python 3.10 or higher (Python 3.10+ recommended)
• pip (Python package manager, usually comes with Python)
• Git (optional, if cloning the repository)

Quick Installation

Option 1: Using the Installation Script (Recommended)

For Windows PowerShell:

.\install_requirements.ps1

For Windows Command Prompt:

install_requirements.bat

Option 2: Manual Installation

Step 1: Install Python Dependencies

Install all Python packages from requirements.txt:

# Windows CMD (recommended):
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

# Or using pip directly:
pip install --upgrade pip
pip install -r requirements.txt

Step 2: Install SAM2 Package

Install the SAM2 package from the local sam2 directory:

# On Windows CMD:
set SAM2_BUILD_CUDA=0
cd sam2
python -m pip install -e .
cd ..

# On Windows PowerShell:
$env:SAM2_BUILD_CUDA=0
cd sam2
python -m pip install -e .
cd ..

# On Linux/Mac:
export SAM2_BUILD_CUDA=0
cd sam2
python -m pip install -e .
cd ..

Note: Setting SAM2_BUILD_CUDA=0 disables CUDA extension building, which makes installation faster. The CUDA extension is optional and doesn't affect core functionality. If you have CUDA installed and want to build the extension, you can set SAM2_BUILD_CUDA=1 or omit the environment variable.

What Gets Installed

From requirements.txt:

• FastAPI - Web framework for the API
• Uvicorn - ASGI server
• PyTorch - Deep learning framework
• OpenCV - Image processing
• NumPy, Pillow, scikit-image - Image manipulation
• Hugging Face Hub - For downloading SAM2 models
• Hydra Core - Configuration management (required by SAM2)
• And other dependencies...

From sam2/setup.py:

• SAM2 package - Segment Anything Model 2 (installed in editable mode)

Virtual Environment (Recommended)

It's recommended to use a virtual environment to avoid conflicts with other projects:

Create Virtual Environment:

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python -m venv venv
source venv/bin/activate

Then Install Requirements:

Follow the installation steps above while the virtual environment is activated.

Verification

After installation, verify that everything is installed correctly:

python -c "import torch; import fastapi; import sam2; print('All packages imported successfully!')"

Troubleshooting

Issue: CUDA Extension Build Fails

Solution: This is normal and expected if you don't have CUDA installed. The SAM2 package will still work without the CUDA extension. You can disable CUDA building by setting SAM2_BUILD_CUDA=0.

Issue: pip install fails with permission errors

Solution: Use a virtual environment (see above) or install with --user flag:

pip install --user -r requirements.txt

Issue: PyTorch installation fails

Solution: Install PyTorch separately from the official website:

• Visit: https://pytorch.org/get-started/locally/
• Select your configuration and install the appropriate version

Issue: SAM2 package installation fails

Solution: Make sure you're in the project root directory and the sam2 folder exists. Also ensure all dependencies from requirements.txt are installed first.

Running the Application

After successful installation, you can run the FastAPI application using app.py:

Option 1: Using the Run Script (Recommended)

Windows CMD:

run_app.bat

Windows PowerShell:

.\run_app.ps1

Option 2: Manual Command

Run the FastAPI server directly using uvicorn:

# Windows CMD:
python -m uvicorn app:app --host 0.0.0.0 --port 8000 --reload

# Windows PowerShell:
python -m uvicorn app:app --host 0.0.0.0 --port 8000 --reload

# Linux/Mac:
python -m uvicorn app:app --host 0.0.0.0 --port 8000 --reload

Accessing the API

Once the server is running, you can access:

• API Root: http://localhost:8000/
• Health Check: http://localhost:8000/health
• Interactive API Documentation: http://localhost:8000/docs
• Alternative API Docs: http://localhost:8000/redoc

API Endpoints

The application provides the following endpoints:

1. POST /segment - Segment image using bounding box prompt
2. POST /segment/point - Segment image using point click prompt
3. POST /auto-annotate - Automatically detect and segment all objects

See the interactive documentation at /docs for detailed API usage examples.

Additional Notes

• The installation may take several minutes, especially when installing PyTorch
• If you have a GPU, you may want to install the CUDA-enabled version of PyTorch for better performance
• The SAM2 models will be downloaded automatically from Hugging Face when first used