Skip to content

Commit 55e34b9

Browse files
giswqsgiswqs
authored
Add CLI harness for agent-driven geospatial segmentation (#523)
* Add CLI harness for agent-driven geospatial segmentation Build a complete, stateful CLI (cli-anything-samgeo) that wraps the segment-geospatial library so AI agents can segment satellite/aerial imagery without a GUI. Includes: - Click-based CLI with 7 command groups (project, model, segment, data, vector, export, session) and interactive REPL mode - --json output on every command for machine consumption - PEP 420 namespace package under cli_anything.samgeo - SKILL.md for AI-agent discoverability - 69 tests (45 unit + 24 E2E/subprocess), 100% pass rate - Supports SAM v1/2/3, FastSAM, HQ-SAM, and LangSAM backends * Fix all GitHub Copilot review comments - Guard os.makedirs against empty dirname so outputs like "masks.tif" in the current directory work (10 locations across all core modules) - Fix text_sam default model ID: "sam2" -> "vit_h" (valid LangSAM id) - Update LangSAM model registry with correct model IDs (vit_h, sam2-hiera-large) - Store device as None instead of "auto" to avoid invalid torch device; get_device() now treats "auto" as auto-detect - Preserve project_path in REPL context — only overwrite when explicitly provided, so subsequent commands find the active project - Forward dst_crs through all vector format-specific export branches - Validate column exists before filtering in filter_vectors() - Fix image_to_cog docstring (writes *_cog.tif, not in-place) - Align python_requires to >=3.10 (matching segment-geospatial) - Use self.name in REPL prompt instead of hardcoded "samgeo"
1 parent 278e86d commit 55e34b9

22 files changed

Lines changed: 4216 additions & 0 deletions

‎agent-harness/SAMGEO.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# SAMGEO: Agent Harness SOP
2+
3+
## Software Overview
4+
5+
**segment-geospatial** (samgeo) is a Python package for segmenting geospatial data
6+
using Meta AI's Segment Anything Model (SAM) family. It wraps SAM v1, SAM 2, SAM 3,
7+
FastSAM, HQ-SAM, and LangSAM with geospatial-aware I/O (GeoTIFF, GeoPackage, etc.).
8+
9+
## Backend
10+
11+
The backend is the `samgeo` Python library itself. Unlike GUI applications that need
12+
a headless CLI invocation, samgeo is already a Python library — the CLI harness imports
13+
and calls its classes/functions directly.
14+
15+
**Key classes:**
16+
- `SamGeo` (v1) — `samgeo.samgeo.SamGeo`
17+
- `SamGeo2` (v2) — `samgeo.samgeo2.SamGeo2`
18+
- `SamGeo3` (v3) — `samgeo.samgeo3.SamGeo3`
19+
- `LangSAM` — `samgeo.text_sam.LangSAM`
20+
21+
**Key utility functions** (from `samgeo.common`):
22+
- `tms_to_geotiff()` — Download TMS tiles as GeoTIFF
23+
- `raster_to_vector()` / `raster_to_gpkg()` / `raster_to_shp()` / `raster_to_geojson()`
24+
- `reproject()`, `split_raster()`, `image_to_cog()`
25+
- `get_profile()`, `get_basemaps()`
26+
27+
## Data Model
28+
29+
**Project state** is a JSON file tracking:
30+
- Source image path, CRS, bounds
31+
- Active model type and parameters
32+
- Generated mask paths
33+
- Vector output paths
34+
- Operation history (for undo/redo)
35+
36+
**File formats:**
37+
- Input: GeoTIFF, PNG, JPG, NumPy arrays, URLs
38+
- Mask output: GeoTIFF (raster masks)
39+
- Vector output: GeoPackage (.gpkg), Shapefile (.shp), GeoJSON (.geojson)
40+
- Project: JSON (.json)
41+
42+
## CLI Command Groups
43+
44+
| Group | Purpose |
45+
|-------|---------|
46+
| `project` | Create, open, save, inspect projects |
47+
| `model` | List, download, inspect SAM models |
48+
| `segment` | Automatic, point, box, and text segmentation |
49+
| `data` | Download tiles, inspect rasters, reproject, split |
50+
| `vector` | Convert masks to vectors, inspect, filter |
51+
| `export` | Export masks and vectors to various formats |
52+
| `session` | Undo/redo, history, session state |
53+
54+
## Dependencies
55+
56+
- `segment-geospatial` (the package itself — hard dependency)
57+
- `click` (CLI framework)
58+
- `prompt_toolkit` (REPL)
59+
- PyTorch + SAM model weights (downloaded on first use)

‎agent-harness/cli_anything/samgeo/README.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# cli-anything-samgeo
2+
3+
CLI harness for [segment-geospatial](https://github.com/opengeos/segment-geospatial) — segment geospatial imagery using SAM models from the command line.
4+
5+
## Prerequisites
6+
7+
- Python 3.10+
8+
- segment-geospatial: `pip install segment-geospatial[all]`
9+
- PyTorch with CUDA (recommended) or CPU
10+
11+
## Installation
12+
13+
```bash
14+
cd agent-harness
15+
pip install -e .
16+
```
17+
18+
This installs the `cli-anything-samgeo` command in your PATH.
19+
20+
## Quick Start
21+
22+
```bash
23+
# Create a project
24+
cli-anything-samgeo project new -n my-seg -o project.json -s image.tif
25+
26+
# Run automatic segmentation
27+
cli-anything-samgeo --project project.json segment automatic -o masks.tif
28+
29+
# Convert masks to vectors
30+
cli-anything-samgeo --project project.json vector convert masks.tif output.gpkg
31+
32+
# Export as GeoJSON
33+
cli-anything-samgeo --project project.json export render output.geojson -f geojson
34+
35+
# All commands support --json for machine-readable output
36+
cli-anything-samgeo --json model list
37+
```
38+
39+
## Command Groups
40+
41+
| Command | Description |
42+
|---------|-------------|
43+
| `project` | Create, open, inspect projects |
44+
| `model` | List, inspect, check SAM models |
45+
| `segment` | Automatic, point, box, text segmentation |
46+
| `data` | Download tiles, raster info, reproject, split |
47+
| `vector` | Convert masks to vectors, inspect, filter |
48+
| `export` | Export masks to various formats |
49+
| `session` | Session status and history |
50+
51+
## Interactive REPL
52+
53+
Run without arguments to enter the interactive REPL:
54+
55+
```bash
56+
cli-anything-samgeo
57+
```
58+
59+
## JSON Output
60+
61+
Add `--json` before any command for machine-readable output:
62+
63+
```bash
64+
cli-anything-samgeo --json data info image.tif
65+
cli-anything-samgeo --json model list
66+
```
67+
68+
## Using with Claude Code
69+
70+
This CLI ships with a `SKILL.md` file that lets Claude Code discover and use all
71+
commands automatically. There are two ways to enable it.
72+
73+
### Option 1: Add SKILL.md to your CLAUDE.md
74+
75+
Append a reference to the skill file in your project or user `CLAUDE.md`:
76+
77+
```markdown
78+
# In your CLAUDE.md
79+
Read the skill file at /path/to/agent-harness/cli_anything/samgeo/skills/SKILL.md
80+
for the full cli-anything-samgeo command reference. Use `--json` for all
81+
cli-anything-samgeo commands so output is machine-readable.
82+
```
83+
84+
Replace `/path/to/` with the actual absolute path. Claude Code reads `CLAUDE.md`
85+
at the start of every conversation, so it will know the CLI exists and how to
86+
call it.
87+
88+
### Option 2: Point Claude Code at the skill on the fly
89+
90+
In any Claude Code conversation, paste:
91+
92+
```
93+
Read agent-harness/cli_anything/samgeo/skills/SKILL.md and use that CLI
94+
to segment this satellite image.
95+
```
96+
97+
Claude Code will read the skill file, learn the command syntax, and start
98+
using `cli-anything-samgeo` with `--json` output.
99+
100+
### Example Claude Code session
101+
102+
Once Claude Code knows about the skill, you can give it natural-language tasks:
103+
104+
```
105+
> Segment all buildings in satellite.tif and export the results as a GeoPackage.
106+
107+
# Claude Code will run:
108+
cli-anything-samgeo --json project new -n buildings -o project.json -s satellite.tif -t sam2
109+
cli-anything-samgeo --json --project project.json segment automatic -o masks.tif
110+
cli-anything-samgeo --json vector convert masks.tif buildings.gpkg
111+
```
112+
113+
```
114+
> Download OpenStreetMap tiles for downtown Portland and tell me about the image.
115+
116+
# Claude Code will run:
117+
cli-anything-samgeo --json data download-tiles -o portland.tif -b "-122.68,45.51,-122.66,45.53" -z 17
118+
cli-anything-samgeo --json data info portland.tif
119+
```
120+
121+
### Tips for Claude Code usage
122+
123+
- The `--json` flag is essential — it gives Claude Code structured output it can
124+
parse and reason about, rather than human-formatted tables.
125+
- The `--project` flag must appear *before* the command group (e.g.,
126+
`--project proj.json segment automatic`, not `segment automatic --project proj.json`).
127+
- Claude Code can chain multiple commands in sequence to build full pipelines
128+
(download → segment → vectorize → export).
129+
- Use `model check sam2` to let Claude Code verify a model backend is installed
130+
before attempting segmentation.
131+
132+
## Running Tests
133+
134+
```bash
135+
cd agent-harness
136+
python -m pytest cli_anything/samgeo/tests/ -v -s
137+
```
138+
139+
## Supported Models
140+
141+
| Type | Models | Install |
142+
|------|--------|---------|
143+
| SAM v1 | vit_h, vit_l, vit_b | `pip install segment-geospatial` |
144+
| SAM 2 | hiera-tiny/small/base-plus/large | `pip install segment-geospatial[samgeo2]` |
145+
| SAM 3 | facebook/sam3 | `pip install segment-geospatial[samgeo3]` |
146+
| FastSAM | FastSAM-x, FastSAM-s | `pip install segment-geospatial[fast]` |
147+
| HQ-SAM | vit_h, vit_l, vit_b, vit_tiny | `pip install segment-geospatial[hq]` |
148+
| LangSAM | text-based (SAM2 backend) | `pip install segment-geospatial[text]` |

‎agent-harness/cli_anything/samgeo/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
"""cli-anything-samgeo: CLI harness for segment-geospatial."""
2+
3+
__version__ = "0.1.0"

‎agent-harness/cli_anything/samgeo/__main__.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
"""Allow running as python -m cli_anything.samgeo."""
2+
3+
from cli_anything.samgeo.samgeo_cli import cli
4+
5+
if __name__ == "__main__":
6+
cli()

‎agent-harness/cli_anything/samgeo/core/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
"""Core modules for cli-anything-samgeo."""

0 commit comments

Comments
 (0)