Gee Scripting

This skill is a built-in skill for GeoAgent. Follow these guidelines when writing and executing GEE scripts — they will help you avoid the most common failure scenarios and write efficient, reliable scripts.

GEE Scripting Workflow Guide

All GEE scripts must be executed using the RunGeeScript tool. When performing GEE operations, you MUST strictly follow this skill and read the document references/image-composite.md(first 600 lines).

1. Script Mode Selection

RunGeeScript provides two execution modes:

Inline mode (script parameter) — suitable for quick queries and simple one-off operations: querying image bands, collection size, date ranges; single-step computations and quick validations.

File mode (script_path parameter) — suitable for multi-step tasks: data filtering → processing → analysis → export pipelines; complex scripts requiring iterative debugging; scripts worth preserving for the user.

2. Script Writing Standards

Standard Script Structure

# 1. Imports
from geocode import init_gee, load_region, download_image, check_coverage, heartbeat
import ee

# 2. Initialization (must be the first step)
init_gee("project-id")

# 3. Define study area
roi = load_region("/path/to/boundary.shp").geometry()

# 4. Data retrieval and processing (wrap each slow operation with heartbeat)
with heartbeat("Filtering collection"):
    ... read: references/image-composite.md ...

# 5. Compositing
with heartbeat("Computing composite"):
    composite = ......

# 6. Quality check — decide whether to proceed or adjust parameters
report = check_coverage(composite, roi)

# 7. Output
download_image(composite, "/path/to/output.tif", roi, scale=10)

Heartbeat Usage Rules

When in doubt, wrap it. Any operation involving GEE server-side computation should be wrapped — because you cannot accurately predict server-side execution time, and a single missed heartbeat could cause the script to be unexpectedly terminated.

Common operations that must be wrapped: .getInfo(), reduceRegion()/reduceRegions(), classify(), train(), download_image()/export_image().

# heartbeat wraps slow operations, outputting status every 30 seconds to keep the process alive
with heartbeat("Computing NDVI statistics"):
    stats = ndvi.reduceRegion(
        reducer=ee.Reducer.mean(),
        geometry=roi, scale=30, maxPixels=1e9
    ).getInfo()
print(f"NDVI mean: {stats['NDVI_mean']:.4f}")

The equivalent code without heartbeat could silently wait 2-3 minutes on large regions before being terminated by timeout.

When chaining operations, use a separate heartbeat for each stage, and print stage results between heartbeat blocks. This both keeps the process alive and lets the user track progress.

Print Output Standards

Good output habits help the user understand what the script is doing and where it's at:

• Print a description and key parameters at the start of the task (study area, time range, etc.)
• Print stage results after each stage completes
• Structure the final results clearly
• Use flush=True to ensure immediate visibility

3. geocode Module Practical Notes

The tool description already lists the complete API signatures for the geocode module. Here are supplementary notes on key practical considerations.

init_gee(project_id)

The first step in every script. project_id is the user's GEE Cloud Project ID — if unknown, ask the user to confirm.

load_region(file_path)

Uploads a local vector file (.shp, .geojson) as an ee.FeatureCollection.

Process the boundary files locally before uploading them to GEE; do not process the boundary files on GEE!

Prefer this function for loading study area boundaries over GEE's built-in boundary datasets (e.g., FAO/GAUL, USDOS/LSIB). Local files are more precise and user-controlled, and built-in datasets' administrative boundaries may not match the user's specific needs.

The return value is an ee.FeatureCollection — you typically need .geometry() to get the boundary for filterBounds() and clip(). Uploading large vector files may be slow; the function has built-in heartbeat.