Metadata-Version: 2.4
Name: sam-mask-cli
Version: 0.1.0
Summary: A command-line tool for generating segmentation masks using SAM (Segment Anything Model)
Project-URL: Homepage, https://github.com/yourusername/sam-mask-cli
Project-URL: Repository, https://github.com/yourusername/sam-mask-cli
Project-URL: Issues, https://github.com/yourusername/sam-mask-cli/issues
Author-email: Adam Barbato <adambarbato94@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,computer-vision,mask,sam,segmentation,ultralytics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: numpy>=2.2.6
Requires-Dist: opencv-python>=4.11.0.86
Requires-Dist: torch>=2.9.0
Requires-Dist: ultralytics>=8.3.218
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: flake8>=6.0; extra == 'dev'
Requires-Dist: isort>=5.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# SAM Mask CLI

A command-line tool for generating segmentation masks using SAM (Segment Anything Model). This tool takes an input image and a bounding box, then generates a binary mask where detected objects are white and the background is black.

## Features

- Generate segmentation masks using SAM 2.1
- Command-line interface for easy automation
- Support for various image formats (JPEG, PNG, WebP, etc.)
- Binary mask output (white for detected objects, black for background)
- Robust error handling and validation

## Installation

### Prerequisites

- Python 3.10 or higher
- CUDA-compatible GPU (recommended for better performance)

### Install from source

1. Clone the repository:
```bash
git clone <repository-url>
cd sam-mask-cli
```

2. Install the package:
```bash
pip install -e .
```

### Install dependencies only

If you just want to install the dependencies:
```bash
pip install -r requirements.txt
```

Or using uv:
```bash
uv pip install -e .
```

## Usage

The basic syntax is:
```bash
sam-mask-cli <image_path> <bounding_box> <output_path> <output_filename>
```

### Parameters

- `image_path`: Path to the input image
- `bounding_box`: Bounding box coordinates in format `x_min,y_min,x_max,y_max`
- `output_path`: Directory where the mask will be saved
- `output_filename`: Name of the output mask file (e.g., `mask.png`)

### Examples

Generate a mask for an object in an image:
```bash
sam-mask-cli input.jpg "100,50,300,250" output/ mask.png
```

Process a WebP image with specific coordinates:
```bash
sam-mask-cli image.webp "981,57,1261,720" ./masks/ result.png
```

Save to a nested directory (will be created if it doesn't exist):
```bash
sam-mask-cli photo.png "200,100,400,300" results/masks/ person_mask.png
```

### Bounding Box Format

The bounding box should be specified as four comma-separated integers:
- `x_min`: Left edge of the box
- `y_min`: Top edge of the box  
- `x_max`: Right edge of the box
- `y_max`: Bottom edge of the box

Where (0,0) is the top-left corner of the image.

## Output

The tool generates a binary mask image with:
- **White pixels (255)**: Areas where SAM detected the segmented object
- **Black pixels (0)**: Background areas

The output mask has the same dimensions as the input image.

## Supported Image Formats

- JPEG (.jpg, .jpeg)
- PNG (.png)
- WebP (.webp)
- BMP (.bmp)
- TIFF (.tiff, .tif)

## Error Handling

The tool provides clear error messages for common issues:

- Invalid image paths or unsupported formats
- Malformed bounding box coordinates
- Bounding boxes outside image boundaries
- Output directory creation failures

## Development

### Setting up development environment

1. Install development dependencies:
```bash
pip install -e ".[dev]"
```

2. Run code formatting:
```bash
black sam_mask_cli/
isort sam_mask_cli/
```

3. Run type checking:
```bash
mypy sam_mask_cli/
```

4. Run linting:
```bash
flake8 sam_mask_cli/
```

### Project Structure

```
sam-mask-cli/
├── sam_mask_cli/
│   ├── __init__.py
│   └── cli.py
├── pyproject.toml
├── README.md
└── LICENSE
```

## Model Requirements

This tool uses the SAM 2.1 large model (`sam2.1_l.pt`). The model will be automatically downloaded by ultralytics on first use, or you can place the model file in your working directory.

## Performance Notes

- First run may be slower due to model downloading and initialization
- GPU acceleration is recommended for better performance
- Larger images and complex scenes may require more processing time

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Troubleshooting

### Common Issues

**Model download fails:**
- Ensure you have a stable internet connection
- Check that you have sufficient disk space
- Try running the command again

**CUDA out of memory:**
- Try processing smaller images
- Close other GPU-intensive applications
- Consider using CPU-only mode (though slower)

**Invalid bounding box errors:**
- Verify coordinates are within image bounds
- Ensure x_min < x_max and y_min < y_max
- Check that coordinates are positive integers

**Permission errors:**
- Ensure you have write permissions to the output directory
- Try running with appropriate user permissions

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Search existing issues in the repository
3. Create a new issue with detailed information about your problem