# 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> [options]
```
### 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`)
### Options
- `--model`: Choose SAM model variant (sam2.1_t.pt, sam2.1_s.pt, sam2.1_b.pt, sam2.1_l.pt)
- `--draw-box`: Also save the original image with the bounding box drawn on it
### 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
```
Use a faster model for quicker processing:
```bash
sam-mask-cli image.jpg "100,50,300,250" output/ mask.png --model sam2.1_b.pt
```
Generate mask and visualize the bounding box:
```bash
sam-mask-cli photo.png "200,100,400,300" output/ mask.png --draw-box
```
This creates two files:
- `mask.png` - The binary segmentation mask
- `mask_bbox.png` - Original image with green bounding box drawn on it
### 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.
When using `--draw-box`, an additional image is created showing the original image with:
- **Green bounding box**: Rectangle outline showing the specified coordinates
- **Coordinate label**: Text showing the exact bounding box values
## SAM Model Options
The tool supports different SAM 2.1 model variants with different speed/accuracy tradeoffs:
| Model | Size | Speed | Accuracy | Use Case |
|-------|------|-------|----------|----------|
| `sam2.1_t.pt` | Smallest | Fastest | Lower | Quick prototyping, real-time applications |
| `sam2.1_s.pt` | Small | Fast | Good | Balanced performance |
| `sam2.1_b.pt` | Medium | Moderate | Better | Recommended for most use cases |
| `sam2.1_l.pt` | Large | Slowest | Best | High-accuracy requirements (default) |
## 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 SAM 2.1 models which are automatically downloaded and cached on first use. Models are stored in `~/.cache/ultralytics/` (Linux/macOS) or `%USERPROFILE%\.cache\ultralytics\` (Windows) to avoid polluting your working directory.
**Model Cache Behavior:**
- ✅ Models download to system cache directory
- ✅ Shared across all installations (pip, pipx, uvx)
- ✅ No files created in your current working directory
- ✅ Automatic cache management by ultralytics
The cache location is displayed when loading models for transparency.
## Performance Notes
- First run may be slower due to model downloading and initialization
- Models are cached globally - subsequent runs are faster
- GPU acceleration is recommended for better performance
- Larger images and complex scenes may require more processing time
- Use smaller models (`--model sam2.1_b.pt`) for faster inference
## 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 in `~/.cache/ultralytics/`
- Try running the command again
- Models download to cache directory, not current working directory
**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
Raw data
{
"_id": null,
"home_page": null,
"name": "sam-mask-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cli, computer-vision, mask, sam, segmentation, ultralytics",
"author": null,
"author_email": "Adam Barbato <adambarbato94@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a0/c3/f4ea997f38faaec6ffdddcdbf38870a2f41f94afae782013a04d7521ae8d/sam_mask_cli-0.1.1.tar.gz",
"platform": null,
"description": "# SAM Mask CLI\n\nA 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.\n\n## Features\n\n- Generate segmentation masks using SAM 2.1\n- Command-line interface for easy automation\n- Support for various image formats (JPEG, PNG, WebP, etc.)\n- Binary mask output (white for detected objects, black for background)\n- Robust error handling and validation\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- CUDA-compatible GPU (recommended for better performance)\n\n### Install from source\n\n1. Clone the repository:\n```bash\ngit clone <repository-url>\ncd sam-mask-cli\n```\n\n2. Install the package:\n```bash\npip install -e .\n```\n\n### Install dependencies only\n\nIf you just want to install the dependencies:\n```bash\npip install -r requirements.txt\n```\n\nOr using uv:\n```bash\nuv pip install -e .\n```\n\n## Usage\n\nThe basic syntax is:\n```bash\nsam-mask-cli <image_path> <bounding_box> <output_path> <output_filename> [options]\n```\n\n### Parameters\n\n- `image_path`: Path to the input image\n- `bounding_box`: Bounding box coordinates in format `x_min,y_min,x_max,y_max`\n- `output_path`: Directory where the mask will be saved\n- `output_filename`: Name of the output mask file (e.g., `mask.png`)\n\n### Options\n\n- `--model`: Choose SAM model variant (sam2.1_t.pt, sam2.1_s.pt, sam2.1_b.pt, sam2.1_l.pt)\n- `--draw-box`: Also save the original image with the bounding box drawn on it\n\n### Examples\n\nGenerate a mask for an object in an image:\n```bash\nsam-mask-cli input.jpg \"100,50,300,250\" output/ mask.png\n```\n\nProcess a WebP image with specific coordinates:\n```bash\nsam-mask-cli image.webp \"981,57,1261,720\" ./masks/ result.png\n```\n\nSave to a nested directory (will be created if it doesn't exist):\n```bash\nsam-mask-cli photo.png \"200,100,400,300\" results/masks/ person_mask.png\n```\n\nUse a faster model for quicker processing:\n```bash\nsam-mask-cli image.jpg \"100,50,300,250\" output/ mask.png --model sam2.1_b.pt\n```\n\nGenerate mask and visualize the bounding box:\n```bash\nsam-mask-cli photo.png \"200,100,400,300\" output/ mask.png --draw-box\n```\n\nThis creates two files:\n- `mask.png` - The binary segmentation mask\n- `mask_bbox.png` - Original image with green bounding box drawn on it\n\n### Bounding Box Format\n\nThe bounding box should be specified as four comma-separated integers:\n- `x_min`: Left edge of the box\n- `y_min`: Top edge of the box \n- `x_max`: Right edge of the box\n- `y_max`: Bottom edge of the box\n\nWhere (0,0) is the top-left corner of the image.\n\n## Output\n\nThe tool generates a binary mask image with:\n- **White pixels (255)**: Areas where SAM detected the segmented object\n- **Black pixels (0)**: Background areas\n\nThe output mask has the same dimensions as the input image.\n\nWhen using `--draw-box`, an additional image is created showing the original image with:\n- **Green bounding box**: Rectangle outline showing the specified coordinates\n- **Coordinate label**: Text showing the exact bounding box values\n\n## SAM Model Options\n\nThe tool supports different SAM 2.1 model variants with different speed/accuracy tradeoffs:\n\n| Model | Size | Speed | Accuracy | Use Case |\n|-------|------|-------|----------|----------|\n| `sam2.1_t.pt` | Smallest | Fastest | Lower | Quick prototyping, real-time applications |\n| `sam2.1_s.pt` | Small | Fast | Good | Balanced performance |\n| `sam2.1_b.pt` | Medium | Moderate | Better | Recommended for most use cases |\n| `sam2.1_l.pt` | Large | Slowest | Best | High-accuracy requirements (default) |\n\n## Supported Image Formats\n\n- JPEG (.jpg, .jpeg)\n- PNG (.png)\n- WebP (.webp)\n- BMP (.bmp)\n- TIFF (.tiff, .tif)\n\n## Error Handling\n\nThe tool provides clear error messages for common issues:\n\n- Invalid image paths or unsupported formats\n- Malformed bounding box coordinates\n- Bounding boxes outside image boundaries\n- Output directory creation failures\n\n## Development\n\n### Setting up development environment\n\n1. Install development dependencies:\n```bash\npip install -e \".[dev]\"\n```\n\n2. Run code formatting:\n```bash\nblack sam_mask_cli/\nisort sam_mask_cli/\n```\n\n3. Run type checking:\n```bash\nmypy sam_mask_cli/\n```\n\n4. Run linting:\n```bash\nflake8 sam_mask_cli/\n```\n\n### Project Structure\n\n```\nsam-mask-cli/\n\u251c\u2500\u2500 sam_mask_cli/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 cli.py\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 README.md\n\u2514\u2500\u2500 LICENSE\n```\n\n## Model Requirements\n\nThis tool uses SAM 2.1 models which are automatically downloaded and cached on first use. Models are stored in `~/.cache/ultralytics/` (Linux/macOS) or `%USERPROFILE%\\.cache\\ultralytics\\` (Windows) to avoid polluting your working directory.\n\n**Model Cache Behavior:**\n- \u2705 Models download to system cache directory \n- \u2705 Shared across all installations (pip, pipx, uvx)\n- \u2705 No files created in your current working directory\n- \u2705 Automatic cache management by ultralytics\n\nThe cache location is displayed when loading models for transparency.\n\n## Performance Notes\n\n- First run may be slower due to model downloading and initialization\n- Models are cached globally - subsequent runs are faster\n- GPU acceleration is recommended for better performance\n- Larger images and complex scenes may require more processing time\n- Use smaller models (`--model sam2.1_b.pt`) for faster inference\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Troubleshooting\n\n### Common Issues\n\n**Model download fails:**\n- Ensure you have a stable internet connection\n- Check that you have sufficient disk space in `~/.cache/ultralytics/`\n- Try running the command again\n- Models download to cache directory, not current working directory\n\n**CUDA out of memory:**\n- Try processing smaller images\n- Close other GPU-intensive applications\n- Consider using CPU-only mode (though slower)\n\n**Invalid bounding box errors:**\n- Verify coordinates are within image bounds\n- Ensure x_min < x_max and y_min < y_max\n- Check that coordinates are positive integers\n\n**Permission errors:**\n- Ensure you have write permissions to the output directory\n- Try running with appropriate user permissions\n\n## Support\n\nFor issues and questions:\n1. Check the troubleshooting section above\n2. Search existing issues in the repository\n3. Create a new issue with detailed information about your problem",
"bugtrack_url": null,
"license": null,
"summary": "A command-line tool for generating segmentation masks using SAM (Segment Anything Model)",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/yourusername/sam-mask-cli",
"Issues": "https://github.com/yourusername/sam-mask-cli/issues",
"Repository": "https://github.com/yourusername/sam-mask-cli"
},
"split_keywords": [
"cli",
" computer-vision",
" mask",
" sam",
" segmentation",
" ultralytics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ed4f40613e5f7ea3fa637b27d258092138df2339a27c14d4a66dd7fb824473fa",
"md5": "4bdf206bfd7d8ed004ae8bf107b44ebc",
"sha256": "ad965dd7ba4fb616b14e9e563df071a3bb173d9431b1046a0b44ddd4cc6217dc"
},
"downloads": -1,
"filename": "sam_mask_cli-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bdf206bfd7d8ed004ae8bf107b44ebc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9802,
"upload_time": "2025-10-21T03:32:41",
"upload_time_iso_8601": "2025-10-21T03:32:41.056057Z",
"url": "https://files.pythonhosted.org/packages/ed/4f/40613e5f7ea3fa637b27d258092138df2339a27c14d4a66dd7fb824473fa/sam_mask_cli-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a0c3f4ea997f38faaec6ffdddcdbf38870a2f41f94afae782013a04d7521ae8d",
"md5": "7ffda6be4df9545686ae9e663cecadff",
"sha256": "621cdd8bc176fd266bfe6b988213b4296df6a545d9e744fe12215ad6be308d81"
},
"downloads": -1,
"filename": "sam_mask_cli-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "7ffda6be4df9545686ae9e663cecadff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 124914,
"upload_time": "2025-10-21T03:32:42",
"upload_time_iso_8601": "2025-10-21T03:32:42.233088Z",
"url": "https://files.pythonhosted.org/packages/a0/c3/f4ea997f38faaec6ffdddcdbf38870a2f41f94afae782013a04d7521ae8d/sam_mask_cli-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 03:32:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "sam-mask-cli",
"github_not_found": true,
"lcname": "sam-mask-cli"
}
JSON
