detect-objects

name	detect-objects
description	Run pre-trained AI models on geospatial imagery. Detect buildings, cars, ships, solar panels, agriculture fields, or use text-prompted segmentation with GroundedSAM. Requires GPU for best performance.
argument-hint	<model> <input_raster> [--text PROMPT] [--output FILE]
allowed-tools	Bash

You are helping the user run AI object detection on geospatial imagery using geoai.

Input: $@

Follow these steps in order.

Step 1 -- Parse arguments

Extract:

• $0 as the model name: buildings, cars, ships, solar-panels, parking-lots, agriculture, or grounded-sam
• $1 as the input raster path
• --text PROMPT for GroundedSAM text-prompted segmentation (required when model is grounded-sam)
• --output FILE for the output vector file (default: ./<model>_detections.gpkg)

If the model name is not recognized, list the available models and ask the user to pick one.

Model mapping:

Argument	GeoAI Class
buildings	geoai.BuildingFootprintExtractor
cars	geoai.CarDetector
ships	geoai.ShipDetector
solar-panels	geoai.SolarPanelDetector
parking-lots	geoai.ParkingSplotDetector
agriculture	geoai.AgricultureFieldDelineator
grounded-sam	geoai.GroundedSAM

Step 2 -- Check GPU availability

python3 -c "
import torch
if torch.cuda.is_available():
    print(f'GPU: {torch.cuda.get_device_name(0)}')
    print(f'CUDA: {torch.version.cuda}')
    print(f'Memory: {torch.cuda.get_device_properties(0).total_mem / 1e9:.1f} GB')
else:
    print('GPU: not available (CPU mode)')
    print('Warning: inference will be significantly slower without a GPU')
"

If no GPU is available, warn the user but continue.

Step 3 -- Resolve the input file

If $1 looks like an absolute path, use it directly. Otherwise:

find "$PWD" -name "$1" -not -path '*/.git/*' 2>/dev/null

If no file specified and state exists, check for recently inspected/downloaded files:

STATE_DIR=""
test -f .geoai-skills/state.json && STATE_DIR=".geoai-skills"
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
PROJECT_ID="$(echo "$PROJECT_ROOT" | tr '/' '-')"
test -f "$HOME/.geoai-skills/$PROJECT_ID/state.json" && STATE_DIR="$HOME/.geoai-skills/$PROJECT_ID"

Step 4 -- Run the detector

Pre-trained detectors (buildings, cars, ships, solar-panels, parking-lots, agriculture)

python3 -c "
import geoai

detector = geoai.DETECTOR_CLASS()
gdf = detector.predict(
    'INPUT_PATH',
    output_path='OUTPUT_PATH',
)
print(f'Detections: {len(gdf)}')
print(f'Output: OUTPUT_PATH')
print(f'Columns: {list(gdf.columns)}')
if len(gdf) > 0:
    print('---')
    print('Sample (first 5):')
    print(gdf.head().to_string())
"

Replace DETECTOR_CLASS with the appropriate class from the mapping table (e.g. BuildingFootprintExtractor).

GroundedSAM (text-prompted segmentation)

python3 -c "
import geoai

sam = geoai.GroundedSAM()
gdf = sam.predict(
    'INPUT_PATH',
    text_prompt='TEXT_PROMPT',
    output_path='OUTPUT_PATH',
)
print(f'Segments: {len(gdf)}')
print(f'Output: OUTPUT_PATH')
print(f'Columns: {list(gdf.columns)}')
if len(gdf) > 0:
    print('---')
    print('Sample (first 5):')
    print(gdf.head().to_string())
"

Replace TEXT_PROMPT with the user's text prompt.

Replace INPUT_PATH and OUTPUT_PATH with actual values before running.

Step 5 -- Report results

Summarize:

• Model used
• Number of detections/segments
• Output file path
• Sample of results

Then suggest: "Use /geoai-skills:inspect-geo to examine the detection output."

Error handling

• import geoai fails -> delegate to /geoai-skills:install-geoai.
• import torch fails -> suggest installing PyTorch: pip install torch torchvision.
• CUDA out of memory -> suggest reducing the tile size or processing a smaller area. If the detector accepts a tile_size parameter, recommend a smaller value.
• Model download fails -> check network connectivity. Models are downloaded from Hugging Face on first use.
• Input is not a raster -> suggest using a GeoTIFF file. If the user has a vector file, suggest /geoai-skills:process-raster vector-to-raster first.
• GroundedSAM without --text -> ask the user for a text prompt describing what to detect.