{"id":37798306,"url":"https://github.com/umitkacar/sam2-edge-cpp","last_synced_at":"2026-07-14T01:32:24.043Z","repository":{"id":323103256,"uuid":"753131710","full_name":"umitkacar/sam2-edge-cpp","owner":"umitkacar","description":"Real-time SAM2 segmentation on edge devices - 40x faster C++ inference with ONNX Runtime for iOS/Android deployment","archived":false,"fork":false,"pushed_at":"2025-11-14T03:33:14.000Z","size":68965,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-14T05:33:04.929Z","etag":null,"topics":["android-edge","arm-optimization","computer-vision","cpp-inference","edge-ai","edge-deployment","edgetam","embedded-ai","ios-deployment","lightweight-ai","mobile-segmentation","npu-acceleration","on-device-inference","onnx-runtime","picosam","prompt-segmentation","real-time-segmentation","sam2","tensorrt","zero-shot-segmentation"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/umitkacar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-02-05T14:31:40.000Z","updated_at":"2025-11-14T03:33:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/umitkacar/sam2-edge-cpp","commit_stats":null,"previous_names":["umitkacar/edgesam-onnxruntime-cpp","umitkacar/sam2-edge-cpp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/umitkacar/sam2-edge-cpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umitkacar%2Fsam2-edge-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umitkacar%2Fsam2-edge-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umitkacar%2Fsam2-edge-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umitkacar%2Fsam2-edge-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umitkacar","download_url":"https://codeload.github.com/umitkacar/sam2-edge-cpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umitkacar%2Fsam2-edge-cpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35442828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-edge","arm-optimization","computer-vision","cpp-inference","edge-ai","edge-deployment","edgetam","embedded-ai","ios-deployment","lightweight-ai","mobile-segmentation","npu-acceleration","on-device-inference","onnx-runtime","picosam","prompt-segmentation","real-time-segmentation","sam2","tensorrt","zero-shot-segmentation"],"created_at":"2026-01-16T15:23:30.806Z","updated_at":"2026-07-14T01:32:24.037Z","avatar_url":"https://github.com/umitkacar.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🎯 EdgeSAM - ONNX Runtime C++\n### *40x Faster Edge AI Segmentation with C++17*\n\n\u003cimg src=\"https://readme-typing-svg.demolab.com?font=Fira+Code\u0026size=22\u0026duration=3000\u0026pause=1000\u0026color=6366F1\u0026center=true\u0026vCenter=true\u0026multiline=true\u0026width=900\u0026lines=Real-Time+SAM2+Segmentation+%F0%9F%9A%80;C%2B%2B17+%2B+ONNX+Runtime+1.12.1+%E2%9A%A1;40x+Faster+Edge+Inference+%F0%9F%94%A5\" alt=\"Typing SVG\" /\u003e\n\n[![Stars](https://img.shields.io/github/stars/umitkacar/sam2-edge-cpp?style=for-the-badge\u0026logo=github\u0026color=yellow)](https://github.com/umitkacar/sam2-edge-cpp/stargazers)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE)\n[![C++](https://img.shields.io/badge/C++-17-00599C?style=for-the-badge\u0026logo=cplusplus\u0026logoColor=white)](https://isocpp.org/)\n[![Python](https://img.shields.io/badge/Python-3.9+-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://python.org)\n[![ONNX](https://img.shields.io/badge/ONNX-Runtime_1.12.1-005CED?style=for-the-badge)](https://onnxruntime.ai/)\n[![OpenCV](https://img.shields.io/badge/OpenCV-4.8.0-5C3EE8?style=for-the-badge\u0026logo=opencv\u0026logoColor=white)](https://opencv.org/)\n\n[![Tests](https://img.shields.io/badge/Tests-11/11_Pass-success?style=for-the-badge\u0026logo=pytest)](tests/)\n[![Coverage](https://img.shields.io/badge/Coverage-73.06%25-brightgreen?style=for-the-badge\u0026logo=codecov)](htmlcov/)\n[![MyPy](https://img.shields.io/badge/MyPy-0_Errors-blue?style=for-the-badge)](http://mypy-lang.org/)\n[![Ruff](https://img.shields.io/badge/Ruff-0_Violations-red?style=for-the-badge)](https://github.com/astral-sh/ruff)\n\n\u003c/div\u003e\n\n---\n\n## 🌟 Overview\n\nThis project implements the **EdgeSAM** (Segmentation-Anything Model) using ONNX Runtime and OpenCV in C++, delivering **40x faster inference** for edge device deployment.\n\n## 🌐 Web Interface\n\nVisit our ultra-modern web interface by opening `index.html` in your browser to explore:\n\n- 🎨 Interactive demo with animations\n- ⚡ Feature showcase with glassmorphism design\n- 📚 Quick installation guide\n- 🎯 Technology stack overview\n\n**Features:**\n\n- Modern, responsive design\n- Smooth animations and transitions\n- Interactive UI elements\n- Dark theme with gradient effects\n\n## Paper\n\n- [EdgeSAM: Prompt-In-the-Loop Distillation for On-Device Deployment of SAM](https://arxiv.org/pdf/2312.06660.pdf)\n\n## Features\n\n- Uses Edge SAM model for segmentation, which includes a preprocessing model and a SAM model.\n- Image preprocessing and segmentation with ONNX Runtime and OpenCV.\n- Efficient handling of image inputs and outputs.\n- Customizable for different segmentation tasks.\n\n## Model Compatibility\n\n- This implementation is compatible with the Edge SAM model in ONNX format. The model paths are specified in the parameters and expected to be in the ONNX format.\n\n## Installation\n\nBefore running the project, ensure that the following libraries are installed:\n\n- C++ Compiler (supporting C++17 or later)\n- OpenCV (4.8.0)\n- ONNX Runtime (1.12.1)\n\nThese libraries can typically be installed via `pip` or your system's package manager.\n\n## Usage\n\n- Place your ONNX model files in the models directory.\n- Place the images for processing in the images directory.\n- Compile the code using a C++ compiler.\n- Run the executable. The program processes the image using the EdgeSAM model and outputs the results.\n\n```bash\n. ./build.sh\n./edgeSamOrtCpp ../images/xxx.png\n```\n\n## Input Format\n\nThe application expects the following input format:\n\n- Model path: \"../models/edge_sam_3x_encoder.onnx\" or \"../models/edge_sam_3x_decoder.onnx\"\n- Image path: \"../images/xxx.png\"\n\n## Output\n\nThe program outputs the segmented image with applied masks. Additional information like image resizing and processing steps are logged to the console.\n\n---\n\n## 🐍 Python Package\n\nEdgeSAM now includes a comprehensive Python package with modern development tooling!\n\n### Installation\n\n```bash\n# Install from source\npip install -e .\n\n# Install with development dependencies\npip install -e \".[dev]\"\n\n# Install with all optional dependencies\npip install -e \".[all]\"\n```\n\n### Quick Start (Python)\n\n```python\nfrom edgesam_py import EdgeSAMSegmenter\nimport numpy as np\n\n# Initialize segmenter\nsegmenter = EdgeSAMSegmenter(\n    encoder_path=\"models/edge_sam_3x_encoder.onnx\",\n    decoder_path=\"models/edge_sam_3x_decoder.onnx\"\n)\n\n# Segment an image\nimage, mask = segmenter.segment(\"path/to/image.png\")\n\n# Save result\nsegmenter.save_result(image, mask, \"output.png\")\n```\n\n### Command Line Interface\n\n```bash\n# Basic usage\nedgesam -i input.png\n\n# With custom prompt point\nedgesam -i input.png --point-x 512 --point-y 512\n\n# With GPU acceleration\nedgesam -i input.png --gpu\n\n# Full options\nedgesam -i input.png -o output.png \\\n  -e models/encoder.onnx \\\n  -d models/decoder.onnx \\\n  --threshold 0.7 \\\n  --verbose\n```\n\n## 🛠️ Development Tools\n\nThis project uses **ultra-modern** Python development tooling for production-ready code:\n\n### Core Tools\n\n- **[Hatch](https://hatch.pypa.io/)** - Modern Python project manager with environment isolation\n- **[Ruff](https://github.com/astral-sh/ruff)** ⚡ - Ultra-fast linter **AND** formatter (10-100x faster than traditional tools!)\n  - Replaces Black + Flake8 + isort + pyupgrade in a single tool\n  - Written in Rust for maximum performance\n- **[UV](https://github.com/astral-sh/uv)** 🚀 - Blazing fast Python package installer (10-100x faster than pip)\n- **[MyPy](https://mypy-lang.org/)** - Strict static type checker with full coverage\n- **[Pytest](https://pytest.org/)** - Testing framework with:\n  - **pytest-xdist** for parallel execution (6x faster!)\n  - **pytest-cov** for comprehensive coverage tracking (73%+ coverage)\n  - **pytest-benchmark** for performance testing\n- **[Pre-commit](https://pre-commit.com/)** - Automated quality gates on every commit\n\n### Test Results ✅\n\n```\n✅ 11/11 tests passing (100%)\n✅ 73.06% code coverage\n✅ 0 mypy errors\n✅ 0 ruff violations\n✅ 0 security issues (bandit)\n✅ Production ready!\n```\n\n### Coverage Breakdown\n\n```\nName                         Stmts   Miss Branch BrPart   Cover\n-----------------------------------------------------------------\nedgesam_py/__init__.py           7      2      0      0  71.43%\nedgesam_py/cli.py               64     21     22      8  59.30%\nedgesam_py/segmentation.py      78      8     22      7  85.00%\n-----------------------------------------------------------------\nTOTAL                          149     31     44     15  73.06%\n```\n\n### Quick Start for Development\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/umitkacar/edgeSAM-onnxruntime-cpp\ncd edgeSAM-onnxruntime-cpp\n\n# 2. Install with development dependencies\npip install -e \".[dev]\"\n\n# 3. Install pre-commit hooks\npre-commit install\n\n# 4. Run tests to verify installation\npytest -n auto\n\n# 5. You're ready to develop! 🎉\n```\n\n### Development Commands\n\n#### Using Hatch (Recommended)\n\n```bash\n# Run tests\nhatch run test\n\n# Run tests with coverage\nhatch run test-cov\n\n# Run tests in parallel (6x faster!)\npytest -n auto\n\n# Run linters and type checking\nhatch run lint:all\n\n# Format code (Ruff)\nhatch run lint:fmt\n\n# Type checking (MyPy)\nhatch run lint:typing\n```\n\n#### Using pytest directly\n\n```bash\n# Run all tests (fast, parallel)\npytest -n auto\n\n# Run with verbose output\npytest -xvs\n\n# Run with coverage report\npytest --cov=edgesam_py --cov-report=term-missing\n\n# Run only fast tests (skip slow integration tests)\npytest -m \"not slow\"\n\n# Run specific test file\npytest tests/test_segmentation.py\n\n# Run specific test\npytest tests/test_cli.py::TestCLI::test_version_flag\n```\n\n#### Code Quality Commands\n\n```bash\n# Lint and auto-fix with Ruff\nruff check --fix .\n\n# Format code with Ruff\nruff format .\n\n# Type check with MyPy\nmypy edgesam_py tests\n\n# Run all quality checks\nruff check . \u0026\u0026 ruff format --check . \u0026\u0026 mypy edgesam_py tests\n```\n\n### Pre-commit Hooks\n\nInstall pre-commit hooks:\n\n```bash\npre-commit install\n```\n\nRun on all files:\n\n```bash\npre-commit run --all-files\n```\n\n### Advanced Testing\n\n```bash\n# Run all tests with parallel execution (FAST!)\npytest -n auto\n\n# Run with comprehensive coverage\npytest --cov=edgesam_py --cov-branch --cov-report=html\n# Open htmlcov/index.html in browser to see detailed coverage\n\n# Run only unit tests\npytest -m unit\n\n# Run only integration tests\npytest -m integration\n\n# Run only slow tests\npytest -m slow\n\n# Run benchmarks\npytest -m benchmark\n\n# Run with verbose output and stop on first failure\npytest -xvs --tb=short\n\n# Run and generate all report formats\npytest --cov=edgesam_py --cov-report=term --cov-report=html --cov-report=xml\n```\n\n### Using UV for Faster Package Management\n\n```bash\n# Install dependencies with UV (10-100x faster than pip!)\nuv pip install -e \".[dev]\"\n\n# Compile requirements with lock file\nuv pip compile pyproject.toml -o requirements.txt\n\n# Sync dependencies\nuv pip sync requirements.txt\n\n# Install a single package\nuv pip install numpy\n```\n\n## 📊 Code Quality \u0026 Standards\n\n### Automated Quality Enforcement\n\nEvery commit is automatically checked for:\n\n- ✅ **Code Style**: Ruff formatting (Black-compatible, 100-char lines)\n- ✅ **Linting**: Ruff linter (20+ rule categories including security)\n- ✅ **Type Safety**: MyPy strict type checking with zero errors\n- ✅ **Testing**: 73.06% code coverage, all tests passing\n- ✅ **Security**: Bandit security scanning, no vulnerabilities\n- ✅ **Secrets**: No credentials or API keys in code (detect-secrets)\n- ✅ **Shell Scripts**: ShellCheck validation for bash scripts\n- ✅ **Documentation**: Markdownlint for consistent docs\n\n### Quality Metrics\n\n| Metric | Target | Current | Status |\n|--------|--------|---------|--------|\n| Test Coverage | ≥70% | **73.06%** | ✅ Pass |\n| Tests Passing | 100% | **11/11 (100%)** | ✅ Pass |\n| MyPy Errors | 0 | **0** | ✅ Pass |\n| Ruff Violations | 0 | **0** | ✅ Pass |\n| Security Issues | 0 | **0** | ✅ Pass |\n| Type Hints | 100% | **100%** | ✅ Pass |\n\n### Pre-commit Hooks Pipeline\n\nWhen you commit, these checks run automatically:\n\n1. **General Checks** (5 hooks)\n   - Trailing whitespace removal\n   - End-of-file fixing\n   - YAML/TOML/JSON validation\n   - Merge conflict detection\n   - Large file prevention (\u003e1MB)\n\n2. **Python Quality** (4 hooks)\n   - Ruff linting with auto-fix\n   - Ruff formatting\n   - MyPy type checking\n   - PyUpgrade syntax modernization\n\n3. **Security** (2 hooks)\n   - Bandit security scanning\n   - Detect-secrets credential scanning\n\n4. **Multi-language** (5 hooks)\n   - ShellCheck for bash scripts\n   - Clang-format for C++ code\n   - CMake-format for CMake files\n   - Prettier for web files (JS/CSS/HTML)\n   - Markdownlint for documentation\n\n5. **Testing** (on push only - slower)\n   - Full pytest suite\n   - Coverage threshold check (≥70%)\n\n**Total time**: ~5 seconds on commit, ~30 seconds on push\n\n## 🏗️ Project Structure\n\n```\nedgeSAM-onnxruntime-cpp/\n├── 📦 edgesam_py/              # Python package (production-ready)\n│   ├── __init__.py             # Package exports and version\n│   ├── _version.py             # Auto-generated version (VCS)\n│   ├── segmentation.py         # Core EdgeSAM segmentation (85% coverage)\n│   └── cli.py                  # Command-line interface (59% coverage)\n│\n├── 🧪 tests/                   # Comprehensive test suite (73% coverage)\n│   ├── __init__.py\n│   ├── conftest.py             # Pytest fixtures and configuration\n│   ├── test_segmentation.py   # Segmentation tests (7 tests)\n│   └── test_cli.py             # CLI tests (4 tests)\n│\n├── 🔧 src/                     # C++ source code\n│   ├── edgeSam.cpp             # C++ implementation\n│   ├── edgeSam.h               # C++ headers\n│   └── main.cpp                # C++ entry point\n│\n├── 📚 include/                 # ONNX Runtime headers\n│   └── onnxruntime/            # ONNX Runtime C++ API\n│\n├── 🤖 models/                  # ONNX model files (not in repo)\n│   ├── edge_sam_3x_encoder.onnx\n│   └── edge_sam_3x_decoder.onnx\n│\n├── 🖼️ images/                  # Test images (not in repo)\n│\n├── 🌐 Web Interface\n│   ├── index.html              # Modern glassmorphism UI\n│   ├── styles.css              # Responsive styling\n│   └── script.js               # Interactive features\n│\n├── 📋 Documentation\n│   ├── README.md               # This file\n│   ├── CHANGELOG.md            # Detailed version history\n│   └── LESSONS_LEARNED.md      # Development insights (400+ lines)\n│\n├── ⚙️ Configuration\n│   ├── pyproject.toml          # Python project config (modern, Hatch-based)\n│   ├── .pre-commit-config.yaml # 15+ pre-commit hooks\n│   ├── .clang-format           # C++ formatting rules\n│   ├── .secrets.baseline       # Secret scanning baseline\n│   └── build.sh                # C++ build script\n│\n└── 🔨 Build artifacts\n    ├── htmlcov/                # Coverage HTML reports\n    ├── .coverage               # Coverage data\n    └── .pytest_cache/          # Pytest cache\n```\n\n### Key Files\n\n- **pyproject.toml**: Modern Python packaging with Hatch, Ruff, MyPy configuration\n- **LESSONS_LEARNED.md**: In-depth analysis of refactoring decisions (must-read!)\n- **CHANGELOG.md**: Complete version history with migration guides\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Setup\n\n1. **Fork and clone**:\n```bash\ngit clone https://github.com/YOUR_USERNAME/edgeSAM-onnxruntime-cpp\ncd edgeSAM-onnxruntime-cpp\n```\n\n2. **Create a feature branch**:\n```bash\ngit checkout -b feature/amazing-feature\n```\n\n3. **Install development dependencies**:\n```bash\npip install -e \".[dev]\"\n# Or use UV for faster installation:\nuv pip install -e \".[dev]\"\n```\n\n4. **Install pre-commit hooks**:\n```bash\npre-commit install\n```\n\n### Development Workflow\n\n1. **Make your changes** with confidence - tests will catch issues!\n\n2. **Run tests locally**:\n```bash\n# Fast parallel tests\npytest -n auto\n\n# With coverage\npytest --cov=edgesam_py\n```\n\n3. **Format and lint**:\n```bash\n# Auto-format code\nruff format .\n\n# Lint and auto-fix\nruff check --fix .\n\n# Type check\nmypy edgesam_py tests\n```\n\n4. **Commit your changes**:\n```bash\ngit add .\ngit commit -m 'Add amazing feature'\n# Pre-commit hooks will run automatically!\n```\n\n5. **Push and create PR**:\n```bash\ngit push origin feature/amazing-feature\n# Then open a Pull Request on GitHub\n```\n\n### Quality Requirements\n\nAll contributions must pass:\n\n- ✅ **Ruff linting** (no violations)\n- ✅ **Ruff formatting** (Black-compatible style)\n- ✅ **MyPy type checking** (strict mode, zero errors)\n- ✅ **Pytest tests** (all tests passing)\n- ✅ **Coverage** (maintain or improve 73%+ coverage)\n- ✅ **Pre-commit hooks** (15+ automated checks)\n- ✅ **Security scanning** (Bandit, no vulnerabilities)\n\n### Testing Your Changes\n\n```bash\n# Run the full test suite\npytest -xvs\n\n# Run with coverage check\npytest --cov=edgesam_py --cov-report=term-missing --cov-fail-under=70\n\n# Run pre-commit on all files (same as CI)\npre-commit run --all-files\n\n# Verify type safety\nmypy edgesam_py tests\n```\n\n### Documentation\n\nIf you're adding new features:\n- Add docstrings (Google style)\n- Update README.md if needed\n- Add tests for new functionality\n- Update CHANGELOG.md\n\n### Code Style Guidelines\n\nWe use **Ruff** for both linting and formatting:\n\n```python\n# Good - Type hints, clear names, docstrings\ndef segment_image(\n    image_path: Path,\n    point_coords: NDArray[np.float32] | None = None,\n) -\u003e tuple[NDArray[np.uint8], NDArray[np.float32]]:\n    \"\"\"Segment an image using EdgeSAM.\n\n    Args:\n        image_path: Path to input image.\n        point_coords: Optional point coordinates for prompting.\n\n    Returns:\n        Tuple of (original image, segmentation mask).\n\n    Raises:\n        FileNotFoundError: If image doesn't exist.\n    \"\"\"\n    # Implementation here\n```\n\n### Need Help?\n\n- 📖 Read [LESSONS_LEARNED.md](LESSONS_LEARNED.md) for detailed insights\n- 📋 Check [CHANGELOG.md](CHANGELOG.md) for recent changes\n- 💬 Open an issue for questions or suggestions\n- 🐛 Report bugs with minimal reproduction examples\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumitkacar%2Fsam2-edge-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumitkacar%2Fsam2-edge-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumitkacar%2Fsam2-edge-cpp/lists"}