# opengeos/segment-geospatial architecture

> Architecture diagram of the GitHub repository opengeos/segment-geospatial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opengeos/segment-geospatial
- Repository: https://github.com/opengeos/segment-geospatial

## Overview

SamGeo is a geospatial image-segmentation product exposed through a Python library, a Click CLI, a REST API, and a QGIS plugin. The main workflow is to supply imagery and prompts or select automatic segmentation, run a SAM-family model, then save or visualize raster/vector results. The graph also preserves documented tile download, text prompting, time-series/video, and plugin-installation capabilities. Some feature branches are documented but not fully sampled; those links are omitted rather than inferred from names alone.

Main entry points: [`agent-harness/cli_anything/samgeo/utils/samgeo_backend.py`](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/utils/samgeo_backend.py) (Model Backend), [`agent-harness/cli_anything/samgeo/samgeo_cli.py`](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/samgeo_cli.py) (CLI), [`samgeo/api.py`](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/api.py) (REST API), [`samgeo/common.py`](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/common.py) (Geospatial Utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[samgeo_cli.py]"]
  node_rest["REST API<br/>[api.py]"]
end

subgraph group_workflow["Segmentation Workflow"]
  node_project["Project State<br/>[project.py]"]
  node_session["Session History<br/>[session.py]"]
  node_raster_data["Raster Data<br/>[data.py]"]
  node_prompted_seg["Prompted Segmentation<br/>[segment.py]"]
  node_vector_data["Vector Data<br/>[vector.py]"]
  node_export["Result Export<br/>[export.py]"]
  node_common["Geospatial Utilities<br/>[common.py]"]
end

subgraph group_models["Model Backends"]
  node_backend["Model Backend<br/>[samgeo_backend.py]"]
  node_sam1["SAM<br/>[samgeo.py]"]
  node_sam2["SAM 2<br/>[samgeo2.py]"]
  node_sam3["SAM 3<br/>[samgeo3.py]"]
  node_fast["Fast SAM<br/>[fast_sam.py]"]
  node_hq["HQ-SAM<br/>[hq_sam.py]"]
  node_text["Text Prompts<br/>[text_sam.py]"]
  node_registry["Model Registry<br/>[model_registry.py]"]
end

subgraph group_qgis["QGIS Plugin"]
  node_qgis_ui["QGIS Interface<br/>[samgeo_plugin.py]"]
  node_installer["Dependency Setup<br/>[venv_manager.py]"]
  node_python["Python Manager<br/>[python_manager.py]"]
  node_uv["UV Manager<br/>[uv_manager.py]"]
  node_install_worker["Install Worker"]
  node_install_dialog["Install Dialog"]
  node_map_tools["Map Tools<br/>[map_tools.py]"]
end

node_user(("User"))
node_tile_service["TMS Service"]
node_raster_store[("Geospatial Files")]

node_user -->|"runs commands"| node_cli
node_user -->|"sends requests"| node_rest
node_user -->|"uses plugin"| node_qgis_ui
node_cli -->|"manages projects"| node_project
node_cli -->|"uses sessions"| node_session
node_cli -->|"calls data tools"| node_raster_data
node_cli -->|"runs segmentation"| node_prompted_seg
node_cli -->|"calls vector tools"| node_vector_data
node_cli -->|"exports results"| node_export
node_prompted_seg -->|"updates state"| node_project
node_prompted_seg -->|"creates model"| node_backend
node_raster_data -->|"uses utilities"| node_backend
node_vector_data -->|"uses utilities"| node_backend
node_export -->|"reads project"| node_project
node_export -->|"uses utilities"| node_backend
node_raster_data -->|"reads and writes"| node_raster_store
node_export -->|"writes results"| node_raster_store
node_raster_data -->|"downloads tiles"| node_tile_service
node_backend -->|"instantiates"| node_sam1
node_backend -->|"instantiates"| node_sam2
node_backend -->|"instantiates"| node_sam3
node_backend -->|"instantiates"| node_fast
node_backend -->|"instantiates"| node_hq
node_backend -->|"instantiates"| node_text
node_sam1 -->|"uses utilities"| node_common
node_sam2 -->|"uses utilities"| node_common
node_sam3 -->|"uses utilities"| node_common
node_fast -->|"uses utilities"| node_common
node_hq -->|"uses utilities"| node_common
node_text -->|"uses utilities"| node_common
node_text -->|"uses model"| node_sam2
node_rest -->|"routes inference"| node_sam1
node_rest -->|"routes inference"| node_sam2
node_rest -->|"routes inference"| node_sam3
node_rest -->|"uses registry"| node_registry
node_rest -->|"uses utilities"| node_common
node_qgis_ui -->|"uses tools"| node_map_tools
node_qgis_ui -->|"manages dependencies"| node_installer
node_qgis_ui -->|"opens dialog"| node_install_dialog
node_qgis_ui -->|"starts worker"| node_install_worker
node_install_dialog -->|"signals requests"| node_qgis_ui
node_install_worker -->|"runs installation"| node_installer
node_installer -->|"uses manager"| node_python
node_installer -->|"uses manager"| node_uv

click node_cli "https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/samgeo_cli.py"
click node_rest "https://github.com/opengeos/segment-geospatial/blob/main/samgeo/api.py"
click node_qgis_ui "https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/samgeo_plugin.py"
click node_project "https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/project.py"
click node_session "https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/session.py"
click node_raster_data "https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/data.py"
click node_prompted_seg "https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/segment.py"
click node_vector_data "https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/vector.py"
click node_export "https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/export.py"
click node_backend "https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/utils/samgeo_backend.py"
click node_common "https://github.com/opengeos/segment-geospatial/blob/main/samgeo/common.py"
click node_sam1 "https://github.com/opengeos/segment-geospatial/blob/main/samgeo/samgeo.py"
click node_sam2 "https://github.com/opengeos/segment-geospatial/blob/main/samgeo/samgeo2.py"
click node_sam3 "https://github.com/opengeos/segment-geospatial/blob/main/samgeo/samgeo3.py"
click node_fast "https://github.com/opengeos/segment-geospatial/blob/main/samgeo/fast_sam.py"
click node_hq "https://github.com/opengeos/segment-geospatial/blob/main/samgeo/hq_sam.py"
click node_text "https://github.com/opengeos/segment-geospatial/blob/main/samgeo/text_sam.py"
click node_registry "https://github.com/opengeos/segment-geospatial/blob/main/samgeo/model_registry.py"
click node_installer "https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/core/venv_manager.py"
click node_python "https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/core/python_manager.py"
click node_uv "https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/core/uv_manager.py"
click node_install_worker "https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/workers/deps_install_worker.py"
click node_install_dialog "https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/deps_install_dialog.py"
click node_map_tools "https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/map_tools.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_rest,node_user toneBlue
class node_project,node_session,node_raster_data,node_prompted_seg,node_vector_data,node_export,node_common,node_raster_store toneAmber
class node_backend,node_sam1,node_sam2,node_sam3,node_fast,node_hq,node_text,node_registry toneMint
class node_qgis_ui,node_installer,node_python,node_uv,node_install_worker,node_install_dialog,node_map_tools toneRose
class node_tile_service toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/samgeo_cli.py): `agent-harness/cli_anything/samgeo/samgeo_cli.py`
- [REST API](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/api.py): `samgeo/api.py`

### Segmentation Workflow

- [Project State](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/project.py): `agent-harness/cli_anything/samgeo/core/project.py`
- [Session History](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/session.py): `agent-harness/cli_anything/samgeo/core/session.py`
- [Raster Data](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/data.py): `agent-harness/cli_anything/samgeo/core/data.py`
- [Prompted Segmentation](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/segment.py): `agent-harness/cli_anything/samgeo/core/segment.py`
- [Vector Data](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/vector.py): `agent-harness/cli_anything/samgeo/core/vector.py`
- [Result Export](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/core/export.py): `agent-harness/cli_anything/samgeo/core/export.py`
- [Geospatial Utilities](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/common.py): `samgeo/common.py`

### Model Backends

- [Model Backend](https://github.com/opengeos/segment-geospatial/blob/main/agent-harness/cli_anything/samgeo/utils/samgeo_backend.py): `agent-harness/cli_anything/samgeo/utils/samgeo_backend.py`
- [SAM](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/samgeo.py): `samgeo/samgeo.py`
- [SAM 2](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/samgeo2.py): `samgeo/samgeo2.py`
- [SAM 3](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/samgeo3.py): `samgeo/samgeo3.py`
- [Fast SAM](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/fast_sam.py): `samgeo/fast_sam.py`
- [HQ-SAM](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/hq_sam.py): `samgeo/hq_sam.py`
- [Text Prompts](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/text_sam.py): `samgeo/text_sam.py`
- [Model Registry](https://github.com/opengeos/segment-geospatial/blob/main/samgeo/model_registry.py): `samgeo/model_registry.py`

### QGIS Plugin

- [QGIS Interface](https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/samgeo_plugin.py): `qgis-samgeo-plugin/samgeo_plugin.py`
- [Dependency Setup](https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/core/venv_manager.py): `qgis-samgeo-plugin/core/venv_manager.py`
- [Python Manager](https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/core/python_manager.py): `qgis-samgeo-plugin/core/python_manager.py`
- [UV Manager](https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/core/uv_manager.py): `qgis-samgeo-plugin/core/uv_manager.py`
- [Install Worker](https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/workers/deps_install_worker.py): `qgis-samgeo-plugin/workers/deps_install_worker.py`
- [Install Dialog](https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/deps_install_dialog.py): `qgis-samgeo-plugin/deps_install_dialog.py`
- [Map Tools](https://github.com/opengeos/segment-geospatial/blob/main/qgis-samgeo-plugin/map_tools.py): `qgis-samgeo-plugin/map_tools.py`

### Other components

- **User**
- **TMS Service**
- **Geospatial Files**

## Connections

- User → CLI: runs commands (evidence: `README.md`)
- User → REST API: sends requests (evidence: `README.md`)
- User → QGIS Interface: uses plugin (evidence: `README.md`)
- CLI → Project State: manages projects (evidence: `agent-harness/cli_anything/samgeo/samgeo_cli.py`)
- CLI → Session History: uses sessions (evidence: `agent-harness/cli_anything/samgeo/samgeo_cli.py`)
- CLI → Raster Data: calls data tools (evidence: `agent-harness/cli_anything/samgeo/samgeo_cli.py`)
- CLI → Prompted Segmentation: runs segmentation (evidence: `agent-harness/cli_anything/samgeo/samgeo_cli.py`)
- CLI → Vector Data: calls vector tools (evidence: `agent-harness/cli_anything/samgeo/samgeo_cli.py`)
- CLI → Result Export: exports results (evidence: `agent-harness/cli_anything/samgeo/samgeo_cli.py`)
- Prompted Segmentation → Project State: updates state (evidence: `agent-harness/cli_anything/samgeo/core/segment.py`)
- Prompted Segmentation → Model Backend: creates model (evidence: `agent-harness/cli_anything/samgeo/core/segment.py`)
- Raster Data → Model Backend: uses utilities (evidence: `agent-harness/cli_anything/samgeo/core/data.py`)
- Vector Data → Model Backend: uses utilities (evidence: `agent-harness/cli_anything/samgeo/core/vector.py`)
- Result Export → Project State: reads project (evidence: `agent-harness/cli_anything/samgeo/core/export.py`)
- Result Export → Model Backend: uses utilities (evidence: `agent-harness/cli_anything/samgeo/core/export.py`)
- Raster Data → Geospatial Files: reads and writes (evidence: `README.md`)
- Result Export → Geospatial Files: writes results (evidence: `README.md`)
- Raster Data → TMS Service: downloads tiles (evidence: `README.md`)
- Model Backend → SAM: instantiates (evidence: `agent-harness/cli_anything/samgeo/utils/samgeo_backend.py`)
- Model Backend → SAM 2: instantiates (evidence: `agent-harness/cli_anything/samgeo/utils/samgeo_backend.py`)
- Model Backend → SAM 3: instantiates (evidence: `agent-harness/cli_anything/samgeo/utils/samgeo_backend.py`)
- Model Backend → Fast SAM: instantiates (evidence: `agent-harness/cli_anything/samgeo/utils/samgeo_backend.py`)
- Model Backend → HQ-SAM: instantiates (evidence: `agent-harness/cli_anything/samgeo/utils/samgeo_backend.py`)
- Model Backend → Text Prompts: instantiates (evidence: `agent-harness/cli_anything/samgeo/utils/samgeo_backend.py`)
- SAM → Geospatial Utilities: uses utilities (evidence: `samgeo/samgeo.py`)
- SAM 2 → Geospatial Utilities: uses utilities (evidence: `samgeo/samgeo2.py`)
- SAM 3 → Geospatial Utilities: uses utilities (evidence: `samgeo/samgeo3.py`)
- Fast SAM → Geospatial Utilities: uses utilities (evidence: `samgeo/fast_sam.py`)
- HQ-SAM → Geospatial Utilities: uses utilities (evidence: `samgeo/hq_sam.py`)
- Text Prompts → Geospatial Utilities: uses utilities (evidence: `samgeo/text_sam.py`)
- Text Prompts → SAM 2: uses model (evidence: `samgeo/text_sam.py`)
- REST API → SAM: routes inference (evidence: `samgeo/api.py`)
- REST API → SAM 2: routes inference (evidence: `samgeo/api.py`)
- REST API → SAM 3: routes inference (evidence: `samgeo/api.py`)
- REST API → Model Registry: uses registry (evidence: `samgeo/api.py`)
- REST API → Geospatial Utilities: uses utilities (evidence: `samgeo/api.py`)
- QGIS Interface → Map Tools: uses tools (evidence: `qgis-samgeo-plugin/samgeo_plugin.py`)
- QGIS Interface → Dependency Setup: manages dependencies (evidence: `qgis-samgeo-plugin/samgeo_plugin.py`)
- QGIS Interface → Install Dialog: opens dialog (evidence: `qgis-samgeo-plugin/samgeo_plugin.py`)
- QGIS Interface → Install Worker: starts worker (evidence: `qgis-samgeo-plugin/samgeo_plugin.py`)
- Install Dialog → QGIS Interface: signals requests (evidence: `qgis-samgeo-plugin/samgeo_plugin.py`)
- Install Worker → Dependency Setup: runs installation (evidence: `qgis-samgeo-plugin/workers/deps_install_worker.py`)
- Dependency Setup → Python Manager: uses manager (evidence: `qgis-samgeo-plugin/core/venv_manager.py`)
- Dependency Setup → UV Manager: uses manager (evidence: `qgis-samgeo-plugin/core/venv_manager.py`)
