{"id":42881972,"url":"https://github.com/opengeos/qgis-samgeo-plugin","last_synced_at":"2026-05-09T00:06:41.740Z","repository":{"id":328348138,"uuid":"1113158556","full_name":"opengeos/qgis-samgeo-plugin","owner":"opengeos","description":"QGIS plugin for the SamGeo Python package","archived":false,"fork":false,"pushed_at":"2025-12-14T01:02:35.000Z","size":76,"stargazers_count":59,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-12-14T05:50:02.044Z","etag":null,"topics":["deep-learning","geoai","geospatial","qgis","qgis-plugin","samgeo","segementation"],"latest_commit_sha":null,"homepage":"https://samgeo.gishub.org","language":"Python","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/opengeos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","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":"2025-12-09T15:46:24.000Z","updated_at":"2025-12-14T04:27:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/opengeos/qgis-samgeo-plugin","commit_stats":null,"previous_names":["opengeos/qgis-samgeo-plugin"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/opengeos/qgis-samgeo-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opengeos%2Fqgis-samgeo-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opengeos%2Fqgis-samgeo-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opengeos%2Fqgis-samgeo-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opengeos%2Fqgis-samgeo-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opengeos","download_url":"https://codeload.github.com/opengeos/qgis-samgeo-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opengeos%2Fqgis-samgeo-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28914650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T12:13:43.263Z","status":"ssl_error","status_checked_at":"2026-01-30T12:13:22.389Z","response_time":66,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["deep-learning","geoai","geospatial","qgis","qgis-plugin","samgeo","segementation"],"created_at":"2026-01-30T14:41:44.136Z","updated_at":"2026-01-30T14:41:44.217Z","avatar_url":"https://github.com/opengeos.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SamGeo QGIS Plugin\n\n[![DOI](https://joss.theoj.org/papers/10.21105/joss.05663/status.svg)](https://doi.org/10.21105/joss.05663)\n[![QGIS](https://img.shields.io/badge/QGIS-plugin-orange.svg)](https://github.com/opengeos/qgis-samgeo-plugin)\n[![QGIS](https://img.shields.io/badge/SamGeo-repository-blue.svg)](https://github.com/opengeos/segment-geospatial)\n\nA QGIS plugin for remote sensing image segmentation using [SamGeo](https://samgeo.gishub.org), powered by Meta's Segment Anything Model ([SAM](https://github.com/facebookresearch/sam3)).\n\n## Features\n\n- **Multiple SAM versions**: Support for SamGeo (SAM1), SamGeo2 (SAM2), and SamGeo3 (SAM3)\n- **Text-based segmentation**: Describe what you want to segment (e.g., \"building\", \"tree\", \"road\")\n- **Interactive point prompts**: Click on the map to add foreground/background points\n- **Box prompts**: Draw rectangles to segment specific regions\n- **GeoTIFF support**: Works with georeferenced images, preserving spatial reference\n- **Multiple output formats**: Save as vector (GeoPackage, Shapefile) or raster (GeoTIFF)\n\n## Demos\n\nCheck out this [short video demo](https://youtu.be/DKKrQKeU3Ik) and [full video tutorial](https://youtu.be/oPZc7BvDsHE) on how to use the plugin.\n\n[![](https://github.com/user-attachments/assets/0a9dbc4a-98fa-4a14-8238-be5b871926fa)](https://youtu.be/oPZc7BvDsHE)\n\n## Requirements\n\n- QGIS 3.22 or later\n- Python 3.10+\n- SamGeo package\n- Hugging Face account (for model downloads)\n- Access to Meta's SAM 3 model\n\n## Installation\n\n### 1. Install SamGeo\n\nFirst, install SamGeo in your QGIS Python environment. It is recommended to create a new conda environment **and** install QGIS and SamGeo. Install [Miniconda ](https://www.anaconda.com/docs/getting-started/miniconda/install), then run the following commands to install SamGeo on macOS/Linux:\n\n```bash\nconda create -n geo python=3.12\nconda activate geo\nconda install -c conda-forge qgis segment-geospatial\n```\n\nSome SamGeo dependencies are only available on PyPI. Run the following command to install all dependencies:\n\n```bash\npip install -U \"segment-geospatial[samgeo3]\"\n```\n\nIt is a bit tricky to install SAM 3 on Windows. Run the following commands on Windows to install SamGeo:\n\n```bash\nconda create -n geo python=3.12\nconda activate geo\nconda install pytorch torchvision pytorch-cuda=12.1 -c pytorch -c nvidia\npip install \"segment-geospatial[samgeo3]\" triton-windows\nconda install -c conda-forge qgis\n```\n\n### 2. Install the Plugin\n\n#### Option A: Using the install script\n\n```bash\n# Clone the repository\ngit clone https://github.com/opengeos/qgis-samgeo-plugin.git\ncd qgis-samgeo-plugin\nconda activate geo\n\n# Install (Linux/macOS)\npython install_plugin.py\n\n# Or use the shell script\nchmod +x install_plugin.sh\n./install_plugin.sh\n```\n\n#### Option B: Manual installation\n\n1. Find your QGIS plugins directory:\n\n   - Linux: `~/.local/share/QGIS/QGIS3/profiles/default/python/plugins`\n   - macOS: `~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins`\n   - Windows: `%APPDATA%\\QGIS\\QGIS3\\profiles\\default\\python\\plugins`\n\n2. Copy or symlink this entire folder (qgis-samgeo-plugin) to the plugins directory and rename it to `samgeo_plugin`:\n\n   ```bash\n   ln -s /path/to/qgis-samgeo-plugin ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/samgeo_plugin\n   ```\n\n3. Restart QGIS\n\n4. Enable the plugin: Go to **Plugins \u003e Manage and Install Plugins**, find \"SamGeo\", and enable it.\n\n### 3. Set up Hugging Face authentication\n\nSign up for a free account at [Hugging Face](https://huggingface.co/join) if you don't have one. Then, generate an access token by following the instructions [here](https://huggingface.co/docs/hub/en/security-tokens).\n\nRun the following command in your terminal to log in to Hugging Face:\n\n```bash\nhf auth login\n```\n\nProvide your access token when prompted.\n\n### 4. Request access to SAM 3 model\n\nTo use SamGeo3 (SAM 3), you need to request access to the model. Go to the [SAM 3 model page](https://huggingface.co/facebook/sam3) and log in with your Hugging Face account. Fill out the access request form and click on the \"Submit\" button to send your request. The approval process might take a few hours. Once approved, you can use SamGeo3 in the plugin.\n\nIf your request is denied, you can try to download the model from [ModelScope](https://www.modelscope.cn/models/facebook/sam3/files), which does not require access permission. After downloading, place the model files in the following directory:\n\n- Linux/macOS: `~/.cache/huggingface/hub/models--facebook--sam3`\n- Windows: `%USERPROFILE%\\.cache\\huggingface\\hub\\models--facebook--sam3`\n\n## Usage\n\n### Start QGIS\n\nRun the following commands to start QGIS and use the SamGeo plugin:\n\n```bash\nconda activate geo\nqgis\n```\n\n### Opening the Plugin\n\n1. Click the SamGeo icon in the toolbar, or\n2. Go to **Raster \u003e SamGeo \u003e SamGeo Segmentation**\n\n### Workflow\n\n#### 1. Load the Model\n\n1. In the **Model** tab, select your preferred SAM version:\n   - **SamGeo3 (SAM3)**: Latest version with text prompts support\n   - **SamGeo2 (SAM2)**: Second generation SAM\n   - **SamGeo (SAM1)**: Original SAM model\n2. Choose the backend (meta or transformers)\n3. Select the device (auto, cuda, or cpu)\n4. Set the confidence threshold (default: 0.5)\n5. Enable interactive mode if you want to use point/box prompts\n6. Click **Load Model**\n\n   ![](https://github.com/user-attachments/assets/f1e4e356-e460-4d94-83ec-1f596d65156e)\n\n#### 2. Set an Image\n\n- Select a raster layer from the dropdown and click **Set Image from Layer**, or\n- Browse for an image file and click **Set Image from File**\n- You can download a sample image from [here](https://huggingface.co/datasets/giswqs/geospatial/resolve/main/uc_berkeley.tif)\n\n  ![](https://github.com/user-attachments/assets/b7c6a430-c4c3-4359-855c-b198cdcf2c91)\n\n#### 3. Segment the Image\n\n##### Text-Based Segmentation (Text tab)\n\n1. Enter a text prompt describing what to segment (e.g., \"tree\", \"building\")\n2. Optionally set min/max size filters\n3. Click **Segment by Text**\n\n   ![](https://github.com/user-attachments/assets/37012722-e1aa-4abe-9b25-8955064cfd8d)\n\n##### Point-Based Segmentation (Interactive tab)\n\n1. Click **Add Foreground Points** and click on objects to include\n2. Click **Add Background Points** and click on areas to exclude\n3. Click **Segment by Points**\n4. Right-click to finish adding points\n\n   ![](https://github.com/user-attachments/assets/0eb1174d-5e22-4555-be7d-aec0714c147d)\n\n##### Box-Based Segmentation (Interactive tab)\n\n1. Click **Draw Box**\n2. Draw a rectangle around the area to segment\n3. Click **Segment by Box**\n\n   ![](https://github.com/user-attachments/assets/5aa962ae-4ed2-4696-a609-c586006a2ed8)\n\n##### Batch Point Segmentation (Batch tab)\n\nUse this mode to process many points at once (e.g., building centroids):\n\n1. Select a point vector layer from the dropdown, or browse for a vector file (GeoJSON, Shapefile, etc.)\n2. Optionally specify the CRS if not auto-detected (e.g., \"EPSG:4326\")\n3. Set min/max size filters if needed\n4. Optionally specify an output raster file path\n5. Click **Run Batch Segmentation**\n\n   ![](https://github.com/user-attachments/assets/b7714361-2122-4953-9fe0-61f2e9ae9b1d)\n\nEach point generates a separate mask, making this efficient for segmenting many individual objects.\n\n#### 4. Save Results (Output tab)\n\n1. Choose output format (vector or raster)\n2. Set the output file path\n3. Click **Save Masks**\n\n   ![](https://github.com/user-attachments/assets/84d00598-56a2-42c3-8cea-bfbf739c4e65)\n\n## Programmatic Usage\n\nYou can also use SamGeo programmatically in the QGIS Python console:\n\n```python\nfrom samgeo import SamGeo3\n\n# Initialize the model\nsam = SamGeo3(\n    backend=\"meta\",\n    enable_inst_interactivity=True,\n    confidence_threshold=0.5,\n)\n\n# Set an image (GeoTIFF)\nsam.set_image(\"/path/to/your/image.tif\")\n\n# Text-based segmentation\nsam.generate_masks(\"building\")\nsam.save_masks(\"buildings.tif\", unique=True)\n\n# Point-based segmentation\npoint_coords = [[500, 300], [600, 400]]  # pixel coordinates\npoint_labels = [1, 1]  # 1=foreground, 0=background\nsam.generate_masks_by_points(point_coords, point_labels)\nsam.save_masks(\"points_result.tif\")\n\n# Batch point segmentation (from vector file)\nsam.generate_masks_by_points_patch(\n    point_coords_batch=\"building_centroids.geojson\",\n    point_crs=\"EPSG:4326\",\n    output=\"building_masks.tif\",\n    unique=True,\n)\n\n# Box-based segmentation\nboxes = [[100, 100, 500, 500]]  # [xmin, ymin, xmax, ymax] in pixels\nsam.generate_masks_by_boxes(boxes)\nsam.save_masks(\"box_result.tif\")\n\n# Convert raster mask to vector\nfrom samgeo import common\ncommon.raster_to_vector(\"buildings.tif\", \"buildings.gpkg\")\n```\n\n## Troubleshooting\n\n### Model fails to load\n\n- Ensure segment-geospatial is installed with the appropriate SAM support\n- Check that you have enough GPU memory (or switch to CPU)\n- Try restarting QGIS\n\n### Segmentation is slow\n\n- Use a GPU if available (select \"cuda\" device)\n- Reduce image resolution before processing\n- Use the transformers backend which may be faster for some tasks\n\n### No objects found\n\n- Try a different text prompt\n- Lower the confidence threshold\n- Adjust min/max size filters\n- Ensure the image is properly loaded\n\n## License\n\nThis plugin is released under the MIT License.\n\n## Citation\n\nIf you use this plugin in your research, please cite:\n\n```bibtex\n@article{wu2023samgeo,\n  title     = \"{samgeo: A Python package for segmenting geospatial data with the\n               Segment Anything Model (SAM)}\",\n  author    = \"Wu, Qiusheng and Osco, Lucas Prado\",\n  journal   = \"Journal of Open Source Software\",\n  volume    =  8,\n  number    =  89,\n  pages     =  5663,\n  year      =  2023,\n  url       = \"https://doi.org/10.21105/joss.05663\",\n  doi       = \"10.21105/joss.05663\",\n  issn      = \"2475-9066\"\n}\n```\n\n## Contributing\n\nContributions are welcome! Please see the [GitHub repository](https://github.com/opengeos/qgis-samgeo-plugin) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopengeos%2Fqgis-samgeo-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopengeos%2Fqgis-samgeo-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopengeos%2Fqgis-samgeo-plugin/lists"}