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:
```powershell
.\install_requirements.ps1
```

#### For Windows Command Prompt:
```cmd
install_requirements.bat
```

### Option 2: Manual Installation

#### Step 1: Install Python Dependencies

Install all Python packages from `requirements.txt`:

```bash
# 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:

```bash
# 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:

```bash
# 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
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:
```bash
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:
```cmd
run_app.bat
```

#### Windows PowerShell:
```powershell
.\run_app.ps1
```

### Option 2: Manual Command

Run the FastAPI server directly using uvicorn:

```bash
# 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